> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Defining Blueprint stages

Define stages in a Warp Factories Blueprint, assign workers, and specify the instructions and results each handoff needs.

Give each part of your workflow a stage with a clear result. For example, an implementation stage returns a PR and check results; an independent review stage returns findings against that PR.

Edit the stages under `blueprint.stages` in your factory’s `factory.yaml`. If your definition has no Blueprint, add the [Blueprint fragment](https://docs.warp.dev/factories/factory-as-code/#blueprint), retain your factory settings, and set `schemaVersion: v1alpha2`. Older `v1alpha1` definitions do not contain a Blueprint.

Use agents already declared in the definition, or [create a custom agent](https://docs.warp.dev/factories/factory-agents/creating-custom-agents/). Replace any `spawnableBy` allowlists in those agents with stage worker assignments.

## Choose the worker and instructions

The stage says what work to do now. The agent configuration supplies the worker’s model, harness, tools, and instructions that apply across its work.

1.  In `factory.yaml`, find the stage to change under `blueprint.stages`, or add a new named stage. Choose a name for the work, such as `implement` or `review`, rather than for its model.
    
2.  Set `worker` to an agent declared in `agents/<name>/agent.md`. In this example, `implementer` makes the change and `reviewer` checks it independently. Configure their repository access and tools in their [agent settings](https://docs.warp.dev/factories/factory-agents/configuration/).
    
3.  Write `inputs`, `prompt`, and `outputs` so the next stage has the evidence it needs:
    
    ```yaml title="Stages under blueprint.stages"
    implement:
      worker: implementer
      inputs: The approved plan and repository context.
      prompt: |
        Implement the approved plan on the existing branch and PR, if any.
        Run the repository checks and report failures honestly. Do not merge.
      outputs: The PR URL, head commit, changed files, and check results.
      to: review
    review:
      worker: reviewer
      inputs: The PR URL, head commit, approved plan, and check results.
      prompt: |
        Review the diff against the plan and repository conventions.
        Check the reported evidence. Return findings; do not edit or merge.
      outputs: Findings with locations, or acceptance of the reviewed head.
      to: end
    ```
    
    Keep the rest of your definition, including its entry route. Make both stages reachable; if an earlier stage led directly to `end`, route it to `implement` or `review` as appropriate.
    

Inputs and outputs are instructions, not typed schemas. “The checks passed” is less useful than the command, exit code, and tested commit. Put recurring check procedures in a [skill](https://docs.warp.dev/factories/factory-skills/), and name that skill in the stage prompt.

## Reuse an agent across stages

A stage name and a worker name serve different purposes. Two stages can use the same worker with different procedures. The worker receives the named stage’s instructions; it does not decide which other stage to do next.

When a stage uses the worker already driving its workflow, it runs in that conversation. A different worker receives a delegated stage. For later revisions, the coordinator continues that worker’s existing conversation for the task.

Do not copy the Blueprint’s full routing procedure into each `agent.md`. Keep communication rules and reusable behavior there; keep stage work in `prompt` and next-step decisions in [`to`](https://docs.warp.dev/factories/blueprints/routes/).

## Group related stages

A stage can contain its own `start` and `stages` instead of a leaf `prompt`. Its worker drives that group, runs stages assigned to itself, and delegates other stages. Reaching the group’s `end` returns its declared outputs to the enclosing workflow; it does not finish the whole task.

Use a group when one worker needs to coordinate a subworkflow, such as implementation and review, before returning a single result. Stage names must be unique across the Blueprint. See [Blueprint syntax](https://docs.warp.dev/factories/factory-as-code/#blueprint) for the fields and constraints.

## Apply and check the handoff

1.  [Validate and apply the complete definition](https://docs.warp.dev/factories/factory-as-code/#validate-a-definition), then start a new test request in a repository you control.
2.  Ask for one bounded change, such as fixing a broken README command. Inspect the stage’s conversation and confirm the assigned worker used the intended prompt and returned the required outputs.
3.  Inspect review’s inputs. Confirm it received the same PR and tested head, rather than a summary without the diff or check results.
4.  To add a revision loop, configure [review’s outgoing routes](https://docs.warp.dev/factories/blueprints/routes/). The unconditional `to: end` above finishes the workflow after review; it does not itself request another implementation pass.

## Related pages

-   [Routing work between Blueprint stages](https://docs.warp.dev/factories/blueprints/routes/) - Return findings to implementation
-   [Adding human gates to a Blueprint](https://docs.warp.dev/factories/blueprints/gates/) - Require an answer before work continues
-   [Configuring factory agents](https://docs.warp.dev/factories/factory-agents/configuration/) - Change worker resources and base instructions
