From a7b7bcdf93633080f526f50b522663828c35daa8 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 25 Aug 2026 15:06:54 -0600 Subject: [PATCH 01/10] docs(factories): document Skills and Automations primitives, factory sizing guidance - Add automation, runner, and scorer entries to the Warp Factories glossary in terminology.md. - State the 'one factory per product surface, not per workflow' sizing guidance explicitly on the Factories overview, cross-linked from the quickstart and Connect your factory pages. - Add a new Factory skills page covering skills/** vs. agents//skills/** scoping, built-in skills, and when to add a custom one. - Rename Automation filters to Automations and reposition it under Factory configuration as that primitive's conceptual home (was nested under Integrations); update the sidebar, cross-references, and add a redirect. Co-Authored-By: Warp --- .agents/references/terminology.md | 9 +++ ...automation-filters.mdx => automations.mdx} | 12 +-- .../docs/factories/connect-your-factory.mdx | 4 +- src/content/docs/factories/factory-agents.mdx | 2 +- .../docs/factories/factory-as-code.mdx | 2 +- src/content/docs/factories/factory-skills.mdx | 75 +++++++++++++++++++ src/content/docs/factories/index.mdx | 4 +- .../docs/factories/integrations/github.mdx | 4 +- .../docs/factories/integrations/jira.mdx | 4 +- .../docs/factories/integrations/linear.mdx | 2 +- .../docs/factories/integrations/slack.mdx | 2 +- src/content/docs/factories/quickstart.mdx | 2 +- .../docs/factories/troubleshooting.mdx | 6 +- src/sidebar.ts | 25 +++---- vercel.json | 5 ++ 15 files changed, 125 insertions(+), 33 deletions(-) rename src/content/docs/factories/{automation-filters.mdx => automations.mdx} (86%) create mode 100644 src/content/docs/factories/factory-skills.mdx diff --git a/.agents/references/terminology.md b/.agents/references/terminology.md index e33e04198..2ca930658 100644 --- a/.agents/references/terminology.md +++ b/.agents/references/terminology.md @@ -320,6 +320,15 @@ Docs match the screen; the fix belongs in the app. - **factory dashboard** — The web app surface for operating a single factory: its work items, runs, agents, automations, and settings. *Usage note:* Lowercase common noun. Distinct from **Dashboard**, the metrics page inside it, which is also the factory's landing page — bold **Dashboard** when you mean that page, and leave "factory dashboard" unbolded when you mean the surface. Replaced "control room," a docs-only coinage that appeared nowhere in the product. +- **automation** — A factory resource, defined by an `automations//automation.md` file, that starts runs on one or more triggers (a connected-tool event or a schedule) and routes them to a chosen agent, with optional filters and execution overrides. + *Usage note:* Lowercase common noun. Distinct from the **Automation Platform**, the product; and from a **trigger**, the event that fires an automation. + +- **runner** — A factory resource, defined by a `runners/.yaml` file, that defines the compute a run executes on: operating system, architecture, sandbox image, and instance shape. Agents and automations select a runner by name, or inherit the factory's default. + *Usage note:* Lowercase common noun. Scoped to a factory's definition; distinct from the general [cloud agent runner](/platform/runners/) reference, which covers the same concept for standalone cloud agents outside a factory. + +- **Scorer** — An LLM judge, configured per factory, that classifies completed agent conversations against criteria a team defines, scoped to chosen agents and sampled at a set rate. Feeds the **Dashboard** page's Scorer cards, benchmarks, and Self-improvement. + *Usage note:* Capitalize, since it names a specific configured entity in the factory dashboard's UI (parallel to **Dashboard**), not a generic industry term. + - **AI sovereignty** — Warp Factories' positioning around customer ownership and control of inference, hosting, and data exhaust (agent conversations, evals, memories) for their factory. ## Technical terms diff --git a/src/content/docs/factories/automation-filters.mdx b/src/content/docs/factories/automations.mdx similarity index 86% rename from src/content/docs/factories/automation-filters.mdx rename to src/content/docs/factories/automations.mdx index e848e2dec..5b2688243 100644 --- a/src/content/docs/factories/automation-filters.mdx +++ b/src/content/docs/factories/automations.mdx @@ -1,13 +1,15 @@ --- -title: Automation filters +title: Automations description: >- - Automation filters decide which events from connected tools start factory - runs: matching rules, per-source filters, and what filters don't control. + An automation starts factory runs on a trigger from a connected tool or a + schedule, routes them to an agent, and filters which events qualify. sidebar: - label: Automation filters + label: Automations --- -Automation filters decide which events from your connected tools start factory work. Every trigger on a [factory automation](/factories/connect-your-factory/) carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. +An **automation** is a factory resource that starts runs: it declares one or more triggers (an event from a connected tool, or a schedule), the agent that handles the run, and, for connected-tool triggers, the filters that decide which events qualify. Every default automation Warp creates when you connect a provider, and every custom one you add, is this same resource. See [`automations//automation.md`](/factories/factory-as-code/#automationsautomationmd) for the full schema. + +Automation filters decide which events from your connected tools start factory work. Every trigger on an automation carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. ## How matching works diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index c8775e14c..cd40d3006 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -9,6 +9,8 @@ sidebar: Connect your factory to the tools where your team already discusses, tracks, and reviews work. Wherever work starts, the factory keeps the original context — the thread, issue, or pull request — and posts results back to the same place. +Every source below routes into the same factory and its repository set. If the work you're connecting belongs to a different product surface, [size a new factory](/factories/#what-is-a-software-factory) for it instead of routing it into this one. + ## Choose a source 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/). @@ -26,7 +28,7 @@ Pick the sources that match where work starts for your team. You can connect mul ## Connect a 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. +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/automations/) 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. diff --git a/src/content/docs/factories/factory-agents.mdx b/src/content/docs/factories/factory-agents.mdx index f79e6f054..eeac8078f 100644 --- a/src/content/docs/factories/factory-agents.mdx +++ b/src/content/docs/factories/factory-agents.mdx @@ -53,7 +53,7 @@ Review independently examines the change for unmet requirements, broken conventi ## Built-in skills -Every default agent comes with GitHub skills, and the foreman also comes with a Slack skill. The issue tracker you choose during setup adds to that baseline: choosing Linear or Jira gives the agents that tracker's skill and instructions. If you don't choose a tracker, the agents get only the baseline skills. Define custom procedures with [skills](/agents/capabilities/skills/) to extend what an agent can do beyond the built-in set. +Every default agent comes with GitHub skills, and the foreman also comes with a Slack skill. The issue tracker you choose during setup adds to that baseline: choosing Linear or Jira gives the agents that tracker's skill and instructions. If you don't choose a tracker, the agents get only the baseline skills. Define custom procedures with [factory skills](/factories/factory-skills/) to extend what an agent can do beyond the built-in set. ## Configure agent behavior diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index ca996e9ed..2488a4861 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -321,7 +321,7 @@ The operating system and architecture. `os` is `linux` (the default) or `macos`, ## Skills -A skill is a directory containing a `SKILL.md`, not a YAML key. Skills under `skills/` are available to every agent in the factory; skills under `agents//skills/` are available only to that agent. See [Skills for agents](/agents/capabilities/skills/). +A skill is a directory containing a `SKILL.md`, not a YAML key. Skills under `skills/` are available to every agent in the factory; skills under `agents//skills/` are available only to that agent. See [factory skills](/factories/factory-skills/) for when to add one, and [Skills](/agents/capabilities/skills/) for the file format. ## Example factory definition diff --git a/src/content/docs/factories/factory-skills.mdx b/src/content/docs/factories/factory-skills.mdx new file mode 100644 index 000000000..ef2ef92c1 --- /dev/null +++ b/src/content/docs/factories/factory-skills.mdx @@ -0,0 +1,75 @@ +--- +title: Factory skills +description: >- + Skills give a factory's agents repeatable, version-controlled procedures, + shared across every agent or scoped to just one. +sidebar: + label: "Factory skills" +--- + +A skill is a reusable, version-controlled procedure an agent can follow: what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override what the [default agents](/factories/factory-agents/) already know how to do, without editing their prompts directly. + +:::note +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. +::: + +## Factory-wide and per-agent skills + +A skill is a directory containing a `SKILL.md`, not a configuration key, so it follows the factory's [definition](/factories/factory-as-code/) rather than an agent's settings. Where you place that directory decides who can use it: + +```text +skills/ + repository-conventions/ + SKILL.md +agents/ + foreman/ + skills/ + incident-triage/ + SKILL.md +``` + +* **`skills//SKILL.md`** - Available to every agent in the factory. Use this for procedures that apply regardless of role, such as your repository's coding conventions or a shared escalation policy. +* **`agents//skills//SKILL.md`** - Available only to that agent. Use this for procedures specific to one role, such as how the review agent should apply your security checklist. + +Both forms use the same `SKILL.md` format as skills anywhere else in Warp. See [Skills](/agents/capabilities/skills/) for the file format, front matter, and argument syntax. + +## Built-in skills + +Every default agent starts with a baseline of built-in skills so the factory works immediately after setup, before you write anything custom: + +* **GitHub** - Every default agent gets a GitHub skill, covering how to read issues, open pull requests, and follow your repository's conventions. +* **Slack** - The foreman also gets a Slack skill, since it's the agent that replies in threads and DMs. +* **Issue tracker** - The tracker you choose during setup, Linear or Jira, adds that tracker's skill and instructions to the agents that use it. If you don't connect a tracker, agents keep only the GitHub and Slack baseline. + +These baseline skills aren't files in your definition; they come from the agent roles and integrations you choose. Anything you add under `skills/` or `agents//skills/` extends this baseline rather than replacing it. + +## When to add a custom skill + +Add a custom skill when a default agent needs to do something the built-in baseline doesn't cover, such as: + +* Enforcing a specific test, lint, or validation command before a change is considered complete. +* Following a runbook for a category of incident or request your triage agent sees repeatedly. +* Applying a security or compliance checklist during review that goes beyond general code quality. +* Teaching a custom agent (one you've added beyond the defaults) how to do its job at all, since a custom agent has no built-in skills of its own. + +A skill changes what an agent knows how to do, not what it can reach. Scoping what an agent can access is a [secrets](/platform/secrets/) and [MCP server](/platform/mcp/) configuration question, covered in [factory agents](/factories/factory-agents/#configure-agent-behavior) and [infrastructure and security](/factories/infrastructure-and-security/#credential-boundaries). + +## Add or edit a skill + +Where you edit a skill depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives): + +* **Warp-managed** - Add or edit `SKILL.md` files directly in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step. +* **GitHub or GitLab-backed** - Add or edit the files in the connected repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) that validate the rest of the definition apply to skill files. + +For worked examples, including a factory-wide skill and a per-agent skill together, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository. + +## Skills and self-improvement + +Skills are part of what a factory can propose changes to. When [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) is on for a Scorer and it flags a recurring failure, the follow-up run it opens can edit the skill responsible, the same way it can edit application code. The change still arrives as a pull request for your team to review, whether that's through the factory dashboard or your Git host. + +## Related pages + +* [Factory agents](/factories/factory-agents/) - The agents that use a factory's skills, and how to configure each one. +* [Definitions as code](/factories/factory-as-code/) - The full schema for `factory.yaml`, agents, automations, and runners alongside skills. +* [Skills](/agents/capabilities/skills/) - The general skill file format, shared across Warp, cloud agents, and factories. +* [Measure and improve a factory](/factories/measure-and-improve/) - How Self-improvement turns repeated failures into skill and code changes. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 037f81ba3..a8a95dcaa 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -20,6 +20,8 @@ In practice, that means tracking each request as a **work item**, such as an iss 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. +Size a factory by product surface, not by workflow: one factory per repository group that ships as a unit — your main application, your marketing site, your data pipelines — rather than separate factories for each kind of work (frontend, platform, docs) layered on top of repositories another factory already covers. Specialization happens through the factory's [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/), which the foreman can invoke differently per request, not through deploying additional factories over the same repositories. +
![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.
@@ -36,7 +38,7 @@ Warp Factories is designed for engineering teams with repeatable work that exten ## What you get with Warp Factories * **Coordinated specialist agents** - A team of [factory agents](/factories/factory-agents/) handles each work item. A coordinating foreman routes it through the triage, spec, implement, and review agents, skipping stages that don't apply. You can add custom agents and automations to handle work the defaults don't cover. -* **Definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, skills, and MCP servers, so factory changes get the same review, history, and rollback as code changes. +* **Definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, [skills](/factories/factory-skills/), and MCP servers, so factory changes get the same review, history, and rollback as code changes. * **Integrations and the Factory MCP** - Work flows in from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/), plus direct runs and schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. * **Model and harness choice** - Each agent can use a different model and [supported harness](/platform/harnesses/), including the Warp Agent, Claude Code, and Codex. * **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/) grade completed work, and [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) turns repeated failures into follow-up work the factory proposes for review. diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 3cab5a3a2..351b1f0d3 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -29,7 +29,7 @@ To confirm the connection works, mention the factory on a test issue and check t ## Add a custom automation -The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity, such as a failed CI run or a review request, add an automation with a **GitHub** trigger for that event, then narrow it with the filters below. [Automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. +The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity, such as a failed CI run or a review request, add an automation with a **GitHub** trigger for that event, then narrow it with the filters below. [Automation filters](/factories/automations/#edit-filters-on-an-automation) covers the steps. The CI failure triage automation in [`06-common-automations`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/06-common-automations) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository starts work when a workflow run fails on the default branch: @@ -124,7 +124,7 @@ Branches and pull requests the factory creates follow the repository's normal ru 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/automations/) 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 d3f7cb3fb..2e8f23464 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -57,10 +57,10 @@ All Jira work reaches the factory through a single event, `agent_session_created * **`project_keys`** - Match work items in these Jira projects. * **`keywords`** - Match assignment text that contains any of these words. Matching is case-insensitive. -A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. For the matching rules shared by every source, see [automation filters](/factories/automation-filters/). +A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. For the matching rules shared by every source, see [automation filters](/factories/automations/). :::caution -A Jira event is offered to every automation in the connected workspace, so another team's automation with a broader filter can start its own run on the same work item. Filters decide what *your* automation picks up, not who else can see the event. See [automation filters](/factories/automation-filters/#filters-route-work-they-dont-restrict-access). +A Jira event is offered to every automation in the connected workspace, so another team's automation with a broader filter can start its own run on the same work item. Filters decide what *your* automation picks up, not who else can see the event. See [automation filters](/factories/automations/#filters-route-work-they-dont-restrict-access). ::: ## What happens during a run diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx index 52b7f7370..ee6d4686e 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -39,7 +39,7 @@ Replies in an existing session continue that run rather than starting a new one. ## Configure Linear triggers -Agent sessions cover explicit requests. To start work automatically from issue and comment activity too, add an automation with a **Linear** trigger for one of these events: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**. [Automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. +Agent sessions cover explicit requests. To start work automatically from issue and comment activity too, add an automation with a **Linear** trigger for one of these events: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**. [Automation filters](/factories/automations/#edit-filters-on-an-automation) covers the steps. Every Linear trigger filters on teams and labels, and **More filters** adds project, workflow state, assignee, mentioned user, and, for comment events, a specific issue. For example, a trigger can require that an issue belongs to one team, enters a chosen workflow state, and carries a release label. diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index 6cba620c6..435075530 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -25,7 +25,7 @@ Each factory appears in Slack as its own app with the factory's name and avatar. ## Configure factory automations for Slack -Use a factory automation to start work from Slack activity automatically, without anyone mentioning the app, such as on every message in a triage channel or on a specific emoji reaction. Add a **Slack** trigger to an automation and pick one of these events; [automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. +Use a factory automation to start work from Slack activity automatically, without anyone mentioning the app, such as on every message in a triage channel or on a specific emoji reaction. Add a **Slack** trigger to an automation and pick one of these events; [automation filters](/factories/automations/#edit-filters-on-an-automation) covers the steps. - **App mentioned** - Filter by joined conversations, authors, and keywords. - **Direct message received** - Filter by direct-message conversations, authors, and keywords. diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 948a389fd..4283009c7 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -57,7 +57,7 @@ Warp walks you through a setup wizard:
Choose the organization or group whose repositories the factory will use. GitLab shows an equivalent screen for groups.
-3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. +3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. Group repositories by product surface rather than by team or kind of work — see [sizing a factory](/factories/#what-is-a-software-factory) before adding a repository another factory already covers.
![The Select your repos screen, searching for repositories by name.](../../../assets/factories/quickstart-select-repos.png) diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx index 78d827bda..c7ca9ee79 100644 --- a/src/content/docs/factories/troubleshooting.mdx +++ b/src/content/docs/factories/troubleshooting.mdx @@ -45,7 +45,7 @@ Fix the problems teams hit most often when setting up a factory and running thei **Fix:** 1. Confirm the automation is enabled and its trigger's event type matches what happened. -2. Check every filter on the trigger. Filters combine with AND, so a single mismatched repository, label, author, or state stops the routing. See [automation filters](/factories/automation-filters/#troubleshooting). +2. Check every filter on the trigger. Filters combine with AND, so a single mismatched repository, label, author, or state stops the routing. See [automation filters](/factories/automations/#troubleshooting). 3. Confirm the source is connected to *this* factory. Connecting a provider to your workspace doesn't attach it to every factory in that workspace. Then check the causes specific to where the work came from: @@ -62,7 +62,7 @@ Then check the causes specific to where the work came from: **Cause:** Two automations match the same event — commonly an app-mention trigger and a channel-message trigger pointed at the same place. -**Fix:** Narrow or remove one of the overlapping triggers so a single path owns each kind of request. See [how matching works](/factories/automation-filters/#how-matching-works). +**Fix:** Narrow or remove one of the overlapping triggers so a single path owns each kind of request. See [how matching works](/factories/automations/#how-matching-works). ## Runs and work items @@ -90,5 +90,5 @@ Then check the causes specific to where the work came from: * [**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. -* [**Automation filters**](/factories/automation-filters/) - The matching rules that decide which events start work. +* [**Automations**](/factories/automations/) - The matching rules that decide which events start work. * [**Factory dashboard**](/factories/factory-dashboard/) - Where to watch work items, runs, and their outputs. diff --git a/src/sidebar.ts b/src/sidebar.ts index 9bcdf3828..838824cfd 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -404,12 +404,17 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // Parallel to 'Agent configuration' in the Automation Platform tab. // Scoped to the factory itself: who runs the work, how it is defined, // and where it runs. - label: 'Factory configuration', - items: [ - { slug: 'factories/factory-agents', label: 'Factory agents' }, - { slug: 'factories/factory-as-code', label: 'Definitions as code' }, - { slug: 'factories/infrastructure-and-security', label: 'Infrastructure & security' }, - ], + label: 'Factory configuration', + items: [ + { slug: 'factories/factory-agents', label: 'Factory agents' }, + { slug: 'factories/factory-skills', label: 'Factory skills' }, + // Moved from 'Integrations' (was 'Automation filters'): this page is + // now the Automations primitive's conceptual home, parallel to Factory + // agents and Factory skills, not just a filters reference. + { slug: 'factories/automations', label: 'Automations' }, + { slug: 'factories/factory-as-code', label: 'Definitions as code' }, + { slug: 'factories/infrastructure-and-security', label: 'Infrastructure & security' }, + ], }, { // 'Integrations' per HYC (8/17), replacing 'Work intake'. @@ -430,14 +435,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/integrations/gitlab', label: 'GitLab' }, { slug: 'factories/integrations/linear', label: 'Linear' }, { slug: 'factories/integrations/jira', label: 'Jira' }, - // Kept with the integrations rather than moved to Factory - // configuration. Filters act on "events from your connected tools", - // and the page's core reference is a per-source table that links out - // to the Slack, GitHub, and Linear pages directly above. It reads as - // the last step of wiring up a source, not as something you define - // about the factory itself. "It is configuration" does not separate - // it from the integration pages, which are equally configuration. - { slug: 'factories/automation-filters', label: 'Automation filters' }, // Alongside Factory MCP: both are direct API-style connection // mechanisms rather than third-party services, so they trail the // per-service integrations above. diff --git a/vercel.json b/vercel.json index 33467c0d9..cf1548f84 100644 --- a/vercel.json +++ b/vercel.json @@ -82,6 +82,11 @@ "destination": "/factories/", "statusCode": 308 }, + { + "source": "/factories/automation-filters(/?)", + "destination": "/factories/automations/", + "statusCode": 308 + }, { "source": "/cli/", "destination": "/agents/cli/", From 1d274f9f2d717cf3944171f4a4849379fb491f0b Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 25 Aug 2026 15:38:44 -0600 Subject: [PATCH 02/10] Update src/content/docs/factories/factory-skills.mdx Co-authored-by: warp-for-oss[bot] <277970191+warp-for-oss[bot]@users.noreply.github.com> --- src/content/docs/factories/factory-skills.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/factories/factory-skills.mdx b/src/content/docs/factories/factory-skills.mdx index ef2ef92c1..fc2a7b8a5 100644 --- a/src/content/docs/factories/factory-skills.mdx +++ b/src/content/docs/factories/factory-skills.mdx @@ -59,7 +59,7 @@ A skill changes what an agent knows how to do, not what it can reach. Scoping wh Where you edit a skill depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives): * **Warp-managed** - Add or edit `SKILL.md` files directly in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step. -* **GitHub or GitLab-backed** - Add or edit the files in the connected repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) that validate the rest of the definition apply to skill files. +* **GitHub-backed** - Add or edit the files in the connected definition repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) that validate the rest of the definition apply to skill files. For worked examples, including a factory-wide skill and a per-agent skill together, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository. From 1303b6d1ebf0bd8d63a82128dffaa11be3310fdb Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 25 Aug 2026 17:22:46 -0600 Subject: [PATCH 03/10] docs(factories): address review feedback - factory-skills.mdx: correct definition-repo editing to GitHub-backed only; GitLab is not yet a supported definition host. - integrations/github.mdx: remove unnecessary bold on 'GitHub' in prose. - automations.mdx: reword frontmatter description ('from a trigger'); fix the automation.md heading anchor to #automationsnameautomationmd, verified against the deployed preview. - index.mdx: split the overloaded sizing-guidance sentence into two. - quickstart.mdx: move the sizing-guidance addition into a :::note callout. Co-Authored-By: Warp --- src/content/docs/factories/automations.mdx | 6 +++--- src/content/docs/factories/factory-skills.mdx | 2 +- src/content/docs/factories/index.mdx | 2 +- src/content/docs/factories/integrations/github.mdx | 2 +- src/content/docs/factories/quickstart.mdx | 6 +++++- 5 files changed, 11 insertions(+), 7 deletions(-) diff --git a/src/content/docs/factories/automations.mdx b/src/content/docs/factories/automations.mdx index 5b2688243..3278ab3a9 100644 --- a/src/content/docs/factories/automations.mdx +++ b/src/content/docs/factories/automations.mdx @@ -1,13 +1,13 @@ --- title: Automations description: >- - An automation starts factory runs on a trigger from a connected tool or a - schedule, routes them to an agent, and filters which events qualify. + An automation starts factory runs from a trigger, routes them to an agent, + and filters which events qualify. sidebar: label: Automations --- -An **automation** is a factory resource that starts runs: it declares one or more triggers (an event from a connected tool, or a schedule), the agent that handles the run, and, for connected-tool triggers, the filters that decide which events qualify. Every default automation Warp creates when you connect a provider, and every custom one you add, is this same resource. See [`automations//automation.md`](/factories/factory-as-code/#automationsautomationmd) for the full schema. +An **automation** is a factory resource that starts runs: it declares one or more triggers (an event from a connected tool, or a schedule), the agent that handles the run, and, for connected-tool triggers, the filters that decide which events qualify. Every default automation Warp creates when you connect a provider, and every custom one you add, is this same resource. See [`automations//automation.md`](/factories/factory-as-code/#automationsnameautomationmd) for the full schema. Automation filters decide which events from your connected tools start factory work. Every trigger on an automation carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. diff --git a/src/content/docs/factories/factory-skills.mdx b/src/content/docs/factories/factory-skills.mdx index ef2ef92c1..fc2a7b8a5 100644 --- a/src/content/docs/factories/factory-skills.mdx +++ b/src/content/docs/factories/factory-skills.mdx @@ -59,7 +59,7 @@ A skill changes what an agent knows how to do, not what it can reach. Scoping wh Where you edit a skill depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives): * **Warp-managed** - Add or edit `SKILL.md` files directly in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step. -* **GitHub or GitLab-backed** - Add or edit the files in the connected repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) that validate the rest of the definition apply to skill files. +* **GitHub-backed** - Add or edit the files in the connected definition repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) that validate the rest of the definition apply to skill files. For worked examples, including a factory-wide skill and a per-agent skill together, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index a8a95dcaa..b72bf8372 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -20,7 +20,7 @@ In practice, that means tracking each request as a **work item**, such as an iss 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. -Size a factory by product surface, not by workflow: one factory per repository group that ships as a unit — your main application, your marketing site, your data pipelines — rather than separate factories for each kind of work (frontend, platform, docs) layered on top of repositories another factory already covers. Specialization happens through the factory's [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/), which the foreman can invoke differently per request, not through deploying additional factories over the same repositories. +Size a factory by product surface, not by workflow. Group repositories that ship as a unit — your main application, your marketing site, your data pipelines — into one factory, rather than running separate factories for different kinds of work, such as frontend and platform, over repositories another factory already covers. Specialization happens through the factory's [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/), which the foreman can invoke differently per request, not through deploying additional factories over the same repositories.
![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) diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 351b1f0d3..58ec99f78 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -29,7 +29,7 @@ To confirm the connection works, mention the factory on a test issue and check t ## Add a custom automation -The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity, such as a failed CI run or a review request, add an automation with a **GitHub** trigger for that event, then narrow it with the filters below. [Automation filters](/factories/automations/#edit-filters-on-an-automation) covers the steps. +The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity, such as a failed CI run or a review request, add an automation with a GitHub trigger for that event, then narrow it with the filters below. [Automation filters](/factories/automations/#edit-filters-on-an-automation) covers the steps. The CI failure triage automation in [`06-common-automations`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/06-common-automations) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository starts work when a workflow run fails on the default branch: diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 4283009c7..05f2b5ecd 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -57,7 +57,11 @@ Warp walks you through a setup wizard:
Choose the organization or group whose repositories the factory will use. GitLab shows an equivalent screen for groups.
-3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. Group repositories by product surface rather than by team or kind of work — see [sizing a factory](/factories/#what-is-a-software-factory) before adding a repository another factory already covers. +3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. + + :::note + Group repositories by product surface rather than by team or kind of work. See [sizing a factory](/factories/#what-is-a-software-factory) before adding a repository another factory already covers. + :::
![The Select your repos screen, searching for repositories by name.](../../../assets/factories/quickstart-select-repos.png) From 207640900ea3cbfe942b9436e7dd9f0960eadde8 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 26 Aug 2026 11:34:14 -0600 Subject: [PATCH 04/10] docs(guides): cross-link software-factory guides to specific Factories primitives Each DIY guide already pointed to the Warp Factories overview as the managed alternative. Add more specific cross-links to the primitive page that parallels what each guide teaches: - build-a-triage-agent.mdx: Factory agents (Triage role) and the new Factory skills page. - write-product-and-tech-specs-with-agents.mdx: Factory agents (Spec role). - set-up-a-software-factory.mdx: Automations (the label-based state machine's managed equivalent) and Factory agents (all four roles). - run-a-software-factory-in-the-cloud.mdx: Infrastructure and security. build-a-self-improving-agent.mdx already links to the specific Self-improvement anchor, so it's left unchanged. No sizing-guidance callouts added to these guides -- they build one role/repo at a time, so factory-sizing isn't a relevant concept at that scope. Co-Authored-By: Warp --- .../docs/guides/agent-workflows/build-a-triage-agent.mdx | 2 ++ .../agent-workflows/run-a-software-factory-in-the-cloud.mdx | 1 + .../docs/guides/agent-workflows/set-up-a-software-factory.mdx | 2 ++ .../write-product-and-tech-specs-with-agents.mdx | 1 + 4 files changed, 6 insertions(+) diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index 0a8a16fdb..54b6bca53 100644 --- a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -122,6 +122,8 @@ Add repo-specific context without forking the core skill by creating a `triage-i ## Next steps * [Warp Factories overview](/factories/) — The managed product where a triage role like this scopes every incoming work item. +* [Factory agents](/factories/factory-agents/#triage) — The Triage role in the managed product, doing the same job as the agent you just built. +* [Factory skills](/factories/factory-skills/) — How the managed product scopes and shares a skill file like the one you just wrote. * [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Add the spec role once your backlog is well-triaged. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Automate skill improvement based on your corrections. * [GitHub Actions integration](/platform/integrations/github-actions) — Full documentation for `warpdotdev/oz-agent-action`. diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx index 9d6a8bb3e..1eb8c6744 100644 --- a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -97,6 +97,7 @@ See [Multi-agent orchestration](/platform/orchestration) for fan-out, sharding, ## Next steps * [Warp Factories overview](/factories/) — The managed product that runs this same loop end to end. +* [Infrastructure and security](/factories/infrastructure-and-security/) — The managed product's environment, runner, and credential model for the same execution concerns you configured by hand here. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop on a schedule. * [Environments](/platform/environments) — Full reference for cloud agent environments. * [Deployment patterns](/platform/deployment-patterns) — Choose the right architecture for your team. diff --git a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx index 42dd7765e..52657fa25 100644 --- a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx +++ b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx @@ -163,6 +163,8 @@ The reviewer agent surfaces issues and inconsistencies; the human makes the fina ## Next steps * [Warp Factories overview](/factories/) — The managed product that runs this same intake-to-review loop, without the workflow wiring. +* [Automations](/factories/automations/) — The managed product's equivalent of the label-based state machine you just wired by hand. +* [Factory agents](/factories/factory-agents/) — The managed product's take on the same four roles: Triage, Spec, Implement, and Review. * [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop into a managed {VARS.WARP_AUTOMATION_PLATFORM} deployment. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. * [Review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code) — The human review workflow for agent-generated PRs. diff --git a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx index ad3140496..6a8646659 100644 --- a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx +++ b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx @@ -73,6 +73,7 @@ A tech spec defines how the feature will be implemented, including architecture ## Next steps * [Warp Factories overview](/factories/) — The managed product where a spec stage gates implementation the same way. +* [Factory agents](/factories/factory-agents/#spec) — The Spec role in the managed product, gating implementation the same way. * [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) — Connect the spec role to implementation and review. * [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) — The full set of shared skills including `write-product-spec`, `write-tech-spec`, and `validate-changes-match-specs`. * [Planning](/agents/capabilities/planning) — Warp's built-in planning feature for smaller tasks. From 1dae9e62ca6e990ab292a53ede927f1eb9018573 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 26 Aug 2026 11:43:12 -0600 Subject: [PATCH 05/10] fix(check_links): stop stripping -style code-span content as JSX slugify_heading() stripped anything matching <...> before unwrapping code spans, so a heading like `automations//automation.md` lost its placeholder and produced #automationsautomationmd instead of the anchor Starlight actually renders. Verified against the deployed preview's real heading id attributes: agents//agent.md -> #agentsnameagentmd automations//automation.md -> #automationsnameautomationmd runners/.yaml -> #runnersnameyaml This was failing CI on this PR (the link-check job runs this exact script) even though the link in automations.mdx was already correct. Also fixes a pre-existing broken link in factory-as-code.mdx that used the old, incorrect #runnersyaml anchor -- unrelated to this PR's diff, found while investigating the same root cause. Co-Authored-By: Warp --- .../skills/check_for_broken_links/check_links.py | 16 +++++++++++++++- src/content/docs/factories/factory-as-code.mdx | 2 +- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/.agents/skills/check_for_broken_links/check_links.py b/.agents/skills/check_for_broken_links/check_links.py index 4a5af7fd6..3aebcf7a8 100644 --- a/.agents/skills/check_for_broken_links/check_links.py +++ b/.agents/skills/check_for_broken_links/check_links.py @@ -80,11 +80,25 @@ def slugify_heading(text): """Approximate github-slugger, which is what Starlight uses for anchor ids.""" + # Code span contents are literal text, never Markdown/MDX/JSX. Protect them + # from the substitutions below by stashing them first and restoring the raw + # text afterward. Without this, a heading like `automations//automation.md` + # has its `` placeholder stripped as if it were a real JSX tag, even + # though Starlight's actual heading-id generator keeps it (verified against + # the rendered `id` attribute: `automationsnameautomationmd`, not + # `automationsautomationmd`). + code_spans = [] + + def _stash(m): + code_spans.append(m.group(1)) + return f'\x00{len(code_spans) - 1}\x00' + + text = re.sub(r'`([^`]*)`', _stash, text) # code spans (stashed) text = re.sub(r'\{[^}]*\}', '', text) # MDX expressions, e.g. {VARS.X} text = re.sub(r'<[^>]+>', '', text) # inline HTML/JSX - text = re.sub(r'`([^`]*)`', r'\1', text) # code spans text = re.sub(r'\[([^\]]*)\]\([^)]*\)', r'\1', text) # links keep their text text = re.sub(r'[*_]{1,3}', '', text) # emphasis + text = re.sub(r'\x00(\d+)\x00', lambda m: code_spans[int(m.group(1))], text) text = text.strip().lower() text = re.sub(r'[^\w\- ]+', '', text, flags=re.UNICODE) return text.replace(' ', '-') diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 2488a4861..6ca324cc4 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -182,7 +182,7 @@ For a definition that runs a different harness per agent, with managed-secret au ### `agentDefaults.runner` -The name of a runner defined under [`runners/`](#runnersyaml) that provides the compute for runs. +The name of a runner defined under [`runners/`](#runnersnameyaml) that provides the compute for runs. ### `agentDefaults.environmentId` From 3aa54f613fdaaeb4434a608e8d4b1f4f5aa9cc83 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 26 Aug 2026 12:34:13 -0600 Subject: [PATCH 06/10] docs(factories): address review feedback on factory-skills.mdx - Remove awkward colon-led sentence in the opening paragraph. - Say 'GitHub and Slack skills' instead of 'baseline'. - Drop the redundant '-backed' suffix on the GitHub bullet. - Tighten the self-improvement paragraph's phrasing. Co-Authored-By: Warp --- src/content/docs/factories/factory-skills.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/factories/factory-skills.mdx b/src/content/docs/factories/factory-skills.mdx index fc2a7b8a5..be91903e6 100644 --- a/src/content/docs/factories/factory-skills.mdx +++ b/src/content/docs/factories/factory-skills.mdx @@ -7,7 +7,7 @@ sidebar: label: "Factory skills" --- -A skill is a reusable, version-controlled procedure an agent can follow: what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override what the [default agents](/factories/factory-agents/) already know how to do, without editing their prompts directly. +A skill is a reusable, version-controlled procedure an agent can follow. It tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override what the [default agents](/factories/factory-agents/) already know how to do, without editing their prompts directly. :::note 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. @@ -39,7 +39,7 @@ Every default agent starts with a baseline of built-in skills so the factory wor * **GitHub** - Every default agent gets a GitHub skill, covering how to read issues, open pull requests, and follow your repository's conventions. * **Slack** - The foreman also gets a Slack skill, since it's the agent that replies in threads and DMs. -* **Issue tracker** - The tracker you choose during setup, Linear or Jira, adds that tracker's skill and instructions to the agents that use it. If you don't connect a tracker, agents keep only the GitHub and Slack baseline. +* **Issue tracker** - The tracker you choose during setup, Linear or Jira, adds that tracker's skill and instructions to the agents that use it. If you don't connect a tracker, agents keep only the GitHub and Slack skills. These baseline skills aren't files in your definition; they come from the agent roles and integrations you choose. Anything you add under `skills/` or `agents//skills/` extends this baseline rather than replacing it. @@ -59,13 +59,13 @@ A skill changes what an agent knows how to do, not what it can reach. Scoping wh Where you edit a skill depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives): * **Warp-managed** - Add or edit `SKILL.md` files directly in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step. -* **GitHub-backed** - Add or edit the files in the connected definition repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) that validate the rest of the definition apply to skill files. +* **GitHub** - Add or edit the files in the connected definition repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) that validate the rest of the definition apply to skill files. For worked examples, including a factory-wide skill and a per-agent skill together, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository. ## Skills and self-improvement -Skills are part of what a factory can propose changes to. When [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) is on for a Scorer and it flags a recurring failure, the follow-up run it opens can edit the skill responsible, the same way it can edit application code. The change still arrives as a pull request for your team to review, whether that's through the factory dashboard or your Git host. +A factory can propose changes to a skill. When [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) is on for a Scorer and it flags a recurring failure, it can edit the responsible skill in a follow-up run, the same way it can edit application code. The change still arrives as a pull request for your team to review, whether that's through the factory dashboard or your Git host. ## Related pages From dca5aceb4ef3f21adef416b526d31cf9014ae8bd Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 26 Aug 2026 16:22:29 -0600 Subject: [PATCH 07/10] docs(factories): revise for AI-sounding language, wordiness, and scannability Per HYC's review feedback on the PR, plus a broader top-to-bottom pass over every new/touched file for the same issues: - factories/index.mdx: replaced the dense sizing paragraph with a new 'Sizing a factory' subheading and a bulleted list of concrete examples, instead of one long sentence stacking an em-dash clause and a parenthetical. - factories/quickstart.mdx: added a concrete example to the sizing callout. - factories/connect-your-factory.mdx: rewrote two AI-sounding passages (semicolon-heavy 'X; Y' construction, 'Filters route work, not access: ...' aphorism) into plainer sentences, cutting a point already covered in full on the Automations page. - factory-skills.mdx: tightened three more passages (nominalizations, redundant parentheticals) beyond the earlier review-comment fixes. - The 4 DIY guides: removed the repeated 'the manage- The 4 DIY guides: removed the repeated 'the manage- The 4 DIY guides: removed the repeated 'the manage- The 4 DIY guides: removed the repeated 'the muthored-By: Warp --- src/content/docs/factories/connect-your-factory.mdx | 4 ++-- src/content/docs/factories/factory-skills.mdx | 6 +++--- src/content/docs/factories/index.mdx | 10 +++++++++- src/content/docs/factories/quickstart.mdx | 2 +- .../guides/agent-workflows/build-a-triage-agent.mdx | 6 +++--- .../run-a-software-factory-in-the-cloud.mdx | 4 ++-- .../agent-workflows/set-up-a-software-factory.mdx | 6 +++--- .../write-product-and-tech-specs-with-agents.mdx | 4 ++-- 8 files changed, 25 insertions(+), 17 deletions(-) diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index cd40d3006..8e7215ead 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -9,7 +9,7 @@ sidebar: Connect your factory to the tools where your team already discusses, tracks, and reviews work. Wherever work starts, the factory keeps the original context — the thread, issue, or pull request — and posts results back to the same place. -Every source below routes into the same factory and its repository set. If the work you're connecting belongs to a different product surface, [size a new factory](/factories/#what-is-a-software-factory) for it instead of routing it into this one. +Every source below feeds into this factory's repositories. If the work belongs to a different product surface, [start a new factory](/factories/#sizing-a-factory) for it instead. ## Choose a source @@ -28,7 +28,7 @@ Pick the sources that match where work starts for your team. You can connect mul ## Connect a 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/automations/) 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. +Each integration guide walks through authorizing access — grant only what the factory needs. New connections add default automations, so events start working right away. Review the [automations](/factories/automations/) and adjust their filters and run settings to fit your workflow. 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. diff --git a/src/content/docs/factories/factory-skills.mdx b/src/content/docs/factories/factory-skills.mdx index be91903e6..2b4062b9e 100644 --- a/src/content/docs/factories/factory-skills.mdx +++ b/src/content/docs/factories/factory-skills.mdx @@ -15,7 +15,7 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ ## Factory-wide and per-agent skills -A skill is a directory containing a `SKILL.md`, not a configuration key, so it follows the factory's [definition](/factories/factory-as-code/) rather than an agent's settings. Where you place that directory decides who can use it: +A skill is a directory containing a `SKILL.md`. It's part of the factory's [definition](/factories/factory-as-code/), not an agent's settings. Where you place the directory decides who can use it: ```text skills/ @@ -50,9 +50,9 @@ Add a custom skill when a default agent needs to do something the built-in basel * Enforcing a specific test, lint, or validation command before a change is considered complete. * Following a runbook for a category of incident or request your triage agent sees repeatedly. * Applying a security or compliance checklist during review that goes beyond general code quality. -* Teaching a custom agent (one you've added beyond the defaults) how to do its job at all, since a custom agent has no built-in skills of its own. +* Teaching a custom agent its job. Custom agents have no built-in skills. -A skill changes what an agent knows how to do, not what it can reach. Scoping what an agent can access is a [secrets](/platform/secrets/) and [MCP server](/platform/mcp/) configuration question, covered in [factory agents](/factories/factory-agents/#configure-agent-behavior) and [infrastructure and security](/factories/infrastructure-and-security/#credential-boundaries). +A skill changes what an agent knows how to do, not what it can reach. To scope access, configure the agent's [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/) — see [factory agents](/factories/factory-agents/#configure-agent-behavior) and [infrastructure and security](/factories/infrastructure-and-security/#credential-boundaries). ## Add or edit a skill diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index b72bf8372..d012272c4 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -20,7 +20,15 @@ In practice, that means tracking each request as a **work item**, such as an iss 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. -Size a factory by product surface, not by workflow. Group repositories that ship as a unit — your main application, your marketing site, your data pipelines — into one factory, rather than running separate factories for different kinds of work, such as frontend and platform, over repositories another factory already covers. Specialization happens through the factory's [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/), which the foreman can invoke differently per request, not through deploying additional factories over the same repositories. +### Sizing a factory + +Size factories by product surface, not by workflow. Group the repositories that ship together into one factory. For example: + +* One factory for your main application +* One factory for your marketing site +* One factory for your data pipelines + +Don't split those same repositories across multiple factories by team or task (frontend vs. platform, for example). Add [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/) to specialize instead.
![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) diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 05f2b5ecd..ae425a5d4 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -60,7 +60,7 @@ Warp walks you through a setup wizard: 3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. :::note - Group repositories by product surface rather than by team or kind of work. See [sizing a factory](/factories/#what-is-a-software-factory) before adding a repository another factory already covers. + Group repositories by product surface, not by team or task — for example, all the repos behind one application. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. :::
diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index 54b6bca53..21964e395 100644 --- a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -121,9 +121,9 @@ Add repo-specific context without forking the core skill by creating a `triage-i ## Next steps -* [Warp Factories overview](/factories/) — The managed product where a triage role like this scopes every incoming work item. -* [Factory agents](/factories/factory-agents/#triage) — The Triage role in the managed product, doing the same job as the agent you just built. -* [Factory skills](/factories/factory-skills/) — How the managed product scopes and shares a skill file like the one you just wrote. +* [Warp Factories overview](/factories/) — Warp's product for running this same loop without the manual wiring. +* [Factory agents](/factories/factory-agents/#triage) — The Triage agent role, doing the same job as the agent you just built. +* [Factory skills](/factories/factory-skills/) — How Warp Factories scopes and shares a skill file like the one you just wrote. * [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Add the spec role once your backlog is well-triaged. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Automate skill improvement based on your corrections. * [GitHub Actions integration](/platform/integrations/github-actions) — Full documentation for `warpdotdev/oz-agent-action`. diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx index 1eb8c6744..6167264f4 100644 --- a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -96,8 +96,8 @@ See [Multi-agent orchestration](/platform/orchestration) for fan-out, sharding, ## Next steps -* [Warp Factories overview](/factories/) — The managed product that runs this same loop end to end. -* [Infrastructure and security](/factories/infrastructure-and-security/) — The managed product's environment, runner, and credential model for the same execution concerns you configured by hand here. +* [Warp Factories overview](/factories/) — Warp's product for running this same loop end to end. +* [Infrastructure and security](/factories/infrastructure-and-security/) — The environment, runner, and credential model behind the concerns you configured by hand here. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop on a schedule. * [Environments](/platform/environments) — Full reference for cloud agent environments. * [Deployment patterns](/platform/deployment-patterns) — Choose the right architecture for your team. diff --git a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx index 52657fa25..509738e38 100644 --- a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx +++ b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx @@ -162,9 +162,9 @@ The reviewer agent surfaces issues and inconsistencies; the human makes the fina ## Next steps -* [Warp Factories overview](/factories/) — The managed product that runs this same intake-to-review loop, without the workflow wiring. -* [Automations](/factories/automations/) — The managed product's equivalent of the label-based state machine you just wired by hand. -* [Factory agents](/factories/factory-agents/) — The managed product's take on the same four roles: Triage, Spec, Implement, and Review. +* [Warp Factories overview](/factories/) — Warp's product for running this same intake-to-review loop without the workflow wiring. +* [Automations](/factories/automations/) — Replaces the label-based state machine you just wired by hand. +* [Factory agents](/factories/factory-agents/) — The same four roles — Triage, Spec, Implement, Review — as managed agents. * [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop into a managed {VARS.WARP_AUTOMATION_PLATFORM} deployment. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. * [Review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code) — The human review workflow for agent-generated PRs. diff --git a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx index 6a8646659..f0983809b 100644 --- a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx +++ b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx @@ -72,8 +72,8 @@ A tech spec defines how the feature will be implemented, including architecture ## Next steps -* [Warp Factories overview](/factories/) — The managed product where a spec stage gates implementation the same way. -* [Factory agents](/factories/factory-agents/#spec) — The Spec role in the managed product, gating implementation the same way. +* [Warp Factories overview](/factories/) — Warp's product for running this same loop without the manual wiring. +* [Factory agents](/factories/factory-agents/#spec) — The Spec agent role, gating implementation the same way. * [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) — Connect the spec role to implementation and review. * [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) — The full set of shared skills including `write-product-spec`, `write-tech-spec`, and `validate-changes-match-specs`. * [Planning](/agents/capabilities/planning) — Warp's built-in planning feature for smaller tasks. From a637e21a1d116f1c98f9ae4089bc5e916a8815a9 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 27 Aug 2026 11:17:10 -0600 Subject: [PATCH 08/10] Address latest round of language/copy review comments - Simplify integration guide phrasing pointing to Automations - Rewrite automations.mdx opening, filters paragraph, and H2 heading for clarity and brevity (em dash and semicolon cleanup) - Tighten connect-your-factory.mdx wording and rename a table column - Rewrite factory-skills.mdx description/intro, move Early Access note right after frontmatter - Apply reviewer-suggested sizing callout text in quickstart.mdx - Add cross-reference to factory sizing guidance from how-factories-work.mdx - Fix stale anchor in jira.mdx after automations.mdx heading rename Co-Authored-By: Warp --- src/content/docs/factories/automations.mdx | 12 ++++++------ src/content/docs/factories/connect-your-factory.mdx | 6 +++--- src/content/docs/factories/factory-skills.mdx | 8 ++++---- src/content/docs/factories/how-factories-work.mdx | 2 ++ src/content/docs/factories/integrations/github.mdx | 2 +- 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/quickstart.mdx | 2 +- 9 files changed, 20 insertions(+), 18 deletions(-) diff --git a/src/content/docs/factories/automations.mdx b/src/content/docs/factories/automations.mdx index 3278ab3a9..8561a652d 100644 --- a/src/content/docs/factories/automations.mdx +++ b/src/content/docs/factories/automations.mdx @@ -2,18 +2,18 @@ title: Automations description: >- An automation starts factory runs from a trigger, routes them to an agent, - and filters which events qualify. + and filters which events start a run. sidebar: label: Automations --- -An **automation** is a factory resource that starts runs: it declares one or more triggers (an event from a connected tool, or a schedule), the agent that handles the run, and, for connected-tool triggers, the filters that decide which events qualify. Every default automation Warp creates when you connect a provider, and every custom one you add, is this same resource. See [`automations//automation.md`](/factories/factory-as-code/#automationsnameautomationmd) for the full schema. +An **automation** is a factory resource that starts runs from a trigger and routes them to an agent. Triggers fired by a connected tool also carry filters that decide which events start a run. Every default automation Warp creates when you connect a provider, and every custom one you add, is this same resource. See [`automations//automation.md`](/factories/factory-as-code/#automationsnameautomationmd) for the full schema. -Automation filters decide which events from your connected tools start factory work. Every trigger on an automation carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. +Automation filters decide which events from your connected tools start factory work. Every trigger on an automation carries filters (e.g., a repository, channel, team, project, label, or author) and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. ## How matching works -An event starts an automation only when it matches the trigger's provider, its event type, and every filter set on that trigger: +An event starts an automation only when it matches the trigger's provider, event type, and filters: * **Every filter must match.** A trigger that sets both a team and a label matches only events carrying both. * **Within one filter, any value matches.** A **Labels** filter listing `bug` and `regression` matches an issue with either label. @@ -21,9 +21,9 @@ An event starts an automation only when it matches the trigger's provider, its e One event can match more than one automation, and each match starts its own run. If a single action starts duplicate runs, narrow or remove one of the overlapping triggers. -## Filters route work; they don't restrict access +## Filters don't control access -Filters decide when work starts, not what a running agent can reach. Access comes from what you authorize on each provider — the GitHub App installation, the GitLab bot's project membership, the Slack app's authorization, the Linear OAuth scope, or the Jira app installation. Tightening a filter never shrinks that access, and removing one never widens it. To change what an integration can reach, change what you authorize for that provider. +Filters decide when work starts, not what a running agent can reach. Access comes from what you authorize on each provider: the GitHub App installation, the GitLab bot's project membership, the Slack app's authorization, the Linear OAuth scope, or the Jira app installation. Tightening a filter never shrinks that access, and removing one never widens it. To change what an integration can reach, change what you authorize for that provider. Filters are still your main control over who starts runs. On GitHub and GitLab, the event author doesn't need to be a Warp team member, so use author, member, and branch filters to decide whose activity starts work. Slack mentions and direct messages additionally require a Slack account linked to a member of the factory's Warp team. diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index 8e7215ead..eca61c797 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -7,15 +7,15 @@ sidebar: label: "Connect your factory" --- -Connect your factory to the tools where your team already discusses, tracks, and reviews work. Wherever work starts, the factory keeps the original context — the thread, issue, or pull request — and posts results back to the same place. +Connect your factory to the tools where your team already discusses, tracks, and reviews work. Wherever work starts, the factory keeps the original context from that source (the thread, issue, or pull request), and posts results in the same place. -Every source below feeds into this factory's repositories. If the work belongs to a different product surface, [start a new factory](/factories/#sizing-a-factory) for it instead. +Each source feeds into this factory's repositories. If the work belongs to a different product surface, [start a new factory](/factories/#sizing-a-factory) for it instead. ## Choose a source 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 | +| Source | Best for | Continues in | | --- | --- | --- | | [Slack](/factories/integrations/slack/) | Chat and support requests | The Slack thread or DM | | [GitHub](/factories/integrations/github/) | Issues, pull requests, reviews, and CI | The issue, pull request, or review thread | diff --git a/src/content/docs/factories/factory-skills.mdx b/src/content/docs/factories/factory-skills.mdx index 2b4062b9e..a5c5ad333 100644 --- a/src/content/docs/factories/factory-skills.mdx +++ b/src/content/docs/factories/factory-skills.mdx @@ -1,18 +1,18 @@ --- title: Factory skills description: >- - Skills give a factory's agents repeatable, version-controlled procedures, - shared across every agent or scoped to just one. + Skills give a factory's agents repeatable, version-controlled procedures + that can be shared across every agent or scoped to just one. sidebar: label: "Factory skills" --- -A skill is a reusable, version-controlled procedure an agent can follow. It tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override what the [default agents](/factories/factory-agents/) already know how to do, without editing their prompts directly. - :::note 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. ::: +A skill tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override [default agents](/factories/factory-agents/), without editing their prompts directly. + ## Factory-wide and per-agent skills A skill is a directory containing a `SKILL.md`. It's part of the factory's [definition](/factories/factory-as-code/), not an agent's settings. Where you place the directory decides who can use it: diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index 6e2c5fd54..d6b5eb75f 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -13,6 +13,8 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ A factory is a team of cloud agents that ships software the way your team does: a request comes in, moves through the stages it needs, and comes back as a pull request ready for review. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle. +Deciding which repositories belong in this factory is a separate question. See [sizing a factory](/factories/#sizing-a-factory) for that guidance. + A **work item** is a single request the factory acts on, such as an issue, support request, pull request, or Factory MCP task. It keeps its identity from intake to handoff, however many agents contribute to it along the way. ## How a work item moves through the factory diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 58ec99f78..628610683 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -29,7 +29,7 @@ To confirm the connection works, mention the factory on a test issue and check t ## Add a custom automation -The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity, such as a failed CI run or a review request, add an automation with a GitHub trigger for that event, then narrow it with the filters below. [Automation filters](/factories/automations/#edit-filters-on-an-automation) covers the steps. +The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity, such as a failed CI run or a review request, add an automation with a GitHub trigger for that event, then narrow it with the filters below. To learn how to edit those filters, see [Automations](/factories/automations/#edit-filters-on-an-automation). The CI failure triage automation in [`06-common-automations`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/06-common-automations) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository starts work when a workflow run fails on the default branch: diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 2e8f23464..1e74b441e 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -60,7 +60,7 @@ All Jira work reaches the factory through a single event, `agent_session_created A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. For the matching rules shared by every source, see [automation filters](/factories/automations/). :::caution -A Jira event is offered to every automation in the connected workspace, so another team's automation with a broader filter can start its own run on the same work item. Filters decide what *your* automation picks up, not who else can see the event. See [automation filters](/factories/automations/#filters-route-work-they-dont-restrict-access). +A Jira event is offered to every automation in the connected workspace, so another team's automation with a broader filter can start its own run on the same work item. Filters decide what *your* automation picks up, not who else can see the event. See [Automations](/factories/automations/#filters-dont-control-access). ::: ## What happens during a run diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx index ee6d4686e..882e558a4 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -39,7 +39,7 @@ Replies in an existing session continue that run rather than starting a new one. ## Configure Linear triggers -Agent sessions cover explicit requests. To start work automatically from issue and comment activity too, add an automation with a **Linear** trigger for one of these events: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**. [Automation filters](/factories/automations/#edit-filters-on-an-automation) covers the steps. +Agent sessions cover explicit requests. To start work automatically from issue and comment activity too, add an automation with a **Linear** trigger for one of these events: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**. To learn how to edit those filters, see [Automations](/factories/automations/#edit-filters-on-an-automation). Every Linear trigger filters on teams and labels, and **More filters** adds project, workflow state, assignee, mentioned user, and, for comment events, a specific issue. For example, a trigger can require that an issue belongs to one team, enters a chosen workflow state, and carries a release label. diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index 435075530..d51d242ca 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -25,7 +25,7 @@ Each factory appears in Slack as its own app with the factory's name and avatar. ## Configure factory automations for Slack -Use a factory automation to start work from Slack activity automatically, without anyone mentioning the app, such as on every message in a triage channel or on a specific emoji reaction. Add a **Slack** trigger to an automation and pick one of these events; [automation filters](/factories/automations/#edit-filters-on-an-automation) covers the steps. +Use a factory automation to start work from Slack activity automatically, without anyone mentioning the app, such as on every message in a triage channel or on a specific emoji reaction. Add a **Slack** trigger to an automation and pick one of these events. To learn how to edit those filters, see [Automations](/factories/automations/#edit-filters-on-an-automation). - **App mentioned** - Filter by joined conversations, authors, and keywords. - **Direct message received** - Filter by direct-message conversations, authors, and keywords. diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index ae425a5d4..ac569d2fd 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -60,7 +60,7 @@ Warp walks you through a setup wizard: 3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. :::note - Group repositories by product surface, not by team or task — for example, all the repos behind one application. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. + Group repositories by product surface, not by team or task. For example, group all the repos behind one application. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. :::
From c9ef7330693d80c6cdbd152d77cc1a65a0590df7 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 27 Aug 2026 12:01:09 -0600 Subject: [PATCH 09/10] Remove remaining em dash in automations.mdx Replace em dash with a colon in the "What each source can filter on" intro sentence, per review feedback. Co-Authored-By: Warp --- src/content/docs/factories/automations.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/factories/automations.mdx b/src/content/docs/factories/automations.mdx index 8561a652d..7b6bfe0ec 100644 --- a/src/content/docs/factories/automations.mdx +++ b/src/content/docs/factories/automations.mdx @@ -29,7 +29,7 @@ Filters are still your main control over who starts runs. On GitHub and GitLab, ## What each source can filter on -Every source filters on where the event happened — a repository, project, conversation, or team. The remaining filters vary by source and event type: +Every source filters on where the event happened: a repository, project, conversation, or team. The remaining filters vary by source and event type: | Source | Filters | | --- | --- | From d6888154c7797377167514cf5086647a81f9c2a8 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 27 Aug 2026 13:07:09 -0600 Subject: [PATCH 10/10] Link integration pages to the canonical automation event-slug reference The Slack, GitHub, and Linear integration pages describe triggers by prose/UI label only, with no pointer to the exact `event:` value each one maps to in an automation.md file. Add a one-line cross-link from each page's trigger section to the existing event-slug list in factory-as-code.mdx, rather than duplicating those slugs on every page. Jira and GitLab already state their event slugs inline, so they are unchanged. Co-Authored-By: Warp --- src/content/docs/factories/integrations/github.mdx | 2 ++ src/content/docs/factories/integrations/linear.mdx | 2 ++ src/content/docs/factories/integrations/slack.mdx | 2 ++ 3 files changed, 6 insertions(+) diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 628610683..7b4d2708d 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -71,6 +71,8 @@ For a review automation that fires when pull requests open, see [`04-code-review Re-running a check starts work only for checks Warp itself created. GitHub doesn't send re-run events for other providers' checks, so those can't trigger a factory. +For the exact `event` value each trigger uses in a definition file, see [triggers](/factories/factory-as-code/#triggers). + ### Automation filters Every trigger names the repository it watches. The remaining filters appear only on the event types they apply to: diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx index 882e558a4..cc5a612ca 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -43,6 +43,8 @@ Agent sessions cover explicit requests. To start work automatically from issue a Every Linear trigger filters on teams and labels, and **More filters** adds project, workflow state, assignee, mentioned user, and, for comment events, a specific issue. For example, a trigger can require that an issue belongs to one team, enters a chosen workflow state, and carries a release label. +For the exact `event` value each of these triggers uses in a definition file, see [triggers](/factories/factory-as-code/#triggers). + ## Supported events and outputs Each event determines the context the agent receives and the updates the factory sends back. diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index d51d242ca..854792138 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -33,6 +33,8 @@ Use a factory automation to start work from Slack activity automatically, withou - **Reaction added** - Filter by conversations, reactors, keywords, emoji, and reacted-message authors. - **Member joined channel** - Filter by conversations and members. +For the exact `event` value each of these triggers uses in a definition file, see [triggers](/factories/factory-as-code/#triggers). + The reaction-intake automation in [`06-common-automations`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/06-common-automations) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository files a GitHub issue when someone reacts with `:ticket:`: ```markdown title="automations/slack-reaction-intake/automation.md"