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

Workflow files

A workflow's file is YAML: an optional description, then steps, which run in order. The workflow's name is not in the file. 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, 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).

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.

Stage field	Meaning
model	Also picks the vendor: gpt-* models run on Codex, gemini-* models on Antigravity, every other model on Claude Code.
prompt	The stage agent's instructions.
agents	In place of model: a list of at least two, each with name, model 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 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 or parallel can't be empty.

description: Build a change, review and test it in parallel, then fix what they found.
steps:
  - stage: Build
    model: claude-opus-5-5
    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.
  - stage: Fix
    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.
    prompt: Merge the branches you are given and address both reports.