From 2cf55282507dd49e49a53fa2b04a6b9b970b9472 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:02 +0000 Subject: [PATCH 1/3] docs: add Factory issue implementation recipe Co-Authored-By: Oz --- .../use-cases/issue-implementation.mdx | 72 ++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/src/content/docs/factories/use-cases/issue-implementation.mdx b/src/content/docs/factories/use-cases/issue-implementation.mdx index bbefc0ed4..01f6e2f29 100644 --- a/src/content/docs/factories/use-cases/issue-implementation.mdx +++ b/src/content/docs/factories/use-cases/issue-implementation.mdx @@ -1,8 +1,78 @@ --- -title: Implement issues with a factory +title: Implementing issues with a factory description: >- Configure a factory to turn approved GitHub, Linear, or Jira issues into tested pull requests. --- +An implementation factory picks up an approved issue, determines the shortest safe path through planning and code changes, validates the result, and opens a pull request. Use this pattern when your backlog already distinguishes ready work from requests that still need triage or product decisions. +The factory hands the pull request to a person. It doesn't merge by default. + +## Prerequisites + +* **A code-host connection** - Connect the factory to the repositories it may change and grant branch and pull request write access. +* **One issue source** - Connect [GitHub](/factories/integrations/github/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/). +* **A ready-work signal** - Use a label, workflow state, or explicit assignment that means requirements are approved. +* **Repository validation** - Document the build, test, lint, and formatting commands the implement agent must run. +* **Protected merges** - Keep required review and merge authority in the code host. + +## Recommended recipe + +Route ready work to the foreman, not directly to the implement agent. The foreman can skip unnecessary stages, request a specification for ambiguous work, and send the finished change through independent review. + +| Source | Recommended trigger | Ready-work filter | +| --- | --- | --- | +| GitHub | `issue_labeled` | A label such as `factory-ready` | +| Linear | `issue_state_changed` | A workflow state such as `Ready for Engineering` | +| Jira | `agent_session_created` | Assignment text with a keyword such as `implement` | + +Use the default foreman, triage, spec, implement, and review roles. Add a shared repository-conventions skill and an implementation skill that names required validation and visual-proof rules. + +```markdown title="automations/implement-approved-issues/automation.md" +--- +agent: foreman +triggers: + - provider: github + event: issue_labeled + filter: + repos: [acme/payments-service] + labels: [factory-ready] +--- + +Implement the approved issue. Preserve its acceptance criteria. Use the +shortest safe factory path, ask a human before resolving product ambiguity, +run the repository's required validation, and open a draft pull request. +Never merge. +``` + +## Configure issue implementation + +1. Create a factory for repositories that ship together, then enable the default foreman, implement, and review agents. Keep triage and spec enabled if incoming work can still contain uncertainty. +2. Connect one issue source. For Linear and Jira, connect repository access separately because tracker authorization doesn't permit code changes. +3. Define the ready-work signal with your maintainers. The signal must mean the issue has a clear outcome and enough context to start. +4. Add the matching automation. For GitHub, use the example above. For Linear, select **Issue state changed** and the approved state. For Jira, route an **Agent session created** event with a narrow project and keyword filter. +5. Add repository-specific skills. Require the implement agent to add meaningful tests, run the documented checks, and capture visual evidence for user-facing changes. +6. Test with a small documentation or configuration issue. Confirm the factory links the pull request back to the source issue and leaves merging to a person. + +## Example workflow + +A Linear issue asks for validation on a new `currency` API field and moves to `Ready for Engineering`. The automation routes the issue to the foreman. Because the acceptance criteria are explicit, the foreman skips triage and planning and dispatches implementation. + +The implement agent adds validation and regression tests, runs the service test suite, and opens a draft pull request linked to the Linear issue. The review agent checks the API behavior and tests. The foreman posts the pull request and validation result back to Linear, where a maintainer decides whether to merge. + +## Best practices + +* **Make readiness explicit** - Don't start implementation from every new issue. +* **Keep one intake owner** - Avoid overlapping label, assignment, and comment automations for the same issue. +* **Preserve source criteria** - Tell the foreman to carry acceptance criteria into the pull request and validation. +* **Use the spec gate selectively** - Require human approval for new behavior or unresolved tradeoffs, but let small, clear fixes proceed. +* **Limit credentials** - Grant only the repositories, secrets, and MCP servers needed for the change. +* **Keep review independent** - Follow the [code review recipe](/factories/use-cases/code-review/) before human handoff. + +## Related pages + +* [Factory use cases](/factories/use-cases/) - Compare implementation with narrower factory recipes. +* [How Warp Factories work](/factories/how-factories-work/) - Understand stage skipping, revision, and human handoff. +* [Factory agents](/factories/factory-agents/) - Configure foreman, implement, and review roles. +* [Factory skills](/factories/factory-skills/) - Add repository-specific implementation procedures. {/* This scaffold is completed by its dependent guide PR. */} From daedd3a7c4a370f5f6c108912c491b6cbbe56d57 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 2/3] docs: remove scaffold marker --- src/content/docs/factories/use-cases/issue-implementation.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/factories/use-cases/issue-implementation.mdx b/src/content/docs/factories/use-cases/issue-implementation.mdx index 01f6e2f29..8c6605f5d 100644 --- a/src/content/docs/factories/use-cases/issue-implementation.mdx +++ b/src/content/docs/factories/use-cases/issue-implementation.mdx @@ -75,4 +75,3 @@ The implement agent adds validation and regression tests, runs the service test * [How Warp Factories work](/factories/how-factories-work/) - Understand stage skipping, revision, and human handoff. * [Factory agents](/factories/factory-agents/) - Configure foreman, implement, and review roles. * [Factory skills](/factories/factory-skills/) - Add repository-specific implementation procedures. -{/* This scaffold is completed by its dependent guide PR. */} From d3d8e58691c28c7b17794bd16e531afe33096f50 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 21 Oct 2026 16:23:00 -0600 Subject: [PATCH 3/3] docs: clarify issue implementation recipe and intake setup Co-Authored-By: Warp --- .../use-cases/issue-implementation.mdx | 154 ++++++++++++------ 1 file changed, 104 insertions(+), 50 deletions(-) diff --git a/src/content/docs/factories/use-cases/issue-implementation.mdx b/src/content/docs/factories/use-cases/issue-implementation.mdx index 8c6605f5d..59516528b 100644 --- a/src/content/docs/factories/use-cases/issue-implementation.mdx +++ b/src/content/docs/factories/use-cases/issue-implementation.mdx @@ -1,73 +1,127 @@ --- -title: Implementing issues with a factory +title: Configuring issue implementation in your factory description: >- - Configure a factory to turn approved GitHub, Linear, or Jira issues into - tested pull requests. + Automate implementation of approved issues with your factory, from + readiness signals to validated pull requests for human review. --- -An implementation factory picks up an approved issue, determines the shortest safe path through planning and code changes, validates the result, and opens a pull request. Use this pattern when your backlog already distinguishes ready work from requests that still need triage or product decisions. +import { Tabs, TabItem } from '@astrojs/starlight/components'; -The factory hands the pull request to a person. It doesn't merge by default. +Turn approved issues into code changes and pull requests with your existing factory. Use this pattern when your team distinguishes work that's ready to implement from issues that still need investigation or product decisions. + +This [recipe](/factories/use-cases/) routes approved issues to the foreman, which coordinates implementation and independent review. It can request research or a specification when needed. The automation prompt leaves specification approval and merging to people. Enforce merge permissions through your code host's branch protection and required reviews. ## Prerequisites -* **A code-host connection** - Connect the factory to the repositories it may change and grant branch and pull request write access. -* **One issue source** - Connect [GitHub](/factories/integrations/github/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/). -* **A ready-work signal** - Use a label, workflow state, or explicit assignment that means requirements are approved. -* **Repository validation** - Document the build, test, lint, and formatting commands the implement agent must run. -* **Protected merges** - Keep required review and merge authority in the code host. +* A [factory](/factories/quickstart/) with access to the target repositories and permission to push branches and open pull requests. +* A connected issue source ([GitHub](/factories/integrations/github/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/)) with permission to read and update issues. +* Approved issues with acceptance criteria and a readiness label, workflow state, or explicit request. +* Documented build, test, lint, and formatting commands. +* Required reviews and protected merge permissions in the code host. -## Recommended recipe +## Recommended configuration -Route ready work to the foreman, not directly to the implement agent. The foreman can skip unnecessary stages, request a specification for ambiguous work, and send the finished change through independent review. +Use the following table to choose the intake signal, agents, skills, and expected output for your implementation automation. -| Source | Recommended trigger | Ready-work filter | -| --- | --- | --- | -| GitHub | `issue_labeled` | A label such as `factory-ready` | -| Linear | `issue_state_changed` | A workflow state such as `Ready for Engineering` | -| Jira | `agent_session_created` | Assignment text with a keyword such as `implement` | +| Part | Recommendation | +| --- | --- | +| Trigger | A readiness label, an approved workflow state, or an explicit Jira implementation request | +| Agents | Foreman, implement, and review, with triage and spec available when needed | +| Skills | Shared repository conventions and implementation-specific validation procedures | +| Settings | Limit intake to the relevant repositories, team, or project | +| Output | A pull request linked to the source issue, validation results, and a review report | -Use the default foreman, triage, spec, implement, and review roles. Add a shared repository-conventions skill and an implementation skill that names required validation and visual-proof rules. +## Set up issue implementation -```markdown title="automations/implement-approved-issues/automation.md" ---- -agent: foreman -triggers: - - provider: github - event: issue_labeled - filter: - repos: [acme/payments-service] - labels: [factory-ready] ---- +1. Use your factory's existing [foreman, implement, and review agents](/factories/factory-agents/#the-default-agents). Keep triage and spec available for issues that need investigation or planning. Preserve the agents' shared instructions. +2. Add shared repository guidance under `skills/` and implementation procedures under `agents/implement/skills/`, using your agent's directory name if different. Record required checks, tests for behavior changes, and when to ask a human. Include visual-evidence requirements for user-facing changes. See [factory skills](/factories/factory-skills/) for the file format. +3. Add or edit an automation that targets `agent: foreman`, replacing `foreman` if yours has a different name. Choose a signal that maintainers apply after approving the issue's requirements. A label, state, or request routes work but doesn't independently verify approval. -Implement the approved issue. Preserve its acceptance criteria. Use the -shortest safe factory path, ask a human before resolving product ambiguity, -run the repository's required validation, and open a draft pull request. -Never merge. -``` + Check existing label, assignment, comment, and agent-session automations before adding a route. Reuse an existing automation where appropriate, or narrow overlapping filters so one request doesn't start duplicate work. -## Configure issue implementation + Select your issue source from the tabs below, then follow the instructions to configure the automation. -1. Create a factory for repositories that ship together, then enable the default foreman, implement, and review agents. Keep triage and spec enabled if incoming work can still contain uncertainty. -2. Connect one issue source. For Linear and Jira, connect repository access separately because tracker authorization doesn't permit code changes. -3. Define the ready-work signal with your maintainers. The signal must mean the issue has a clear outcome and enough context to start. -4. Add the matching automation. For GitHub, use the example above. For Linear, select **Issue state changed** and the approved state. For Jira, route an **Agent session created** event with a narrow project and keyword filter. -5. Add repository-specific skills. Require the implement agent to add meaningful tests, run the documented checks, and capture visual evidence for user-facing changes. -6. Test with a small documentation or configuration issue. Confirm the factory links the pull request back to the source issue and leaves merging to a person. + + -## Example workflow + This automation starts when `factory-ready` is applied to an issue in `acme/payments-service`. Replace the repository and label with your own. + + ```markdown title="automations/implement-approved-issues/automation.md" + --- + agent: foreman + triggers: + - provider: github + event: issue_labeled + filter: + repos: [acme/payments-service] + labels: [factory-ready] + --- + + Implement the approved issue against its acceptance criteria. Ask a human + about missing requirements or product decisions rather than guessing. + If the triggering request asks only for information or investigation, + do not implement. + If a specification is needed, obtain approval before implementing it. + Delegate implementation, run the repository's required checks, and obtain + independent review. Continue an existing specification PR when provided. + Return the pull request link, validation results, and review findings to + the source issue. Report any failed or unverified checks. Never merge. + ``` + + For events sent by bots, see the published [GitHub bot-event policy](https://docs.warp.dev/factories/integrations/github/#events-from-bots-dont-start-work). + + + + + Copy `agent: foreman` and the implementation prompt from the GitHub tab's `automations/implement-approved-issues/automation.md` example. Replace its entire `triggers` list with the configuration below. Replace `Payments` and `Ready for Engineering` with the team and approved workflow-state names in your connected Linear workspace. + + ```yaml title="Linear implementation trigger" + triggers: + - provider: linear + event: issue_state_changed + filter: + teams: [Payments] + states: [Ready for Engineering] + ``` -A Linear issue asks for validation on a new `currency` API field and moves to `Ready for Engineering`. The automation routes the issue to the foreman. Because the acceptance criteria are explicit, the foreman skips triage and planning and dispatches implementation. + The trigger matches issues entering the selected state, including issues created in that state. Name-based filters are resolved through the connected Linear integration when the definition is applied. Connecting Linear doesn't grant repository access. -The implement agent adds validation and regression tests, runs the service test suite, and opens a draft pull request linked to the Linear issue. The review agent checks the API behavior and tests. The foreman posts the pull request and validation result back to Linear, where a maintainer decides whether to merge. + + + + Copy `agent: foreman` and the implementation prompt from the GitHub tab's `automations/implement-approved-issues/automation.md` example. Replace its entire `triggers` list with the configuration below, using your Jira project key in place of `ENG`. + + ```yaml title="Jira implementation trigger" + triggers: + - provider: jira + event: agent_session_created + filter: + project_keys: [ENG] + labels: [factory-ready] + ``` + + After approving the issue, apply `factory-ready`, then assign or mention **Warp** with an explicit request such as “Implement this issue against its acceptance criteria.” The label must be present when the session starts. Follow the [Jira setup and account-linking requirements](/factories/integrations/jira/). + + Jira setup may already have created a project-wide session automation. Update that automation if it handles only implementation requests. Otherwise, preserve its other workflows and make both routes' filters nonoverlapping before adding this one. Adding the readiness label to the new route's filter alone doesn't exclude those requests from a broader existing route. + + + + +4. Apply the definition changes before testing. Save edits in the factory dashboard for a Warp-managed factory, or merge them into the configured production branch for a GitHub-backed factory. Confirm validation succeeds and the changes are applied. See [where the factory definition lives](/factories/factory-as-code/#where-the-definition-lives). +5. Test with a fresh, approved documentation or configuration issue that matches every filter. + * **GitHub** - Apply the readiness label. + * **Linear** - Move the issue into the approved state, or create it in that state. + * **Jira** - Apply the readiness label, then assign or mention **Warp** with the implementation request. + + Confirm the foreman coordinates implementation and review, posts the pull request link and validation results to the issue, and leaves merging to a person. Check that this automation doesn't start when the required label or state is missing, or the issue belongs to a different team or project. + + These examples configure initial intake. If the factory already tracks an issue as a work item, send an explicit implementation request in its existing conversation rather than assuming a new intake prompt will replace the current instructions. +6. Test missing requirements and failed validation. Confirm the foreman asks for clarification or specification approval when needed and reports failed checks rather than claiming success. Review the results before widening the automation's filters. + +## Example workflow -## Best practices +A Linear issue requests validation for a `currency` API field and specifies the accepted codes, error response, and required tests. A maintainer approves the requirements and moves it to `Ready for Engineering`. The automation routes the issue to the foreman, which delegates implementation. -* **Make readiness explicit** - Don't start implementation from every new issue. -* **Keep one intake owner** - Avoid overlapping label, assignment, and comment automations for the same issue. -* **Preserve source criteria** - Tell the foreman to carry acceptance criteria into the pull request and validation. -* **Use the spec gate selectively** - Require human approval for new behavior or unresolved tradeoffs, but let small, clear fixes proceed. -* **Limit credentials** - Grant only the repositories, secrets, and MCP servers needed for the change. -* **Keep review independent** - Follow the [code review recipe](/factories/use-cases/code-review/) before human handoff. +The implement agent adds validation and regression tests, runs the service checks, and opens a pull request linked to the issue. The review agent checks the behavior and tests and reports to the foreman. The foreman posts the pull request and verification results to Linear for a maintainer to review and merge. ## Related pages