diff --git a/src/assets/factories/factories-concept-loop.png b/src/assets/factories/factories-concept-loop.png new file mode 100644 index 00000000..c2706746 Binary files /dev/null and b/src/assets/factories/factories-concept-loop.png differ diff --git a/src/assets/factories/factory-dashboard-activity-filters.png b/src/assets/factories/factory-dashboard-activity-filters.png new file mode 100644 index 00000000..79e86e4c Binary files /dev/null and b/src/assets/factories/factory-dashboard-activity-filters.png differ diff --git a/src/assets/factories/factory-dashboard-activity.png b/src/assets/factories/factory-dashboard-activity.png new file mode 100644 index 00000000..9803a4ab Binary files /dev/null and b/src/assets/factories/factory-dashboard-activity.png differ diff --git a/src/assets/factories/factory-dashboard-metrics.png b/src/assets/factories/factory-dashboard-metrics.png new file mode 100644 index 00000000..61b63c20 Binary files /dev/null and b/src/assets/factories/factory-dashboard-metrics.png differ diff --git a/src/assets/factories/slack-factory-thread-reply.png b/src/assets/factories/slack-factory-thread-reply.png new file mode 100644 index 00000000..065a5d94 Binary files /dev/null and b/src/assets/factories/slack-factory-thread-reply.png differ diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index f7cd67e7..93ffce53 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -11,7 +11,7 @@ Connect your factory to the tools where your team already discusses, tracks, and ## Choose a source -Pick the sources that match where work starts for your team. You can connect more than one, though a factory can use Linear or Jira, or no tracker at all, but not both at once. The setup wizard currently offers Linear; to use Jira, connect it after setup or in your [factory definition](/factories/factory-as-code/). +Pick the sources that match where work starts for your team. You can connect multiple sources, but not both Linear and Jira at the same time. The setup wizard currently offers Linear; to use Jira, connect it after setup or in your [factory definition](/factories/factory-as-code/). | Source | Best for | Where follow-ups continue | | --- | --- | --- | @@ -25,10 +25,9 @@ Pick the sources that match where work starts for your team. You can connect mor ## Connect a source -1. Pick the factory you want to connect. If you don't have one yet, follow the [Warp Factories quickstart](/factories/quickstart/). -2. Connect the source: install the provider integration, set up the [Factory MCP](/factories/factory-mcp/), or create a schedule. Each integration guide below walks through authorization; grant only the access the factory needs. -3. Tell the factory how to respond. Provider connections come with default automations that decide which events start work and which agent handles them. Review their [filters](/factories/automation-filters/) and run settings. Filters route work, not access: what a running agent can reach depends on its own configuration, not the filters that started it. Schedules and direct runs skip this step. -4. Send a test request, such as mentioning the factory in Slack or assigning it an issue, and confirm it picks up the work and replies at the source. +Each source's integration guide walks through authorizing access; grant only what the factory needs. Provider connections come with default automations that decide which events start work and which agent handles them. Review their [filters](/factories/automation-filters/) and run settings after connecting. Filters route work, not access: what a running agent can reach depends on its own configuration, not the filters that started it. + +After connecting, send a test request, such as mentioning the factory in Slack or assigning it an issue, and confirm it picks up the work and replies at the source. ## How work reaches your factory @@ -42,9 +41,9 @@ flowchart LR Work --> Results["Results posted
back to the source"] ``` -An event from a connected tool starts the automation whose filters match it, such as a specific repository, channel, or label. Schedules start their automation on a timer, and direct requests go straight to the factory. +An event from a connected tool starts the automation based on filter matching, such as a specific repository, channel, or label. Schedules start their automation on a timer, and direct requests go straight to the factory. -Every request then lands with the foreman agent, the factory's orchestrator. The foreman turns the request into a work item, determines which stage the work needs next, and dispatches a specialized agent for each stage: triage to scope the request, spec when the design needs agreement, implementation to write the code, and review to check it. Between stages it relays questions and progress back to the source, and it pauses wherever a decision belongs to a human, such as approving a spec or [merging a pull request](/factories/how-factories-work/#where-your-team-stays-in-charge). A reply in the same thread, issue, or pull request adds to that work item instead of starting a new one, and repeated event deliveries from a provider don't create duplicates. See [how Warp Factories work](/factories/how-factories-work/) for the full lifecycle. +Every request lands with the foreman agent, which turns it into a work item and dispatches the agents each stage needs. A reply in the same thread, issue, or pull request continues that work item instead of starting a new one, and repeated event deliveries don't create duplicates. See [how Warp Factories work](/factories/how-factories-work/) for the full lifecycle, including where people stay in the loop. ## Review the default automations @@ -58,25 +57,13 @@ When you create a factory through the setup wizard, Warp adds default automation These defaults are starting points. Review each automation's filters, agent, and run settings, and adjust them to match your workflow. -## Integration guides - -* [Slack](/factories/integrations/slack/) - Route chat requests, direct messages, and thread follow-ups through a dedicated factory app. -* [GitHub](/factories/integrations/github/) - Route repository events with issue, pull request, review, or CI context. -* [GitLab](/factories/integrations/gitlab/) - Route merge request events and bot mentions through a per-factory service account. -* [Linear](/factories/integrations/linear/) - Route planned issues through issue activity and agent sessions. -* [Jira](/factories/integrations/jira/) - Route Jira work items assigned to Warp into factory work. - ## Factory MCP -The Factory MCP connects local coding agents and other MCP clients to your factory, and it works in both directions: send work to the factory, or take work over from it — pull a task down to your machine, iterate on it locally, and hand it back to the same work item. See the [Factory MCP guide](/factories/factory-mcp/). +The Factory MCP connects local coding agents and other MCP clients to your factory, and it works in both directions. Send work to the factory, or take work over from it by pulling a task down to your machine, iterating on it locally, and handing it back to the same work item. See the [Factory MCP guide](/factories/factory-mcp/). ## Direct runs and schedules Not every task starts in an external tool: -* Start a direct factory run for one-off work: describe the task and the foreman agent takes it from there. -* Create a scheduled automation for recurring work such as maintenance or reports. - -See the [triggers overview](/platform/triggers/) for how schedules and other triggers work across the platform. - -Next, customize which agents receive work and how it's routed with [factory definitions as code](/factories/factory-as-code/). +* Start a direct run for one-off work. Click **New** on the factory's Runs page and describe the task to the foreman, the same way you would from Slack or an issue tracker. +* Create a scheduled automation for recurring work, such as maintenance or reports. See the [triggers overview](/platform/triggers/) for how schedules and other triggers work across the platform. diff --git a/src/content/docs/factories/factory-dashboard.mdx b/src/content/docs/factories/factory-dashboard.mdx index 92be3b9c..8e90fd66 100644 --- a/src/content/docs/factories/factory-dashboard.mdx +++ b/src/content/docs/factories/factory-dashboard.mdx @@ -29,12 +29,27 @@ A factory opens on its **Dashboard** page, covered next. **Factory definition** The page also charts opened versus merged PRs and a breakdown of runs, and the **Cost per PR** card expands to list the most expensive PRs in the range. When Scorers are set up, Scorer cards summarize recent classification results. +
+![The Dashboard page showing a Cost per PR chart broken down by compute, platform, and inference cost, plus two example Scorer cards.](../../../assets/factories/factory-dashboard-metrics.png) +
Cost per PR and example Scorer cards on the Dashboard page.
+
+ ## Track work items on Activity **Activity** shows the factory's work items grouped by stage: Triage, Planning, Building, and Reviewing. Finished work items move to two terminal stages, Complete and Cancelled. +
+![The Activity page of the factory dashboard, listing work items grouped under Triage, Planning, Building, and Reviewing.](../../../assets/factories/factory-dashboard-activity.png) +
Activity groups work items by stage, with counts for each.
+
+ By default, Activity shows only work items you created, and only the four active stages. Change the **Created by** filter to see a teammate's work, and add a **Stage** filter for **Complete** or **Cancelled** to see finished work. +
+![The Activity page with a Stage filter chip applied above the work item list, plus a search box and results count.](../../../assets/factories/factory-dashboard-activity-filters.png) +
Filter Activity by stage, creator, or a text search.
+
+ Click a work item to open its detail pane, which includes the prompt that started it, the ticket or thread it came from, the pull requests it produced, and its cost. **View agent** opens the agent's session, **Event history** lists the runs behind the work item, and **Stop task** cancels the current run. :::caution diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 61b056c7..221ae44c 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 runs cloud software factories where specialized agents move - engineering work from intake to a reviewed pull request. + Warp Factories runs cloud software factories where specialized agents work + engineering requests from intake to a mergeable pull request. sidebar: label: "Overview" --- @@ -12,21 +12,26 @@ import { VARS } from '@data/vars'; Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: -Warp Factories lets engineering teams define and operate **software factories**: cloud workflows where specialized agents move engineering work from intake to a reviewed pull request. The factory does the repetitive work; your team stays in the loop at the points that matter, approving specs when needed and merging every pull request. +A software factory takes in requests (bug reports, feature specs, support escalations), and a coordinated fleet of agents works them into a stream of mergeable pull requests instead of a growing backlog. Warp Factories gives you the building blocks, so your team stays in the loop where it matters, approving specs when needed and merging every pull request. ## What is a software factory? -A software factory automates the software development lifecycle. It takes a **work item**, such as an issue, ticket, or triggered task, and moves it through specialized agents that triage it, write a specification when one is needed, implement the change, and review the result. +In practice, that means tracking each request as a **work item**, such as an issue, ticket, or triggered task, and moving it through specialized agents that triage it, write a specification when one is needed, implement the change, and review the result. A **factory** is one deployed instance of that pattern. It connects your repositories and engineering tools to a team of agents, execution infrastructure, and a measurable workflow. Each factory applies a single policy across all of its work sources, so deploy separate factories for repository groups that need different policies. +
+![A circular diagram of the software factory loop: triage, spec, implement, review, verify, ship, and monitor, with human review checkpoints for the spec, code, and product.](../../../assets/factories/factories-concept-loop.png) +
The general software factory loop. Warp Factories' default agents cover triage through review; add custom agents for the rest.
+
+ ## Who benefits from Warp Factories -Warp Factories is designed for engineering teams with repeatable work that extends beyond one coding session, such as: +Warp Factories is designed for engineering teams with repeatable work that extends beyond one coding session. Here's where it helps most: -* **Backlog work** - Process issues with a consistent triage and delivery policy. -* **Operational requests** - Fix defects reported through support channels. -* **Code maintenance** - Review incoming pull requests or maintain services across repositories. +* 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. ## What you get with Warp Factories diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 8c36d78b..37fb52bc 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -96,13 +96,13 @@ New activity on an issue, pull request, or review thread the factory is already Issues and pull requests the factory opens carry its label, the same one you use to mention it. Warp adds the label to each repository you connect and removes it when you disconnect one or delete the factory, so you never create or clean it up by hand. If a label is ever left behind, delete it like any other GitHub label. -Branches and pull requests the factory creates follow the repository's normal rules — branch protection, required reviews, and merge requirements all still apply. +Branches and pull requests the factory creates follow the repository's normal rules: branch protection, required reviews, and merge requirements all still apply. ## Permissions Runs authenticate with the GitHub App installation, not with the account of the person whose activity triggered them: -* **The app installation decides what agents can reach.** Agents get exactly the repositories and permissions the installation grants, so change the installation to change access — [automation filters](/factories/automation-filters/) only change when work starts. +* **The app installation decides what agents can reach.** Agents get exactly the repositories and permissions the installation grants, so change the installation to change access. [Automation filters](/factories/automation-filters/) only change when work starts. * **Anyone who can create matching activity can start work.** The event author doesn't need to be a Warp team member. Use author, label, and branch filters to control what starts runs. For the full credential model, see [Permissions and identity](/platform/integrations/github/#permissions-and-identity) on the GitHub integration page. diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 791b7c1a..4ba8a13c 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -25,7 +25,7 @@ Connect Jira Cloud to your factory so your team can start factory work without l 3. **Point an automation at Jira.** In the factory's dashboard, open **Automations** and add a trigger for **Jira** > **Agent session created**. Use **Projects** and, optionally, **Keywords** to scope which sessions start a run, and choose the agent that handles them. - If you picked Jira projects when you created the factory, that automation already exists — edit it rather than adding a second one. + If you picked Jira projects when you created the factory, that automation already exists. Edit it rather than adding a second one. To set this up in code instead, declare the `jira` integration in the factory's `factory.yaml` (`integrations: [{type: jira}]`), then add a file under `automations/`, such as `automations/jira-assignment/automation.md`, with an `agent_session_created` trigger: diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx index 5a54ff61..132b3643 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -7,7 +7,7 @@ sidebar: label: "Linear" --- -Connect Linear to your factory so your team can send it issues without leaving Linear. Assign an issue to the factory or tag it in a comment, and the factory picks it up with the issue's full context, then keeps the issue updated as the work moves through [its stages](/factories/how-factories-work/). +Connect Linear to your factory so your team can send issues without leaving Linear. Assign an issue to the factory or tag it in a comment, and the factory picks it up with the issue's full context, then keeps the issue updated as the work moves through [its stages](/factories/how-factories-work/). When the factory needs an answer, reply in Linear, or open the live run to steer the agent directly. diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index 5f650577..a3b48041 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -7,39 +7,21 @@ sidebar: label: "Slack" --- -Connect a factory to Slack so your team can send it work without leaving their conversations. Mention the factory in a channel or send it a direct message, and it picks up the request with the conversation as context, then posts progress and results back into the same thread. +Connect a factory to Slack so your team can send work without leaving their conversations. Mention the factory in a channel or send it a direct message, and it picks up the request with the conversation as context, then posts progress and results back into the same thread. -Each factory appears in Slack as its own app, carrying the factory's name and avatar. A channel can host several factories, and you choose which one to mention. +Each factory appears in Slack as its own app with the factory's name and avatar. A channel can host several factories, and you choose which one to mention. ## Prerequisites -* **Permission to install Slack apps** - You need it in the target workspace, and workspace policy can require an administrator to approve the app before it installs. +* **Permission to install Slack apps in the target workspace** - Workspace policy may require administrator approval before the app installs. * **Permission to update the factory** - Connecting Slack changes the factory's configuration. ## Connect the factory -Select Slack while creating a factory and Warp installs its app for you. If the install can't finish on its own — usually because your workspace requires administrator approval — click **Add to Slack** in factory setup to complete it. - -Then invite the app to each channel it should listen in. Private channels always need an invitation. - -To check that it worked, mention the app in one of those channels. It reacts with 👀 to show it picked up the request. - -## Start and continue work from Slack - -| Slack activity | Context used by the factory | Slack output | -| -------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -| Mention the app in a channel or thread | The triggering message, available thread history, and supported attachments | An acknowledgment, progress updates, a final summary, and links to the run, issue, or pull request when available | -| Send the app a direct message | The direct-message conversation and supported attachments | An acknowledgment, progress updates, and links to results when available | -| Reply in an existing factory thread | The existing work item and your reply | A follow-up on the existing work item instead of new work | -| Slack activity matches an automation | The event details plus the automation's agent and instructions | A factory run, with results posted back to the source conversation when supported | - -A plain reply in a thread continues work only if that thread already has a factory work item; to start new work in a channel, mention the app. You can attach files to a request or a follow-up. The factory includes the files it supports, and a file it can't include doesn't stop the text of your request from going through. - -## Who can start work - -To start work with a mention or direct message, your Slack account must be linked to an active member of the factory's Warp team. If it isn't, the app prompts you to connect an account instead of starting work. - -Work started by an automation runs as the factory agent you chose for it, not as whoever triggered it. +1. **Select Slack while creating a factory**, or connect it later from the factory's **Settings**. Warp installs its Slack app for you. +2. **Complete the install if it can't finish on its own.** This usually happens when your workspace requires administrator approval. Click **Add to Slack** in factory setup to finish. +3. **Invite the app to each channel it should listen in.** Private channels always need an invitation. +4. **Confirm the connection.** Mention the app in one of those channels. It reacts with 👀 to show it picked up the request. ## Configure factory automations for Slack @@ -55,14 +37,33 @@ The **Conversations** picker only shows conversations the factory's app has join A single Slack message can match more than one automation. For example, if one automation triggers on **App mentioned** and another triggers on **Message posted in channel** in the same channel, a channel message that mentions the app starts two separate runs, one for each automation. To avoid duplicate runs, don't point both triggers at the same channel. +## Start and continue work from Slack + +Mention the app in a channel or thread, or send it a direct message, to start work. The factory picks up the message, including available thread history and supported attachments, and replies in the same place with an acknowledgment, progress updates, and links to results. + +A plain reply in a thread continues work only if that thread already has a factory work item; to start new work in a channel, mention the app instead. Slack activity that matches an automation starts work the same way, without a mention, using the event details and the automation's assigned agent. + +You can attach files to a request or a follow-up. The factory includes the files it supports, and a file it can't include doesn't stop the text of your request from going through. + ## Follow work and review outputs The Slack thread where work started is also where you follow it: the factory posts progress and the final response there. Reply in the thread to add information or attachments while work is active, or to pick the same work item back up later. +
+![A Slack thread where the Warp Factories app replies with tracking and triage progress updates, including links to open the session and view it in the factory.](../../../../assets/factories/slack-factory-thread-reply.png) +
The factory's Slack app posting progress updates in the thread where work started.
+
+ For an overview of the factory's work items, open the app's **Home** tab in Slack. It groups them by the same stages as the factory dashboard's [Activity view](/factories/factory-dashboard/#track-work-items-on-activity) (Triage, Planning, Building, Reviewing, Completed, and Cancelled), offers stage and date filters, and links each work item back to its Slack thread, factory run, issue, or pull request when available. Work that starts in Slack still ends at a pull request for a person to review — see [how Warp Factories work](/factories/how-factories-work/). +## Who can start work + +To start work with a mention or direct message, your Slack account must be linked to an active member of the factory's Warp team. If it isn't, the app prompts you to connect an account instead of starting work. + +Work started by an automation runs as the factory agent you chose for it, not as whoever triggered it. + ## Troubleshooting and reconnection - **The app doesn't acknowledge a request** - Confirm Slack is connected for that factory, that you mentioned the right factory's app, and that the app is in the channel. diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 4ec95f93..b4674cab 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -2,7 +2,7 @@ title: Warp Factories quickstart description: >- Set up a factory, connect your repositories, and take your first work item - from prompt to pull request in about 10 minutes. + from prompt to pull request in less than 10 minutes. sidebar: label: "Quickstart" --- @@ -14,7 +14,7 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ A factory is a group of cloud agents that turns incoming requests into pull requests. You talk to one agent, the **foreman**. It picks up the request from wherever it starts, such as Slack, an issue tracker, or a code host, then dispatches the factory's other agents, each owning one part of the software development lifecycle. People stay in the loop at the points that matter: approving specs when needed and merging pull requests. -In this quickstart, you will create a factory and take one small work item from prompt to pull request in about 10 minutes. +In this quickstart, you will create a factory and take one small work item from prompt to pull request in less than 10 minutes. ## What you'll decide @@ -41,7 +41,7 @@ _~5 minutes_ Already using an agent connected to [Factory MCP](/factories/factory-mcp/)? Ask it to run `create_factory` with the team, repositories, and factory name to create the factory directly, skipping the wizard below. Choose agents and connect your tools afterward in the factory's dashboard. ::: -Otherwise, Warp walks you through a setup wizard: +Warp walks you through a setup wizard: 1. Sign in to the {VARS.FACTORY_WEB_APP}. Next to **Factories**, click **+**. @@ -64,14 +64,14 @@ Otherwise, Warp walks you through a setup wizard:
Search for and select the repositories the factory works in.
-4. Name the factory. Warp derives a matching [**Foreman name**](/factories/factory-as-code/#alias) from it, the handle your team @-mentions to reach the factory from connected tools like Slack and Linear. Keep it short and recognizable, or set your own. +4. Name the factory. This also sets its [**Foreman name**](/factories/factory-as-code/#alias), the handle your team @-mentions to reach it from Slack and Linear. Keep it short and recognizable, or set your own.
![The Give your factory some personality screen, with Factory name and Foreman name fields filled in.](../../../assets/factories/quickstart-name-factory.png)
Name the factory and, optionally, add a description and avatar.
-5. Optionally, connect a chat tool so teammates can hand work to the factory from Slack, or skip it and add it later from [connect your factory](/factories/connect-your-factory/). +5. Optionally, connect a chat tool so teammates can hand work to the factory from Slack. You can also skip this step and connect Slack later. See [connect your factory](/factories/connect-your-factory/). 6. Toggle the subagents the foreman can dispatch: **Triage**, **Spec**, **Code**, and **Review**. All four start enabled, and at least one is required. Leave **Code** on so this quickstart can end in a pull request. See [factory agents](/factories/factory-agents/) for what each does.
@@ -79,7 +79,7 @@ Otherwise, Warp walks you through a setup wizard:
Toggle which default agents the foreman can dispatch.
-7. Optionally, connect an issue tracker so teammates can hand work to the factory from Linear or Jira, or skip it and add one later from [connect your factory](/factories/connect-your-factory/). +7. Optionally, connect an issue tracker so teammates can hand work to the factory from Linear or Jira. You can also skip this step and connect one later. See [connect your factory](/factories/connect-your-factory/). Warp creates the factory and opens its [dashboard](/factories/factory-dashboard/). @@ -87,7 +87,7 @@ Warp creates the factory and opens its [dashboard](/factories/factory-dashboard/ _~5 minutes_ -Send the request from the tool your team already works in. Mention the factory in a Slack channel, or assign it an issue in your tracker, and it replies right there. If you skipped the integrations, start a run from the **Runs** page of the factory's [dashboard](/factories/factory-dashboard/) instead. +You can request work from the tools your team already uses. Mention the factory in a Slack channel, or assign it an issue in your tracker, and it replies right there. If you skipped the integrations, start a run from the **Runs** page of the factory's [dashboard](/factories/factory-dashboard/) instead. 1. Describe one small, verifiable change and send it: @@ -104,6 +104,13 @@ Send the request from the tool your team already works in. Mention the factory i * **Runs** - The foreman's run and the child runs it dispatches. * **Activity** - The work item as it moves through its stages. Open it for the event history and pull request artifacts. + If you connected Slack, you can follow along there instead: + +
+ ![A Slack thread where the Warp Factories app replies with tracking and triage progress updates, including links to open the session and view it in the factory.](../../../assets/factories/slack-factory-thread-reply.png) +
The factory's Slack app posting progress updates back in the thread where you sent the request.
+
+ 3. When the Code agent finishes, the work item links to the pull request. Review and merge it the way you would any other: a factory hands off at the pull request and never merges for you. ## Next steps