Configure a pipeline for your project

Keep workflow, project environment and runner selection in their respective settings. Changing a model then does not require rebuilding a route.

Where to change each setting

Change	Location
Stages, instructions and transitions	Route draft in the editor.
Commands, paths and previews	Project profile.
Runner, model, effort and fallback	Project launch policy.
Lead and worker pairing	Route loop field and pair transitions.
Handoff limit	Profile PROFILE_LOOP_MAX_ROUNDS.
Task result	Task description and acceptance criteria.
Current work needing changes	Attempt controls.

For environment files, hooks, model keys and when changes take effect, read the project profile reference. Its route and node fields explain the definition settings.

Stage types

• Agent (agent) executes its instruction with the supplied context.
• Command (command) calls a command allowed by the profile, such as a build or test.
• Gate (gate) waits for a human decision.
• Status (status) displays its owner's result and does not execute separately.

Instructions and context

Define a clear result and completion criteria for each stage. A reviewer needs criteria and changes; a planner needs the task, project information and exploration results.

The editor combines Markdown blocks, inclusion conditions and required context. Use Show instruction to inspect the assembled result.

Reviewer rules

Rules for repeat reviews, new blockers and unavailable checks are collected in the recommendations for profiles and routes. Put them in reviewer instructions and route transitions.

Transitions and rework

Define the action for every outcome: move forward, return, stop or use another supported route. Return implementation defects to the author, incomplete plans to planning, and restore unavailable environments before continuing.

Feedback needs a recipient

Rejection text goes to the agent at the return destination. A command stage cannot process rework instructions.

Retrying a stage can help after a temporary failure. Returning to an earlier stage is appropriate when inputs or work must change. If an outcome already returns work, avoid configuring a conflicting retry policy.

Loop routes declare a pair with loop. The lead assigns and reviews work; both pair nodes use retry.productFailure: 0. The profile limit does not replace progress checks or reset between stages. Read loop mode.

Runners and models

A stage has a runKey, which launch policy uses to select a runner and model settings. Route definitions do not include provider, model or effort.

Use the project CLI to preserve settings version checks. Replace <name> with the profile:

engine/bin/factory profile <name> runner show
engine/bin/factory profile <name> runner set claude --failover codex
engine/bin/factory profile <name> runner set REVIEW codex --failover claude

The first set configures the project runner and fallback; the second configures the REVIEW stage. Select installed, authenticated runners and model names from their catalogs.

After policy changes, run:

RUN_HOST_PREFLIGHT=1 engine/bin/factory-check <name> --host-preflight

Rule priority: task stage → task → profile stage → project settings. For inheritance, fallbacks and FAMILY, VERSION, EFFORT, EXACT, see the runner and model reference.

Initial scouting

Scout configuration is separate from catalog routes. A route can require or skip it when allowed by catalog validation. Triage assesses a task before launch; scouting belongs to execution of the chosen workflow.

Import, publication and rollback

Import creates a new draft and revalidates profile bindings. Commands, repository paths and model settings are not transferred automatically.

Validate and compare before publication. Rollback changes the revision for new attempts. Existing attempts keep their pinned routes, and working drafts remain available.