Workflows and steps

A workflow is a stored definition the engine runs. The fields that shape a run are:

• appliesTo — ticket, pull_request, documentation, a list of those, or none when the workflow has no subject.
• subjectHandling — per-subject runs one subject at a time. collection runs the whole resolved set together.
• inputSchema — parameters collected at launch. Field types are string, number, boolean, select, and localRepository.
• steps — the sequence below.
• notificationPolicy — which events notify: on_fail, on_complete, and on_needs_input. The trigger list may be empty.

Any public step can carry a condition. When that predicate holds (field_empty or field_equals on an earlier step), the step is skipped.

Step types

agent

Runs a configured agent instance with an objective. The output format is questionnaire, confirmation, comment_suggestions, or free_text. The step can name skills and MCP servers, and an optional working directory that does not change the job’s cwd.

interaction

Pauses until a person responds. The interaction is questionnaire, confirmation, conversation, or comment_review.

shell

Runs a command. An optional cwd applies to this step only.

git

One git operation: create_worktree, checkout, create_branch, commit, or push.

provider_action

Runs a catalog action (actionId) on a provider instance. It uses the job’s subject unless target names a different subject.

sub_workflow

Runs another workflow once per item. forEach is either selection or a { source } reference.

loop

Repeats an inline list of steps until an exit condition holds, or until maxIterations. When the cap is hit, onMaxIterations is fail, continue, or ask_human.

extract

Reads a value from a source string, with an optional path or pattern. When nothing matches, onNoMatch is fail, empty, or ask_human.

parallel

Runs several inline branches at the same time as child jobs. The branches share the subject and the context so far, and each branch has its own steps.

switch

Runs exactly one branch in the current job. Cases are tested in order and the first match runs. defaultSteps, when set, runs if none match.

editor_handoff

Writes a prompt file and, when the editor adapter has a scheme, a deep link. It does not launch the editor or wait for it to finish. The editor id is cursor, claude-code, or file. When the step omits editorId, the engine uses the default editor from settings.