--- name: claude-team-review description: > Use when user says /claude-team-review, requests adversarial review of a plan or code change, wants peer review without external API dependencies, or needs to verify implementation against a plan before merging. user_invocable: true --- # Claude Team Review Adversarial review of plans and code through a peer-reviewer subagent. The reviewer reads the project, runs tests and docs lookups, and delivers findings. The lead **evaluates** those findings (not blindly applies them), fixes what holds up, pushes back with reasoning on what doesn't, and asks for re-review. Up to 5 rounds. Works on **any host that supports subagents** — Claude Code (via Task tool or Agent Teams) and Codex (native subagents) are both fine. The skill is platform-agnostic; the platform decides how to spawn. --- ## When to invoke Invocation grammar: `/claude-team-review [] [xhigh]` — both pieces are independently optional. `xhigh` is an effort flag, not a mode, and can be combined with any of the mode arguments below. - `/claude-team-review` — auto-detect what to review - `/claude-team-review plan` — force plan review - `/claude-team-review code` — force code review - `/claude-team-review code-vs-plan` — force code-vs-plan review (uses the plan most recently shown in this conversation) - `/claude-team-review code-vs-plan ` — force code-vs-plan review against an explicit plan file - `/claude-team-review ` — review a specific file as a **plan** (argument contains `/` or `.`; the file is treated as the plan artifact). For plan-vs-code comparison use `code-vs-plan ` explicitly. - `xhigh` (anywhere in args) — use max reasoning effort for the reviewer --- ## Step 1: Determine review mode First, strip an `xhigh` token from the args if present (it does not consume the mode slot — see Step 2 "Effort override"). Then resolve mode in priority order: **1. Explicit argument** (`plan`, `code`, `code-vs-plan`, `code-vs-plan `, or a file path) → use it. For `plan` and `code-vs-plan` without an explicit path, skip git for the plan side and proceed to Step 2. A bare file path (no preceding `code-vs-plan` token) resolves to **plan** mode with that file as the plan artifact; if the user wants plan-vs-code, they must invoke `code-vs-plan ` explicitly. **2. Plan Mode active** (Claude Code) — if context contains the system message "Plan mode is active" → mode = `plan`, skip git. **3. Auto-detect** (no explicit argument, not in Plan Mode): 1. Check for code changes — there are **three independent scopes**, and any non-empty output from any of them means code changes exist: - `git diff --name-only` — unstaged - `git diff --cached --name-only` — staged - `git diff --name-only ...HEAD` — committed on the current branch since it diverged from its base. Resolve `` by trying in order: `git symbolic-ref refs/remotes/origin/HEAD` (canonical remote default), then `origin/main`, `origin/master`, `main`, `master`. If none resolve, skip this check. The three scopes are independent, not a fallback chain. The typical PR has commits on the branch *and* often an in-progress local tweak on top; the briefing in Step 2 reviews the union, not just the first non-empty one. 2. Check if a **structured plan artifact** exists in the current conversation context. This means one of: - The user pasted or referenced a markdown plan document with section headers like `Goals`, `Steps`, `Verification`, `Tasks`, or similar - The user explicitly labeled content as a "plan", "design", "spec", or "RFC" - A previous turn produced a written plan (e.g. via `superpowers:writing-plans` or a saved plan file) A casual sentence of intent ("I'll refactor auth next") is **not** a plan in context. | Code changes? | Plan in context? | Mode | |---------------|------------------|---------------------| | No | Yes | **plan** | | Yes | Yes | **code-vs-plan** | | Yes | No | **code** | | No | No | Ask the user | If the "Plan in context?" call is genuinely ambiguous (something looks plan-ish but doesn't match the criteria above), ask the user rather than guessing — silently misclassifying into `code-vs-plan` produces contorted reviews. --- ## Step 2: Spawn the reviewer **Spawn a reviewer subagent using your host's standard mechanism**, and pass it the briefing assembled from `reviewer-prompt.md`. - **Claude Code:** Task tool with `general-purpose` type, OR — if Agent Teams is enabled — spawn a teammate. Note: **only Agent Teams supports continuation between rounds** (via `SendMessage`, which is gated on `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). Without Agent Teams, the Task tool spawn is one-shot — Round 2+ has to go through the operator- gated fresh-spawn path in Step 6. - **Codex:** native subagent spawn (host orchestrates spawn/wait/consolidate). Codex supports intra-session continuation — the lead can address a running subagent thread by name in its next instruction and Codex's orchestration routes the message there. (`/agent` is a human-facing CLI command for inspecting/switching threads from the terminal, not a tool the lead invokes.) - **Other hosts:** equivalent subagent mechanism. The skill works as long as the host can spawn a subagent and (optionally) route follow-up messages to it. Spawn on the host that is executing this skill. Do not probe for or shell out to **another** host's mechanism (e.g. looking for the Claude Code CLI or Agent Teams env vars from inside Codex) — "the other host's mechanism is unavailable" is never a reason to skip the review. The reviewer is a full agent session — it explores the repo, runs git commands, and reads files on its own. **Do not pre-collect diffs or file lists for it.** Pass mode-specific context only: - For `plan` — path to plan file, or inline plan text - For `code` — instruct the reviewer to review the **union of three scopes**: unstaged (`git diff`), staged (`git diff --cached`), and committed since base (`git diff ...HEAD`, base resolved the same way as in Step 1). Branch-vs-base is *not* a fallback — do not skip it just because the working tree is non-empty. The typical PR has both. When scopes are mixed, the reviewer should label findings by scope where it matters and surface the mixed-state to the operator. - For `code-vs-plan` — pass the plan and instruct the same union git lookup as `code` (all three scopes, not a fallback chain) Fill the placeholders in `reviewer-prompt.md` and pass the result as the subagent's prompt. The template includes operating stance, finding bar, scope exclusions, and required output format. **Effort override:** if the user passed `xhigh`, route the spawn through a maximum-reasoning configuration if the host supports it. **Language.** The skill template is intentionally English (stable, host- agnostic), but the reviewer's *output* should match the operator's session language so verbatim show-back to the operator works without translation. Detect the language from recent operator messages (the last few human turns in the conversation). If it's English — no extra block needed (default). Otherwise, append a `## Language` section to the briefing with this content: ``` ## Language Respond in . The following stay in English (they are literals parsed by the lead and must not be translated): section headers (Summary, Findings, Verdict), severity tags (`[severity: critical|high|medium]`), and the final verdict line (`VERDICT: APPROVED` or `VERDICT: REVISE`). All other content — prose, reasoning, descriptions, recommendations — in . ``` The verbatim reply from the reviewer is shown to the operator as-is — do not translate it back; it should already be in the operator's language. **Tool restrictions.** The briefing's "must NOT modify files" rule is the primary control on both hosts and the default. **Do not reach for host-level sandboxes by reflex** — the reviewer also needs to run things (tests, linters, git, MCP queries) to verify findings, and hard sandboxes that block writes typically block exec too, which guts the reviewer. If the operator explicitly wants enforced no-write on top and accepts the trade-off, both hosts have an option: - **Claude Code:** define a custom subagent (e.g. `~/.claude/agents/adversarial-reviewer.md`) with frontmatter `disallowedTools: Write, Edit`, and dispatch that agent type instead of `general-purpose`. The built-in `general-purpose` has no invocation-time tool-restriction knob. - **Codex:** `sandbox_mode = "read-only"` applies natively, **but also disables shell exec for the subagent** — the reviewer will not be able to run tests or commands. Use only when the operator wants a read-only audit and is willing to give up empirical verification. --- ## Step 3: Show findings When the reviewer responds, show the user the response **verbatim** — do not rephrase, summarize, or reorder: ``` ## Team Review — Round N (mode: ) [Reviewer's response — verbatim] ``` Then check the verdict line: | Verdict | Next step | |---------------------|------------------------------------------------------| | `VERDICT: APPROVED` | Step 7 (final result) | | `VERDICT: REVISE` | Step 4 (evaluate findings) | | Unclear / missing | Send a message back asking for a clear verdict line | | Round 5 reached | Step 7 with the "Max rounds reached" terminal state | If instead of a response the host delivers an idle notification with no report attached, apply the idle guard from Step 6 ("Detecting a dead reviewer"): request the report once before concluding the reviewer is gone. This applies to Round 1 as much as to re-review rounds. --- ## Step 4: Evaluate findings (do NOT apply yet) **External feedback = suggestions to evaluate, not orders to follow.** This step exists because the reviewer may be technically wrong — and applying its findings blindly causes real damage (large structural edits based on cited issues that turn out to be feature requests, not bugs). **Use `superpowers:receiving-code-review` when available** — it has the full discipline for this step. The key principles are inlined below as the always-available fallback (so the matrix step works on any host, even where Superpowers is not installed). ### Build the evaluation matrix For each finding, fill out: | # | Severity | Verified? | Type | Action | |---|----------|-----------|------|--------| | 1 | high | ✓ Context7 confirms behavior | arch | accept | | 2 | critical | ✗ cited issue is feature request, not bug | tool-mechanic | reject with reasoning | | 3 | medium | ✓ quick repro confirms | tool-mechanic | accept | **Action** options are equal — `accept`, `reject with reasoning`, and `re-scope` (apply a narrower fix). Reject and re-scope are not exceptions; they are first-class outcomes. ### Verification methods by finding type | Finding type | What constitutes verification | |---|---| | Architectural / design | Reasoning + codebase grep, plus pattern check against existing code | | Tool-mechanic (DSL syntax, config parser, API contract, library behavior) | **Empirical test on the real system** — reasoning is not enough | | Style / convention | Match against actual codebase conventions | | Security | Reasoning + concrete threat model | **Tool-mechanic findings are the most dangerous to accept on reasoning alone.** Mental models of obscure tools are often wrong. If the reviewer cites an upstream issue or doc — **open it**. Do not trust the citation by number; issues get reclassified, closed, or turn out to describe a different case. ### Receiving feedback — key principles Inlined from `superpowers:receiving-code-review` for portability: - Read all findings end-to-end before reacting - Restate the technical claim in your own words (or ask) - Verify against codebase / docs / a quick run before accepting - Push back when wrong — with technical reasoning, not deference - No performative agreement ("you're absolutely right" is a violation) - Skip thanks. Just state the fix or the reasoning. ### Show the matrix to the user If an operator is present, show the matrix before applying. In headless or autonomous runs, proceed but be ready to explain each decision in the final summary. ### Decide which fixes need operator sign-off After the matrix is built and every finding has an action (`accept` / `reject with reasoning` / `re-scope`), classify each `accept` / `re-scope` fix as **structural** or **non-structural** — this controls whether the operator is paused. **Structural** — pause operator before applying: - Changes the invocation grammar (new/removed args, renamed mode, changed argument semantics) - Changes an external contract: output format, parsed literals (e.g. the `VERDICT: APPROVED|REVISE` line), section header names, named workflow states, public-facing option semantics - Adds or removes a workflow step or a terminal state - Changes the meaning of a publicly documented option (e.g. what `xhigh` does, what `code-vs-plan` means) - Any fix the lead is uncertain how to scope — when in doubt, classify as structural **Non-structural** — apply without pausing: - Wording / phrasing changes that don't change semantics - Correcting factual inaccuracies in descriptions (e.g. wrong API name, wrong tool mechanic, wrong attribution) - Removing outdated comments or examples - Adding clarifying sentences or examples that don't change behavior - Internal heuristic refinements that don't change observable behavior **Batch-pause rule.** Do not pause once per fix. Instead: 1. Walk the entire matrix first, classify every accepted/re-scoped fix. 2. If structural count is **zero** → apply everything, no pause. 3. If structural count is **≥ 1** → make exactly **one** pause showing the operator: - The list of structural fixes (one-line per fix; ask for go/no-go on each, or as a batch) - The list of non-structural fixes (informational only — auto-applied) - The list of rejects with reasoning (informational only) **Headless / no operator.** If no operator is reachable, apply structural fixes anyway but flag them explicitly in the final summary as "structural changes applied without operator sign-off" — the operator reviews them after the fact rather than gating them up-front. --- ## Step 5: Apply or push back For findings marked **accept** — fix them: - **Plan review:** update the plan to address the finding - **Code review:** edit files, run tests if applicable - **Code-vs-plan:** either update the plan or the code, depending on which is wrong **Verify your own technical claims before publishing them.** This is the reverse direction of receiving-code-review — not "don't accept someone else's unverified claim", but "don't publish your own". When a fix or a reply to the reviewer makes a claim about tool mechanics (DSL syntax, config parser behavior, API contract, library behavior), verify it empirically: - If a quick test is possible — run it (`docker run …`, a real database container, a small repro script, whatever maps to the claim) - If a quick test is not possible — frame the claim as a hypothesis ("seems to", "needs verification") rather than as fact Skip a fix that contradicts the user's explicit requirements — note this in the response to the reviewer. Show the user a brief account: ``` ### Round N fixes - Applied: [#1 — what changed, 1 line] - Re-scoped: [#3 — what changed, why narrower] - Rejected: [#2 — short reason; full reasoning goes to the reviewer] ``` --- ## Step 6: Request re-review (Rounds 2–5) Compose a structured response and send it to the reviewer. ### Response format ``` I've evaluated the findings. Here's the state: ## Applied - [#N]: [what was changed and why, 1–2 lines] - ... ## Re-scoped - [#N]: [scope/tone adjustment, with reasoning] - ... ## Rejected with reasoning - [#N]: [technical reason for not applying — not just "I disagree"] - ... ## Specific asks for re-review 1. Are my rejections technically valid? 2. Any new issues introduced by the applied fixes? 3. [Any specific question about a high-risk fix] [For plan mode with inline plans — append the full revised plan text:] ## Current revised plan [Full text of the revised plan] ``` The three-section format gives the reviewer a chance to **contest the rejections**. A re-review that says "your rejection of #2 is valid; here's why" is just as useful as one that fixes new issues — both keep the loop honest. ### Continuation vs fresh subagent The cheap path is **continuation** — the same reviewer keeps context between rounds. Fresh-spawn is expensive: the new subagent must re-read the project from scratch. Because of that cost, **fresh-spawn is always operator-gated**, regardless of platform. ```dot digraph re_review { "Continuation supported by host\nand previous reviewer alive?" [shape=diamond]; "Continue same reviewer" [shape=box style=filled fillcolor=lightgreen]; "Operator available?" [shape=diamond]; "Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" [shape=box]; "Spawn fresh subagent\nwith PREVIOUS_FINDINGS block" [shape=box]; "Step 7 — NOT VERIFIED terminal state" [shape=box style=filled fillcolor=lightyellow]; "Continuation supported by host\nand previous reviewer alive?" -> "Continue same reviewer" [label="yes"]; "Continuation supported by host\nand previous reviewer alive?" -> "Operator available?" [label="no"]; "Operator available?" -> "Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" [label="yes"]; "Operator available?" -> "Step 7 — NOT VERIFIED terminal state" [label="no — headless"]; "Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" -> "Spawn fresh subagent\nwith PREVIOUS_FINDINGS block" [label="re-spawn"]; "Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" -> "Step 7 — NOT VERIFIED terminal state" [label="conclude"]; } ``` **Continuation support, by host (verify against current docs before relying on this):** | Host | Continuation | Mechanism | |---|---|---| | Claude Code + Agent Teams (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) | yes | `SendMessage` to the teammate inbox | | Claude Code without Agent Teams | **no** — Task spawn is one-shot | — | | Codex | yes — intra-session | address the running subagent thread by name in the next instruction; Codex orchestration routes it (operators can use `/agent` from the CLI to inspect/switch threads — not a lead-side tool) | Two routes lead to the "ask operator" step: - The host has no continuation mechanism for our use case (Claude Code without Agent Teams) — every round after Round 1 lands here - The host has continuation but the previous reviewer is no longer reachable (process ended, thread closed, inbox dead) **Detecting a dead reviewer (continuation-supporting hosts).** The send itself is fire-and-forget — `SendMessage` returns immediately with a routing acknowledgment regardless of teammate liveness, and the reply arrives asynchronously in a later turn via the host's automatic message delivery. **Do not treat the ack as the reply.** After sending, wait for the reply to be delivered. Treat the reviewer as unreachable only when one of the following is true: - The host surfaces an explicit shutdown / "teammate exited" / "no such teammate" event. On Claude Code + Agent Teams this includes the documented case where a resumed session no longer has the previous teammates alive. - An idle-without-report **repeats after a nudge**: the reviewer went idle with no report delivered, you requested the report once, and the answer was another idle-without-report. (A single idle notification alone is not a death signal — a live reviewer sometimes goes idle with its report undelivered on the first attempt, and the nudge retrieves it; observed repeatedly in practice.) - Send fails outright (error response, not a success ack). - The reply is overdue (no `TeammateIdle` / message-delivery notification in a reasonable window) **and** an operator is present to confirm — surface the wait and let the operator decide whether to abandon. If no operator is present, keep waiting; auto-abandoning on a wall-clock guess is worse than waiting (LLMs don't track wall time reliably and the host's notification channel is the documented signal). When unreachable is confirmed, fall through to the operator question. **Detecting an operator.** Treat the run as **interactive** (operator available) only if both conditions hold: 1. The current conversation has a direct human message — not just an automated trigger, hook, scheduled run, or CI invocation 2. The host exposes a user-facing channel to surface the question When in doubt, default to **presenting the choice** — pausing once is cheaper than concluding unverified by mistake. **Asking the operator.** Present the choice plainly: ``` The reviewer cannot be continued from the previous round (reason: ). Fixes applied: [List from Step 5] Options: (a) Spawn a new reviewer to verify fixes (expensive — full project re-read) (b) Conclude the review — fixes applied, verification is on you ``` **Fresh subagent re-review (if operator chose re-spawn).** Fill the `{PREVIOUS_FINDINGS_BLOCK}` placeholder in `reviewer-prompt.md` with: 1. Verbatim previous findings 2. The Applied / Re-scoped / Rejected-with-reasoning sections 3. For plan mode with inline plans: the full revised plan text The fresh reviewer has zero prior context — it must see the actual artifact, not a paraphrase. When the reviewer responds — return to **Step 3** with N+1. ### Severity declination (soft signal) Expect severity of findings to decline across rounds: ``` R1: 3 critical, 6 high, 5 medium (typical) R2: 1 high, 1 medium, 3 low (good) R3: 1 high (closing in) R4: APPROVED (terminal) ``` If severity **stays flat** (e.g. high → high → high), something is structurally off — the lead may not understand the technology, the reviewer may be looping on the same misunderstanding, or the artifact has a deep problem that surface fixes can't reach. Pause and surface to the user. This is a soft signal, not a hard gate. --- ## Step 7: Final result The **Reviewer:** line reports the actual pedigree — what performed the review (e.g. `Agent Teams teammate, Claude Opus` or `Codex native subagent, GPT`), not what was planned. **Approved:** ``` ## Team Review — Summary (mode: ) **Status:** Approved after N round(s) **Reviewer:** [Final review verbatim] --- **Reviewed and approved by the reviewer. Awaiting your decision.** ``` **Not re-verified** (reviewer became unreachable mid-loop and the operator chose to conclude, or the run is headless): ``` ## Team Review — Summary (mode: ) **Status:** NOT VERIFIED — fixes applied, reviewer did not re-verify **Reviewer:** **Round N findings:** [Verbatim findings from the last reviewer round] **Applied / Re-scoped / Rejected:** [The three sections from the last round] --- **WARNING: This is NOT an approval. Fixes were applied but never verified by the reviewer. Manual review of the fixes is required before merging.** ``` **Maximum rounds reached:** ``` ## Team Review — Summary (mode: ) **Status:** Maximum reached (5 rounds) — not fully approved **Reviewer:** **Remaining findings:** [Unresolved issues] --- **The reviewer still has findings. Please review them and decide how to proceed.** ``` --- ## Step 8: Cleanup If the host provides a subagent / teammate cleanup mechanism, use it. Failures are non-blocking — subagents are reclaimed when the session ends. Do NOT delete plan files that existed before the review. --- ## Rules - Lead **actively evaluates and acts** on findings — this is NOT message forwarding, and it is NOT blind acceptance - Reviewer findings shown **verbatim** — do not rephrase or shorten - Auto-detect mode from context; user arguments take priority - The reviewer **never writes files** — enforced by the briefing rule, and by the host's sandbox if available - The reviewer **can run commands** (tests, linters, git) and **use MCP** (Context7, web search) to verify findings - Maximum 5 rounds to protect against infinite loops - Show the user findings and the applied/rejected breakdown for each round - Avoid creating auxiliary files (memory files, state files, logs, temporary markdown) — prefer working within the conversation context - If a fix contradicts user requirements — skip it and explain why - Never skip or silently substitute the review. Declaring a spawn or continuation mechanism unavailable without having attempted it is a process violation — the **Reviewer:** line in the summary reports what actually ran - For re-review, prefer continuation (cheap). Fresh-spawn is the expensive path — always confirm with the operator before doing it. In headless runs without operator access, conclude unverified rather than auto-respawning. - The ultimate goal is **higher quality** of plans, code, and other artifacts. Token economy is a means, not an end — never skip a verification step or cut a round short just to save tokens. --- ## Red Flags — STOP and reconsider When you catch yourself thinking any of these, you are about to violate the skill. Stop, re-read Steps 4–5. | Thought | Reality | |---|---| | "Reviewer flagged this as critical — apply right away" | Build the matrix first. Verify before apply. | | "The reviewer cites issue #N, I'll trust the number" | Open the issue. Citations age; issues get reclassified. | | "I know how `` works, no need to test the fix" | Tool-mechanic claims need empirical verification, not reasoning. Run it or hedge it. | | "I disagree with #2 but I'll just stay silent about it" | Reject with reasoning. The reviewer needs the chance to contest. | | "You're absolutely right, applying now" | Performative agreement. Restate the requirement, then act. | | "5 rounds is a lot, let me wrap this up at round 3" | Don't compress the loop to save tokens. Run it until terminal. | | "Just paraphrase the findings to save space" | Verbatim. Always verbatim. Paraphrase loses signal. | | "Severity hasn't dropped in 3 rounds, but I'll push through" | Pause. Surface to operator. Something is structurally off. | | "Continuation isn't available — let me just spawn a fresh reviewer" | Ask the operator first. Fresh-spawn is expensive; the operator may prefer to conclude unverified. | | "This host can't run the skill — skip the review and note why" | Use the host's own subagent mechanism (Step 2). Attempt, then report what actually ran in the **Reviewer:** line. | | "The reviewer went idle — it must be dead" | Idle ≠ dead. Request the report once (Step 6 idle guard); reports sometimes fail to deliver on the first attempt. | --- ## Comparison with adversarial-review `adversarial-review` is a related but distinct skill (different repo): Claude writes, Codex reviews — cross-model coverage. | Aspect | adversarial-review (cross-model) | claude-team-review (same-host) | |-------------------------|------------------------------------------|-----------------------------------| | Reviewer model | External (GPT via Codex CLI from Claude) | Whatever the host runs | | Cross-model blind spots | Yes — different model biases | No — same model family | | Session persistence | Via `codex exec resume` | Continuation if host supports it; otherwise operator-gated fresh-spawn | | External dependencies | Codex CLI + OpenAI API key (from Claude) | None — uses host's native subagent mechanism | | Reviewer capabilities | Read-only sandbox | Read + execute + MCP + web | | Host compatibility | Designed for Claude Code as lead | Claude Code AND Codex as lead | Use `adversarial-review` for cross-model diversity. Use `claude-team-review` when you want zero external dependencies and a richer reviewer (tests, docs, web), regardless of which host is the lead.