Skip to content

Factories > Blueprints

Defining Blueprint stages

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

Open in ChatGPT ↗
Ask ChatGPT about this page
Open in Claude ↗
Ask Claude about this page
Copied!

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, 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. Replace any spawnableBy allowlists in those agents with stage worker assignments.

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.

  3. Write inputs, prompt, and outputs so the next stage has the evidence it needs:

    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, and name that skill in the stage prompt.

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.

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 for the fields and constraints.

  1. Validate and apply the complete 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. The unconditional to: end above finishes the workflow after review; it does not itself request another implementation pass.