From fe605af0dfd73299e3e4e3f067f730924c0c1b2c 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:01 +0000 Subject: [PATCH 1/3] docs: add Factory code review recipe Co-Authored-By: Oz --- .../docs/factories/use-cases/code-review.mdx | 85 ++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) diff --git a/src/content/docs/factories/use-cases/code-review.mdx b/src/content/docs/factories/use-cases/code-review.mdx index 29ddb89ba..7d7263383 100644 --- a/src/content/docs/factories/use-cases/code-review.mdx +++ b/src/content/docs/factories/use-cases/code-review.mdx @@ -1,8 +1,91 @@ --- -title: Review pull requests with a factory +title: Reviewing pull requests with a factory description: >- Configure a factory to inspect pull requests, identify potential bugs, and return actionable review findings. --- +A review factory examines a pull request against its requirements, repository conventions, tests, and security boundaries. It returns findings on the pull request without changing or merging the code. +Use this pattern for independent review after human or agent implementation. Keep the review model or harness different from the one that wrote the change when possible. + +## Prerequisites + +* **A connected code forge** - Connect [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), or [Azure DevOps](/factories/integrations/azure-devops/) with access to the repositories under review. +* **Pull request read and comment permissions** - The agent needs the diff, checks, and review conversation, plus permission to post findings. +* **Repository guidance** - Keep build, test, security, and style requirements in the repository or a factory skill. +* **A review policy** - Decide which findings block handoff and which need human judgment. + +## Recommended recipe + +Route ready pull requests to a `REVIEW` agent. Start with one event so a single pull request action doesn't create overlapping runs. + +| Part | Recommendation | +| --- | --- | +| Trigger | `pull_request_ready`; add `pull_request_synchronized` later if every new commit needs automatic re-review | +| Agent | A `REVIEW` agent that doesn't edit, approve, or merge | +| Skills | Code quality, code review, and repository-specific test or security procedures | +| Settings | Filter by repository and default base branch; use a model or harness different from implementation | +| Output | Inline findings where supported, a concise verdict, and the validation commands checked | + +```markdown title="automations/review-ready-prs/automation.md" +--- +agent: review +triggers: + - provider: github + event: pull_request_ready + filter: + repos: [acme/api-service] + base_branches: [main] + labels: + not_in: [skip-factory-review] +--- + +Review the pull request against its stated requirements and the repository's +guidance. Inspect the full diff and existing checks. Post only actionable +findings, cite the affected lines, and state whether the change needs revision +or human judgment. Do not edit, approve, or merge the pull request. +``` + +```markdown title="agents/review/agent.md" +--- +description: Independently reviews pull requests and reports actionable findings +agentType: REVIEW +--- + +Treat the pull request description as a claim, not proof. Verify behavior +against code, tests, and repository guidance. Keep each finding specific, +explain its impact, and name the correction. +``` + +The public [`04-code-review-only`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/04-code-review-only) definition provides a complete review-only factory to adapt. + +## Configure pull request review + +1. Create a factory that includes the repositories to review. +2. Configure the review agent with read access to code and checks, plus pull request comment access. Don't grant push credentials when the agent only reviews. +3. Add repository-specific review skills under `agents/review/skills/`. Include exact validation commands and any security or migration checklists. +4. Add the `pull_request_ready` automation above. Keep a skip label so maintainers can exclude generated, experimental, or sensitive changes. +5. Open a draft test pull request containing one known defect, then mark it ready. Confirm the review points to the defect, avoids duplicate summary comments, and doesn't change the branch. +6. Add `pull_request_synchronized` only after deciding how re-reviews should replace or reply to earlier findings. + +## Example workflow + +A pull request changes a cache key from `account_id:region` to `account_id`. When the author marks it ready, the factory reads the requirements, diff, and checks. The review agent finds that two regions now share one entry and posts a line-level finding with the collision scenario and the expected key shape. + +After the author pushes a fix, a follow-up automation can re-run the same review. The agent verifies the new key and reports no remaining findings. A person still decides whether to approve and merge. + +## Best practices + +* **Review only ready changes** - Ignore drafts unless your team explicitly wants early feedback. +* **Give findings a threshold** - Ask for bugs, security risks, unmet requirements, and missing meaningful tests, not stylistic preference. +* **Use independent configuration** - A different model or harness reduces shared blind spots between implementation and review. +* **Avoid duplicate reviews** - One event should own initial review; add re-review events deliberately. +* **Keep merge authority human** - Warp Factories doesn't merge by default. Enforce approval and merge rules in branch protection. + +## Related pages + +* [Factory use cases](/factories/use-cases/) - Compare review with triage, implementation, and verification recipes. +* [Factory automations](/factories/automations/) - Configure pull request events and filters. +* [Factory agents](/factories/factory-agents/) - Configure the review role and choose a separate model or harness. +* [GitHub integration](/factories/integrations/github/) - Review supported pull request events and permissions. {/* This scaffold is completed by its dependent guide PR. */} From 009f1169bb93c6c314c96bf44acec833e4d5efc7 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/code-review.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/factories/use-cases/code-review.mdx b/src/content/docs/factories/use-cases/code-review.mdx index 7d7263383..92bb19286 100644 --- a/src/content/docs/factories/use-cases/code-review.mdx +++ b/src/content/docs/factories/use-cases/code-review.mdx @@ -88,4 +88,3 @@ After the author pushes a fix, a follow-up automation can re-run the same review * [Factory automations](/factories/automations/) - Configure pull request events and filters. * [Factory agents](/factories/factory-agents/) - Configure the review role and choose a separate model or harness. * [GitHub integration](/factories/integrations/github/) - Review supported pull request events and permissions. -{/* This scaffold is completed by its dependent guide PR. */} From 4204e5c57729875fa90db5a5acd5ae17b7f70960 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:57:21 +0000 Subject: [PATCH 3/3] docs: clarify provider review triggers --- .../docs/factories/use-cases/code-review.mdx | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/content/docs/factories/use-cases/code-review.mdx b/src/content/docs/factories/use-cases/code-review.mdx index 92bb19286..a4a403f31 100644 --- a/src/content/docs/factories/use-cases/code-review.mdx +++ b/src/content/docs/factories/use-cases/code-review.mdx @@ -19,14 +19,22 @@ Use this pattern for independent review after human or agent implementation. Kee Route ready pull requests to a `REVIEW` agent. Start with one event so a single pull request action doesn't create overlapping runs. +| Provider | Initial review | Review after updates | +| --- | --- | --- | +| GitHub | `pull_request_ready` | `pull_request_synchronized` | +| GitLab | `merge_request` | `merge_request` | +| Azure DevOps | `pull_request_created` | `pull_request_updated` | + | Part | Recommendation | | --- | --- | -| Trigger | `pull_request_ready`; add `pull_request_synchronized` later if every new commit needs automatic re-review | +| Trigger | Start with the provider's initial-review event; add its update event only when every new commit needs automatic re-review | | Agent | A `REVIEW` agent that doesn't edit, approve, or merge | | Skills | Code quality, code review, and repository-specific test or security procedures | | Settings | Filter by repository and default base branch; use a model or harness different from implementation | | Output | Inline findings where supported, a concise verdict, and the validation commands checked | +The configuration example below is specific to GitHub. + ```markdown title="automations/review-ready-prs/automation.md" --- agent: review @@ -64,9 +72,9 @@ The public [`04-code-review-only`](https://github.com/warpdotdev/warp-factory-ex 1. Create a factory that includes the repositories to review. 2. Configure the review agent with read access to code and checks, plus pull request comment access. Don't grant push credentials when the agent only reviews. 3. Add repository-specific review skills under `agents/review/skills/`. Include exact validation commands and any security or migration checklists. -4. Add the `pull_request_ready` automation above. Keep a skip label so maintainers can exclude generated, experimental, or sensitive changes. +4. Add the GitHub `pull_request_ready` automation above. For GitLab, use `merge_request`. For Azure DevOps, use `pull_request_created`. Keep a skip label so maintainers can exclude generated, experimental, or sensitive changes. 5. Open a draft test pull request containing one known defect, then mark it ready. Confirm the review points to the defect, avoids duplicate summary comments, and doesn't change the branch. -6. Add `pull_request_synchronized` only after deciding how re-reviews should replace or reply to earlier findings. +6. Add the provider's update event only after deciding how re-reviews should replace or reply to earlier findings: `pull_request_synchronized` for GitHub, `merge_request` for GitLab, or `pull_request_updated` for Azure DevOps. ## Example workflow