/review-pr

description: Context-aware PR review — analyzes what the PR touches, spawns domain-specific agents with project conventions. Supports staging reviews.
argument-hint: "[PR number, URL, \"open\", or \"staging\" for feature→main review]"
allowed-tools: Task, Agent, Bash, Read, Grep, Glob, WebFetch, Skill

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

PR Review — Orchestrator

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

**Input**: $ARGUMENTS

**NEVER use plan mode (EnterPlanMode)** during review — it breaks execution context. **Sub-agent dispatch tool: `Task` preferred, `Agent` is the documented fallback.** review-pr dispatches domain review agents via a sub-agent-spawning tool. Resolve which one is available ONCE per invocation, before Phase 3C, per the **Sub-Agent Dispatch Tool Resolution** rule below; do not halt to ask the operator. Never fall back to reviewing inline in the orchestrator's context: it is a strictly weaker substitute for an isolated reviewer.

**Agent model policy**: `model: "{DEFAULT_MODEL}"` — forge.yaml `agents.default_model`, else "sonnet" (standard tier); the always-on General Security & Quality reviewer uses `effort: xhigh` (deep tier). Fallback `model: "opus"` if rate-limited; `--model <name>` overrides. Pass model and effort explicitly in every `Task` call; pass `effort` only on Claude Code >= 2.1.154. **Domain-review agents** (`commands/review-pr-agents/*.md`) use `model: "{SUBAGENT_MODEL}"` — `agents.subagent_model`, else `agents.default_model`, else `"sonnet"`.

<!-- FORGE:SPEC_LOADED — review-pr.md loaded and active. Agent is bound by this spec. -->

HARD RULES — READ BEFORE ANYTHING ELSE

1. **Use the resolved `{DISPATCH_TOOL}(...)` for ALL domain agent launches** (resolved once, below; never mixed). Each agent MUST run in an isolated, fresh-context sub-agent (never inline) and post findings to the PR via `gh pr comment` in structured form.

2. **Post the FORGE:REVIEW verdict regardless of finding severity**: a review with no `<!-- FORGE:REVIEW -->` comment is invisible to the pipeline, even a PASS.

3. **Review findings do NOT block merge UNLESS they meet the Blocking Criteria in §7B** (a CONFIRMED HIGH/CRITICAL finding, a purpose regression, a merge conflict, or a build/type/test failure) **or §7B.5 sets `CALIBRATION_NEEDS_HUMAN=true`**. File every finding that passes the §6B.4 provenance gates and survives the §6B.5 note disposition and per-review cap (the scripts own the rules; HIGH/CRITICAL are never capped) as a GitHub issue with the `review-finding` label. LOW/POSSIBLE notes are fixed in-PR, listed in the PR body, or dropped, never filed. Minor/style findings never block; §7B's and §7B.5's blocking conditions always do, including under `--auto-merge`. <!-- forge#1741 -->

4. **Route correctly at Phase 0.** If the input is "staging" or the PR targets `main`, invoke `Skill("{FORGE_SKILL_PREFIX}review-pr-staging", ...)` — do NOT run the standard PR review pipeline against a staging→main PR.

5. **`spec-evolution` PRs are NEVER auto-merged.** A PR with the `spec-evolution` label (from `/spec-doctor`) gets `AUTO_MERGE=false` and `needs-human` in Phase -1, before any other processing; no caller can override it (see the Phase -1 `spec-evolution guard`). <!-- Added: forge#1742 -->

6. **Every `bash` fence is a fresh shell.** Each fence re-declares the state it needs with the orchestrator's values (its first lines) and re-resolves ForgeDock scripts through its own `forge_resolve` locator line; nothing carries over from an earlier fence.

7. **Never mutate the main checkout.** Neither the orchestrator nor any reviewer runs `git checkout`, `git switch`, `git reset`, `git stash`, or `git merge` in the main checkout (the primary working tree, `{REPO_PATH}`, shared with the operator and other agents). Read PR code only through `git show <sha>:<path>`, `gh pr diff`, `gh api`, or a throwaway per-PR worktree (`git worktree add --detach`) removed afterward. <!-- Added: forge#3650 -->

Sub-Agent Dispatch Tool Resolution (MANDATORY — run once, before Phase 3C)

Resolve deterministically, once per invocation, and use the same tool for every dispatch call in this run:

OpenCode Runtime Override

Under OpenCode, resolve the native tool before applying the Claude-specific order below:

IS_OPENCODE_RUNTIME=false
if [ "${FORGE_RUNTIME:-}" = "opencode" ] ||
   [ -n "${OPENCODE_SESSION_ID:-}" ] ||
   [ -n "${OPENCODE_PID:-}" ] ||
   [ -n "${OPENCODE:-}" ]; then
  IS_OPENCODE_RUNTIME=true
  DISPATCH_TOOL=task
  DISPATCH_SUBAGENT_TYPE=general
fi

Under OpenCode lowercase native `task` is the isolated dispatch tool (do not enter the `Neither tool is available` branch merely because `Task` and `Agent` are absent); every call needs a top-level `subagent_type` (`general` for review work) and is foreground. If native `task` is absent, hard-stop with `FORGE:REVIEW_BLOCKED`; never review inline.

1. **`Task` available**: `{DISPATCH_TOOL} = Task` (preferred; tightest `allowed-tools` scoping). 2. **Else `Agent`**: `{DISPATCH_TOOL} = Agent`, the documented fallback (not degraded): one call per selected agent, same prompt template, `subagent_type: "general-purpose"`. 3. **Neither is available**: a setup defect, usually the sub-agent depth limit (`Agent` is withheld at layer 3 and deeper, `docs/WORK-ON-RUNTIME.md` F1/F5) because this review was invoked from inside a forked phase instead of by the router (R1): name the depth limit in the blocker. HARD STOP, comment, add `needs-human`, exit without a verdict. Never review inline. 4. **Dispatch pool exhausted or dispatch call fails** (distinct from tool absence): HARD STOP. No inline review of that domain, no