claude-team-review/SKILL.md

---
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 [<mode-or-path>] [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 <plan-path>` — force code-vs-plan review against an explicit plan file
- `/claude-team-review <file-path>` — 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 <plan-path>` 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 <plan-path>`, 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 <plan-path>`
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 (any non-empty output means changes exist):
   - `git diff --name-only` — unstaged
   - `git diff --cached --name-only` — staged
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.

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 it to use git status / git diff
- For `code-vs-plan` — pass the plan and instruct git lookup for changes

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 <detected language>. 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
<detected language>.
```

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: <plan|code|code-vs-plan>)

[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  |

---

## 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, and idle notifications (`TeammateIdle` /
  message-delivery events) — when present, these are the authoritative
  liveness signal.
- 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: <no continuation on this host | previous reviewer ended>).

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

**Approved:**
```
## Team Review — Summary (mode: <mode>)

**Status:** Approved after N round(s)

[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: <mode>)

**Status:** NOT VERIFIED — fixes applied, reviewer did not re-verify

**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: <mode>)

**Status:** Maximum reached (5 rounds) — not fully approved

**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
- 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 `<tool>` 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. |

---

## 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.