diff --git a/src/content/docs/factories/factory-agents.mdx b/src/content/docs/factories/factory-agents.mdx
index ad7510bec..9b1c6a98a 100644
--- a/src/content/docs/factories/factory-agents.mdx
+++ b/src/content/docs/factories/factory-agents.mdx
@@ -11,7 +11,7 @@ Every factory has a **foreman**, the agent you talk to from the tool that sends
## The default agents
-Every factory gets a foreman, and you choose one to four other agents to go with it. These defaults are a starting point — you can [add custom agents and automations](#add-custom-agents-and-automations) for work they don't cover. The default agents' prompts, descriptions, and models are reproduced as files in [`00-warp-default-agents`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/00-warp-default-agents) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository.
+Every factory gets a foreman, and you choose one to four other agents to go with it. These defaults are a starting point; [add custom agents](#add-custom-agents) for work they don't cover. The default agents' prompts, descriptions, and models are reproduced as files in [`00-warp-default-agents`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/00-warp-default-agents) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository.
| Agent | What it does | What it produces |
| --- | --- | --- |
@@ -27,7 +27,7 @@ For the complete lifecycle, see [how Warp Factories work](/factories/how-factori
### Foreman
-The **foreman agent** runs the factory floor. It decides which agent a work item goes to next, hands the work over, and keeps the requester informed. It's the only default agent that talks to the requester directly. When another agent needs a human answer, the foreman asks the question and routes the answer back. For revisions and follow-ups, the foreman goes back to the same agent and continues its existing conversation instead of starting a new one, so no context is lost.
+The **foreman agent** runs the factory floor. It decides which agent a work item goes to next, hands the work over, and keeps the requester informed. It's the only default agent that talks to the requester directly. When another agent needs a human answer, the foreman asks the question and routes the answer back. For revisions and follow-ups, the foreman goes back to the same agent and continues its existing conversation instead of starting a new one.
When the work is done, the foreman presents the final pull request and its supporting evidence, then marks the work item complete. Complete means the work was handed to a human, not that the change was merged or deployed. Merging stays with your team.
@@ -55,7 +55,7 @@ Review independently examines the change for unmet requirements, broken conventi
## Built-in skills
-Every default agent comes with GitHub skills, and the foreman also comes with a Slack skill. The issue tracker you choose during setup adds to that baseline: choosing Linear or Jira gives the agents that tracker's skill and instructions. If you don't choose a tracker, the agents get only the baseline skills. Define custom procedures with [factory skills](/factories/factory-skills/) to extend what an agent can do beyond the built-in set.
+A new factory's definition includes skills for code quality, code review, and UI verification, plus one for each tool you connect: your code host, Slack or Microsoft Teams, and Linear or Jira. They live in the definition's `skills/` directory, so every agent can use them. See [factory skills](/factories/factory-skills/) for what each one covers and how to add your own.
## Configure agent behavior
@@ -73,13 +73,12 @@ Every default agent comes with GitHub skills, and the foreman also comes with a
An agent's settings page, where you configure its model, harness, runner, and host.
-You can also manage the factory as version-controlled code with [factory definition files](/factories/factory-as-code/) in a Git repository. A factory's settings live in one of two places:
-* A **Warp-managed factory** lets you edit everything, including harness, auth, and credential strategy, from the dashboard.
-* A **GitHub-backed factory** keeps those settings in its definition files. The dashboard shows them read-only, and you edit the files to make changes.
+Where you make these changes depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives):
-For more information about the two locations, see [where the definition lives](/factories/factory-as-code/#where-the-definition-lives).
+* **Warp-managed factory** - Edit everything, including harness, auth, and credential strategy, from the dashboard.
+* **GitHub-backed factory** - The settings live in the definition files. The dashboard shows them read-only, and you change them by editing the files.
-Factory setup doesn't choose models for you. To change the model an agent uses, edit that agent.
+Setup assigns each default agent a model suited to its role. To change it, edit the agent.
## Choose models and harnesses per agent
@@ -124,26 +123,21 @@ Change an agent's harness to Claude Code or Codex to run it with that provider's
With a Warp-managed factory, you can edit harness, auth, and model from the dashboard. A GitHub-backed factory sets them through [`agentDefaults.harness` or a per-agent `harness` override](/factories/factory-as-code/#agentdefaultsharness) in the definition files. For an example, see [`03-multi-harness`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/03-multi-harness).
-## Add custom agents and automations
+## Add custom agents
Add a custom agent for a role that needs separate instructions, configuration, and runs.
For a Warp-managed factory, open **Agents** in the [factory dashboard](/factories/factory-dashboard/), click **New**, then click **Custom agent**. For a GitHub-backed factory, add `agents//agent.md`. See the [`agent.md` configuration keys](/factories/factory-as-code/#agentsnameagentmd).
-Custom agents have no built-in skills. Add [factory skills](/factories/factory-skills/) based on who needs them:
+A custom agent gets the factory-wide skills under `skills/` but no role instructions of its own, so write its job into `agent.md`. For procedures only that agent needs, add a skill under `agents//skills/`. See [factory skills](/factories/factory-skills/).
-* **One agent** - Put the skill under `agents//skills/`.
-* **Every agent** - Put the skill under `skills/`.
+### How the foreman dispatches agents
-### Choose a configured factory agent
+The foreman starts the factory's other agents as child runs with the `run_agents` tool, selecting each one by its UID in `agent_run_configs[].agent_identity_uid`. A child run started this way inherits that agent's environment, runner, host, harness, and model unless the call overrides them; a child started without a factory agent's UID runs with no factory configuration, as in [multi-agent orchestration](/platform/orchestration/) from any Warp conversation. Keep that dispatch step if you rewrite the foreman's instructions or add a custom coordinating agent.
-Use `run_agents` when the foreman should give work to one of the agents configured in your factory. The foreman receives a list of those agents, with a unique ID (UID) for each one.
+### Automations
-Run the child remotely by setting the call's `remote` field, then copy the chosen agent's UID into `agent_run_configs[].agent_identity_uid`. Only use UIDs from the list, and select an agent for every child in the call. The `name` field only labels the child run; it doesn't choose the factory agent.
-
-Warp uses the UID to load that agent's configured environment, runner, host, harness, and model unless the call overrides them. To start a child without factory configuration, use [multi-agent orchestration](/platform/orchestration/) from any Warp conversation.
-
-Automations start a chosen agent on a [schedule](/factories/factory-as-code/#triggersschedule) or when an event fires. They're one more way for work to enter your factory; the foreman still coordinates whatever they start. For all the ways to route work into a factory, see [connect your factory](/factories/connect-your-factory/).
+[Automations](/factories/automations/) start a chosen agent on a [schedule](/factories/factory-as-code/#triggersschedule) or when an event arrives from a connected tool. They're one more way for work to enter the factory; the foreman still coordinates whatever they start. For every way to route work into a factory, see [connect your factory](/factories/connect-your-factory/).
## Human decision points and permissions
@@ -153,8 +147,12 @@ Automations start a chosen agent on a [schedule](/factories/factory-as-code/#tri
| Merging | Agents never merge; the foreman hands the finished pull request to a human | Your repository's permissions decide who can approve and merge |
| Runtime access | Each agent reaches only the repositories, secrets, and MCP servers in its configuration | Platform configuration and the permissions of the connected providers |
-The first two rows are conventions: they live in the foreman's instructions and your repository settings, and your team can change them. Access is different. What an agent can reach comes from its configuration and the permissions of the connected providers, never from its instructions — changing what an agent is told to do doesn't change what it's able to do.
+Instructions decide what an agent is told to do; configuration and provider permissions decide what it can reach. Enforce merge policy with branch protection and repository permissions, and enforce access with each agent's configuration.
-So enforce with the real controls: branch protection and repository permissions decide who merges, and each agent's configuration decides what it can reach.
+## Related pages
-Next, capture these choices in [factory definitions as code](/factories/factory-as-code/).
+* [How Warp Factories work](/factories/how-factories-work/) - The stages a work item moves through and where people decide.
+* [Factory skills](/factories/factory-skills/) - The built-in skills every agent starts with, and how to add your own.
+* [Factory definition syntax](/factories/factory-as-code/) - Every `agent.md` key, including per-agent model, harness, and runner overrides.
+* [Harnesses for cloud agents](/platform/harnesses/) - What each harness supports and how to authenticate it.
+* [Connect your factory](/factories/connect-your-factory/) - The sources that send work to the foreman.
diff --git a/src/content/docs/factories/factory-skills.mdx b/src/content/docs/factories/factory-skills.mdx
index e279b6fb7..5965538d5 100644
--- a/src/content/docs/factories/factory-skills.mdx
+++ b/src/content/docs/factories/factory-skills.mdx
@@ -7,19 +7,28 @@ sidebar:
label: "Factory skills"
---
-A skill tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override [default agents](/factories/factory-agents/), without editing their prompts directly.
+A skill tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override the [default agents](/factories/factory-agents/) without editing their prompts directly.
-## Skill sources in a factory
+A factory's agents draw on three kinds of skills:
-A factory run can use skills from three sources:
+* **Built-in skills** - `SKILL.md` files Warp adds to the factory definition for the code host, chat tool, and issue tracker you connect, plus shared code-quality and review procedures.
+* **Custom skills** - `SKILL.md` files your team adds to the definition, available to every agent or scoped to one.
+* **Bundled Warp skills** - Skills that ship with the Warp Agent harness, such as `factory-files` for editing definitions and `factory-mcp` for working with a factory through [Factory MCP](/factories/factory-mcp/).
-* **Factory role and integration skills** - Baseline procedures that come from the default agent roles and integrations you configure, such as GitHub, Slack, Linear, or Jira.
-* **Warp-provided platform-bundled skills** - Product capabilities that Warp provides, such as `oz-platform`, `factory-files`, and `factory-mcp`.
-* **Custom file-based factory skills** - Team-owned `SKILL.md` files in the factory definition, available to every agent or scoped to one agent.
+## Built-in skills
-## Custom file-based factory skills
+When you create a factory, Warp writes a set of skills into the definition's `skills/` directory so the agents know how to work with your tools before you write anything custom:
-A custom skill is a directory containing a `SKILL.md`. It's part of the factory's [definition](/factories/factory-as-code/), not an agent's settings. Where you place the directory decides who can use it:
+* **Code quality, code review, and UI verification** - Every factory gets these three: the standard a code change is held to, how to review a change and write up findings, and how to capture visual proof of a UI change with [Computer Use](/agents/capabilities/computer-use/).
+* **Code host** - The skill for your connected code host: `github`, `gitlab`, or `azuredevops`. It covers branches, commits, draft pull requests, review comments, and CI status.
+* **Chat tool** - A `slack` or `microsoft-teams` skill when you connect that tool. The foreman's instructions tell it to use the skill, since it's the agent that replies in threads.
+* **Issue tracker** - A `linear` or `jira` skill when you connect that tracker. Connecting a tracker later adds its skill then.
+
+Because these live under `skills/`, every agent in the factory can use them, including custom agents. They're ordinary files: read them in the **Factory definition** tab of a Warp-managed factory or in the repository of a GitHub-backed one, and edit them the same way you edit any other skill. Anything you add alongside them extends the set rather than replacing it.
+
+## Custom skills
+
+A custom skill is a directory containing a `SKILL.md`. It's part of the factory's [definition](/factories/factory-as-code/), not an agent's settings, and where you place the directory decides who can use it:
```text
skills/
@@ -33,79 +42,41 @@ agents/
```
* **`skills//SKILL.md`** - Available to every agent in the factory. Use this for procedures that apply regardless of role, such as your repository's coding conventions or a shared escalation policy.
-* **`agents//skills//SKILL.md`** - Available only to that agent. Use this for procedures specific to one role, such as how the review agent should apply your security checklist.
-
-Both forms use the same `SKILL.md` format as skills anywhere else in Warp. See [Skills](/agents/capabilities/skills/) for the file format, front matter, and argument syntax.
-
-## Factory role and integration skills
-
-Every default agent starts with a baseline of role and integration skills so the factory works immediately after setup, before you write anything custom:
-
-* **GitHub** - Every default agent gets a GitHub skill, covering how to read issues, open pull requests, and follow your repository's conventions.
-* **Slack** - The foreman also gets a Slack skill, since it's the agent that replies in threads and DMs.
-* **Issue tracker** - The tracker you choose during setup, Linear or Jira, adds that tracker's skill and instructions to the agents that use it. If you don't connect a tracker, agents keep only the GitHub and Slack skills.
-
-These baseline skills aren't files in your definition; they come from the agent roles and integrations you choose. Anything you add under `skills/` or `agents//skills/` extends this baseline rather than replacing it.
-
-## Warp-provided platform-bundled skills
+* **`agents//skills//SKILL.md`** - Available only to that agent. Use this for procedures specific to one role, such as how the review agent applies your security checklist.
-Platform-bundled skills are separate from factory role and integration skills. They provide Warp capabilities such as operating cloud agents with `oz-platform`, editing factory definitions with `factory-files`, and sending work through Factory MCP with `factory-mcp`.
+Both forms use the same `SKILL.md` format as skills anywhere else in Warp. See [Skills](/agents/capabilities/skills/) for the file format, frontmatter, and argument syntax.
-Warp provides these stable bundled-skill IDs:
+### When to add a custom skill
-| Bundled skill ID | Purpose |
-| --- | --- |
-| `add-mcp-server` | Add an MCP server to Warp configuration. |
-| `change-keybinding` | Change or remove Warp keyboard shortcuts. |
-| `claude-api` | Build and maintain applications that use the Anthropic SDK. |
-| `create-skill` | Create, improve, and evaluate skills. |
-| `create-tab-config` | Create a Warp tab configuration. |
-| `factory-files` | Create and validate file-based Warp factory definitions. |
-| `factory-mcp` | Send work to a factory and collaborate through Factory MCP. |
-| `modify-settings` | View or change Warp settings using the bundled settings schema. |
-| `oz-platform` | Run, configure, and inspect cloud agents through the API and CLI. |
-| `pr-comments` | Fetch GitHub pull request review comments for the current branch. |
-| `tab-configs` | Look up the tab configuration schema and validation rules. |
-| `tui-migrate-setup` | Migrate supported settings into the Warp Agent CLI. |
-| `update-tab-config` | Update an existing Warp tab configuration. |
-| `warpctrl` | Control and inspect a running Warp app with Warp Control. |
+Add a custom skill when an agent needs to do something the built-in set doesn't cover, such as:
-See [skill actions in conversation data](/factories/api-and-sdk/#skill-actions-in-conversation-data) for the API reference.
-
-## Attribute team-owned skill usage
-
-The [Conversation API](/api) returns skill loads as `read_skill` actions. Use the action's `input` to classify the skill:
-
-* **`input.bundled_skill_id` is present** - The action loaded a Warp-provided bundled reference. Exclude it when measuring usage of skills your team owns.
-* **Only `input.skill_path` is present** - A path alone doesn't identify the skill's owner. Count it as team-owned only when the path is under a skill root your team manages, such as `skills/` or `agents//skills/` in the factory definition.
-
-## When to add a custom skill
-
-Add a custom skill when a default agent needs to do something the built-in baseline doesn't cover, such as:
-
-* Enforcing a specific test, lint, or validation command before a change is considered complete.
+* Running a specific test, lint, or validation command before a change counts as complete.
* Following a runbook for a category of incident or request your triage agent sees repeatedly.
* Applying a security or compliance checklist during review that goes beyond general code quality.
-* Teaching a custom agent its job. Custom agents have no built-in skills.
+* Teaching a custom agent its job. Custom agents start with the factory-wide skills but no role instructions of their own.
-A skill changes what an agent knows how to do, not what it can reach. To scope access, configure the agent's [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/) — see [factory agents](/factories/factory-agents/#configure-agent-behavior) and [infrastructure and security](/factories/infrastructure-and-security/#credential-boundaries).
+A skill changes what an agent knows how to do, not what it can reach. To scope access, configure the agent's [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/). See [configure agent behavior](/factories/factory-agents/#configure-agent-behavior) and [credential boundaries](/factories/infrastructure-and-security/#credential-boundaries).
-## Add or edit a skill
+### Add or edit a skill
Where you edit a skill depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives):
-* **Warp-managed** - Add or edit `SKILL.md` files directly in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step.
-* **GitHub** - Add or edit the files in the connected definition repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks) that validate the rest of the definition apply to skill files.
+* **Warp-managed** - Add or edit `SKILL.md` files in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step.
+* **GitHub-backed** - Add or edit the files in the definition repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks) that validate the rest of the definition apply to skill files.
+
+For a factory-wide skill and a per-agent skill side by side, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository.
+
+## Bundled Warp skills
-For worked examples, including a factory-wide skill and a per-agent skill together, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository.
+Agents on the Warp Agent harness also carry Warp's bundled skills, which aren't files in your definition. The ones that matter for factory work are `factory-files`, which reads the definition schema and validates a definition tree, `factory-mcp`, which sends work to a factory and takes it back through Factory MCP, and `oz-platform`, which runs and inspects cloud agents through the API and CLI. In run data, a bundled skill load carries a `bundled_skill_id`; see [skill actions in conversation data](/factories/api-and-sdk/#skill-actions-in-conversation-data) for the full list and how to tell bundled loads apart from your own skills.
-## Skills and self-improvement
+## Skills and Self-improvement
-A factory can propose changes to a skill. When [Self-improvement](/factories/measure-and-improve/self-improvement/) is on for a Scorer and it flags a recurring failure, it can edit the responsible skill in a follow-up run, the same way it can edit application code. The change still arrives as a pull request for your team to review, whether that's through the factory dashboard or your Git host.
+A factory can propose changes to a skill. When [Self-improvement](/factories/measure-and-improve/self-improvement/) is on for a Scorer and that Scorer flags a recurring failure, the follow-up run can edit the responsible skill the same way it can edit application code. The change arrives as a pull request for your team to review, in the factory dashboard or on your Git host.
## Related pages
* [Factory agents](/factories/factory-agents/) - The agents that use a factory's skills, and how to configure each one.
-* [Definitions as code](/factories/factory-as-code/) - The full schema for `factory.yaml`, agents, automations, and runners alongside skills.
+* [Factory definition syntax](/factories/factory-as-code/) - The full schema for `factory.yaml`, agents, automations, and runners alongside skills.
* [Skills](/agents/capabilities/skills/) - The general skill file format, shared across Warp, cloud agents, and factories.
* [Measure and improve a factory](/factories/measure-and-improve/) - How Self-improvement turns repeated failures into skill and code changes.
diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx
index eb87c381c..372438085 100644
--- a/src/content/docs/factories/how-factories-work.mdx
+++ b/src/content/docs/factories/how-factories-work.mdx
@@ -7,24 +7,22 @@ sidebar:
label: "How factories work"
---
-A factory is a fleet of agents wired to your software development lifecycle. It connects your repositories and tools to move requests through triage, specification, implementation, review, and verification, while people stay in control of key decisions. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle.
-
-Deciding which repositories belong in this factory is a separate question. See [sizing a factory](/factories/#sizing-a-factory) for that guidance.
+A factory is a team of cloud agents attached to a set of repositories. You talk to one of them, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, each of which owns one part of the software development lifecycle, and people make the key decisions along the way.
A **work item** is a single request the factory acts on, such as an issue, support request, pull request, or Factory MCP task. It keeps its identity from intake to handoff, however many agents contribute to it along the way.
-The diagram's components, from intake to improvement:
+The diagram, from intake to improvement:
-* **Work sources** - Work items arrive from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), from [custom webhooks](/factories/webhooks/) and [factory endpoints](/factories/factory-api/), from local coding agents through the [Factory MCP](/factories/factory-mcp/), or from direct runs and schedules.
-* **Automations** - [Automations](/factories/automations/) filter provider events and decide which agent handles them. Schedules fire them on a timer; direct requests go straight to the foreman.
-* **Foreman and stage agents** - The foreman holds one conversation per work item and dispatches the Triage, Spec, Implement, and Review agents as the work needs them. See [factory agents](/factories/factory-agents/) and the stages below.
-* **Human handoff** - The factory opens a pull request with evidence, updates the original work item, and you review and merge.
-* **Factory definition** - Version-controlled agents, automations, runners, scorers, skills, and webhooks define the factory, either Warp-managed or in a GitHub repository your team owns. See [definitions as code](/factories/factory-as-code/).
-* **Execution** - Every stage runs as a cloud agent run on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, with the workspace from the factory's repositories and each stage's configured model and [harness](/platform/harnesses/).
-* **Factory dashboard** - Metrics, work items by stage, and runs and costs. See the [factory dashboard](/factories/factory-dashboard/).
-* **Measure and improve** - [Scorers](/factories/measure-and-improve/) classify completed runs, benchmarks compare configurations, and self-improvement turns repeat failures into follow-up pull requests for your review.
+* **Work sources** - [Slack](/factories/integrations/slack/), [Microsoft Teams](/factories/integrations/teams/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), [Jira](/factories/integrations/jira/), [custom webhooks](/factories/webhooks/), [factory endpoints](/factories/factory-api/), the [Factory MCP](/factories/factory-mcp/), direct runs, and schedules.
+* **Automations** - [Automations](/factories/automations/) filter provider events and schedules and decide which agent handles them. Direct requests go straight to the foreman.
+* **Foreman and stage agents** - The foreman holds one conversation per work item and dispatches the triage, spec, implement, and review agents as the work needs them. See [factory agents](/factories/factory-agents/).
+* **Human handoff** - The factory opens a pull request with evidence and updates the original work item. You review and merge.
+* **Factory definition** - Version-controlled agents, automations, runners, scorers, skills, and webhooks, either Warp-managed or in a GitHub repository your team owns. See [definitions as code](/factories/factory-as-code/).
+* **Execution** - Every stage is a cloud agent run on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, using the factory's repositories and each stage's configured model and [harness](/platform/harnesses/).
+* **Factory dashboard** - Metrics, work items by stage, runs, and costs. See the [factory dashboard](/factories/factory-dashboard/).
+* **Measure and improve** - [Scorers](/factories/measure-and-improve/) classify completed runs, benchmarks compare configurations, and Self-improvement turns repeated failures into pull requests for your review.
## How a work item moves through the factory
@@ -64,7 +62,7 @@ Stages and agents are named separately, so the spec agent works the Planning sta
## Where your team stays in charge
-A factory is built to pause when there is a decision that needs to be made by a person. By default, that's three places:
+A factory pauses when a person needs to decide. By default, that's three places:
* **Approving the spec** - When work goes through the Planning stage, the Building stage waits until a person signs off on the plan.
* **Answering questions** - When requirements are unclear or a review finding is ambiguous, the foreman asks instead of guessing.
@@ -74,8 +72,14 @@ The first two are workflow policy, written into the foreman's instructions; edit
## How the factory improves itself
-Your factory is self-improving, and you define what "better" means. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, and [Self-improvement](/factories/measure-and-improve/self-improvement/) groups the failures they flag into follow-up runs that propose fixes — to the application code or to the factory's own definition. Every proposal arrives as a change for your review; nothing is adopted on its own.
+[Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, and [Self-improvement](/factories/measure-and-improve/self-improvement/) groups the failures they flag into follow-up runs that propose fixes to the application code or to the factory's own definition. Every proposal arrives as a pull request for your review; nothing is adopted on its own.
The factory's definition is open to the same loop. Anyone on the team, or an agent, can propose changes to its instructions, skills, models, or other [definition files](/factories/factory-as-code/), and definitions stored in GitHub go through pull request review and [configuration checks](/factories/factory-as-code/#pull-request-checks) before a change reaches the production branch.
-See [measure and improve](/factories/measure-and-improve/) for the evaluation workflow, or [build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent/) to apply the same pattern to a standalone agent.
+## Related pages
+
+* [Sizing a factory](/factories/#sizing-a-factory) - Which repositories belong in one factory.
+* [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure it.
+* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory.
+* [Measure and improve](/factories/measure-and-improve/) - Scorers, benchmarks, and Self-improvement.
+* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent/) - Apply the same loop to a standalone agent.
diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx
index d0945518f..23b57f4ba 100644
--- a/src/content/docs/factories/index.mdx
+++ b/src/content/docs/factories/index.mdx
@@ -1,8 +1,8 @@
---
title: Warp Factories overview
description: >-
- Warp Factories is open infrastructure for building internal software
- factories as code, from triage to implementation, review, and monitoring.
+ Warp Factories turns issues, tickets, and Slack requests into reviewed pull
+ requests with teams of cloud agents, while people approve specs and merges.
sidebar:
label: "Overview"
---
@@ -10,7 +10,7 @@ import { VARS } from '@data/vars';
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
import VideoEmbed from '@components/VideoEmbed.astro';
-A factory is a group of agents that shares repositories and delivery policy. Its foreman accepts work from connected tools, dispatches the right agents, and returns the result to the source.
+A factory is a team of cloud agents attached to a set of repositories. It takes work from Slack, GitHub, Linear, or Jira through triage, spec, implementation, and review, and returns a pull request where the work started.
+## What a factory does
+
+A coordinating agent called the foreman takes each request, decides which stages it needs, and dispatches the triage, spec, implement, and review agents in turn. The result comes back where the work started, usually as a pull request. For example, a factory can work through a backlog of issues, fix defects reported in a support channel, or review incoming pull requests across several repositories.
+
+People stay in the loop at the points that matter: approving a spec, answering the foreman's questions, and merging.
+
-## What is a software factory?
+
+
+The software factory loop. The default agents cover triage through review.
+
-Each request becomes a work item, such as an issue, ticket, or triggered task. Specialized agents can triage it, write a specification, implement the change, and review the result.
+## The parts of a factory
-Each factory applies a single policy across its work sources, so deploy separate factories for repository groups that need different policies.
+### Work items
-### Sizing a factory
+A work item is one request the factory acts on: an issue, a support thread, a pull request, or a scheduled job. It keeps its source context from intake to handoff, however many agents contribute along the way.
-Size factories by product surface, not by workflow. Group the repositories that ship together into one factory. For example:
+### Foreman and factory agents
-* One factory for your main application
-* One factory for your marketing site
-* One factory for your data pipelines
+Every factory has one foreman, the agent you talk to. It decides which agent a work item goes to next, asks you when it needs a decision, and hands back the finished pull request. Behind it are the default triage, spec, implement, and review agents; add custom agents for work they don't cover. Each agent can run on its own model and harness, including the Warp Agent, Claude Code, and Codex. See [factory agents](/factories/factory-agents/).
-Don't split those same repositories across multiple factories by team or task (frontend vs. platform, for example). Add [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/) to specialize instead.
+Setup gives the foreman the same handle as the factory, so `payments` is the factory and `@payments` reaches its foreman from Slack or Linear. See [Foreman name](/factories/factory-agents/#foreman-name).
-
-
-The general software factory loop. Warp Factories' default agents cover triage through review; add custom agents for the rest.
-
+### Stages and checkpoints
-## Who benefits from Warp Factories
+The foreman moves a work item through the Triage, Planning, Building, and Reviewing stages, skipping the ones a well-defined request doesn't need and sending work back when review finds problems. Spec approval and the foreman's questions are written into its instructions, which your team can edit. Merging is enforced by your repository's branch protection. See [how Warp Factories work](/factories/how-factories-work/).
-Warp Factories is for engineering teams with repeatable work that extends beyond one coding session:
+### Factory definition
-* Process a backlog of issues with a consistent triage and delivery policy.
-* Fix defects reported through support channels.
-* Review incoming pull requests or maintain services across repositories.
+A factory's repositories, agents, automations, runners, skills, and MCP servers are declared in definition files, either managed by Warp or stored in a GitHub repository your team owns. Changes to a GitHub-backed factory go through pull request review like any other code. See [definitions as code](/factories/factory-as-code/).
-## What you get with Warp Factories
+### Work sources
-* **Coordinated specialist agents** - A team of [factory agents](/factories/factory-agents/) handles each work item. A coordinating foreman routes it through the triage, spec, implement, and review agents, skipping stages that don't apply. You can add custom agents and automations to handle work the defaults don't cover.
-* **Definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, [skills](/factories/factory-skills/), and MCP servers, so factory changes get the same review, history, and rollback as code changes.
-* **Code forges and work sources** - Connect [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), or [another code forge](/factories/code-forges/other-code-forges/) to the repository your factory works in. Route work from [Slack](/factories/integrations/slack/), [Linear](/factories/integrations/linear/), [Jira](/factories/integrations/jira/), [custom webhooks](/factories/webhooks/), direct runs, or schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients.
-* **Model and harness choice** - Each agent can use a different model and [supported harness](/platform/harnesses/), including the Warp Agent, Claude Code, and Codex.
-* **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs, [Benchmarks](/factories/benchmarks/) compare fixed tasks across configurations, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into follow-up work the factory proposes for review.
-* **Infrastructure control** - Choose Warp-hosted execution, or use managed self-hosted execution on an eligible Enterprise plan. The [infrastructure and security](/factories/infrastructure-and-security/) page compares execution models and links to the self-hosting setup path, as well as available inference and credential controls.
+Connect [Slack](/factories/integrations/slack/), [Microsoft Teams](/factories/integrations/teams/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), and the factory posts results back in the same thread, issue, or pull request. [Custom webhooks](/factories/webhooks/) and [factory endpoints](/factories/factory-api/) cover other systems, schedules start recurring work, and the [Factory MCP](/factories/factory-mcp/) lets a local coding agent hand work to a factory and take it back. See [connect your factory](/factories/connect-your-factory/).
-## How Warp Factories fits into Warp
+### Execution
-Warp Factories builds on the same agent infrastructure used across Warp. Every factory agent produces a standard [cloud agent run](/platform/), so the same APIs, runners, models, security controls, and observability apply.
+Every agent run in a factory is an ordinary [cloud agent run](/platform/) on the {VARS.WARP_AUTOMATION_PLATFORM}. Runs execute on Warp-hosted compute by default; Enterprise teams can keep checkout and execution on their own infrastructure with [managed self-hosting](/factories/self-hosting/). See [infrastructure and security](/factories/infrastructure-and-security/) for runners, inference, and credential boundaries.
-| Product | Role |
-| --- | --- |
-| **Warp** | The interactive development experience for local work with agents and code review. |
-| **Warp Agent** | The built-in agent harness that can power an individual factory agent. |
-| **Warp Factories** | Multi-agent workflows for software development. |
+### Measurement
-## Key terms
+The [factory dashboard](/factories/factory-dashboard/) shows work items by stage, runs, and cost per pull request. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, [benchmarks](/factories/benchmarks/) compare models, harnesses, and runners on the same tasks, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into pull requests for your review. See [measure and improve](/factories/measure-and-improve/).
-Setup gives a factory and its foreman the same name by default, so it's easy to mistake one for the other. Here's how the terms differ:
+## Sizing a factory
-* **factory** - The repositories, delivery policy, agents, and connected tools that handle a related set of work. It is distinct from Warp Factories, the product, and from the foreman, its coordinating agent.
-* **foreman** - The coordinating agent inside a factory, and the only one you talk to. It dispatches the other [factory agents](/factories/factory-agents/) and reports back. Every factory has exactly one.
-* **Foreman name** - The handle your team @-mentions in Slack and Linear to reach the foreman. Setup copies it from the factory's name, so the two usually match even though they're different things. See [Foreman name](/factories/factory-agents/#foreman-name).
+Group the repositories that ship together into one factory, and keep separate products in separate factories. For example:
+
+* One factory for your main application
+* One factory for your marketing site
+* One factory for your data pipelines
-```mermaid
-flowchart LR
- subgraph Factory["One factory"]
- Foreman["Foreman"] --> Agents["Triage, spec, implement, and review agents"]
- end
- Slack["Slack or Linear"] -->|"@handle"| Foreman
-```
+Don't split the same repositories across factories by team or task, such as frontend and platform. Add [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/) to specialize instead.
## Related pages
-* [**Set up a factory**](/factories/quickstart/) - Create a factory and send its first work item.
-* [**Understand the execution model**](/factories/how-factories-work/) - See how the foreman coordinates stages, runs, and human decisions.
-* [**Meet the factory agents**](/factories/factory-agents/) - See what each agent does and how to configure its model, harness, and instructions.
-* **Adapt the system** - [Define the factory as code](/factories/factory-as-code/) and [connect its work sources](/factories/connect-your-factory/), or start from a working definition in [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples).
+* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item.
+* [How Warp Factories work](/factories/how-factories-work/) - The work-item lifecycle, stage by stage.
+* [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure its model and harness.
+* [Definitions as code](/factories/factory-as-code/) - The definition file format, with working examples in [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples).
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index e3695b83f..4f6eed92c 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -31,7 +31,7 @@ The {VARS.WARP_AUTOMATION_PLATFORM} runs cloud agents from triggers, schedules,
## Warp Factories
-A factory turns incoming engineering work into a repeatable, multi-stage workflow with specialized agents, review points, and measurable outcomes.
+A factory is a team of cloud agents attached to a set of repositories. It takes work from Slack, GitHub, Linear, or Jira through triage, spec, implementation, and review, and returns a pull request where the work started.
* [Warp Factories overview](/factories/) - Learn how a factory receives, routes, and tracks work.
* [Factory quickstart](/factories/quickstart/) - Create a factory and send it its first work item.
diff --git a/src/content/docs/platform/orchestration/index.mdx b/src/content/docs/platform/orchestration/index.mdx
index 65e1a3791..6c3582562 100644
--- a/src/content/docs/platform/orchestration/index.mdx
+++ b/src/content/docs/platform/orchestration/index.mdx
@@ -43,7 +43,7 @@ An ad hoc child's prompt comes from the parent at spawn time. The model, harness
Use a [skill](/agents/capabilities/skills/) for reusable instructions. A local child discovers the project and home-directory skills in scope from its working directory. For cloud children, the parent attaches skills from a repository in the [environment](/platform/environments/).
-For named agents with standing configuration, use [Warp Factories](/factories/). A factory's foreman can dispatch its [factory agents](/factories/factory-agents/#choose-a-configured-factory-agent).
+For named agents with standing configuration, use [Warp Factories](/factories/). A factory's foreman can dispatch its [factory agents](/factories/factory-agents/#how-the-foreman-dispatches-agents).
## Run state transitions