Factories
How Warp Factories work
# How Warp Factories work Warp Factories organizes software development as two connected loops. The **inner loop** moves a work item from intake to a human-reviewed outcome. The **outer loop** uses completed work to improve the factory. A **work item** is one unit of engineering work, such as an issue, support request, pull request, or Factory MCP task. It retains its identity as agents contribute at different stages. ## The inner execution loop The default inner loop is intake, triage, specification when needed, implementation, review and verification, human handoff, and completion. Not every work item needs every stage. The foreman chooses the shortest path that preserves the team's quality requirements. ```mermaid flowchart LR Intake[Intake] --> Foreman[Foreman] Foreman --> Triage[Triage] Triage --> Decision{Specification needed?} Decision -->|Yes| Spec[Specify] Decision -->|No| Implement[Implement] Spec --> Approval["Human review<br/>(default policy)"] Approval --> Implement Implement --> Review[Review and verify] Review --> Revision{Revision needed?} Revision -->|Yes| Implement Revision -->|No| Handoff["Human handoff<br/>(default policy)"] Handoff --> Complete[Complete] ``` ### 1. Intake creates the work item Work enters through a connected engineering tool, automation, direct run, or the [Factory MCP](./factory-mcp). Intake preserves the source context, such as the issue description, Slack thread, repository event, or note from a local coding agent. The factory associates later activity with the same work item so follow-up messages continue the existing workstream. ### 2. The foreman selects the route The **foreman agent** is the factory's orchestrator. It reads the request and its context, decides whether triage or specification is necessary, and dispatches the sibling agent responsible for the next stage. It also gathers results, routes revisions back to the existing agent conversation, and communicates decisions to the person who requested the work. The foreman maintains continuity across specialized agents. Triage scopes the problem, specification resolves requirements, implementation changes and validates code, and review examines the result independently. ### 3. Triage establishes scope The triage agent investigates the request before code changes begin. It searches the codebase and existing work, reproduces a failure when evidence is missing, estimates complexity, and reports ambiguity to the foreman. Clear work can proceed to implementation. Duplicates, incomplete reports, and unclear requirements return to the foreman for a human decision. ### 4. Specification is conditional Substantial or ambiguous work moves to a spec agent. The agent drafts product behavior, technical constraints, and validation criteria. The foreman presents unresolved questions to a human. Specification is not required for every task. A localized fix with an established expected result can skip this stage. The default seeded workflow asks for human review after a spec and before implementation, but this gate is workflow policy rather than a platform-enforced approval role. ### 5. Implementation includes validation The implementation agent works from approved requirements and repository context. It makes the change, adds regression coverage, runs the repository's validation commands, and reviews the complete diff. User-facing changes also require visual verification when the execution environment supports it. When a spec already has a branch or draft pull request, implementation continues that work. The implementation agent does not merge the pull request. ### 6. Review and verification share one quality gate The review agent examines the implementation against requirements, code conventions, tests, and security expectations. It classifies clear defects separately from questions that need human judgment and returns an advisory verdict to the foreman. Verification is part of implementation and review, not a separate default agent role. Implementation produces test and visual evidence. Review checks that evidence, reruns or extends validation where necessary, and requests revisions when the result does not meet the criteria. The foreman routes revision requests back to the implementation agent without losing the existing context. ### 7. Humans decide what ships Under the default workflow, the foreman hands the pull request, validation evidence, and review findings to a human. A human decides whether and when to merge, resolves unclear requirements, and handles review findings that involve tradeoffs. These gates come from the seeded agent instructions and the team's repository policy. Warp Factories does not assign a factory-specific approver or enforce human-only merges. Teams that require human-only merges should enforce that requirement through branch protection and repository permissions. Once the factory hands off the result, the foreman marks the work item complete. Completion does not imply that the factory merged or deployed code. ## How agents coordinate Each specialized agent runs independently with its own instructions and execution context. The foreman dispatches child runs, exchanges messages with them, and supplies the relevant work-item context. Follow-up requests continue the existing conversation when possible. This structure keeps responsibilities narrow: * **The foreman** - Owns routing, continuity, human communication, and completion. * **Triage** - Owns problem definition, evidence gathering, issue context, and scope. * **Specification** - Owns requirements, technical approach, and validation criteria when a spec is needed. * **Implementation** - Owns code changes, tests, repository validation, and implementation evidence. * **Review** - Owns independent analysis, verification, findings, and an advisory verdict. Teams can add custom agents or automations, but every role still needs a clear responsibility and handoff. ## Work-item state and agent runs The work item and agent runs describe different levels of the same activity. A work-item stage is a progress signal based on the active or most recently launched role. It is not an authoritative state machine. A stage may move backward when revision sends work to an earlier role. The foreman can also skip a stage or start from a later stage when intake already contains sufficient analysis. Run history is the detailed execution record: a foreman run anchors the workstream, and dispatched runs record the actions and outputs for each stage. ## What defines a factory A factory combines several layers of configuration and execution: * **Definitions as code** - Version-controlled files describe the factory, its connected repositories, agents, automations, runners, shared defaults, and tool access. Teams review changes to the operating model as code. * **Models and harnesses** - Each agent role can select a model and a supported harness. Teams can match a reasoning-focused model to specification, a coding harness to implementation, and a separate configuration to review. * **Skills and MCP servers** - Skills encode reusable operating instructions. MCP servers give agents access to approved external tools and context. Factory-wide and role-specific resources keep common behavior consistent while preserving specialization. * **Environments and runners** - Environments provide repositories, dependencies, startup configuration, and secrets. Runners determine the compute and operating system that execute the run, whether Warp-hosted or self-hosted. * **Integrations and automations** - Integrations connect the factory to communication tools, issue trackers, and GitHub. Automations define the events or schedules that create work and the agent that receives it. These layers are composable. A Slack request and a Linear issue can enter the same factory and use the same triage policy. Each dispatched role then receives its defined environment, model, and tools. ## The outer improvement loop The inner loop produces software and an execution record. The outer loop uses that record to improve the system that produced it. Factory measurement includes run and pull request activity, costs, evaluations, and benchmark results. Teams use these signals to find repeated failures, compare model and harness configurations, and identify stages that need better instructions or tools. Evaluation results can also create new investigation work for the factory. A team or agent can propose changes to instructions, skills, MCP access, models, environments, or other factory definitions. How the change reaches the factory depends on the definition source. GitHub-backed definitions can use pull request review and factory configuration checks before changes reach the production branch. Changes to a Warp-managed definition can synchronize directly. Teams should set review policy according to the definition source and the risk of the change. Benchmarks help compare configurations, but they do not replace product judgment or guarantee that an automated change is correct. The result is a feedback system: 1. The factory executes work through the inner loop. 2. Runs and outcomes produce evidence. 3. Evaluations and benchmarks organize that evidence. 4. Teams identify a concrete change to the factory. 5. The updated definition governs later work items. The [factory definitions as code](./factory-as-code) page explains the declarative model. See [connect your factory](./connect-your-factory) for intake paths, [Factory MCP](./factory-mcp) for agent-to-factory exchange, and [measure and improve](./measure-and-improve) for the outer loop.Tell me about this feature: https://docs.warp.dev/factories/how-factories-work/Warp Factories coordinate specialized agents from intake through review, human handoff, measurement, and workflow improvement.
Warp Factories organizes software development as two connected loops. The inner loop moves a work item from intake to a human-reviewed outcome. The outer loop uses completed work to improve the factory.
A work item is one unit of engineering work, such as an issue, support request, pull request, or Factory MCP task. It retains its identity as agents contribute at different stages.
The inner execution loop
Section titled “The inner execution loop”The default inner loop is intake, triage, specification when needed, implementation, review and verification, human handoff, and completion. Not every work item needs every stage. The foreman chooses the shortest path that preserves the team’s quality requirements.
flowchart LR Intake[Intake] --> Foreman[Foreman] Foreman --> Triage[Triage] Triage --> Decision{Specification needed?} Decision -->|Yes| Spec[Specify] Decision -->|No| Implement[Implement] Spec --> Approval["Human review<br/>(default policy)"] Approval --> Implement Implement --> Review[Review and verify] Review --> Revision{Revision needed?} Revision -->|Yes| Implement Revision -->|No| Handoff["Human handoff<br/>(default policy)"] Handoff --> Complete[Complete]1. Intake creates the work item
Section titled “1. Intake creates the work item”Work enters through a connected engineering tool, automation, direct run, or the Factory MCP. Intake preserves the source context, such as the issue description, Slack thread, repository event, or note from a local coding agent. The factory associates later activity with the same work item so follow-up messages continue the existing workstream.
2. The foreman selects the route
Section titled “2. The foreman selects the route”The foreman agent is the factory’s orchestrator. It reads the request and its context, decides whether triage or specification is necessary, and dispatches the sibling agent responsible for the next stage. It also gathers results, routes revisions back to the existing agent conversation, and communicates decisions to the person who requested the work.
The foreman maintains continuity across specialized agents. Triage scopes the problem, specification resolves requirements, implementation changes and validates code, and review examines the result independently.
3. Triage establishes scope
Section titled “3. Triage establishes scope”The triage agent investigates the request before code changes begin. It searches the codebase and existing work, reproduces a failure when evidence is missing, estimates complexity, and reports ambiguity to the foreman.
Clear work can proceed to implementation. Duplicates, incomplete reports, and unclear requirements return to the foreman for a human decision.
4. Specification is conditional
Section titled “4. Specification is conditional”Substantial or ambiguous work moves to a spec agent. The agent drafts product behavior, technical constraints, and validation criteria. The foreman presents unresolved questions to a human.
Specification is not required for every task. A localized fix with an established expected result can skip this stage. The default seeded workflow asks for human review after a spec and before implementation, but this gate is workflow policy rather than a platform-enforced approval role.
5. Implementation includes validation
Section titled “5. Implementation includes validation”The implementation agent works from approved requirements and repository context. It makes the change, adds regression coverage, runs the repository’s validation commands, and reviews the complete diff. User-facing changes also require visual verification when the execution environment supports it.
When a spec already has a branch or draft pull request, implementation continues that work. The implementation agent does not merge the pull request.
6. Review and verification share one quality gate
Section titled “6. Review and verification share one quality gate”The review agent examines the implementation against requirements, code conventions, tests, and security expectations. It classifies clear defects separately from questions that need human judgment and returns an advisory verdict to the foreman.
Verification is part of implementation and review, not a separate default agent role. Implementation produces test and visual evidence. Review checks that evidence, reruns or extends validation where necessary, and requests revisions when the result does not meet the criteria. The foreman routes revision requests back to the implementation agent without losing the existing context.
7. Humans decide what ships
Section titled “7. Humans decide what ships”Under the default workflow, the foreman hands the pull request, validation evidence, and review findings to a human. A human decides whether and when to merge, resolves unclear requirements, and handles review findings that involve tradeoffs.
These gates come from the seeded agent instructions and the team’s repository policy. Warp Factories does not assign a factory-specific approver or enforce human-only merges. Teams that require human-only merges should enforce that requirement through branch protection and repository permissions.
Once the factory hands off the result, the foreman marks the work item complete. Completion does not imply that the factory merged or deployed code.
How agents coordinate
Section titled “How agents coordinate”Each specialized agent runs independently with its own instructions and execution context. The foreman dispatches child runs, exchanges messages with them, and supplies the relevant work-item context. Follow-up requests continue the existing conversation when possible.
This structure keeps responsibilities narrow:
- The foreman - Owns routing, continuity, human communication, and completion.
- Triage - Owns problem definition, evidence gathering, issue context, and scope.
- Specification - Owns requirements, technical approach, and validation criteria when a spec is needed.
- Implementation - Owns code changes, tests, repository validation, and implementation evidence.
- Review - Owns independent analysis, verification, findings, and an advisory verdict.
Teams can add custom agents or automations, but every role still needs a clear responsibility and handoff.
Work-item state and agent runs
Section titled “Work-item state and agent runs”The work item and agent runs describe different levels of the same activity. A work-item stage is a progress signal based on the active or most recently launched role. It is not an authoritative state machine.
A stage may move backward when revision sends work to an earlier role. The foreman can also skip a stage or start from a later stage when intake already contains sufficient analysis. Run history is the detailed execution record: a foreman run anchors the workstream, and dispatched runs record the actions and outputs for each stage.
What defines a factory
Section titled “What defines a factory”A factory combines several layers of configuration and execution:
- Definitions as code - Version-controlled files describe the factory, its connected repositories, agents, automations, runners, shared defaults, and tool access. Teams review changes to the operating model as code.
- Models and harnesses - Each agent role can select a model and a supported harness. Teams can match a reasoning-focused model to specification, a coding harness to implementation, and a separate configuration to review.
- Skills and MCP servers - Skills encode reusable operating instructions. MCP servers give agents access to approved external tools and context. Factory-wide and role-specific resources keep common behavior consistent while preserving specialization.
- Environments and runners - Environments provide repositories, dependencies, startup configuration, and secrets. Runners determine the compute and operating system that execute the run, whether Warp-hosted or self-hosted.
- Integrations and automations - Integrations connect the factory to communication tools, issue trackers, and GitHub. Automations define the events or schedules that create work and the agent that receives it.
These layers are composable. A Slack request and a Linear issue can enter the same factory and use the same triage policy. Each dispatched role then receives its defined environment, model, and tools.
The outer improvement loop
Section titled “The outer improvement loop”The inner loop produces software and an execution record. The outer loop uses that record to improve the system that produced it.
Factory measurement includes run and pull request activity, costs, evaluations, and benchmark results. Teams use these signals to find repeated failures, compare model and harness configurations, and identify stages that need better instructions or tools. Evaluation results can also create new investigation work for the factory.
A team or agent can propose changes to instructions, skills, MCP access, models, environments, or other factory definitions. How the change reaches the factory depends on the definition source. GitHub-backed definitions can use pull request review and factory configuration checks before changes reach the production branch. Changes to a Warp-managed definition can synchronize directly. Teams should set review policy according to the definition source and the risk of the change.
Benchmarks help compare configurations, but they do not replace product judgment or guarantee that an automated change is correct.
The result is a feedback system:
- The factory executes work through the inner loop.
- Runs and outcomes produce evidence.
- Evaluations and benchmarks organize that evidence.
- Teams identify a concrete change to the factory.
- The updated definition governs later work items.
The factory definitions as code page explains the declarative model. See connect your factory for intake paths, Factory MCP for agent-to-factory exchange, and measure and improve for the outer loop.