byre/internal/agents/kb/workflow-definitions.md

The fields of a workflow's definition, the object save_workflow takes and read_workflow returns: steps (stage, order, parallel, random), auto_merge and auto_discard, and how stages pass outputs along and branch.

Workflow definitions

A workflow's definition is an object: an optional description, optional auto_merge and auto_discard booleans, then steps, which run in order. With auto_merge, when a stage task of a run calls ready_for_merge, byre merges it right away as the creator of the run, pressing the button the agent picked (complete or continue); with auto_discard, byre discards a stage task that calls suggest_discard. Without them the human decides, as for any task. The workflow's name is not in it. save_workflow takes it as its definition argument and read_workflow returns it, both as JSON. Unknown fields are refused.

Any workflow can run on a brief, each stage as its own task, and any workflow whose stages are single agents can be a project's review workflow (set with set_review_workflow), which reviews its tasks' snapshots: each stage is then one reviewer agent on its model and effort, given the task's change and its stage's prompt (what to look for), and a stage after others also gets their reviews. A project can't review with a workflow that has a team stage (agents).

Each step is exactly one of:

Step	Meaning
stage	A stage, by its name: one line, unique in the workflow. It runs as its own task, with model or agents, and prompt.
order	A list of steps run one after another.
parallel	A list of branches run at the same time, each a step (an order for a branch of several).
random	A list of steps of which one runs, picked when a run or review starts. Each step in it has a weight from 0 to 1, its chance of being picked, and the weights add up to 1. weight is refused anywhere else.

A stage gets the outputs of the stages that end the step before it: the last stage of an order, or the last stage of every branch of a parallel. A stage with nothing before it starts from the brief. A run or review freezes the definition with each random replaced by the step it picked, so read_workflow with its task_id shows only what runs, and the stages of steps it didn't pick never appear in it.

Stage field	Meaning
model	Also picks the vendor: gpt-* models run on Codex, gemini-* models on Antigravity, every other model on Claude Code.
effort	Optional: low, medium, high, xhigh or max (Codex models take low to xhigh). Without it the agent runs at the vendor's default.
prompt	The stage agent's instructions.
agents	In place of model and effort: a list of at least two, each with name, model, an optional effort and prompt, that runs the stage as a team. They work in the stage's one task and worktree and talk through a shared board; each gets the stage's prompt and then its own, and the first agent finishes the stage.

Where a stage's task branches from follows from the shape. A stage after exactly one stage starts from the commit that stage finished at. A stage after a parallel starts from the default branch and is told the branches it can merge. A stage with nothing before it starts where the workflow was started. A run on a brief has a task of its own, with no agent, worktree or branch, and its stage tasks are that task's subtasks; it closes once they all have. A workflow is finished once every stage has finished; when it ends with a parallel, each branch's last stage keeps its task to merge, and the run's other stage tasks are discarded. A review is delivered to the task's agent, every stage's findings in one message, once every stage has reviewed. An order, parallel or random can't be empty.

{
  "description": "Build a change, review and test it in parallel, now and then auditing security in depth, then fix what they found.",
  "steps": [
    {"stage": "Build", "model": "claude-opus-5-5", "effort": "high", "prompt": "Implement the brief."},
    {"parallel": [
      {"stage": "Review", "model": "gpt-6.1-sol", "prompt": "Review the Build stage's work and list the problems."},
      {"stage": "Test", "model": "gemini-4-argon-high", "prompt": "Exercise the change and report what fails."},
      {"random": [
        {"weight": 0.8, "stage": "Security check", "model": "claude-sonnet-5-5", "prompt": "Check the change for security problems."},
        {"weight": 0.2, "stage": "Security audit", "model": "claude-fable-5-1", "prompt": "Audit the change thoroughly for security problems, tracing every input it touches."}
      ]}
    ]},
    {"stage": "Fix", "prompt": "Merge the branches you are given and address every report.", "agents": [
      {"name": "fixer", "model": "claude-opus-5-5", "prompt": "Fix every problem the reports list."},
      {"name": "checker", "model": "gpt-6.1-sol", "prompt": "Check each fix as the fixer lands it."}
    ]}
  ]
}