Skip to content

Factories > Blueprints

Configuring Blueprint transitions

Configure entry points, ordered conditions, and revision loops in a Warp Factories Blueprint, then check the paths with concrete requests.

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

Transitions connect stages and define the conditions for moving between them. For an issue-to-PR workflow, review findings can return to implementation while an accepted change moves to human handoff.

In factory.yaml, blueprint.start.to chooses where new work enters. For one starting stage, use a scalar:

Entry inside blueprint
start:
to: plan

For multiple paths, use ordered objects with stage and when. For example, if your Blueprint declares plan and implement:

Conditional entry inside blueprint
start:
to:
- stage: plan
when: The request has unresolved decisions or explicitly requires a plan.
- stage: implement
when: The request is fully defined.

The worker driving the workflow judges these prose conditions and takes the first match. Put the more specific condition first. Conditions are not Boolean expressions evaluated by a rules engine.

Send different requests to different stages

Section titled “Send different requests to different stages”

For a workflow with docs, triage, and implement stages, transition documentation-only changes to a documentation worker and unknown bugs to investigation:

Entry for documentation, investigation, and implementation
start:
to:
- stage: docs
when: The request is fully defined and changes only documentation.
- stage: triage
when: The cause or scope of the reported problem needs investigation.
- stage: implement
when: The request is fully defined and needs a code change.

Declare all three stages and their workers under blueprint.stages. A defined documentation change takes the first transition, not the implementation transition. A request that fits none of these conditions needs clarification.

  1. In blueprint.stages.implement, set to: review.

  2. In the review stage, require outputs that distinguish findings from acceptance of a particular head.

  3. Replace review’s unconditional exit with:

    Transitions inside the review stage
    to:
    - stage: implement
    when: Review found actionable changes for implementation.
    - stage: end
    when: Review accepted the current PR head with no changes required.

Every item in a conditional list needs when. For one unconditional transition, use to: review or to: end, not a list entry with a missing condition.

The destination must be a sibling stage or end. The order of stage declarations does not set execution order. If no condition fits, the coordinator asks for the missing decision rather than silently treating the work as complete.

Keep the PR and branch in the implementation stage’s inputs and prompt so a revision updates the existing change. A return transition does not mean “open another PR.”

For a triage-only workflow, return findings without starting implementation. With investigator and foreman workers declared, use these sibling stages and set blueprint.start.to: triage:

Investigation and handoff stages
triage:
worker: investigator
inputs: The issue and repository context.
prompt: Investigate the reported problem. Do not edit code.
outputs: Evidence, affected files, open questions, and the recommended next action.
to: handoff
handoff:
worker: foreman
inputs: The investigation findings.
prompt: Return the findings and questions to the requester. Do not start implementation.
outputs: The findings delivered to the requester.
to: end

Here, end finishes the configured workflow after handoff. It does not mean that the bug was fixed or a pull request was merged.

Follow-ups to existing work resume the stage they concern. They do not repeat the entry rules as if every review reply were a new request.

After validation and application, start new test work in a disposable repository you control. Existing tasks keep the definition selected when they started.

Test input or outcomeWhat to check
A request with an unresolved product decisionPlanning runs before implementation
A well-defined fix that also explicitly requires a planThe first entry condition selects planning, not the broader implementation path
A defined documentation-only request with the three-way entry exampleThe documentation stage runs, not implementation
An investigation using the triage-only exampleFindings return to the requester without code changes or implementation
Actionable independent-review findingsThe existing implementation conversation updates the same PR, then returns to review
An outcome that satisfies neither review conditionThe coordinator asks for a decision and does not finish
A definition edit followed by a reply to an existing taskThe existing task keeps its earlier workflow; separate new work uses the applied change

Inspect the conversations, PR identity, and tested commits. A completed run alone does not prove that the intended transition was taken.