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/.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/automation-filters.mdx b/src/content/docs/factories/automations.mdx similarity index 78% rename from src/content/docs/factories/automation-filters.mdx rename to src/content/docs/factories/automations.mdx index e848e2dec..7b6bfe0ec 100644 --- a/src/content/docs/factories/automation-filters.mdx +++ b/src/content/docs/factories/automations.mdx @@ -1,17 +1,19 @@ --- -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 from a trigger, routes them to an agent, + and filters which events start a run. 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 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 (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. @@ -19,15 +21,15 @@ 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. ## 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 | | --- | --- | diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index c8775e14c..eca61c797 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -7,13 +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. + +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 | @@ -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 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-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..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` @@ -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..a5c5ad333 --- /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 + that can be shared across every agent or scoped to just one. +sidebar: + label: "Factory skills" +--- + +:::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: + +```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 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. + +## 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 its job. Custom agents have no built-in skills. + +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 + +Where you edit a skill depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives): + +* **Warp-managed** - Add or edit `SKILL.md` files directly in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step. +* **GitHub** - Add or edit the files in the connected definition repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks-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 + +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 + +* [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/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/index.mdx b/src/content/docs/factories/index.mdx index 037f81ba3..d012272c4 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -20,6 +20,16 @@ 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. +### 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)
The general software factory loop. Warp Factories' default agents cover triage through review; add custom agents for the rest.
@@ -36,7 +46,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..7b4d2708d 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. 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: @@ -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: @@ -124,7 +126,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..1e74b441e 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 [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 52b7f7370..cc5a612ca 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -39,10 +39,12 @@ 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**. 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. +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 6cba620c6..854792138 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. 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. @@ -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" diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 948a389fd..ac569d2fd 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -59,6 +59,10 @@ 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, group all the repos behind one application. See [sizing a factory](/factories/#sizing-a-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)
Search for and select the repositories the factory works in.
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/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index 0a8a16fdb..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,7 +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. +* [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 9d6a8bb3e..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,7 +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. +* [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 42dd7765e..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,7 +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. +* [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 ad3140496..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,7 +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. +* [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. 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/",