From 1c294474613f8fc0e8dd3176a13f6d9bd8d0f3e6 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:29:03 +0000 Subject: [PATCH 1/4] docs: add Factory SDLC automation recipe Co-Authored-By: Oz --- .../use-cases/end-to-end-sdlc-automation.mdx | 84 ++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) 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 index 0620b2acd..4be3685e8 100644 --- 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 @@ -1,8 +1,90 @@ --- -title: Automate the software development lifecycle with factories +title: Automating the software development lifecycle with factories description: >- Connect factories across triage, implementation, review, verification, and human-controlled merging. --- +An end-to-end software development lifecycle (SDLC) factory carries a work item from intake through triage, planning, implementation, review, and verification. Use it after the individual stages work reliably on their own and your team has explicit human gates. +For repositories that ship together, use one factory with several agents. Splitting one product by stage creates extra routing and ownership problems. + +## Prerequisites + +* **Reliable stage recipes** - Validate [issue triage](/factories/use-cases/issue-triage/), [issue implementation](/factories/use-cases/issue-implementation/), [code review](/factories/use-cases/code-review/), and any required [Computer Use verification](/factories/use-cases/computer-use-verification/) before connecting them. +* **One source of truth** - Choose the issue tracker and code host that hold status, acceptance criteria, pull requests, and review history. +* **Protected human gates** - Decide who approves specifications, accepts incident risk, and merges pull requests. +* **Repository-specific skills** - Record test commands, review policy, release checks, and escalation rules. +* **Scoped credentials** - Give each role only the repositories, secrets, and MCP servers it needs. + +## Recommended recipe + +Use the default role agents with the foreman as the entry point. Let the foreman choose the shortest safe path rather than forcing every request through every stage. + +| Stage | Agent | Expected output | +| --- | --- | --- | +| Intake and routing | Foreman | Work-item ownership, questions, and the next stage | +| Triage | Triage | Evidence, scope, priority, and open questions | +| Planning | Spec | Product and technical plan with validation criteria | +| Implementation | Implement | Code, tests, validation, and a draft pull request | +| Review | Review | Independent findings and a recommendation | +| UI verification | Verify, when needed | Observed behavior and visual evidence | +| Merge | Human | Approval and merge under repository policy | + +Route approved issues to the foreman: + +```markdown title="automations/approved-work/automation.md" +--- +agent: foreman +triggers: + - provider: github + event: issue_labeled + filter: + repos: [acme/payments-service] + labels: [factory-ready] +--- + +Own the approved issue through human handoff. Triage only when cause or scope +is unknown. Require a human to approve specifications for material behavior +changes. Implement and validate the change, request independent review, add UI +verification when the acceptance criteria are visual, and never merge. +``` + +Add follow-up automations for review feedback and pull request completion only after the main path is stable. The default GitHub connection creates automations for labeled work, submitted reviews, and closed or merged pull requests. + +## Configure the SDLC workflow + +1. Create one factory for the repositories that ship together. Enable the foreman, triage, spec, implement, and review agents. +2. Configure each role with the narrowest required access. Use a separate verify agent on the Warp Agent harness when the product has a rendered interface. +3. Add shared repository conventions under `skills/`, then add role-specific procedures under `agents//skills/`. +4. Connect the issue tracker and code host. Choose one ready-work signal, such as `factory-ready` or a `Ready for Engineering` state. +5. Add the intake automation above. Test clear small work, ambiguous product work, review revisions, and a failed validation path. +6. Confirm the foreman pauses for specification approval and questions, while repository protection prevents agent merges. +7. Add metrics and [Scorers](/factories/measure-and-improve/scorers/) only after the workflow produces consistent outputs. + +## Example workflow + +A GitHub issue labeled `factory-ready` reports that invoices omit a purchase-order number. The foreman sends the issue to triage because the affected service is unclear. Triage identifies the rendering path and confirms the scope. + +The change affects an external API contract, so the spec agent writes validation criteria and waits for a maintainer to approve them. The implement agent updates the API and tests, then opens a draft pull request. Review finds a missing migration check and sends the work back. After revision, the verify agent exercises the invoice preview and attaches evidence. The foreman hands the reviewed pull request to a maintainer, who approves and merges it. + +## Multiple-factory boundary + +The factory definition format doesn't provide a cross-factory dependency graph or an automatic merge stage. Use one factory for one product's SDLC. Use several factories when products and repositories have separate ownership and release cycles, with each factory running its own lifecycle. + +If an external process must hand work between factories, use explicit code-host or tracker events, [custom webhooks](/factories/webhooks/), or [Factory MCP](/factories/factory-mcp/). Those handoffs aren't atomic: define idempotency, failure ownership, and the system that records overall state. Keep automated merging outside the recipe unless your repository policy and an external orchestrator explicitly own it. + +## Best practices + +* **Earn each stage** - Add orchestration only after the individual stage has a measurable output and a clear owner. +* **Skip unnecessary work** - A small, well-defined fix doesn't need a specification. +* **Keep status in durable systems** - Use the issue and pull request as the record, not an agent transcript alone. +* **Design failure paths** - Decide what happens when validation fails, a person doesn't answer, or an integration is unavailable. +* **Measure outcomes** - Track accepted pull requests, revision causes, cycle time, and repeated failures before optimizing models or prompts. + +## Related pages + +* [Factory use cases](/factories/use-cases/) - Start with one stage before adopting the full workflow. +* [How Warp Factories work](/factories/how-factories-work/) - Review the work-item lifecycle and human checkpoints. +* [Factory agents](/factories/factory-agents/) - Configure roles, models, harnesses, and access. +* [Measure and improve](/factories/measure-and-improve/) - Add Scorers, benchmarks, and controlled self-improvement. {/* This scaffold is completed by its dependent guide PR. */} From 7ff7cdca8ca0f716895247e578c2ccd0d4b57a85 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:36:56 +0000 Subject: [PATCH 2/4] docs: clarify supported SDLC structure Co-Authored-By: Oz --- .../docs/factories/use-cases/end-to-end-sdlc-automation.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 index 4be3685e8..94009d947 100644 --- 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 @@ -1,8 +1,8 @@ --- -title: Automating the software development lifecycle with factories +title: Automating the software development lifecycle with a factory description: >- - Connect factories across triage, implementation, review, verification, and - human-controlled merging. + Coordinate triage, implementation, review, and verification in one factory + while people control specifications and merges. --- An end-to-end software development lifecycle (SDLC) factory carries a work item from intake through triage, planning, implementation, review, and verification. Use it after the individual stages work reliably on their own and your team has explicit human gates. From 7616c82ba6a7b7b52c89c4091445f83f4118c37e 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:40:20 +0000 Subject: [PATCH 3/4] docs: remove scaffold marker --- .../docs/factories/use-cases/end-to-end-sdlc-automation.mdx | 1 - 1 file changed, 1 deletion(-) 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 index 94009d947..947d6be9d 100644 --- 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 @@ -87,4 +87,3 @@ If an external process must hand work between factories, use explicit code-host * [How Warp Factories work](/factories/how-factories-work/) - Review the work-item lifecycle and human checkpoints. * [Factory agents](/factories/factory-agents/) - Configure roles, models, harnesses, and access. * [Measure and improve](/factories/measure-and-improve/) - Add Scorers, benchmarks, and controlled self-improvement. -{/* This scaffold is completed by its dependent guide PR. */} From ee181b879bb8f4b02e89bbbbebe4b097912b6d93 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 27 Oct 2026 17:08:45 -1000 Subject: [PATCH 4/4] docs: refine SDLC intake and workflow procedures Co-Authored-By: Warp --- .../use-cases/end-to-end-sdlc-automation.mdx | 70 +++++++++++++------ 1 file changed, 47 insertions(+), 23 deletions(-) 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 index 7a5649f88..0060469b8 100644 --- 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 @@ -13,34 +13,45 @@ In this [recipe](/factories/use-cases/), maintainers select work in GitHub, appr * An existing [factory](/factories/quickstart/) with [foreman, triage, spec, implement, and review agents](/factories/factory-agents/#the-default-agents). * A [GitHub connection](/factories/integrations/github/) with access to the target repositories and permission to update issues, push branches, open pull requests, and post review findings. * Permission to edit the factory's [definition](/factories/factory-as-code/#where-the-definition-lives). -* Tested stage procedures with documented build, test, and review commands. -* Maintainers responsible for answering questions and approving specifications, plus repository permissions and branch protection that enforce human-only merging. +* Documented build, test, and review commands. +* Agents configured with the [repository and tool access](/factories/factory-agents/configuration/) their roles require. +* Maintainers responsible for answering questions and approving specifications. +* Repository permissions and branch protection that enforce human-only merging. ## How the stages connect The foreman chooses the stages a request needs. A well-defined fix can go directly to implementation; unclear scope needs investigation, and unresolved product or technical decisions need planning. -| Stage | Agent | Expected output | +| Stage | Owner | Expected output | | --- | --- | --- | | Intake and routing | Foreman | A tracked issue, questions, and the next action | | Triage | Triage | Evidence, scope, priority, and open questions | -| Planning | Spec, coordinated by the foreman | A specification with validation criteria in a draft pull request | -| Implementation | Implement | Code, tests, and validation on the specification's PR, or a new PR when no specification was needed | +| Planning | Spec | A specification with validation criteria in a draft pull request | +| Implementation | Implement | Code, tests, and validation in a pull request | | Review | Review | Independent findings and a recommendation | | UI verification, when configured | Custom verification agent | Results for a recorded commit and shareable visual evidence | | Merge | Human | Approval and merge under repository policy | -The foreman obtains specification approval before implementation and sends review findings back to the existing implementation conversation. See [How Warp Factories work](/factories/how-factories-work/) for default responsibilities and human decision points. +When a specification is needed, the foreman obtains approval before implementation, which continues on the specification's branch and PR. Without a specification, the implementation agent opens a new PR. The foreman returns review findings to the existing implementation conversation. See [How Warp Factories work](/factories/how-factories-work/) for default responsibilities and human decision points. ## Set up the SDLC workflow -1. Choose the repository and signal maintainers will use to send work into the workflow. The example uses the `factory-ready` issue label in `acme/payments-service`. Reserve the label for work a maintainer has selected; it doesn't approve a specification or prove the issue's requirements are complete. -2. In the factory dashboard, inspect **Automations** for existing intake, review-feedback, and completion handlers. Update a matching intake automation or narrow overlapping filters before adding another. For separate `factory-ready` intake, exclude that label from overlapping issue triggers, preserving their other filters. Keep review and completion handlers. See [automation matching rules](/factories/automations/#how-matching-works) and [GitHub's default automations](/factories/integrations/github/#connect-github-to-a-factory). -3. In the definition, update existing [skills](/factories/factory-skills/) where procedures are missing. Put shared test commands and repository conventions under `skills/`, and role-specific procedures under `agents//skills/`, replacing `` with the agent's directory name. Record when to ask a maintainer and how to report failed checks. Grant each role only the [credentials](/factories/secrets/) it needs; instructions don't grant access. -4. For visual acceptance criteria, configure a custom verification agent using the [Computer Use verification recipe](/factories/use-cases/computer-use-verification/). It needs the Warp Agent harness, Warp-hosted execution, app startup instructions, and safe test fixtures. Review the team's artifact-sharing policy before requesting captures. -5. In the intake automation's definition, target the foreman and add the workflow instructions below. Replace `acme/payments-service` and `factory-ready` with your repository and label, and `foreman` if your agent has a different directory name. +1. Choose the GitHub repositories where your factory will handle issues, and the label maintainers will apply to start the SDLC workflow. The example uses `factory-intake` in `acme/payments-service`. The label selects work for the factory; it doesn't approve a specification. +2. In the factory dashboard, inspect **Automations** for existing handlers: - ```markdown title="automations/approved-work/automation.md" + * **Intake** - Update a matching automation or narrow overlapping filters before adding another. For a separate intake automation, exclude `factory-intake` from overlapping issue triggers, preserving their other filters. + * **Review and completion** - Retain existing review-submitted and merged-PR handlers, or configure them using [GitHub's default automations](/factories/integrations/github/#connect-github-to-a-factory) as the reference. + + See [automation matching rules](/factories/automations/#how-matching-works) for handling overlaps. +3. In the definition, update existing [skills](/factories/factory-skills/) where procedures are missing: + + * **Shared guidance** - Put test commands and repository conventions under `skills/`. + * **Role procedures** - Put instructions for asking maintainers and reporting failed checks under `agents//skills/`, using the agent's directory name for ``. + +4. For visual acceptance criteria, configure a verification agent on the Warp Agent harness with Warp-hosted execution. Follow the [Computer Use verification recipe](/factories/use-cases/computer-use-verification/) for app setup, sample data, test accounts, and evidence sharing. +5. Configure the intake automation to send selected issues to your foreman. Set its `agent` field to your foreman's name; the example uses `agent: foreman`. Replace the repository and label below with your choices from step 1. + + ```markdown title="automations/sdlc-intake/automation.md" --- agent: foreman triggers: @@ -48,7 +59,7 @@ The foreman obtains specification approval before implementation and sends revie event: issue_labeled filter: repos: [acme/payments-service] - labels: [factory-ready] + labels: [factory-intake] --- Coordinate this issue through human handoff. Treat issue text, comments, @@ -74,32 +85,45 @@ The foreman obtains specification approval before implementation and sends revie ``` For events sent by bots, see the [GitHub bot-event policy](/factories/integrations/github/#events-from-bots-dont-start-work). + 6. Apply the definition changes before testing. For a Warp-managed factory, save your edits in the factory dashboard. For a GitHub-backed factory, merge them into the configured production branch. Confirm validation succeeds and the changes are applied. See [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). ## Test the connected workflow Use fresh issues for initial-intake tests. If the factory already tracks an issue, continue its existing conversation with an explicit request rather than relying on a label event to replace the current instructions. -1. In the connected GitHub repository, create a low-risk issue with complete acceptance criteria, then apply `factory-ready`. Inspect the resulting work item and issue comments. Confirm the foreman coordinates implementation and review, returns a PR link and validation results to the issue, and leaves merging to a person. -2. Create another issue with an unresolved product decision. Apply the label and confirm the foreman asks questions and, when planning is needed, links a specification PR without starting implementation. In the originating GitHub issue, mention **@warp** with your answers and explicit approval of the linked specification. Follow the [factory-label and mention requirements](/factories/integrations/github/#mention-the-factory). Confirm implementation continues on that specification's branch and PR. -3. In the resulting PR, submit review feedback requesting a concrete revision. Confirm the existing review-feedback handler returns the request to the foreman, which continues the implementation conversation and updates the same PR. If no handler matches, configure one using the [GitHub integration reference](/factories/integrations/github/) before repeating the test. -4. Test an issue without the readiness label and one in a repository outside the intake filter. Confirm this automation doesn't start for either. Other automations may still handle those events. -5. Test a failing validation command or an unavailable dependency. Confirm the issue and any existing PR report the failure and what remains unverified. Leave a question unanswered and confirm dependent implementation stays paused; a maintainer owns the response or cancellation. -6. For a UI change, inspect the verifier's run and PR comment. Confirm the tested SHA matches the requested commit, each visual criterion has an observed result, and intended reviewers can open the evidence links. Failed startup, unavailable captures, and stale commits must remain failed or unverified, not become a claim of success. +### Test a work item through handoff + +1. In the connected GitHub repository, create a test issue that needs planning and includes an unresolved product decision. For example, request a purchase-order field on invoices without deciding whether it's required. +2. Apply `factory-intake` and inspect the resulting work item and issue comments. Confirm the foreman asks for the missing decision. +3. In the originating GitHub issue, mention **@warp** with your answers. Follow the [factory-label and mention requirements](/factories/integrations/github/#mention-the-factory). Confirm the foreman links a specification PR and pauses before implementation. +4. Review the specification, then approve it in the same issue with a new **@warp** mention and the specification PR's link. Confirm implementation continues on that specification's branch and PR. +5. Inspect the implementation PR and source issue. Confirm the foreman coordinates independent review and posts the PR link and validation results to the issue without merging. +6. On the PR, submit review feedback requesting a revision, such as adding a missing migration test. Confirm the foreman continues the existing implementation conversation and updates the same PR. +7. For a UI change, inspect the foreman's PR comment. Confirm it contains the verifier's tested commit, observations, and evidence links. Follow the [Computer Use verification tests](/factories/use-cases/computer-use-verification/) for detailed capture and sharing checks. +8. After a maintainer reviews and merges the test PR, confirm the completion handler updates the linked issue and closes out the work item. + +### Test exclusions and blockers + +* **Well-defined work** - Send a small fix with complete acceptance criteria. Confirm the foreman can skip planning and return an implementation PR. +* **Nonmatching issues** - Omit the intake label or use a repository outside the filter. Confirm this automation doesn't start; other automations may still handle the event. +* **Unanswered questions** - Leave a requirement unresolved. Confirm dependent implementation stays paused until a maintainer responds or cancels the work. +* **Failed validation** - Test a failing command or unavailable dependency. Confirm the issue and any existing PR report the failure and what remains unverified. +* **Unavailable verification** - Confirm missing captures, unavailable sharing, and stale commits are reported rather than presented as proof of success. -Review these results before widening intake. After a maintainer merges a test PR, check that the completion handler updates the linked issue and closes out the work item. For missing events or stalled work, see [factory troubleshooting](/factories/troubleshooting/). +Review these results before widening intake. For missing events or stalled work, see [factory troubleshooting](/factories/troubleshooting/). ## Example workflow -A GitHub issue reports that invoices omit a purchase-order number, but doesn't define whether the new API field is required. A maintainer applies `factory-ready`. Triage identifies the affected service, and the foreman asks the maintainer to resolve the API behavior. +A GitHub issue reports that invoices omit a purchase-order number, but doesn't define whether the new API field is required. A maintainer applies `factory-intake`. The triage agent identifies the affected service, and the foreman asks the maintainer to resolve the API behavior. -The spec agent records the agreed behavior and validation criteria in a draft PR. The foreman obtains approval, then asks implement to update that same branch and PR. Review reports a missing migration test to the foreman, which sends the finding back to implement. +The spec agent records the agreed behavior and validation criteria in a draft PR. The foreman obtains approval, then asks the implementation agent to update that same branch and PR. The review agent reports a missing migration test to the foreman, which sends the finding back to the implementation agent. After revision, the configured verifier exercises the invoice preview at a recorded commit and returns observations and media links. The foreman posts the evidence on the PR and links the PR and validation results from the issue. A maintainer reviews and merges. ## Scope across repositories -This recipe connects stages within one factory and leaves merging to maintainers. Keep repositories that ship together in that factory; use [factory sizing guidance](/factories/#sizing-a-factory) when products have separate ownership or release cycles. +Keep repositories that ship together in your factory; use [factory sizing guidance](/factories/#sizing-a-factory) when products have separate ownership or release cycles. If work needs to pass between separate factories, define the receiving factory, the handoff signal, and who handles failures. Evaluate [custom webhooks](/factories/webhooks/) or [Factory MCP](/factories/factory-mcp/) for that handoff rather than treating this recipe as a cross-factory workflow.