/review-pr-agents

description: Review agent catalog (read by /review-pr; not a user entrypoint)
user-invocable: false

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

Agent Catalog Router for `/review-pr`

This file is the routing index referenced by the `/review-pr` orchestrator during Phase 3C (agent dispatch). Per-persona prompt templates have been split into individual files under `commands/review-pr-agents/` to avoid loading the full catalog on every invocation. Protocols live in `docs/spec/review-protocol.md` (canonical source) and are reproduced in `commands/review-pr-agents/protocols.md`.

Do not modify this file without also updating `review-pr.md`. To update either protocol, edit `docs/spec/review-protocol.md` and sync the copy to `commands/review-pr-agents/protocols.md`.

**Dispatch tool: `Task` preferred, `Agent` is the documented fallback.** The orchestrator (`/review-pr` or `/review-pr-staging`) resolves the dispatch tool once per invocation per its **Sub-Agent Dispatch Tool Resolution** rule: `Task` when available, `Agent` when `Task` is absent from the environment — never inline self-review as a substitute for either. Every agent template in this catalog is intended to be passed as the `prompt` argument to whichever tool the orchestrator resolved (`Task(...)` or `Agent(...)`), with the same per-agent isolation and the same requirement that each agent posts structured findings to the PR directly (`gh pr comment`) rather than relaying them through the orchestrator's own context.

**OpenCode override**: When `FORGE_RUNTIME=opencode` or an equivalent OpenCode marker is present, the orchestrator must set `DISPATCH_TOOL=task` before checking literal Claude tool names. A native task argument is shaped as `{ description: "...", prompt: "...", subagent_type: "general"|"explore", background: false }`: use `general` for implementation/review and `explore` for read-only discovery. The `Neither tool is available` hard stop applies only when lowercase native `task` is genuinely absent; it must not be triggered by the absence of `Task` and `Agent` names in an OpenCode session. If native `task` is absent, post `FORGE:REVIEW_BLOCKED` and never replace the isolated review with inline work.

<!-- FORGE:PROTOCOL_SOURCE — canonical definition lives in docs/spec/review-protocol.md -->

---

Read-Only Git Rule (all reviewer agents)

Every reviewer agent is read-only with respect to the main checkout (the repo's shared primary working tree). It MUST NOT run `git checkout`, `git switch`, `git reset`, `git stash`, or `git merge` there: those race with the operator and other agents. Read PR code with `git show <sha>:<path>`, `gh pr diff`, `gh api`, or a per-PR worktree (`git worktree add --detach`) that the agent removes afterward. The orchestrator appends this rule to every dispatched prompt (review-pr.md Phase 3C). <!-- Added: forge#3650 -->

---

How to Load Agents (Phase 3C)

For each agent selected in Phase 3B, read **only** the files relevant to that agent:

1. **Always read first** (shared protocols, all agents require this):

   Read: ${CLAUDE_PLUGIN_ROOT}/commands/review-pr-agents/protocols.md

2. **Then read the persona file for each selected agent**:

| Agent | Trigger | Marker domain | File | |-------|---------|---------------|------| | General Security & Quality Scan | ALWAYS RUNS | `security` | `review-pr-agents/security.md` | | Auth Conventions Auditor | Auth/session/trust-filter files changed (path-gated) | `auth` | `review-pr-agents/auth.md` | | Billing Integrity Auditor | BILLING domain | `billing` | `review-pr-agents/billing.md` | | Concurrency & Race Condition Auditor | CONCURRENCY or BILLING domain | `concurrency` | `review-pr-agents/concurrency.md` | | Domain Logic Auditor | SCRAPING domain (requires `review.domains.scraping` in forge.yaml) | `scraper` | `review-pr-agents/scraper.md` | | Frontend Quality Auditor | WEB service touched | `frontend` | `review-pr-agents/frontend.md` | | API Design & Consistency Auditor | New/modified routers or SDK/OpenAPI files | `api` | `review-pr-agents/api.md` | | Database & Migration Auditor | DATABASE domain | `database` | `review-pr-agents/database.md` | | Infrastructure & Deploy Safety Auditor | Docker, CI, deploy or infra files changed (path-gated) | `infra` | `review-pr-agents/infra.md` |

The table is applied by `scripts/review-roster.sh` (Phase 3B Step 4), which tiers the roster by diff size and fix-PR lineage: small and fix PRs run Security only unless a path trigger fires, and Auth and Infra are selected by file path, never by diff-text score. `--thorough` and milestone-to-staging always run the full union. The tier and reason are recorded in `FORGE:REVIEW_TIER`.

Domain Prefixes (for Structured Findings)

| Agent | Prefix | |-------|--------| | General Security | `SEC` | | Auth Conventions | `AUTH` | | Billing Integrity | `BILL` | | Concurrency | `CONC` | | Domain Logic | `SCRP` | | Frontend Quality | `FE` | | API Design | `API` | | Database & Migration | `DB` | | Infrastructure | `INFRA` |

Loading Instructions for Phase 3C

Replace the single `Read: ${CLAUDE_PLUGIN_ROOT}/commands/review-pr-agents.md` call with:

Read: ${CLAUDE_PLUGIN_ROOT}/commands/review-pr-agents/protocols.md
Read: ${CLAUDE_PLUGIN_ROOT}/commands/review-pr-agents/<persona>.md   (one per selected agent)

Each persona file contains:

• The agent's trigger condition and type
• Its full prompt template with all check items
• Its coverage matrix

The `protocols.md` file contains:

• Per-Agent Input Scoping rules
• Tool-Result Truncation Discipline
• Evidence-Based Review Protocol (all agents follow)
• Structured Findings Protocol (machine-readable findings block format; each finding also carries a `**Failure scenario**` and `**Scope**: changed|pre-existing`, consumed by `/review-pr` §6B.4)

**Spec root (MANDATORY)**: read every file named in this catalog from `${CLAUDE_PLUGIN