From 34ebb3852fa72adadad100a4ca5b9abd57bace35 Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Sat, 10 Oct 2026 00:26:13 +0000 Subject: [PATCH 1/2] docs: scaffold Factory use cases Co-Authored-By: Oz --- .../docs/factories/use-cases/code-review.mdx | 8 +++ .../use-cases/computer-use-verification.mdx | 8 +++ .../use-cases/end-to-end-sdlc-automation.mdx | 8 +++ .../docs/factories/use-cases/index.mdx | 61 +++++++++++++++++++ .../use-cases/issue-implementation.mdx | 8 +++ .../docs/factories/use-cases/issue-triage.mdx | 8 +++ .../production-incident-resolution.mdx | 8 +++ src/sidebar.ts | 12 ++++ 8 files changed, 121 insertions(+) create mode 100644 src/content/docs/factories/use-cases/code-review.mdx create mode 100644 src/content/docs/factories/use-cases/computer-use-verification.mdx create mode 100644 src/content/docs/factories/use-cases/end-to-end-sdlc-automation.mdx create mode 100644 src/content/docs/factories/use-cases/index.mdx create mode 100644 src/content/docs/factories/use-cases/issue-implementation.mdx create mode 100644 src/content/docs/factories/use-cases/issue-triage.mdx create mode 100644 src/content/docs/factories/use-cases/production-incident-resolution.mdx diff --git a/src/content/docs/factories/use-cases/code-review.mdx b/src/content/docs/factories/use-cases/code-review.mdx new file mode 100644 index 000000000..29ddb89ba --- /dev/null +++ b/src/content/docs/factories/use-cases/code-review.mdx @@ -0,0 +1,8 @@ +--- +title: Review pull requests with a factory +description: >- + Configure a factory to inspect pull requests, identify potential bugs, and + return actionable review findings. +--- + +{/* This scaffold is completed by its dependent guide PR. */} diff --git a/src/content/docs/factories/use-cases/computer-use-verification.mdx b/src/content/docs/factories/use-cases/computer-use-verification.mdx new file mode 100644 index 000000000..981bc9df6 --- /dev/null +++ b/src/content/docs/factories/use-cases/computer-use-verification.mdx @@ -0,0 +1,8 @@ +--- +title: Verify changes with Computer Use +description: >- + Configure a factory to exercise rendered interfaces and attach screenshots + or recordings as verification evidence. +--- + +{/* This scaffold is completed by its dependent guide PR. */} diff --git a/src/content/docs/factories/use-cases/end-to-end-sdlc-automation.mdx b/src/content/docs/factories/use-cases/end-to-end-sdlc-automation.mdx new file mode 100644 index 000000000..0620b2acd --- /dev/null +++ b/src/content/docs/factories/use-cases/end-to-end-sdlc-automation.mdx @@ -0,0 +1,8 @@ +--- +title: Automate the software development lifecycle with factories +description: >- + Connect factories across triage, implementation, review, verification, and + human-controlled merging. +--- + +{/* This scaffold is completed by its dependent guide PR. */} diff --git a/src/content/docs/factories/use-cases/index.mdx b/src/content/docs/factories/use-cases/index.mdx new file mode 100644 index 000000000..fc08a3a54 --- /dev/null +++ b/src/content/docs/factories/use-cases/index.mdx @@ -0,0 +1,61 @@ +--- +title: Factory use cases +description: >- + Choose a practical Warp Factories recipe for issue triage, implementation, + code review, incident response, UI verification, or SDLC automation. +sidebar: + label: Overview +--- +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; + +Factory use cases are working patterns for combining agents, automations, integrations, skills, and repository controls. Start with the smallest recipe that solves your current bottleneck, then add stages only when the simpler factory is reliable. + +Each guide links to the canonical configuration and integration references. The examples use definitions as code so you can review changes, validate them in CI, and adapt the same pattern to a Warp-managed factory. + +## Choose a use case + + + + + + + + + + +## Start with the smallest recipe + +Use one factory with the repositories that ship together. Add an automation for one clear intake event, route it to the agent responsible for that task, and make the expected output explicit. Keep a human responsible for approving specifications, accepting risk, and merging changes. + +When a workflow spans several roles, prefer the default foreman, triage, spec, implement, and review agents before creating custom agents. Add a custom skill for repository-specific procedures, such as required test commands or an incident runbook. + +## Related pages + +* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item. +* [Factory agents](/factories/factory-agents/) - Configure the default roles and add custom agents. +* [Factory automations](/factories/automations/) - Route provider events to agents with filters. +* [Factory definition syntax](/factories/factory-as-code/) - Look up configuration keys and validate definitions. diff --git a/src/content/docs/factories/use-cases/issue-implementation.mdx b/src/content/docs/factories/use-cases/issue-implementation.mdx new file mode 100644 index 000000000..bbefc0ed4 --- /dev/null +++ b/src/content/docs/factories/use-cases/issue-implementation.mdx @@ -0,0 +1,8 @@ +--- +title: Implement issues with a factory +description: >- + Configure a factory to turn approved GitHub, Linear, or Jira issues into + tested pull requests. +--- + +{/* This scaffold is completed by its dependent guide PR. */} diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx new file mode 100644 index 000000000..2b13a881e --- /dev/null +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -0,0 +1,8 @@ +--- +title: Triage incoming issues with a factory +description: >- + Configure a factory to investigate, categorize, and prioritize incoming + issues before implementation starts. +--- + +{/* This scaffold is completed by its dependent guide PR. */} diff --git a/src/content/docs/factories/use-cases/production-incident-resolution.mdx b/src/content/docs/factories/use-cases/production-incident-resolution.mdx new file mode 100644 index 000000000..200cc7708 --- /dev/null +++ b/src/content/docs/factories/use-cases/production-incident-resolution.mdx @@ -0,0 +1,8 @@ +--- +title: Resolve production incidents with a factory +description: >- + Configure a factory to investigate production failures and propose or + implement evidence-backed fixes. +--- + +{/* This scaffold is completed by its dependent guide PR. */} diff --git a/src/sidebar.ts b/src/sidebar.ts index 5ac2af3a5..7a77eb880 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -403,6 +403,18 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/quickstart', label: 'Quickstart' }, ], }, + { + label: 'Factory use cases', + items: [ + { slug: 'factories/use-cases', label: 'Overview' }, + { slug: 'factories/use-cases/issue-triage', label: 'Issue triage' }, + { slug: 'factories/use-cases/code-review', label: 'Code review' }, + { slug: 'factories/use-cases/issue-implementation', label: 'Issue implementation' }, + { slug: 'factories/use-cases/production-incident-resolution', label: 'Production incident resolution' }, + { slug: 'factories/use-cases/computer-use-verification', label: 'Computer Use verification' }, + { slug: 'factories/use-cases/end-to-end-sdlc-automation', label: 'End-to-end SDLC automation' }, + ], + }, { // Parallel to 'Agent configuration' in the Automation Platform tab. // Scoped to the factory itself: who runs the work, how it is defined, From 648f5a2c39a5250eca6be35625150ed98b48326d Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Tue, 20 Oct 2026 15:31:45 -0600 Subject: [PATCH 2/2] docs: add Factory issue triage recipe (#896) * docs: add Factory issue triage recipe Co-Authored-By: Oz * docs: clarify supported triage sources Co-Authored-By: Oz * docs: remove scaffold marker * docs: clarify provider issue triggers * docs: fix provider-specific issue triage guidance Co-Authored-By: Warp * docs: test the selected issue triage trigger Co-Authored-By: Warp * docs: reframe issue triage as an existing-factory workflow Co-Authored-By: Warp * docs: prevent overlapping Jira triage routes Co-Authored-By: Warp * docs: apply triage definition changes before testing Co-Authored-By: Warp * docs: clarify issue triage description and introduction Co-Authored-By: Warp * docs: clarify recipes and streamline issue triage setup Co-Authored-By: Warp --------- Co-authored-by: warp-agent-staging[bot] <240773466+warp-agent-staging[bot]@users.noreply.github.com> Co-authored-by: Oz Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Co-authored-by: Warp --- .../docs/factories/use-cases/index.mdx | 2 +- .../docs/factories/use-cases/issue-triage.mdx | 124 +++++++++++++++++- 2 files changed, 121 insertions(+), 5 deletions(-) diff --git a/src/content/docs/factories/use-cases/index.mdx b/src/content/docs/factories/use-cases/index.mdx index fc08a3a54..a6ddb2df4 100644 --- a/src/content/docs/factories/use-cases/index.mdx +++ b/src/content/docs/factories/use-cases/index.mdx @@ -8,7 +8,7 @@ sidebar: --- import { CardGrid, LinkCard } from '@astrojs/starlight/components'; -Factory use cases are working patterns for combining agents, automations, integrations, skills, and repository controls. Start with the smallest recipe that solves your current bottleneck, then add stages only when the simpler factory is reliable. +A recipe is a recommended configuration and set of instructions for completing a specific task with your factory. Recipes combine agents, automations, integrations, skills, and repository controls. Test the recipe's results before expanding the workflow. For example, check that issue triage categorizes issues correctly before adding implementation. Each guide links to the canonical configuration and integration references. The examples use definitions as code so you can review changes, validate them in CI, and adapt the same pattern to a Warp-managed factory. diff --git a/src/content/docs/factories/use-cases/issue-triage.mdx b/src/content/docs/factories/use-cases/issue-triage.mdx index 2b13a881e..c4f0ced4a 100644 --- a/src/content/docs/factories/use-cases/issue-triage.mdx +++ b/src/content/docs/factories/use-cases/issue-triage.mdx @@ -1,8 +1,124 @@ --- -title: Triage incoming issues with a factory +title: Configuring issue triage in your factory description: >- - Configure a factory to investigate, categorize, and prioritize incoming - issues before implementation starts. + Have your factory's triage agent investigate, categorize, and prioritize + incoming issues, then recommend what to do next. --- +Automate issue triage in your factory so incoming issues include a category, priority, supporting evidence, and a recommended next step. Use this pattern when your team spends time gathering information about each issue before deciding what to work on. -{/* This scaffold is completed by its dependent guide PR. */} +This [recipe](/factories/use-cases/) configures an intake automation for your factory's existing triage agent. + +The automation prompt asks the agent to stop after triage, but other workflows in the same factory can continue through specification, implementation, and review. + +## Prerequisites + +* A [factory](/factories/quickstart/) with read access to the relevant repositories. +* A connected issue source ([GitHub](/factories/integrations/github/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/)) with permission to comment on and update issues. +* A triage policy defining categories, priority levels, required evidence, and when to ask a human. +* A test repository or issue-tracker project outside your production backlog. + +## Recommended configuration + +Use the following table to choose the trigger, agent, skills, settings, and expected output for your issue-triage automation. + +| Part | Recommendation | +| --- | --- | +| Trigger | A new issue, a triage label added, or an explicit Jira request | +| Agent | Your factory's existing triage agent | +| Skills | A repo-specific triage skill with category, priority, reproduction, duplicate-search, and escalation rules | +| Settings | Start with one repository and one event; use the Warp Agent harness so built-in code-host tools are available | +| Output | One issue update with evidence, classification, priority, and the recommended next stage | + +## Set up issue triage + +1. Use your factory's existing [triage agent](/factories/factory-agents/#triage) and keep its shared instructions intact. +2. Add `agents/triage/skills/issue-triage/SKILL.md`, using your agent's directory name if different. Define allowed categories and priorities, duplicate-search rules, required evidence, and when to ask a human. Require a code location, duplicate issue, log, or reproduction before assigning a root cause. See [factory skills](/factories/factory-skills/) for the file format. +3. Add or edit an automation for your issue source using the examples below. They use `agent: triage`. Replace `triage` if your agent has a different name, and keep the stopping instructions in the automation prompt. + + Reuse an existing automation when it already handles those requests. Avoid overlapping routes, including a broad issue-created automation and a label automation that could both start work on the same issue. See the [trigger schema](/factories/factory-as-code/#triggers) and [filter reference](/factories/factory-as-code/#triggersfilter) for provider-specific values. + + ### GitHub: Triage newly created issues + + This automation starts on every new issue in `acme/payments-service`. Replace that repository with your own. + + ```markdown title="automations/triage-new-issues/automation.md" + --- + agent: triage + triggers: + - provider: github + event: issue_created + filter: + repos: [acme/payments-service] + --- + + Triage the new issue. Search for duplicates, inspect the relevant code, and + reproduce a bug only when the cause is not already supported by evidence. + Use the repository's triage skill for categories and priority. Ask for missing + evidence rather than guessing. Update the issue with category, priority, scope, + and the next action, then stop. Do not implement or start implementation. + ``` + + For a controlled rollout, change the event to `issue_labeled` and add `labels: [needs-triage]` alongside `repos`. + + ### Azure DevOps: Triage labeled work items + + This automation starts when a work item receives the `needs-triage` label: + + ```markdown title="automations/triage-new-work-items/automation.md" + --- + agent: triage + triggers: + - provider: azure_devops + event: work_item_labeled + filter: + labels: [needs-triage] + --- + + Triage the labeled work item using the repository's triage skill. Update it + with evidence, classification, priority, and the next action, then stop. + Ask for missing evidence rather than guessing. Do not implement or start + implementation. + ``` + + Work item events accept `assignees`, `authors`, `labels`, and `work_item_types`, but not `repos`. Use `work_item_created` instead to triage newly created work items that match those filters. See [Azure DevOps events and filters](/factories/integrations/azure-devops/#supported-events-and-filters) for setup and scope. + + ### Linear + + Use `provider: linear` with `issue_created` or `issue_labeled`. Replace the GitHub example's `repos` filter with Linear team or project filters, and add a label filter for a controlled rollout. + + ### Jira + + Use `provider: jira` with `agent_session_created` and a `project_keys` filter. Check existing automations first. [Jira setup](/factories/integrations/jira/#connect-jira-and-add-an-automation) may already have created one for your projects. + + * **All requests need triage** - Retarget the existing automation to your triage agent and use the triage-only prompt above. + * **Other workflows share the handler** - Keep that handler and narrow both routes' project or keyword filters so each request matches only one automation before adding a separate triage automation. + + Adding a keyword filter to the new route alone doesn't exclude it from an existing project-wide route. A triage-only prompt also doesn't stop another automation from starting its own run. + + ### GitLab + + GitLab has no native issue-created trigger. Use an explicit bot mention or a [custom webhook](/factories/webhooks/). + +4. Apply the definition changes. For a Warp-managed factory, save the edits in the factory dashboard. For a GitHub-backed factory, merge the changes into its configured production branch. Confirm validation succeeds and the changes are applied. See [where the factory definition lives](/factories/factory-as-code/#where-the-definition-lives). +5. Test the selected trigger with an issue or work item that describes a concrete symptom and matches every configured filter: + * **Creation intake** - Create an issue for GitHub or Linear, or a work item for Azure DevOps. Include any labels required by the filter when creating it. + * **Label intake** - Apply `needs-triage` to a test issue or work item after creating it. + * **Jira agent sessions** - Assign or mention **Warp** on a test work item in a matching project and ask it to triage the issue. + + Confirm one run starts, updates the issue or work item with evidence, uses only the allowed labels, and stops without creating a branch. For Jira, also test that a non-triage request still reaches its intended handler. +6. Review several results before expanding the repository or event filters. + +## Example workflow + +A customer opens `Checkout fails after applying two coupons` in `acme/payments-service`. The automation starts the triage agent, which searches for duplicates, identifies the discount calculation path, and reproduces the failure with the supplied cart data. + +The agent labels the issue `bug` and `payments`, assigns the team's `P1` priority according to the skill, and posts the failing test output and affected code path. It recommends implementation because the cause is bounded. If the issue lacks cart data, the agent asks for that evidence and leaves the issue waiting for a human instead. + +To take accepted issues through implementation in the same factory, follow the [issue implementation recipe](/factories/use-cases/issue-implementation/). + +## Related pages + +* [Factory use cases](/factories/use-cases/) - Compare this recipe with other factory workflows. +* [Factory automations](/factories/automations/) - Configure triggers and filters. +* [Factory agents](/factories/factory-agents/) - Understand the default triage role. +* [GitHub integration](/factories/integrations/github/) - Review issue triggers, permissions, and outputs.