workflow.yaml specification for Codemod Workflows.
Complete Example
This example demonstrates all five step types working together in a migration workflow:workflow.yaml
Workflow Structure
A workflow has four top-level keys:workflow.yaml
Nodes
Nodes are execution units in your workflow. They can be automatic or manual, depend on other nodes, and may define strategy (matrix), trigger, runtime, env, and an ordered list of steps.Upstream node IDs that must complete before this node runs. See Cyclic Dependencies.
{ type: manual } creates an approval gate. See Manual Triggers.Matrix configuration for parallel fan-out. See Matrix Strategy.
Ordered list of steps to execute.
Git Automation (Campaign/Cloud Runs)
In Campaign/cloud runs, each task executes on its own git branch. Codemod creates that branch before the node’s steps run, can create commits after successful steps, and pushes the branch plus opens a pull request when the node ends with commits.These git automation fields are only used in Campaign/cloud runs. Local
codemod workflow run execution does not create branches, commits, or pull requests automatically.Branch name template for Campaign/cloud runs. The branch is created before the node’s steps run. If omitted, Codemod uses
codemod-<task.signature>.Pull request customization for Campaign/cloud runs. If the node ends with commits, Codemod pushes the task branch and attempts to create a pull request. This field customizes the PR metadata; omitting it does not disable PR creation.
Default Campaign/cloud behavior:If the node ends with commits and
pull_request is omitted, Codemod attempts to open a pull request using the node name as the default title. If no explicit commit checkpoint was created and changes remain at the end of the node, Codemod attempts a fallback commit using the node name before pushing and opening the pull request.Steps
Steps are atomic actions inside a node. They run sequentially and each step performs one transformation or action.Common Step Fields
All step types supportname, if, env, and commit.
Conditional expression to gate step execution. Current runtime support for generic step conditions includes
params.x, state.x, and matrix.x. See Variable Resolution.Optional commit checkpoint for Campaign/cloud runs. After a successful step, Codemod stages the configured paths and creates a git commit. If no step creates a commit but changes remain at the end of the node, Codemod attempts to create a fallback commit using the node name before pushing and opening the pull request.
Paths to stage before committing. If omitted, Codemod stages the entire working tree for that task branch.
If
true, skip the checkpoint when nothing is staged. If false, the step fails when there are no staged changes to commit.Commit checkpoints are Campaign/cloud-only. They run after successful steps on the task branch created for the node.
JSSG Step
Executes a JavaScript/TypeScript codemod using ast-grep for pattern matching and AST manipulation.Conditional expression to gate step execution. Supports
params.x, state.x, and matrix value keys. Operators: ==, !=, >, <, &&, ||. See Variable Resolution.JSSG Documentation
Learn how to write JavaScript/TypeScript codemods.
AI Step
Calls an AI agent with a prompt for LLM-powered transformations.Conditional expression to gate step execution. See Variable Resolution.
Install Skill Step
Installs package skill behavior into a supported harness via the Codemod CLI. Use this in skill-only or workflow + skill packages when you want authored skill files from the package to be installable for coding-agent workflows.--install-skill. See CLI reference.
The target package must expose an authored SKILL.md with valid frontmatter and the authored-package markers:
mcs-v1, that is the marker for the built-in Codemod core skill profile, not for authored package skills installed by this workflow step.
Install Skill Step Parameters:
Conditional expression to gate step execution. See Variable Resolution.
Optional authored skill source path inside the package. Defaults to the conventional
agents/skill/<skill-name>/SKILL.md layout.YAML ast-grep Step
Executes ast-grep using declarative YAML rules for simple, fast pattern matching.Conditional expression to gate step execution. See Variable Resolution.
Codemod Registry Step
Runs another codemod by package name or local path.Conditional expression to gate step execution. See Variable Resolution.
Codemod source (registry package or local path). Supports version pinning:
@scope/pkg@1.2.3. A local path that starts with ./ or ../ is relative to the directory that contains the workflow file with the step, not to the directory you run the CLI from.You can aggregate multiple codemods by adding multiple
codemod steps in the same node. Steps run sequentially from top to bottom.Shell Command Step
Runs shell commands on the host for setup, cleanup, or external tools.$CODEMOD_PATH to run a shell script bundled with your codemod package. It points to the package root. Quote the script path so it works when the package directory contains spaces:
workflow.yaml
Conditional expression to gate step execution. See Variable Resolution.
Inline shell command to execute. It runs with
sh -c on macOS and Linux, and as a batch file with cmd.exe on Windows. Use the CODEMOD_PATH environment variable for scripts or files bundled with the codemod package.On Windows, every line runs in order and the step’s exit code is the last command’s, as with
sh. Batch-file rules apply: write a literal % as %% (for example in a URL, %%20) and for loop variables as %%i. A command that is itself a batch file, such as npm, npx or pnpm, is run with call automatically at the start of a line or after &, && or ||, so the lines after it still run. Inside if or for, write call npm ... yourself.Shard Step
Evaluates file shards and writes results to workflow state for use with matrix strategies. Supports built-in grouping algorithms (directory, codeowner) and custom shard functions.Sharding method. Either
{ type: "directory" | "codeowner", max_files_per_shard: N } for built-in methods, or { function: "path/to/shard.ts" } for custom logic.JSSG codemod configuration for pre-filtering. Dry-runs the codemod and only shards files where the transform produces changes.
Sharding Guide
Full guide covering built-in methods, custom functions, re-evaluation, and examples.
Matrix Strategy
Matrix strategies fan out a node into multiple parallel tasks. Use them to shard work by team, directory, or configuration.from_state field references an array in your workflow’s state schema. Each array item spawns a parallel task.
Accessing Matrix Values:
In JSSG transforms via options.matrixValues:
from_state changes:
- New tasks are created for new items
- Tasks are marked
WontDoif their item is removed - Existing tasks remain untouched if their item persists
Manual Triggers
Add approval gates to pause execution until manual intervention:Shared State
State enables workflows to persist data across runs and coordinate work:State Updates
State updates must be valid JSON if not primitive. Updates are applied only if the task exits successfully.
codemod: step, its child steps share the parent workflow
run’s persisted state. Each child step reads that state before evaluating its if
condition and executing its action, so later steps can use earlier steps’ persisted
updates, including values written with setState in JSSG transforms.
Parameters
Parameters make workflows configurable and reusable:Accessing Parameters
In JSSG transforms viaoptions.params:
PARAM_ prefixed environment variables:
env_ prefix:
Advanced Parameter Usage
Complete parameter patterns and examples in JSSG.
Variable Resolution
Workflow expressions are evaluated in a few different runtime contexts today. The available variables are not identical across all of them.Template interpolation
${{ ... }} interpolation is used in:
runai.promptbranch_namecommit.messagepull_request.titlepull_request.body
${{ env.x }} and generic steps.<id>.outputs.* interpolation are not wired into workflow runtime expression resolution.if Conditions
Current generic workflow if evaluation receives:
params.*state.*matrix.*
if evaluation does not receive:
task.*env.*steps.<id>.outputs.*
if conditions: ==, !=, >, <, >=, <=, &&, ||
Task Statuses
Cyclic Dependencies
Workflows cannot have circular dependencies:Templates
Templates define reusable step blocks (planned feature):Roadmap
Container runtime support
Support for
runtime: docker and other container runtimes.Nested matrix strategies
Matrix strategies within matrix strategies for complex fan-out.
Next Steps
Package Structure
Directory layout and codemod.yaml reference.
CLI Reference
Validate and run workflows from the command line.
JSSG
Write JavaScript/TypeScript codemods.
Publishing
Share your codemod via the Registry.