From 34eef1a3fd4e76340b6bdbd83dacc28ea08b1664 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 15 Aug 2026 16:46:02 -0700 Subject: [PATCH 1/8] docs(factories): add quickstart Co-Authored-By: Warp Co-Authored-By: Warp Agent --- src/content/docs/factories/quickstart.mdx | 113 ++++++++++++++++++++-- 1 file changed, 103 insertions(+), 10 deletions(-) diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 13312a88..3d79e02c 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -1,19 +1,112 @@ --- title: Warp Factories quickstart description: >- - Create a Warp Factory, connect a repo, and trigger your first automated - work item in a few minutes. + Set up a factory, connect GitHub, and submit your first work item in about + 10 minutes. sidebar: label: "Quickstart" --- +import { Steps } from '@astrojs/starlight/components'; -[STUB — pending content from HYC/content team for the 8/18 closed-beta soft launch. Owner: HYC. +Set up a factory, connect its repositories, and submit a first work item in about 10 minutes. -Follow the quickstart template (`.agents/templates/quickstart.md`). Cover: -1. Create a Factory -2. Connect a repo -3. Configure the default agents (triage, spec, implement, review) -4. Trigger work (e.g. via Slack, Linear, GitHub, or the Factory MCP) -5. View / interact with the run in the control room web app +## Prerequisites -Keep prerequisites minimal and link out to How Factories work / Configure your Factory / Connect your Factory for depth rather than inlining it here.] +* **Warp team membership** - Join the [Warp team](../knowledge-and-collaboration/teams) that will own the factory. Ask a team admin to complete connections when your role does not include the required permissions. +* **Factory agent capacity** - A factory starts with 2–5 agents: the fixed Foreman and 1–4 selected subagents. If setup reports an agent limit, contact your workspace admin or Warp to confirm that the team has the required entitlement. +* **GitHub repository access** - Choose at least one repository for the factory. You need permission to authorize or install the GitHub connection, or help from a GitHub organization owner. Review the [GitHub integration requirements](../platform/integrations/github) if your organization restricts app installations. + +## Set up a factory and submit work + + + +1. #### Select a plan or credits + + If your team already has an active plan with available credits, setup skips this step. Otherwise, setup opens **Select a Warp Plan**, where you subscribe to a plan or buy credits for the team. A factory needs available credits to run its agents. + + **Expected outcome:** The team has an active plan with available credits, and setup advances to the code host. + +2. #### Connect GitHub + + In the Warp Factories web app, find **Factories** in the sidebar and click **Create factory**. Select the Warp team that will own the factory, then complete the GitHub authorization or installation flow. + + If GitHub requires organization approval, ask an organization owner to approve the installation and repository access. + + **Expected outcome:** Setup confirms the code-host connection and advances to repository selection. + +3. #### Select repositories + + Select one or more repositories. Start with a focused set so the factory receives only the code context needed for its work. Every agent in the roster uses the same selected repositories. + + Warp provisions a default execution environment for this repository set. See [cloud agent environments](../platform/environments) for details about toolchains, setup commands, and runtime configuration. + + **Expected outcome:** The selected repositories appear in setup. + +4. #### Name the factory + + Enter a name and the required alias. Use a name that identifies the product, service, or repository group, such as `Payments services`, and a short alias your team will recognize. + + **Expected outcome:** Setup accepts both identity fields and advances to communication settings. + +5. #### Optionally connect Slack + + Connect Slack if teammates will submit work from Slack threads. Complete the workspace authorization and return to setup. Otherwise, continue without Slack and connect it later. + + **Expected outcome:** Setup records the Slack connection or advances without one. + +6. #### Choose the subagent flow + + Foreman is always included and cannot be removed. Select at least one of **Triage**, **Specification**, **Implementation**, and **Review**. Each subagent is individually selectable, so the initial roster contains 2–5 agents. Select **Implementation** for the coding task in this quickstart. + + Choose the roles that match the factory's default workflow. The foreman routes work only through applicable roles rather than enforcing every stage. See [factory agents](./factory-agents) for role details. + + **Expected outcome:** Setup shows Foreman and 1–4 selected subagents. + +7. #### Optionally connect Linear and create the factory + + Connect Linear on the tracker step if your team uses it for factory work. A tracker is optional, so you can continue without one. + + Advancing from the final configurable step, which is the tracker step when Warp shows it, creates the factory. Creating the factory does not start any work; agents run only after you submit a request or a connected integration triggers one. + + :::caution + If creation stops at an agent limit, contact your workspace admin or Warp to confirm capacity for the selected 2–5-agent roster. + ::: + + **Expected outcome:** Warp creates the factory and shows a post-creation startup screen that links to the factory control room. + +8. #### Submit the first work item + + Open the factory's **Runs** page and submit a small request with one repository, a narrow scope, a verifiable outcome, and an explicit validation command. + + ```text title="First work item" + In `OWNER/REPO`, update `PATH` so it states `EXPECTED_CHANGE`. Keep the change limited to that file, run `VALIDATION_COMMAND`, and open a pull request. If the repository contradicts the request, stop and report what you found. + ``` + + Replace `OWNER/REPO` with a selected repository, `PATH` with the file to change, `EXPECTED_CHANGE` with the required result, and `VALIDATION_COMMAND` with a command defined by the repository. + + **Expected outcome:** A top-level foreman run appears on **Runs** with the request as context. + +9. #### Verify or stop the work item + + Confirm the request at two levels: + + * **Runs** - Inspect the foreman run and its status. Child runs appear as the foreman dispatches selected subagents. + * **Activity** - Find the work item in its current stage and inspect its event history and any pull request artifacts. + + Use **Stop task** to stop active work when necessary. The control room does not provide controls to approve or steer running agents. By default, specifications and pull requests return to people for review when those steps apply. Use your team's existing process to review the work and decide whether to merge. + + **Expected outcome:** The current run and work-item stage are visible. This does not mean that a pull request is ready or that code has been merged. + + + +## Next steps + +* [**Connect your factory**](./connect-your-factory) - Configure Slack, Linear, and other intake paths. +* [**Factory MCP**](./factory-mcp) - Exchange work from a compatible coding agent or MCP client. +* [**How Warp Factories work**](./how-factories-work) - Follow the work-item lifecycle and default human decision points. + +## Troubleshooting + +### A GitHub repository does not appear + +Confirm that the GitHub installation includes the repository and uses the intended organization. Ask a GitHub organization owner or Warp team admin to update the connection when you do not have permission. From fb18915b315d9b4079de9ec77af22c4ff3c1e301 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sun, 16 Aug 2026 01:22:45 -0400 Subject: [PATCH 2/8] docs(factories): rework quickstart into a reader-first onboarding flow (#539) Editorial rework of the Factories quickstart per senior copy review: - Open with what a factory is and why, not a repeat of the description - Step 1 starts at the real entry point (platform.warp.dev, + next to Factories) instead of the conditional plan gate - Collapse nine wizard-screen steps into two ~5-minute sections with six steps in true wizard order - Drop the nine formulaic 'Expected outcome' blocks - Replace the five-placeholder work-item template with one concrete example request - End on the win (review and merge the PR); move Stop task and the agent-limit failure mode to Troubleshooting - Correct roster labels against current source: Triage/Spec/Code/Review toggles (not Specification/Implementation), all enabled by default - Explain the alias (the @-mention handle) from the field's own hint - Use FACTORY_WEB_APP vars, root-relative links, template-format troubleshooting entries Verified against warp-server client/packages/factory source. Co-authored-by: Warp Agent --- src/content/docs/factories/quickstart.mdx | 107 ++++++++++------------ 1 file changed, 46 insertions(+), 61 deletions(-) diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 3d79e02c..03bb3392 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -7,106 +7,91 @@ sidebar: label: "Quickstart" --- import { Steps } from '@astrojs/starlight/components'; +import { VARS } from '@data/vars'; -Set up a factory, connect its repositories, and submit a first work item in about 10 minutes. +A factory is a team of cloud agents — a foreman you talk to, plus the subagents it dispatches — that turns incoming requests into pull requests for your team to review. In this quickstart you create a factory, connect a GitHub repository, and take one small work item from prompt to pull request in about 10 minutes. ## Prerequisites -* **Warp team membership** - Join the [Warp team](../knowledge-and-collaboration/teams) that will own the factory. Ask a team admin to complete connections when your role does not include the required permissions. -* **Factory agent capacity** - A factory starts with 2–5 agents: the fixed Foreman and 1–4 selected subagents. If setup reports an agent limit, contact your workspace admin or Warp to confirm that the team has the required entitlement. -* **GitHub repository access** - Choose at least one repository for the factory. You need permission to authorize or install the GitHub connection, or help from a GitHub organization owner. Review the [GitHub integration requirements](../platform/integrations/github) if your organization restricts app installations. +* **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/), and its agents consume the team's credits. If the team has no active plan, setup asks you to select one. +* **GitHub repository access** - You authorize GitHub and choose repositories during setup. If your organization restricts app installations, ask a GitHub organization owner to approve the connection. See the [GitHub integration](/platform/integrations/github/) for details. -## Set up a factory and submit work +## Create your factory - - -1. #### Select a plan or credits - - If your team already has an active plan with available credits, setup skips this step. Otherwise, setup opens **Select a Warp Plan**, where you subscribe to a plan or buy credits for the team. A factory needs available credits to run its agents. - - **Expected outcome:** The team has an active plan with available credits, and setup advances to the code host. - -2. #### Connect GitHub - - In the Warp Factories web app, find **Factories** in the sidebar and click **Create factory**. Select the Warp team that will own the factory, then complete the GitHub authorization or installation flow. - - If GitHub requires organization approval, ask an organization owner to approve the installation and repository access. - - **Expected outcome:** Setup confirms the code-host connection and advances to repository selection. +_~5 minutes_ -3. #### Select repositories - - Select one or more repositories. Start with a focused set so the factory receives only the code context needed for its work. Every agent in the roster uses the same selected repositories. - - Warp provisions a default execution environment for this repository set. See [cloud agent environments](../platform/environments) for details about toolchains, setup commands, and runtime configuration. + - **Expected outcome:** The selected repositories appear in setup. +1. #### Start a new factory -4. #### Name the factory + Open the {VARS.FACTORY_WEB_APP} at platform.warp.dev and sign in. In the sidebar, click **+** next to **Factories** to open the setup wizard. - Enter a name and the required alias. Use a name that identifies the product, service, or repository group, such as `Payments services`, and a short alias your team will recognize. + If your account has no team yet, the wizard first asks you to choose the team that will own the factory. When that team has no plan or credits, it opens **Select a Warp Plan**: a factory needs credits to run its agents. - **Expected outcome:** Setup accepts both identity fields and advances to communication settings. +2. #### Connect GitHub and select your repos -5. #### Optionally connect Slack + Click **I want to use repos from GitHub** and complete the GitHub authorization. Then choose the repositories the factory will work in and click **Add repos**. - Connect Slack if teammates will submit work from Slack threads. Complete the workspace authorization and return to setup. Otherwise, continue without Slack and connect it later. + Start with one or two repositories: every agent in the factory shares this repo set, so a focused set keeps their context tight. Warp provisions a default [environment](/platform/environments/) for the selected repos. - **Expected outcome:** Setup records the Slack connection or advances without one. +3. #### Name your factory -6. #### Choose the subagent flow + Enter a **Factory name**, such as `Payments services`. Warp derives a matching **Factory alias**, the handle teammates use to @-mention the factory from connected tools like Slack and Linear. Keep it short and recognizable. - Foreman is always included and cannot be removed. Select at least one of **Triage**, **Specification**, **Implementation**, and **Review**. Each subagent is individually selectable, so the initial roster contains 2–5 agents. Select **Implementation** for the coding task in this quickstart. + The next screen offers to connect Slack. This quickstart skips integrations, so click **Next**. You can connect them any time from [Connect your factory](/factories/connect-your-factory/). - Choose the roles that match the factory's default workflow. The foreman routes work only through applicable roles rather than enforcing every stage. See [factory agents](./factory-agents) for role details. +4. #### Choose your agents and create the factory - **Expected outcome:** Setup shows Foreman and 1–4 selected subagents. + The foreman leads every factory: it is the orchestration agent you interact with directly. Below it, toggle the subagents it can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Keep **Code** on so this quickstart's work item can end in a pull request. See [Factory agents](/factories/factory-agents/) for what each role does. -7. #### Optionally connect Linear and create the factory + Skip the issue tracker screen the same way as Slack: click **Next**, and Warp creates the factory. When the startup screen reports **Factory running!**, click **Go to dashboard**. - Connect Linear on the tracker step if your team uses it for factory work. A tracker is optional, so you can continue without one. + - Advancing from the final configurable step, which is the tracker step when Warp shows it, creates the factory. Creating the factory does not start any work; agents run only after you submit a request or a connected integration triggers one. +## Submit your first work item - :::caution - If creation stops at an agent limit, contact your workspace admin or Warp to confirm capacity for the selected 2–5-agent roster. - ::: +_~5 minutes_ - **Expected outcome:** Warp creates the factory and shows a post-creation startup screen that links to the factory control room. + -8. #### Submit the first work item +1. #### Start a run - Open the factory's **Runs** page and submit a small request with one repository, a narrow scope, a verifiable outcome, and an explicit validation command. + In the sidebar under your factory, open **Runs** and click **New**. Describe one small, verifiable change and submit it: - ```text title="First work item" - In `OWNER/REPO`, update `PATH` so it states `EXPECTED_CHANGE`. Keep the change limited to that file, run `VALIDATION_COMMAND`, and open a pull request. If the repository contradicts the request, stop and report what you found. + ```text title="Example first request" + Add a "Local development" section to README.md that summarizes the setup + steps from CONTRIBUTING.md. Keep the change to that one file, run the + repo's lint check, and open a pull request. ``` - Replace `OWNER/REPO` with a selected repository, `PATH` with the file to change, `EXPECTED_CHANGE` with the required result, and `VALIDATION_COMMAND` with a command defined by the repository. - - **Expected outcome:** A top-level foreman run appears on **Runs** with the request as context. + Adapt the pattern to your repository: name the file, the change you expect, and the command that verifies it. A narrow, explicit request makes the first run easy to judge. -9. #### Verify or stop the work item + The foreman picks up the request as a run on **Runs** and dispatches your subagents as child runs. - Confirm the request at two levels: +2. #### Watch the run and review the pull request - * **Runs** - Inspect the foreman run and its status. Child runs appear as the foreman dispatches selected subagents. - * **Activity** - Find the work item in its current stage and inspect its event history and any pull request artifacts. + Follow progress from two pages in your factory's sidebar: - Use **Stop task** to stop active work when necessary. The control room does not provide controls to approve or steer running agents. By default, specifications and pull requests return to people for review when those steps apply. Use your team's existing process to review the work and decide whether to merge. + * **Runs** - The foreman's run and the child runs it dispatches. + * **Activity** - The work item as it moves through its stages. Open it to see its event history and pull request artifacts. - **Expected outcome:** The current run and work-item stage are visible. This does not mean that a pull request is ready or that code has been merged. + When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it through your normal process: the factory drafts the change, and your team makes the call. ## Next steps -* [**Connect your factory**](./connect-your-factory) - Configure Slack, Linear, and other intake paths. -* [**Factory MCP**](./factory-mcp) - Exchange work from a compatible coding agent or MCP client. -* [**How Warp Factories work**](./how-factories-work) - Follow the work-item lifecycle and default human decision points. +* [**Connect your factory**](/factories/connect-your-factory/) - Route work in from Slack threads, Linear issues, and other intake paths. +* [**Factory MCP**](/factories/factory-mcp/) - Send work to the factory from a coding agent or MCP client. +* [**How Warp Factories work**](/factories/how-factories-work/) - The work-item lifecycle and where people stay in the loop. ## Troubleshooting -### A GitHub repository does not appear +**A GitHub repository doesn't appear in the picker**\ +The GitHub installation doesn't cover it. Confirm the installation includes the repository and the intended organization, or ask a GitHub organization owner or Warp team admin to update the connection. + +**Factory creation stops at an agent limit**\ +Your team's plan limits how many factory agents it can run. Ask a team admin to confirm the team's capacity, or contact Warp. -Confirm that the GitHub installation includes the repository and uses the intended organization. Ask a GitHub organization owner or Warp team admin to update the connection when you do not have permission. +**You need to stop a run**\ +Open **Activity**, select the work item, and click **Stop task** to stop its active run. From adfc702135cb80ad957c6d5ae0fb3b493ca9e188 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Sun, 16 Aug 2026 22:28:24 +0000 Subject: [PATCH 3/8] docs(factories): move quickstart troubleshooting to a dedicated page Per PR review, the quickstart should stay a clean onboarding critical path. Move the three troubleshooting entries to a new /factories/troubleshooting/ page (template-standard cause/fix format), add it to the Operate sidebar group, and link it from Next steps. Validated: astro check clean, 378 pages built, 0 broken internal links, style lint adds no new errors (glossary-candidate warnings only). Co-Authored-By: Warp --- src/content/docs/factories/quickstart.mdx | 12 +----- .../docs/factories/troubleshooting.mdx | 38 +++++++++++++++++++ src/sidebar.ts | 1 + 3 files changed, 40 insertions(+), 11 deletions(-) create mode 100644 src/content/docs/factories/troubleshooting.mdx diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 03bb3392..5321a08d 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -84,14 +84,4 @@ _~5 minutes_ * [**Connect your factory**](/factories/connect-your-factory/) - Route work in from Slack threads, Linear issues, and other intake paths. * [**Factory MCP**](/factories/factory-mcp/) - Send work to the factory from a coding agent or MCP client. * [**How Warp Factories work**](/factories/how-factories-work/) - The work-item lifecycle and where people stay in the loop. - -## Troubleshooting - -**A GitHub repository doesn't appear in the picker**\ -The GitHub installation doesn't cover it. Confirm the installation includes the repository and the intended organization, or ask a GitHub organization owner or Warp team admin to update the connection. - -**Factory creation stops at an agent limit**\ -Your team's plan limits how many factory agents it can run. Ask a team admin to confirm the team's capacity, or contact Warp. - -**You need to stop a run**\ -Open **Activity**, select the work item, and click **Stop task** to stop its active run. +* [**Troubleshooting**](/factories/troubleshooting/) - Fixes for common issues during setup and your first runs. diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx new file mode 100644 index 00000000..40834e4e --- /dev/null +++ b/src/content/docs/factories/troubleshooting.mdx @@ -0,0 +1,38 @@ +--- +title: Troubleshooting Warp Factories +description: >- + Fix missing GitHub repositories and agent limits during factory creation, + and stop an active factory run. +sidebar: + label: "Troubleshooting" +--- +import { VARS } from '@data/vars'; + +Solutions for common issues when creating and operating a factory in the {VARS.FACTORY_WEB_APP}. + +## A GitHub repository doesn't appear in the picker + +**Cause:** The GitHub installation doesn't cover the repository. + +**Fix:** + +1. Confirm the installation includes the repository and the intended organization. See the [GitHub integration](/platform/integrations/github/) for how the connection works. +2. If you can't update the installation yourself, ask a GitHub organization owner or a Warp team admin to update the connection. + +## Factory creation stops at an agent limit + +**Cause:** Your team's plan limits how many factory agents it can run. + +**Fix:** + +1. Ask a team admin to confirm the team's capacity. +2. If the team needs more agents, contact Warp. + +## You need to stop a run + +In the {VARS.FACTORY_WEB_APP}, open **Activity** in your factory's sidebar, select the work item, and click **Stop task** to stop its active run. + +## Related pages + +* [**Warp Factories quickstart**](/factories/quickstart/) - Create a factory and submit your first work item. +* [**Connect your factory**](/factories/connect-your-factory/) - Route work in from Slack threads, Linear issues, and other intake paths. diff --git a/src/sidebar.ts b/src/sidebar.ts index c4fcad8a..7239bc5d 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -414,6 +414,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ items: [ { slug: 'factories/control-room', label: 'Control room' }, { slug: 'factories/measure-and-improve', label: 'Measure and improve' }, + { slug: 'factories/troubleshooting', label: 'Troubleshooting' }, ], }, ], From 66a827596e1a43d9bb445d5a4189da48f084d90a Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 17 Aug 2026 15:13:31 -0600 Subject: [PATCH 4/8] docs(factories): address editorial review feedback on quickstart.mdx - Tighten the intro sentence's transition into the quickstart's goals. - Rewrite the two prerequisite bullets as direct, active-voice statements. - Restructure both Steps sections (Create your factory, Submit your first work item) so each numbered step covers one primary action or a small tightly related group, instead of multi-paragraph prose blocks that bundle several actions together. Move the 'no team yet' conditional into a callout, matching the pattern used in the cloud agents quickstart. Co-Authored-By: Warp --- src/content/docs/factories/quickstart.mdx | 58 ++++++++++++++++------- 1 file changed, 41 insertions(+), 17 deletions(-) diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 5321a08d..8acfb5fb 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -9,12 +9,12 @@ sidebar: import { Steps } from '@astrojs/starlight/components'; import { VARS } from '@data/vars'; -A factory is a team of cloud agents — a foreman you talk to, plus the subagents it dispatches — that turns incoming requests into pull requests for your team to review. In this quickstart you create a factory, connect a GitHub repository, and take one small work item from prompt to pull request in about 10 minutes. +A factory is a team of cloud agents — a foreman you talk to, plus the subagents it dispatches — that turns incoming requests into pull requests for your team to review. In this quickstart, you will create a factory, connect a GitHub repository, and take one small work item from prompt to pull request in about 10 minutes. ## Prerequisites -* **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/), and its agents consume the team's credits. If the team has no active plan, setup asks you to select one. -* **GitHub repository access** - You authorize GitHub and choose repositories during setup. If your organization restricts app installations, ask a GitHub organization owner to approve the connection. See the [GitHub integration](/platform/integrations/github/) for details. +* **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/). Factory agents consume the team's credits. If the team has no active plan, you will be asked to select one during setup. +* **GitHub repository access** - Authorize GitHub and choose repositories during setup. If your organization restricts app installations, ask a GitHub organization owner to approve the connection. See the [GitHub integration](/platform/integrations/github/) for details. ## Create your factory @@ -22,29 +22,47 @@ _~5 minutes_ -1. #### Start a new factory +1. #### Open the Warp Factories web app and sign in - Open the {VARS.FACTORY_WEB_APP} at platform.warp.dev and sign in. In the sidebar, click **+** next to **Factories** to open the setup wizard. + Go to the {VARS.FACTORY_WEB_APP} at platform.warp.dev and sign in. - If your account has no team yet, the wizard first asks you to choose the team that will own the factory. When that team has no plan or credits, it opens **Select a Warp Plan**: a factory needs credits to run its agents. +2. #### Start the setup wizard -2. #### Connect GitHub and select your repos + In the sidebar, next to **Factories**, click **+**. - Click **I want to use repos from GitHub** and complete the GitHub authorization. Then choose the repositories the factory will work in and click **Add repos**. + :::note + **No team yet?** The wizard first asks you to choose the team that will own the factory. If that team has no plan or credits, it opens **Select a Warp Plan** — a factory needs credits to run its agents. + ::: - Start with one or two repositories: every agent in the factory shares this repo set, so a focused set keeps their context tight. Warp provisions a default [environment](/platform/environments/) for the selected repos. +3. #### Connect GitHub -3. #### Name your factory + Click **I want to use repos from GitHub** and complete the GitHub authorization. + +4. #### Select your repositories + + Choose the repositories the factory will work in and click **Add repos**. Start with one or two repositories — every agent in the factory shares this repo set, so a focused set keeps their context tight. + + Warp provisions a default [environment](/platform/environments/) for the selected repos. + +5. #### Name your factory Enter a **Factory name**, such as `Payments services`. Warp derives a matching **Factory alias**, the handle teammates use to @-mention the factory from connected tools like Slack and Linear. Keep it short and recognizable. +6. #### Skip integrations for now + The next screen offers to connect Slack. This quickstart skips integrations, so click **Next**. You can connect them any time from [Connect your factory](/factories/connect-your-factory/). -4. #### Choose your agents and create the factory +7. #### Choose your agents + + The foreman leads every factory — it's the orchestration agent you interact with directly. Below it, toggle the subagents it can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Keep **Code** on so this quickstart's work item can end in a pull request. - The foreman leads every factory: it is the orchestration agent you interact with directly. Below it, toggle the subagents it can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Keep **Code** on so this quickstart's work item can end in a pull request. See [Factory agents](/factories/factory-agents/) for what each role does. + See [Factory agents](/factories/factory-agents/) for what each role does. - Skip the issue tracker screen the same way as Slack: click **Next**, and Warp creates the factory. When the startup screen reports **Factory running!**, click **Go to dashboard**. +8. #### Create the factory + + Skip the issue tracker screen the same way as Slack: click **Next**. Warp creates the factory. + + When the startup screen reports **Factory running!**, click **Go to dashboard**. @@ -54,9 +72,13 @@ _~5 minutes_ -1. #### Start a run +1. #### Open Runs and start a new run + + In the sidebar under your factory, open **Runs** and click **New**. - In the sidebar under your factory, open **Runs** and click **New**. Describe one small, verifiable change and submit it: +2. #### Describe your work item + + Describe one small, verifiable change and submit it: ```text title="Example first request" Add a "Local development" section to README.md that summarizes the setup @@ -68,14 +90,16 @@ _~5 minutes_ The foreman picks up the request as a run on **Runs** and dispatches your subagents as child runs. -2. #### Watch the run and review the pull request +3. #### Watch the run Follow progress from two pages in your factory's sidebar: * **Runs** - The foreman's run and the child runs it dispatches. * **Activity** - The work item as it moves through its stages. Open it to see its event history and pull request artifacts. - When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it through your normal process: the factory drafts the change, and your team makes the call. +4. #### Review and merge the pull request + + When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it through your normal process — the factory drafts the change, and your team makes the call. From c3a5e4c501f36a162045c2dbece5a69db82dbc15 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 17 Aug 2026 15:17:58 -0600 Subject: [PATCH 5/8] docs(factories): remove em dashes from instructional step text Per the style guide, em dashes are only acceptable in narrative/ conceptual text; procedural and instructional text should not use them. Fixes four instances introduced in the previous commit's restructured Steps content. Co-Authored-By: Warp --- src/content/docs/factories/quickstart.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 8acfb5fb..5d9ecf64 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -31,7 +31,7 @@ _~5 minutes_ In the sidebar, next to **Factories**, click **+**. :::note - **No team yet?** The wizard first asks you to choose the team that will own the factory. If that team has no plan or credits, it opens **Select a Warp Plan** — a factory needs credits to run its agents. + **No team yet?** The wizard first asks you to choose the team that will own the factory. If that team has no plan or credits, it opens **Select a Warp Plan**. A factory needs credits to run its agents. ::: 3. #### Connect GitHub @@ -40,7 +40,7 @@ _~5 minutes_ 4. #### Select your repositories - Choose the repositories the factory will work in and click **Add repos**. Start with one or two repositories — every agent in the factory shares this repo set, so a focused set keeps their context tight. + Choose the repositories the factory will work in and click **Add repos**. Start with one or two repositories. Every agent in the factory shares this repo set, so a focused set keeps their context tight. Warp provisions a default [environment](/platform/environments/) for the selected repos. @@ -54,7 +54,7 @@ _~5 minutes_ 7. #### Choose your agents - The foreman leads every factory — it's the orchestration agent you interact with directly. Below it, toggle the subagents it can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Keep **Code** on so this quickstart's work item can end in a pull request. + The foreman leads every factory. It's the orchestration agent you interact with directly. Below it, toggle the subagents it can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Keep **Code** on so this quickstart's work item can end in a pull request. See [Factory agents](/factories/factory-agents/) for what each role does. @@ -99,7 +99,7 @@ _~5 minutes_ 4. #### Review and merge the pull request - When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it through your normal process — the factory drafts the change, and your team makes the call. + When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it through your normal process. The factory drafts the change, and your team makes the call. From 0102e8fbc8d08c3dd481a7fd608b5826594b8a2c Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 17 Aug 2026 15:31:11 -0600 Subject: [PATCH 6/8] docs(factories): drop Steps component in favor of plain numbered lists The + per-step #### heading pattern isn't used anywhere in non-Guides procedural/quickstart content (see reference/cli/api-keys.mdx and platform/integrations/slack.mdx). Convert both procedures to plain numbered lists to match established convention and avoid the redundant, noisy heading-per-step alternative. Co-Authored-By: Warp --- src/content/docs/factories/quickstart.mdx | 62 +++++------------------ 1 file changed, 12 insertions(+), 50 deletions(-) diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 5d9ecf64..e4b854be 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -6,7 +6,6 @@ description: >- sidebar: label: "Quickstart" --- -import { Steps } from '@astrojs/starlight/components'; import { VARS } from '@data/vars'; A factory is a team of cloud agents — a foreman you talk to, plus the subagents it dispatches — that turns incoming requests into pull requests for your team to review. In this quickstart, you will create a factory, connect a GitHub repository, and take one small work item from prompt to pull request in about 10 minutes. @@ -20,65 +19,34 @@ A factory is a team of cloud agents — a foreman you talk to, plus the subagent _~5 minutes_ - - -1. #### Open the Warp Factories web app and sign in - - Go to the {VARS.FACTORY_WEB_APP} at platform.warp.dev and sign in. - -2. #### Start the setup wizard - - In the sidebar, next to **Factories**, click **+**. +1. Go to the {VARS.FACTORY_WEB_APP} at platform.warp.dev and sign in. +2. In the sidebar, next to **Factories**, click **+** to start the setup wizard. :::note **No team yet?** The wizard first asks you to choose the team that will own the factory. If that team has no plan or credits, it opens **Select a Warp Plan**. A factory needs credits to run its agents. ::: -3. #### Connect GitHub - - Click **I want to use repos from GitHub** and complete the GitHub authorization. - -4. #### Select your repositories - - Choose the repositories the factory will work in and click **Add repos**. Start with one or two repositories. Every agent in the factory shares this repo set, so a focused set keeps their context tight. +3. Click **I want to use repos from GitHub** and complete the GitHub authorization. +4. Choose the repositories the factory will work in and click **Add repos**. Start with one or two repositories. Every agent in the factory shares this repo set, so a focused set keeps their context tight. Warp provisions a default [environment](/platform/environments/) for the selected repos. -5. #### Name your factory - - Enter a **Factory name**, such as `Payments services`. Warp derives a matching **Factory alias**, the handle teammates use to @-mention the factory from connected tools like Slack and Linear. Keep it short and recognizable. - -6. #### Skip integrations for now - - The next screen offers to connect Slack. This quickstart skips integrations, so click **Next**. You can connect them any time from [Connect your factory](/factories/connect-your-factory/). - -7. #### Choose your agents - - The foreman leads every factory. It's the orchestration agent you interact with directly. Below it, toggle the subagents it can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Keep **Code** on so this quickstart's work item can end in a pull request. +5. Enter a **Factory name**, such as `Payments services`. Warp derives a matching **Factory alias**, the handle teammates use to @-mention the factory from connected tools like Slack and Linear. Keep it short and recognizable. +6. The next screen offers to connect Slack. This quickstart skips integrations, so click **Next**. You can connect them any time from [Connect your factory](/factories/connect-your-factory/). +7. The foreman leads every factory. It's the orchestration agent you interact with directly. Below it, toggle the subagents it can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Keep **Code** on so this quickstart's work item can end in a pull request. See [Factory agents](/factories/factory-agents/) for what each role does. -8. #### Create the factory - - Skip the issue tracker screen the same way as Slack: click **Next**. Warp creates the factory. +8. Skip the issue tracker screen the same way as Slack: click **Next**. Warp creates the factory. When the startup screen reports **Factory running!**, click **Go to dashboard**. - - ## Submit your first work item _~5 minutes_ - - -1. #### Open Runs and start a new run - - In the sidebar under your factory, open **Runs** and click **New**. - -2. #### Describe your work item - - Describe one small, verifiable change and submit it: +1. In the sidebar under your factory, open **Runs** and click **New**. +2. Describe one small, verifiable change and submit it: ```text title="Example first request" Add a "Local development" section to README.md that summarizes the setup @@ -90,18 +58,12 @@ _~5 minutes_ The foreman picks up the request as a run on **Runs** and dispatches your subagents as child runs. -3. #### Watch the run - - Follow progress from two pages in your factory's sidebar: +3. Follow progress from two pages in your factory's sidebar: * **Runs** - The foreman's run and the child runs it dispatches. * **Activity** - The work item as it moves through its stages. Open it to see its event history and pull request artifacts. -4. #### Review and merge the pull request - - When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it through your normal process. The factory drafts the change, and your team makes the call. - - +4. When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it through your normal process. The factory drafts the change, and your team makes the call. ## Next steps From 2e8ed32d5ef65db202d2d7d91b5c6c4e9100aa0b Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 17 Aug 2026 16:03:47 -0600 Subject: [PATCH 7/8] docs(factories): address third round of review feedback quickstart.mdx: - Remove duplicate 'no active plan' info from the prerequisites bullet now that the setup wizard note covers it. - Condense the 'no team yet' note per suggestion. - Switch 'such as' to 'e.g.,' per suggestion. - Shorten the Slack-skip step and fix the awkward 'connect them any time from [page]' wording -- readers learn about integrations from the linked page, they don't connect them from it. - Trim the agent-selection step: drop the redundant foreman explanation (already covered in the intro) and the non-critical 'all four start enabled' detail. interactive UI element. - Drop the redundant 'on Runs' from the foreman pick-up sentence, since the following step already introduces the Runs page. - Simplify the final review/merge step per suggestion. troubleshooting.mdx: - Replace vague 'contact Warp' with the established contact-sales link convention used elsewhere in the docs. Co-Authored-By: Warp --- src/content/docs/factories/quickstart.mdx | 16 ++++++++-------- src/content/docs/factories/troubleshooting.mdx | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index e4b854be..79beef50 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -12,7 +12,7 @@ A factory is a team of cloud agents — a foreman you talk to, plus the subagent ## Prerequisites -* **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/). Factory agents consume the team's credits. If the team has no active plan, you will be asked to select one during setup. +* **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/). Factory agents consume the team's credits. * **GitHub repository access** - Authorize GitHub and choose repositories during setup. If your organization restricts app installations, ask a GitHub organization owner to approve the connection. See the [GitHub integration](/platform/integrations/github/) for details. ## Create your factory @@ -23,7 +23,7 @@ _~5 minutes_ 2. In the sidebar, next to **Factories**, click **+** to start the setup wizard. :::note - **No team yet?** The wizard first asks you to choose the team that will own the factory. If that team has no plan or credits, it opens **Select a Warp Plan**. A factory needs credits to run its agents. + **No team yet?** If the team that owns the factory has no plan or credits, the wizard will ask you to select one. A factory needs credits to run its agents. ::: 3. Click **I want to use repos from GitHub** and complete the GitHub authorization. @@ -31,15 +31,15 @@ _~5 minutes_ Warp provisions a default [environment](/platform/environments/) for the selected repos. -5. Enter a **Factory name**, such as `Payments services`. Warp derives a matching **Factory alias**, the handle teammates use to @-mention the factory from connected tools like Slack and Linear. Keep it short and recognizable. -6. The next screen offers to connect Slack. This quickstart skips integrations, so click **Next**. You can connect them any time from [Connect your factory](/factories/connect-your-factory/). -7. The foreman leads every factory. It's the orchestration agent you interact with directly. Below it, toggle the subagents it can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Keep **Code** on so this quickstart's work item can end in a pull request. +5. Enter a **Factory name**, e.g., `Payments services`. Warp derives a matching **Factory alias**, the handle teammates use to @-mention the factory from connected tools like Slack and Linear. Keep it short and recognizable. +6. The next screen offers to connect Slack. Click **Next** to skip it for now. See [Connect your factory](/factories/connect-your-factory/) to add integrations later. +7. Toggle the subagents the foreman can dispatch: **Triage**, **Spec**, **Code**, and **Review**. Keep **Code** on so this quickstart's work item can end in a pull request. See [Factory agents](/factories/factory-agents/) for what each role does. 8. Skip the issue tracker screen the same way as Slack: click **Next**. Warp creates the factory. - When the startup screen reports **Factory running!**, click **Go to dashboard**. + When the startup screen reports "Factory running!", click **Go to dashboard**. ## Submit your first work item @@ -56,14 +56,14 @@ _~5 minutes_ Adapt the pattern to your repository: name the file, the change you expect, and the command that verifies it. A narrow, explicit request makes the first run easy to judge. - The foreman picks up the request as a run on **Runs** and dispatches your subagents as child runs. + The foreman picks up the request as a run and dispatches your subagents as child runs. 3. Follow progress from two pages in your factory's sidebar: * **Runs** - The foreman's run and the child runs it dispatches. * **Activity** - The work item as it moves through its stages. Open it to see its event history and pull request artifacts. -4. When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it through your normal process. The factory drafts the change, and your team makes the call. +4. When the Code agent finishes, the work item links a pull request in GitHub. Review and merge it following your normal process. ## Next steps diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx index 40834e4e..ecf874f6 100644 --- a/src/content/docs/factories/troubleshooting.mdx +++ b/src/content/docs/factories/troubleshooting.mdx @@ -26,7 +26,7 @@ Solutions for common issues when creating and operating a factory in the {VARS.F **Fix:** 1. Ask a team admin to confirm the team's capacity. -2. If the team needs more agents, contact Warp. +2. If the team needs more agents, [contact sales]({VARS.CONTACT_SALES_URL}). ## You need to stop a run From 7556525a4452d4bdb0fd6c60d56f9a471dd7e459 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Mon, 17 Aug 2026 16:12:52 -0600 Subject: [PATCH 8/8] docs(factories): fix broken-link CI failure in troubleshooting.mdx The internal link checker doesn't resolve {VARS.X} expressions inside markdown [text](...) links (only via JSX ), so {VARS.CONTACT_SALES_URL} was flagged as a literal broken relative path. Use a hardcoded URL instead, matching the existing pattern in platform/self-hosting/index.mdx for the same contact-sales link. Co-Authored-By: Warp --- src/content/docs/factories/troubleshooting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx index ecf874f6..40ab6d59 100644 --- a/src/content/docs/factories/troubleshooting.mdx +++ b/src/content/docs/factories/troubleshooting.mdx @@ -26,7 +26,7 @@ Solutions for common issues when creating and operating a factory in the {VARS.F **Fix:** 1. Ask a team admin to confirm the team's capacity. -2. If the team needs more agents, [contact sales]({VARS.CONTACT_SALES_URL}). +2. If the team needs more agents, [contact sales](https://www.warp.dev/contact-sales). ## You need to stop a run