From c7f6d404da59062843e68812093c83b90050fe5d Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Thu, 20 Aug 2026 23:15:17 +0000 Subject: [PATCH] docs(factories): consistency pass and visual callout comments - Remove leftover GitLab review-question comment and correct the definition-host claim (GitLab isn't yet a supported definition host). - Fix agent naming: quickstart and troubleshooting referred to the Implement agent as "Code" and called the default agents "subagents"; align both with the Implement Agent name shown in the product UI. - Normalize the GitLab integration page's title/description to the "Connect X to your factory" pattern used by the other integrations. - Rewrite the troubleshooting page's opener to lead with the fix, not "This page covers...". - Fix the How factories work sidebar label casing and align the Complete/Completed terminal-stage label between the dashboard and Slack Home tab docs. - Normalize a few Related pages/Next steps link labels for consistency. - Add brief {/* VISUAL: ... */} comments at sections a product screenshot would help, skipping locations already covered by the open factory-agents.mdx/how-factories-work.mdx screenshot PR (#589). Co-Authored-By: Warp --- src/content/docs/factories/automation-filters.mdx | 8 +++++--- .../docs/factories/connect-your-factory.mdx | 2 ++ src/content/docs/factories/factory-as-code.mdx | 2 ++ src/content/docs/factories/factory-dashboard.mdx | 4 ++++ src/content/docs/factories/factory-mcp.mdx | 14 ++++++++------ src/content/docs/factories/how-factories-work.mdx | 2 +- src/content/docs/factories/integrations/github.mdx | 2 ++ src/content/docs/factories/integrations/gitlab.mdx | 12 +++++++----- src/content/docs/factories/integrations/jira.mdx | 2 ++ src/content/docs/factories/integrations/linear.mdx | 2 ++ src/content/docs/factories/integrations/slack.mdx | 2 +- src/content/docs/factories/measure-and-improve.mdx | 4 ++++ src/content/docs/factories/quickstart.mdx | 8 ++++---- src/content/docs/factories/troubleshooting.mdx | 4 ++-- 14 files changed, 46 insertions(+), 22 deletions(-) diff --git a/src/content/docs/factories/automation-filters.mdx b/src/content/docs/factories/automation-filters.mdx index a81800254..9d9327a68 100644 --- a/src/content/docs/factories/automation-filters.mdx +++ b/src/content/docs/factories/automation-filters.mdx @@ -45,6 +45,8 @@ Each integration guide lists which filters appear on which event types. 2. Under **Triggers**, open a trigger and set the filters shown for its event. Click **More filters** for the event-specific options. 3. Click **Save**. To confirm the routing works, send a matching test event, such as opening a test issue, and check that a work item starts in the factory dashboard. +{/* VISUAL: An automation's trigger editor with More filters expanded. */} + Review the default automations Warp creates when you connect a provider, too: their filters are starting points, not fixed rules. ## Filters in definitions as code @@ -74,7 +76,7 @@ The same matching rules apply: every key must match, any listed value within a k ## Related pages -* [Connect your factory](/factories/connect-your-factory/) - Choose the sources that route work into the factory. +* [**Connect your factory**](/factories/connect-your-factory/) - Choose the sources that route work into the factory. * [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/) integration guides - Per-source setup, events, and filter details. -* [Definitions as code](/factories/factory-as-code/) - Manage automations, triggers, and filters as version-controlled files. -* [Factory dashboard](/factories/factory-dashboard/) - Create and edit automations in the factory's **Automations** view. +* [**Definitions as code**](/factories/factory-as-code/) - Manage automations, triggers, and filters as version-controlled files. +* [**Factory dashboard**](/factories/factory-dashboard/) - Create and edit automations in the factory's **Automations** view. diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index 93ffce53a..7e25a905e 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -29,6 +29,8 @@ Each source's integration guide walks through authorizing access; grant only wha 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. +{/* VISUAL: The factory's Integrations settings connect screen, to ground the abstract source table above in the actual setup flow. */} + ## How work reaches your factory ```mermaid diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 0a0b9f339..e0da791ba 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -23,6 +23,8 @@ Both modes use the same files, so everything on this page applies to either. You Definition files describe how the factory is configured, not what it is doing: work items, runs, and metrics live in the web app and are never written to the files. +{/* VISUAL: The Factory definition tab's file browser for a Warp-managed factory -- this reference page has no screenshots. */} + ## Directory structure Each resource takes its name from its path: `agents/reviewer/agent.md` defines an agent named `reviewer`. diff --git a/src/content/docs/factories/factory-dashboard.mdx b/src/content/docs/factories/factory-dashboard.mdx index 8e90fd66e..6a94a23ea 100644 --- a/src/content/docs/factories/factory-dashboard.mdx +++ b/src/content/docs/factories/factory-dashboard.mdx @@ -62,6 +62,8 @@ A run is a single agent execution. A work item on **Activity** tracks one piece Click **New** on a factory's **Runs** page to send a prompt to the factory's foreman agent. Open a run to see its timeline and cost, plus a **Sub-agents** tab for an orchestrator run's child runs. From there you can view the agent's full session, stop or score the run, or turn it into a benchmark task. +{/* VISUAL: The Runs page with the New button, showing an empty or sample run list. */} + :::note Run pages don't include a chat input, but you can still steer a run: **View session** opens its [shared agent session](/platform/viewing-cloud-agent-runs/), where you follow the agent in real time and send follow-up instructions while the run's sandbox is active. After it shuts down, the same button opens the conversation transcript. ::: @@ -70,6 +72,8 @@ Run pages don't include a chat input, but you can still steer a run: **View sess **Agents** lists the factory's agents. Create agents and edit their instructions, model or harness, runner, host, secrets, and MCP servers. **Automations** defines the triggers that start runs: a schedule (including custom cron expressions) or a GitHub, Linear, Slack, or Jira event. +{/* VISUAL: The Automations editor, to complement the Agents list already shown in Configure agent behavior on the factory agents page. */} + The automation editor doesn't change execution settings; an automation only overrides them through [execution overrides in the definition files](/factories/factory-as-code/#execution-overrides). When the factory's definition lives in an external repository, Agents, Automations, and Scorers are read-only; make changes there through pull requests. ## Edit definitions in the Factory definition tab diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index f16cc3766..665984992 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -81,6 +81,8 @@ The rest of this page describes what happens behind those prompts. ## Send new work to a factory +{/* VISUAL: An MCP client connected to Factory MCP (Warp or Cursor), or a factory task created via send_task -- this page has no product chrome today. */} + To create a task, your agent calls `send_task` with the target factory, a title, and a note. The note is what the foreman starts from, so a good one states the goal, the relevant context and constraints, and any work already done. The foreman takes it from there and reports progress on the task's conversation. If the new task builds on local changes, push the branch or open a pull request first and reference it in the note, so the factory can see that work. @@ -122,9 +124,9 @@ Your MCP client fetches the full input schemas from the server, and tool results ## Related pages -* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the Slack, GitHub, GitLab, Linear, and Jira integrations. -* [Factory agents](/factories/factory-agents/) - The foreman and the other agents that carry out a factory's tasks. -* [How Warp Factories work](/factories/how-factories-work/) - The task lifecycle and the agents that move work through it. -* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send it its first work item. -* [Model Context Protocol in Warp](/agents/capabilities/mcp/) - How MCP servers work in the Warp app, with a catalog of popular MCP servers you can add to Warp directly. -* [Handoff between local and cloud agents](/platform/handoff/) - Move workspaces and conversations between local and cloud outside a factory. +* [**Connect your factory**](/factories/connect-your-factory/) - Every way work can enter a factory, including the Slack, GitHub, GitLab, Linear, and Jira integrations. +* [**Factory agents**](/factories/factory-agents/) - The foreman and the other agents that carry out a factory's tasks. +* [**How Warp Factories work**](/factories/how-factories-work/) - The task lifecycle and the agents that move work through it. +* [**Warp Factories quickstart**](/factories/quickstart/) - Create a factory and send it its first work item. +* [**Model Context Protocol in Warp**](/agents/capabilities/mcp/) - How MCP servers work in the Warp app, with a catalog of popular MCP servers you can add to Warp directly. +* [**Handoff between local and cloud agents**](/platform/handoff/) - Move workspaces and conversations between local and cloud outside a factory. diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index b59ebf041..a960c7c45 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -4,7 +4,7 @@ description: >- A factory's foreman routes each work item through triage, specification, implementation, and review, with humans making the key decisions. sidebar: - label: "How Factories work" + label: "How factories work" --- :::note diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 37fb52bc4..3cf28a130 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -82,6 +82,8 @@ Handing an issue or pull request to a factory takes two things: The factory picks up the request and replies in the same thread. +{/* VISUAL: An issue with the factory: label and an @warp-factory mention -- the two-part mention ritual is easy to miss from prose alone. */} + Both halves matter, because **@warp-factory** is the account every factory listens through. The label is what decides which of your factories answers, so a mention without one doesn't start work. Only new content counts as a mention. Edits to existing comments, mentions inside code blocks, and mentions from bots are ignored. diff --git a/src/content/docs/factories/integrations/gitlab.mdx b/src/content/docs/factories/integrations/gitlab.mdx index 9f6029cf7..bb97b345c 100644 --- a/src/content/docs/factories/integrations/gitlab.mdx +++ b/src/content/docs/factories/integrations/gitlab.mdx @@ -1,8 +1,8 @@ --- -title: Connect a factory to GitLab +title: Connect GitLab to your factory description: >- - Connect a factory to GitLab so merge request events and bot mentions start - factory work and results post back as comments and merge requests. + Connect GitLab to your factory so merge request events and bot mentions + start factory work and results post back as comments and merge requests. sidebar: label: "GitLab" --- @@ -71,6 +71,8 @@ Each GitLab factory has its own bot account, so the mention itself routes the re The **gitlab-bot-mentions** automation starts a work item, and the factory replies in the same thread. To find the bot's username, check that automation's trigger in the [factory dashboard](/factories/factory-dashboard/). +{/* VISUAL: A merge request comment mentioning the factory's bot username, parallel to the GitHub mention visual. */} + Mentions count only in new comments. Edits and activity from Warp's own service accounts never trigger work, so a factory can't re-trigger itself or a sibling factory. ## How the factory responds on GitLab @@ -112,7 +114,7 @@ triggers: Triage newly opened merge requests and post an initial review. ``` -A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out. Warp seeds it with the factory's bot username and rejects definitions that set it. {/* OPEN QUESTION for tech review (PR #549): confirm GitLab is actually supported as a definition host today. main@79f77e55 states GitLab is "not yet available as a definition host" -- this contradicts the claim below. Verify before merging. */}Factory definitions hosted in GitLab repositories sync the same way GitHub-hosted ones do. +A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out. Warp seeds it with the factory's bot username and rejects definitions that set it. GitLab isn't yet supported as a definition-hosting repository, so declare these triggers in a Warp-managed or GitHub-hosted definition even when the factory's automations and mentions run through GitLab; see [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). ## Troubleshooting @@ -136,4 +138,4 @@ Confirm the target project is one of the factory's selected projects and the ope Only top-level groups you own appear, and a group already connected to another Warp workspace can't be connected again. If you don't own the group, ask an owner to establish the connection in Warp. -For the other ways to route work into a factory, see [connecting your factory](/factories/connect-your-factory/). +For the other ways to route work into a factory, see [Connect your factory](/factories/connect-your-factory/). diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 4ba8a13ca..d3f7cb3fb 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -48,6 +48,8 @@ Connect Jira Cloud to your factory so your team can start factory work without l 4. **Test it.** Assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. + {/* VISUAL: A Jira work item assigned to Warp, showing the resulting agent session. */} + ## Filter which sessions start runs All Jira work reaches the factory through a single event, `agent_session_created`, which fires when someone assigns or mentions **Warp** on a work item. A session starts a run only when it matches an enabled automation. Use the trigger's `filter` to narrow what matches: diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx index 132b36431..52b7f7370 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -33,6 +33,8 @@ Warp then adds a default automation that routes new [agent sessions](#route-agen When someone mentions, assigns, or delegates the Warp app on an issue, Linear starts an agent session. The default automation created when you connected Linear routes new sessions from your selected teams to the factory, so assigning an issue or tagging the factory in a comment is enough to start work. If a session doesn't match any automation, the [Linear integration](/platform/integrations/linear/) handles it with its default behavior. +{/* VISUAL: A Linear issue with an assigned or mentioned Warp agent session. */} + Replies in an existing session continue that run rather than starting a new one. To narrow which sessions reach the factory, such as by creator or keyword, edit the `agent_session_created` trigger in the factory's [definition files](/factories/factory-as-code/); session routing isn't editable from the automation editor. ## Configure Linear triggers diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index a3b480419..b9ca54acc 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -54,7 +54,7 @@ The Slack thread where work started is also where you follow it: the factory pos
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. +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, Complete, 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/). diff --git a/src/content/docs/factories/measure-and-improve.mdx b/src/content/docs/factories/measure-and-improve.mdx index cd9408a94..ed61bf9af 100644 --- a/src/content/docs/factories/measure-and-improve.mdx +++ b/src/content/docs/factories/measure-and-improve.mdx @@ -53,6 +53,8 @@ Configure these fields: * **Pass threshold** - The score a conversation needs to pass. * **Sample rate** - The share of the selected agents' completed conversations to evaluate. +{/* VISUAL: The Scorer create/edit form (judge instructions, judge model, classifications, pass threshold, sample rate). */} + While the sample rate is above 0, scoring runs automatically: shortly after a sampled conversation completes, the judge evaluates it and records a classification, a score, and its reasoning. To stop automatic scoring, set the sample rate to 0. You can also score any single conversation on demand, which is useful for testing new judge instructions before raising the sample rate. Scoring a conversation again replaces its previous result from that Scorer. @@ -75,6 +77,8 @@ Every benchmark also runs **Correctness**, a built-in Scorer that marks each tri ## Configure and review Self-improvement +{/* VISUAL: The Self-improvement pull request list, or a Benchmarks suite run -- this section is text-only today. */} + Turn on **Self-improvement** for each Scorer whose failures you want investigated automatically. Self-improvement groups related failures and files follow-up tasks as ordinary agent runs. A follow-up run can propose changes to application code. It can also improve the factory itself: when you manage your factory as [definitions as code](/factories/factory-as-code/), its prompts, skills, and configuration are version-controlled files, so a follow-up run can open a pull request against the factory definition the same way it would against application code. Nothing is adopted without your review. Each Self-improvement pull request includes a **Regressions addressed** section that links the failing runs and Scorer results behind it, so you can trace the change back to its evidence. diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index b4674cab6..0ff515ba6 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -72,10 +72,10 @@ Warp walks you through a setup wizard: 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. +6. Toggle the agents the foreman can dispatch: **Triage**, **Spec**, **Implement**, and **Review**. All four start enabled, and at least one is required. Leave **Implement** on so this quickstart can end in a pull request. See [factory agents](/factories/factory-agents/) for what each does.
- ![The Pick your factory agents screen, with the Foreman and all four default subagents shown as enabled.](../../../assets/factories/quickstart-pick-agents.png) + ![The Pick your factory agents screen, with the Foreman and all four default agents shown as enabled.](../../../assets/factories/quickstart-pick-agents.png)
Toggle which default agents the foreman can dispatch.
@@ -111,11 +111,11 @@ You can request work from the tools your team already uses. Mention the factory
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. +3. When the Implement 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 * [**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**](/factories/troubleshooting/) - Fixes for common issues during setup and your first runs. +* [**Troubleshooting Warp Factories**](/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 index 634d83d47..78d827bda 100644 --- a/src/content/docs/factories/troubleshooting.mdx +++ b/src/content/docs/factories/troubleshooting.mdx @@ -8,7 +8,7 @@ sidebar: --- import { VARS } from '@data/vars'; -This page covers the problems teams hit most often when setting up a factory and running their first work through it. Each entry names the symptom you'd see in the {VARS.FACTORY_WEB_APP}. +Fix the problems teams hit most often when setting up a factory and running their first work through it. Each entry below names the symptom you'd see in the {VARS.FACTORY_WEB_APP}. ## Setting up a factory @@ -84,7 +84,7 @@ Then check the causes specific to where the work came from: **Cause:** The factory can't push, or the work never reached implementation. -**Fix:** Confirm that the **Code** agent is enabled on the factory, that the code host connection still grants write access to the target repository, and that the work item actually reached the implementation stage. Branch protection rules apply to everything the factory pushes. +**Fix:** Confirm that the **Implement** agent is enabled on the factory, that the code host connection still grants write access to the target repository, and that the work item actually reached the implementation stage. Branch protection rules apply to everything the factory pushes. ## Related pages