ddmitry/claude-team-review
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'feat/cross-platform-receiving-review'

Browse Source
This commit is contained in:
ddadmin
2026-05-15 16:28:15 +03:00
parent ef97a43791 933c48fb3c
commit 8a0e5b8879
6 changed files with 843 additions and 373 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -0,0 +1 @@
tmp
EXPERIMENT.md
+9
View File
@@ -1,5 +1,14 @@
# Эксперимент: как две модели ревьюят один и тот же план
> **Note (2026-05-15):** This write-up predates the cross-platform
> redesign of `claude-team-review`. It refers to artifacts that no
> longer exist in their original form — specifically `adversarial-
> reviewer.md` (a Claude Code agent definition that has been replaced
> by `reviewer-prompt.md`, a host-agnostic briefing template). The
> historical descriptions below are preserved as-is for the experiment
> record; for the current skill structure, see `SKILL.md` and
> `reviewer-prompt.md`.
Opus и GPT-5.4 получили одинаковый план и одинаковую adversarial
установку. Нашли разные проблемы. Этот документ — полный ход
эксперимента: от наивного запуска до контролируемого сравнения.
README.md
+166 -56
View File
@@ -1,70 +1,100 @@
# Claude Team Review
Adversarial code and plan review using Claude Code Agent Teams.
Adversarial code and plan review through a peer-reviewer subagent.
One teammate reviews. The lead fixes. Iterate until approved.
One subagent reviews. The lead evaluates findings, fixes what holds up,
pushes back on what doesn't, and asks for re-review. Up to 5 rounds.
**Designed for Claude Code and Codex.** The skill is platform-agnostic
in its instructions, so it can potentially work on other hosts that
support subagents — but Claude Code and Codex are the verified targets.
## What is this
A [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code) that
spawns an adversarial reviewer as an Agent Teams teammate. The reviewer
reads your project, runs tests, checks documentation, and delivers findings
with a skeptical stance. The lead (your main session) fixes issues and
requests re-review from the same teammate. If the teammate is no longer
active, the lead decides how to proceed — re-spawn or conclude.
A skill that spawns an adversarial reviewer as a subagent on the host
of your choice. The reviewer reads your project, runs tests, checks
documentation, and delivers findings with a skeptical stance.
The lead (your main session) **does not blindly apply findings**. It
builds an evaluation matrix, verifies the technical claims, and replies
with applied / re-scoped / rejected-with-reasoning sections. The reviewer
gets a chance to contest the rejections in the next round.
### How it differs from [adversarial-review](https://github.com/dementev-dev/adversarial-review)
**adversarial-review** uses two different models (Claude writes, Codex
reviews) — you get cross-model blind spot coverage and cheap re-review
reviews) — you get cross-model blind-spot coverage and cheap re-review
via `codex exec resume`. It requires Codex CLI and an OpenAI API key.
**claude-team-review** stays within the Claude ecosystem. No external
dependencies. The reviewer is a Claude Code teammate with its own context
**claude-team-review** stays inside whichever host you're using. No
external dependencies. The reviewer is a subagent with its own context
window, MCP access, and the ability to run commands. For re-review, the
lead tries to continue the same teammate; if the teammate is no longer
active, the lead can re-spawn or conclude based on context. The trade-off:
same model family means no cross-model diversity.
lead tries continuation when the host supports it (e.g. Claude Code
Agent Teams), and otherwise spawns a fresh subagent with the previous-
rounds context block.
Use **adversarial-review** when you want maximum review quality through
model diversity. Use **claude-team-review** when you want zero external
dependencies and a richer reviewer (tests, docs, web search).
dependencies and a richer reviewer (tests, docs, web search) running on
the same host as the lead.
## How it works
```
┌──────────┐ spawn ┌────────────┐
│ Lead │ ───────────────> │ Reviewer │
│ (code) │ │ (teammate) │
│ (code) │ │ (subagent) │
└──────────┘ └────────────┘
^ │
│ findings │
│ <────────────────────────────┘
│
│ fix issues
│ evaluate (matrix, verify)
│ apply / re-scope / reject
v
┌──────────┐ message ┌────────────┐
┌──────────┐ re-review ┌────────────┐
│ Lead │ ───────────────> │ Reviewer │
│ (fixed) │ "re-check this" │ (same / new)│
└──────────┘ └────────────┘
│
│ (fixed) │ "applied A, │(same / new)│
│ │ rejected B └────────────┘
│ │ with reason" │
└──────────┘ │
VERDICT: APPROVED
```
The lead tries to continue the **same teammate** for re-review. If the
teammate is no longer active (Agent Teams limitation), the lead can
re-spawn with a full briefing or conclude without re-verification.
The lead tries to **continue the same reviewer** for re-review when the
host supports it (cheaper — context is preserved). Codex supports
intra-session continuation natively; Claude Code requires Agent Teams
(`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) for the `SendMessage`-based
continuation path. When continuation is unavailable, or when the
previous reviewer is no longer reachable, the lead asks the operator
before spawning a fresh subagent — full project re-read is expensive,
and the operator may prefer to conclude the review unverified. Headless
runs without operator access conclude unverified.
### Three modes
| Mode | What it reviews | When to use |
|----------------|------------------------------------|--------------------------|
|----------------|------------------------------------------|--------------------------|
| `plan` | Implementation plan | Before writing code |
| `code` | Git diff (unstaged, staged, branch)| After writing code |
| `code` | Working-tree, staged, and branch changes | After writing code |
| `code-vs-plan` | Code changes against the plan | Verify implementation |
Mode is auto-detected from context, or you can force it with an argument.
For `code` mode, "branch changes" means commits on the current branch
since it diverged from its base (`main`, `master`, or the remote
default). The three scopes (unstaged, staged, branch-vs-base) are
reviewed as a union, not a fallback chain — so the typical PR case
(committed changes on the branch plus an in-progress local tweak) is
covered without an explicit flag.
### Language
The skill detects the operator's session language from recent
conversation and instructs the reviewer to respond in it. No flag,
no configuration. If you write to Claude in Russian, the reviewer's
findings come back in Russian.
### What the reviewer can do
- **Read** any file in the repository
@@ -72,31 +102,73 @@ Mode is auto-detected from context, or you can force it with an argument.
- **Search the web** and **query documentation** via MCP (Context7)
- **Inspect git history** — blame, log, diff
The reviewer **cannot** create, edit, or delete project files.
The reviewer **must not** create, edit, or delete project files. The
briefing forbids it — that's the primary control on both hosts and the
default the skill ships with. The reason for keeping it briefing-only
is that the reviewer also needs to **run things** (tests, linters, git,
MCP queries) to verify findings — hard sandboxes that block writes tend
to block exec too, which would gut the reviewer.
If you accept that trade-off and want enforced no-write on top, both
hosts have an option:
- **Claude Code:** define a custom subagent (e.g.
`~/.claude/agents/adversarial-reviewer.md`) with
`disallowedTools: Write, Edit` and dispatch that agent type. The
built-in `general-purpose` agent has no invocation-time
tool-restriction knob, so this path requires the custom definition.
- **Codex:** `sandbox_mode = "read-only"` applies natively, but it also
disables shell exec for the subagent — the reviewer will not be able
to run tests or commands. Use only when you specifically want a
read-only audit and are willing to give up empirical verification.
### What the lead does (and does NOT do)
**Does:** evaluates each finding through a verification matrix, classifies
by type (architectural / tool-mechanic / style / security), verifies its
own technical claims before publishing them, replies in a structured
applied/re-scoped/rejected-with-reasoning format.
**Does NOT:** apply findings blindly, trust cited upstream issues by
number, make confident tool-mechanic claims without empirical testing,
stay silent about rejections.
**Pauses the operator** only on **structural** fixes — changes to the
invocation grammar, output contract, workflow states, or the meaning of
public options. Wording and factual fixes apply silently; the operator
sees the full breakdown in the round summary. One pause per round at
most, never one per finding.
The skill explicitly invokes `superpowers:receiving-code-review` for the
evaluation step (and inlines its key principles for portability).
## Requirements
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) ≥ 2.1.32
- Agent Teams enabled (experimental)
- A host that supports subagents — Claude Code or Codex
- Optional: Claude Code with Agent Teams enabled, for cheaper re-review
via continuation
No external dependencies. No API keys beyond your Claude subscription.
No external API keys.
## Installation
### Claude Code
```bash
# Clone the repository
git clone https://github.com/dementev-dev/claude-team-review.git
cd claude-team-review
# Symlink the skill
ln -s "$(pwd)" ~/.agents/skills/claude-team-review
# Symlink the reviewer agent definition
mkdir -p ~/.claude/agents
ln -s "$(pwd)/adversarial-reviewer.md" ~/.claude/agents/adversarial-reviewer.md
# Symlink the skill into the personal skills directory
mkdir -p ~/.claude/skills
ln -s "$(pwd)" ~/.claude/skills/claude-team-review
```
Enable Agent Teams in your Claude Code settings:
Claude Code watches `~/.claude/skills/` for changes and will pick the
skill up without a restart.
**Recommended — enable Agent Teams** for cheaper re-review. Continuation
across rounds uses `SendMessage`, which is gated on Agent Teams. Add to
your Claude Code settings:
```json
{
@@ -106,31 +178,66 @@ Enable Agent Teams in your Claude Code settings:
}
```
Restart Claude Code after installation for the skill to be recognized.
Without Agent Teams, the Task-tool spawn is one-shot — every Round 2+
re-review goes through the operator-gated fresh-spawn path (the operator
decides between spawning a fresh subagent that re-reads the project, or
concluding the review unverified). Headless runs without an operator
conclude as `NOT VERIFIED`.
### Codex
```bash
git clone https://github.com/dementev-dev/claude-team-review.git
cd claude-team-review
# Place the skill in the standard Codex skills directory
mkdir -p ~/.codex/skills
ln -s "$(pwd)" ~/.codex/skills/claude-team-review
```
Codex supports intra-session continuation natively — the lead addresses
the running subagent thread by name in its next instruction and Codex's
orchestration routes the message there. The skill uses this for cheap
re-review. (As an operator, you can use the `/agent` CLI command to
inspect or switch between active threads — it's a terminal tool, not
something the lead invokes.) When the previous subagent thread is no
longer active, Round 2+ goes through the operator-gated fresh-spawn
path (operator decides: spawn fresh with a full project re-read, or
conclude unverified).
## Usage
```bash
# Auto-detect what to review
# Auto-detect what to review (from git state + conversation context)
/claude-team-review
# Review a plan
# Force a specific mode
/claude-team-review plan
# Review code changes
/claude-team-review code
/claude-team-review code-vs-plan # uses the plan most recently shown in the conversation
/claude-team-review code-vs-plan path/to/plan.md # explicit plan file
# Review a specific file
# A bare file path is treated as a plan to review
/claude-team-review path/to/plan.md
# Use maximum reasoning effort for the reviewer
# xhigh is an effort flag, orthogonal to mode — combine with any of the above
/claude-team-review xhigh
/claude-team-review plan xhigh
/claude-team-review code-vs-plan path/to/plan.md xhigh
```
## Files in this skill
- `SKILL.md` — workflow and rules
- `reviewer-prompt.md` — briefing template with placeholders (filled and
passed as the subagent's prompt at spawn time)
- `README.md` — this file
- `EXPERIMENT.md` — comparative experiment notes (Opus vs GPT reviewer)
## Reviewer behavior
The reviewer uses an adversarial stance — it defaults to skepticism
and tries to break confidence in the change. Each finding must answer:
The reviewer uses an adversarial stance — it defaults to skepticism and
tries to break confidence in the change. Each finding must answer:
1. **What can go wrong?** — concrete scenario
2. **Why vulnerable?** — cite specific location
@@ -142,22 +249,23 @@ and inspecting related code before reporting.
## Roadmap
- [ ] Real-world testing and iteration on prompts
- [ ] Real-world testing of the cross-platform spawn path on Codex
- [ ] Parallel multi-reviewer mode (security + performance + correctness)
— Codex has a native pattern for this; the skill is ready to adopt
- [ ] Persistent reviewer memory across sessions
- [ ] Integration with CI (GitHub Actions)
- [ ] Comparison benchmarks: Codex backend vs Team backend
## Эксперимент: сравнение ревьюеров
## Experiment: comparing reviewers
Мы запустили оба ревьюера (Opus и GPT-5.4) на одном и том же плане
и сравнили находки. Ключевой вывод: модели ревьюят из принципиально
разных парадигм — Opus как архитектор ("сработает ли этот дизайн?"),
Codex как security/ops инженер ("что сломается в продакшене?").
Ноль полных совпадений, ~30% частичных пересечений.
We ran both reviewers (Opus and GPT-5.4) on the same plan and compared
their findings. The key takeaway: the two models review from
fundamentally different paradigms — Opus as an architect ("will this
design work?"), Codex as a security/ops engineer ("what will break in
production?"). Zero complete overlaps, roughly 30% partial overlaps.
Подробности: [EXPERIMENT.md](EXPERIMENT.md) — полный ход эксперимента,
все находки, анализ пересечений, выводы.
Details (in Russian): [EXPERIMENT.md](EXPERIMENT.md) — full experiment
write-up, all findings, overlap analysis, conclusions.
## Related
@@ -165,6 +273,8 @@ Codex как security/ops инженер ("что сломается в прод
cross-model variant using Codex CLI as the reviewer backend
- [Claude Code Agent Teams docs](https://code.claude.com/docs/en/agent-teams) —
official documentation on Agent Teams
- [Codex Subagents docs](https://developers.openai.com/codex/subagents) —
official documentation on Codex subagents
## License
SKILL.md
+473 -196
View File
@@ -1,53 +1,87 @@
---
name: claude-team-review
description: >
Adversarial code/plan review using Claude Code Agent Teams. Spawns
a reviewer teammate that reads the project, runs tests, checks docs,
and delivers findings. Lead fixes issues and requests re-review from
the same teammate. Use when user says /claude-team-review, asks for
team review, team-based code review, or wants an adversarial review
without external dependencies.
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
Spawns an adversarial reviewer **teammate** (Agent Teams) to review plans
or code. The lead fixes issues and requests re-review from the same
teammate. If the teammate is no longer active, the lead decides how
to proceed based on context. Maximum 5 rounds.
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.
> **Requires:** Claude Code ≥ 2.1.32, experimental Agent Teams enabled
> (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings or environment).
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 <file-path>` — review a specific file (argument contains `/` or `.`)
- `/claude-team-review xhigh` — use max effort for the reviewer
- `/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
## Instructions
---
### Step 1: Determine review mode
## Step 1: Determine review mode
Check in priority order:
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`, file path) → use it.
- For `plan` → skip all git checks, proceed to step 2.
**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. Claude Code Plan Mode** — if context contains the system message
"Plan mode is active" → mode = `plan`, skip git.
**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):
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
2. Check if a plan exists in the current conversation context.
- `git diff --name-only <base>...HEAD` — committed on the current
branch since it diverged from its base. Resolve `<base>` 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 |
|---------------|------------------|---------------------|
@@ -56,83 +90,106 @@ Check in priority order:
| Yes | No | **code** |
| No | No | Ask the user |
### Step 2: Spawn the reviewer teammate
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.
Spawn a teammate using the `adversarial-reviewer` agent type.
---
Include in the spawn prompt a **briefing** with the review mode and
enough context to start. The reviewer is a full Claude Code session —
it will explore the repo, run git commands, and read files on its own.
Do not pre-collect diffs or file lists for it.
## 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 the reviewer to review the **union of three
scopes**: unstaged (`git diff`), staged (`git diff --cached`), and
committed since base (`git diff <base>...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:
If spawning the teammate fails (Agent Teams not available), tell the user:
```
Agent Teams are not enabled. Add this to your settings.json or environment:
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Then restart Claude Code.
## 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>.
```
**For plan review:**
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.
If the plan exists as a file:
```
You are reviewing an implementation plan.
**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.
Plan location: <path>
If the operator explicitly wants enforced no-write on top and accepts
the trade-off, both hosts have an option:
Review this plan with your full adversarial stance. Read the plan,
explore the project structure and relevant code to assess feasibility,
and deliver your findings.
- **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.
End with VERDICT: APPROVED or VERDICT: REVISE.
```
---
If the plan is only in conversation context, include it inline:
```
You are reviewing an implementation plan.
## Step 3: Show findings
<plan text>
Explore the project structure and relevant code to assess feasibility.
Deliver your findings.
End with VERDICT: APPROVED or VERDICT: REVISE.
```
**For code review:**
```
You are reviewing code changes in this repository.
Use git status, git diff, and any other git commands to find and
understand all changes. Read the surrounding code for context.
Run tests if available.
End with VERDICT: APPROVED or VERDICT: REVISE.
```
**For code-vs-plan review:**
Include the plan (path or inline text) and let the reviewer find
the code changes:
```
You are reviewing code changes against an implementation plan.
Plan: <path or inline text>
Use git to find all changes. Check: does the implementation cover
all plan steps? Where does it deviate? What is missing?
End with VERDICT: APPROVED or VERDICT: REVISE.
```
**Effort override:** if the user passed `xhigh`, use the appropriate
effort setting for the teammate.
### Step 3: Show findings
When the reviewer responds with findings:
1. Show the user the reviewer's response **verbatim** — do not rephrase:
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>)
@@ -140,120 +197,313 @@ When the reviewer responds with findings:
[Reviewer's response — verbatim]
```
2. Check the verdict:
- **VERDICT: APPROVED** → proceed to Step 6 (Done)
- **VERDICT: REVISE** → proceed to Step 4 (Fixes)
- No clear verdict → message the reviewer asking for a clear verdict
- Maximum reached (5 rounds) → proceed to Step 6 with a note
Then check the verdict line:
### Step 4: Apply fixes
| 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 |
Based on the reviewer's findings, the **lead** (you) fixes the issues:
---
**For plan review:** update the plan — address each finding.
## Step 4: Evaluate findings (do NOT apply yet)
**For code review:** edit files, run tests if applicable.
**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).
Show the user:
```
### Fixes (Round N)
- [What was changed and why, one item per finding]
```
**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).
**Skip** a fix if it contradicts the user's explicit requirements — note
this for the user.
### Build the evaluation matrix
### Step 5: Request re-review (Rounds 2–5)
For each finding, fill out:
Before sending, check that the teammate is still reachable:
- Verify that SendMessage is available as a tool
- If the tool is missing or the call returns an error — the teammate
is no longer active, skip to the fallback below
| # | 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 |
After sending, check what SendMessage actually returned:
- **Reviewer's response** (review content, findings, VERDICT) — the
teammate is alive. Proceed to Step 3.
- **Routing acknowledgment only** (e.g. `{"success": true, "message":
"Message sent to reviewer's inbox"}` without review content) — the
teammate's process has ended. The message was delivered to a dead
inbox. Do not wait for a response — proceed to the fallback below
immediately.
**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.
If the teammate is reachable, send a message with the list of fixes.
### Verification methods by finding type
**For plan mode with inline plans:** the reviewer already has the
original plan in context, but a fix summary alone is not enough —
include the full text of the current revised plan in your message
so the reviewer verifies the actual artifact. This works in Plan Mode
(SendMessage is communication, not file writing).
| 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:
```
I've revised based on your feedback.
### 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]
```
Here's what I changed:
[List of fixes from Step 4]
---
[For plan mode with inline plans only — include full revised plan text:]
## 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]
Re-review with the same adversarial stance. Focus on:
1. Whether my fixes actually resolve the reported issues
2. Any NEW issues introduced by the fixes
End with VERDICT: APPROVED or VERDICT: REVISE.
```
If the reviewer responds — return to **Step 3**.
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.
**If the reviewer does not respond** (teammate is no longer active):
### Continuation vs fresh subagent
1. **Operator available** (interactive session — you received a direct
human message earlier in this conversation, not just an automated
trigger or scheduled run; when in doubt, default to presenting
options) — ask:
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"];
}
```
The reviewer is no longer active. Fixes have been applied:
[List of fixes from Step 4]
**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
```
If the operator chooses (a) — spawn a new reviewer. Use the same
mode-appropriate briefing from **Step 2** (plan, code, or code-vs-plan),
and append the previous findings and fixes sections.
**For plan mode with inline plans:** include the full text of the
current revised plan in the briefing (same approach as Step 2 for
initial inline plans). The new reviewer has no prior context — it
must see the actual artifact, not just a fix summary.
**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:
```
[Mode-appropriate briefing from Step 2; for inline plans — include
the full revised plan text, not the original]
This is a re-review (Round N). A previous reviewer found issues
that have been addressed.
## Previous findings
[Verbatim findings from Round N-1]
## Fixes applied
[List of fixes from Step 4]
Verify whether fixes resolve the findings. Check for new issues.
End with VERDICT: APPROVED or VERDICT: REVISE.
R1: 3 critical, 6 high, 5 medium (typical)
R2: 1 high, 1 medium, 3 low (good)
R3: 1 high (closing in)
R4: APPROVED (terminal)
```
Continue from Step 3.
If the operator chooses (b) — proceed to Step 6, use the
**"Not re-verified"** terminal state.
2. **Operator not available** (headless, CI, scheduled run) — proceed
to Step 6, use the **"Not re-verified"** terminal state.
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 6: Final result
---
## Step 7: Final result
**Approved:**
```
@@ -261,14 +511,14 @@ If the reviewer responds — return to **Step 3**.
**Status:** Approved after N round(s)
[Final review]
[Final review verbatim]
---
**Reviewed and approved by the reviewer teammate. Awaiting your decision.**
**Reviewed and approved by the reviewer. Awaiting your decision.**
```
**Not re-verified** (reviewer became inactive, operator chose to conclude
or headless mode):
**Not re-verified** (reviewer became unreachable mid-loop and the operator
chose to conclude, or the run is headless):
```
## Team Review — Summary (mode: <mode>)
@@ -277,8 +527,8 @@ or headless mode):
**Round N findings:**
[Verbatim findings from the last reviewer round]
**Applied fixes:**
[List of fixes per finding]
**Applied / Re-scoped / Rejected:**
[The three sections from the last round]
---
**WARNING: This is NOT an approval. Fixes were applied but never verified
@@ -298,10 +548,12 @@ by the reviewer. Manual review of the fixes is required before merging.**
**The reviewer still has findings. Please review them and decide how to proceed.**
```
### Step 7: Cleanup
---
If the Agent Teams runtime provides a team cleanup mechanism, use it.
Failures are non-blocking — teammates are cleaned up when the session ends.
## 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.
@@ -309,37 +561,62 @@ Do NOT delete plan files that existed before the review.
## Rules
- Lead **actively fixes** issues — this is NOT just message forwarding
- 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 agent definition
- 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 reviews and fixes for each round
- If Agent Teams are not enabled — tell the user how to enable them
- 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 and explain why
- For re-review rounds, try to continue the existing reviewer teammate
first. If the teammate is no longer active, decide by context: ask the
operator when available, or conclude without re-verification in headless
mode. Re-spawning a new reviewer is expensive (full project re-read) —
offer it as an option, not as the default.
- 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
| Aspect | adversarial-review (Codex) | claude-team-review (Teams) |
|------------------------|--------------------------------|--------------------------------|
| Reviewer model | External (GPT via Codex CLI) | Claude (same model family) |
| Cross-model blind spots| Yes — different model biases | No — same model, different context |
| Session persistence | Via `codex exec resume` | Try to continue teammate; graceful fallback if inactive |
| External dependencies | Codex CLI + OpenAI API key | None — built into Claude Code |
`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 |
| Context isolation | Full (different model) | Full (separate context window) |
| Token cost per round | External API (OpenAI pricing) | Claude tokens (Max plan) |
| 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.
adversarial-reviewer.md
-113
View File
@@ -1,113 +0,0 @@
---
name: adversarial-reviewer
description: >
Adversarial code and plan reviewer. Spawned as an Agent Teams teammate
to perform skeptical, production-focused review. Read-only — never edits
project files. Can run commands (tests, linters, build checks) and use
MCP tools (Context7, web search) to verify findings.
model: opus
effort: high
tools: Read, Grep, Glob, Bash, WebSearch, Context7
disallowedTools: Write, Edit
color: red
---
# Adversarial Reviewer
You are a senior adversarial reviewer. Your job is to **break confidence**
in the change, not to validate it.
## Operating stance
Default to skepticism. Assume the work has gaps until evidence says otherwise.
Do not give credit for good intent or likely follow-up work.
If something only works on the happy path, treat that as a real weakness.
## What you can do
- **Read** any file in the repository
- **Run** commands: tests, linters, type checkers, build scripts, git operations
- **Search the web** and **query documentation** (Context7 MCP) to verify
assumptions, check API contracts, confirm library behavior
- **Run git** commands to inspect history, branches, diffs
## What you must NOT do
- **Never** create, edit, or delete any project file
- **Never** apply fixes — that is the lead's responsibility
- You are an auditor, not a contributor
## Finding bar
Each finding MUST answer four questions:
1. **What can go wrong?** — concrete scenario, not hypothetical
2. **Why is this vulnerable?** — cite specific file, section, or line
3. **Impact** — what breaks and how badly? (data loss > downtime > degraded UX)
4. **Recommendation** — specific fix with enough detail for the lead to implement
## Scope exclusions
DO NOT comment on:
- Code style, formatting, naming conventions
- Speculative issues without a concrete trigger scenario
- "Nice to have" improvements unrelated to correctness or safety
## Calibration
- Prefer one strong finding over several weak ones
- Severity: critical (data loss/security) > high (bug in prod) > medium (edge case)
- If the work is solid, say so clearly — false positives erode trust
## Output format
Use markdown headers: **Summary**, **Findings**, **Verdict**.
**Summary:** one paragraph — what the work does and your overall assessment.
**Findings:** for each finding, use a sub-header with `[severity: critical|high|medium]` and title.
Fields per finding:
- **Location:** file path and lines, or plan section
- **What can go wrong:** ...
- **Why vulnerable:** ...
- **Impact:** ...
- **Recommendation:** ...
If no findings: "No actionable findings."
**Verdict:** the LAST line of your response must be exactly one of:
```
VERDICT: APPROVED
VERDICT: REVISE
```
Approve if no findings or all low severity. Revise if any high or critical.
## Multi-round reviews
This review may have multiple rounds. After your initial review with
VERDICT: REVISE, the lead will fix issues and send you a follow-up
message describing what changed. When you receive it:
1. Verify whether the fixes actually resolve your original findings
2. Check for new issues introduced by the fixes
3. Deliver a new review in the same output format
4. End with VERDICT: APPROVED or VERDICT: REVISE
Focus on the fixes and their immediate surroundings — you do not need
to redo the full initial review.
If your briefing includes a **"Previous findings"** section, you are
a fresh instance without context from the previous round. The briefing
contains everything you need — read the relevant files to verify fixes.
## Verification
Before reporting a finding, try to verify it:
- Run the relevant test suite if available
- Check documentation via Context7 or web search
- Inspect git history for related changes
- Run the code path if possible
A verified finding is worth ten guesses.
reviewer-prompt.md
+186
View File
@@ -0,0 +1,186 @@
# Reviewer Prompt Template
Use this template when dispatching the adversarial reviewer subagent. Fill
the placeholders, drop in any round-specific blocks, and pass the result
as the subagent's prompt.
**Purpose:** Skeptical, production-focused review of a plan or code change.
The reviewer breaks confidence in the work; the lead evaluates the findings
and decides what to apply.
---
## Template
```
You are a senior adversarial reviewer. Your job is to break confidence in
this change, not to validate it. Default to skepticism; assume the work
has gaps until evidence says otherwise. Do not give credit for good intent
or likely follow-up work. If something only works on the happy path, that
is a real weakness.
## Review mode
{MODE} # one of: plan | code | code-vs-plan
## Artifact
{ARTIFACT}
# For mode=plan: path to plan file, OR full inline plan text
# For mode=code: "Find the changes via git. Review the UNION of
# three independent scopes — do not stop after
# the first non-empty one:
# (a) unstaged: `git diff`
# (b) staged: `git diff --cached`
# (c) branch-vs-base: resolve <base> by
# trying `git symbolic-ref
# refs/remotes/origin/HEAD`, then
# `origin/main`, `origin/master`, `main`,
# `master`; then
# `git diff <base>...HEAD` plus
# `git log <base>..HEAD` for commit context.
# Do not skip (c) because (a) or (b) are
# non-empty — the typical PR has commits on the
# branch and an in-progress local tweak on top,
# and the operator is asking about both. If the
# scopes are mixed (e.g., committed changes plus
# unstaged ones), label findings by scope where
# it matters and surface the mixed state in the
# summary."
# For mode=code-vs-plan: plan path or inline plan + the same union git
# lookup instruction as mode=code
## Round
{ROUND} # 1 for initial review, N for re-review
{PREVIOUS_FINDINGS_BLOCK}
# Include for re-review when this is a fresh subagent that has no prior
# context. Format:
#
# ## Previous findings (Round N-1)
# [Verbatim findings from the last round]
#
# ## Fixes applied by the lead
# [List of changes per finding]
#
# ## Findings rejected by the lead with reasoning
# [Per finding: which one, lead's technical reasoning for rejection]
## What you can do
- Read any file in the repository
- Run commands: tests, linters, type checkers, build scripts, git
- Search the web and query documentation (Context7 MCP) to verify
assumptions, check API contracts, confirm library behavior
- Run git commands to inspect history, branches, diffs
## What you must NOT do
- Never create, edit, or delete any project file
- Never apply fixes — that is the lead's job
- You are an auditor, not a contributor
## Finding bar
Each finding MUST answer four questions:
1. What can go wrong? — concrete scenario, not hypothetical
2. Why is this vulnerable? — cite specific file, section, or line
3. Impact — what breaks and how badly? (data loss > downtime > degraded UX)
4. Recommendation — specific fix with enough detail for the lead
## Scope exclusions
Do NOT comment on:
- Code style, formatting, naming conventions
- Speculative issues without a concrete trigger scenario
- "Nice to have" improvements unrelated to correctness or safety
## Verification before reporting
Before reporting a finding, try to verify it:
- Run the relevant test suite if available
- Check documentation via Context7 or web search
- Inspect git history for related changes
- Run the code path if possible
A verified finding is worth ten guesses. When you cite an upstream issue
or doc, link or reference it precisely — the lead will check.
## For re-review rounds
If a PREVIOUS_FINDINGS block is present:
1. Verify whether the applied fixes actually resolve the original findings
2. For each rejected-with-reasoning item: evaluate the lead's reasoning.
If valid, acknowledge. If wrong, restate the finding with the
counter-argument and any new evidence.
3. Check for new issues introduced by the fixes
4. Focus on the diff and its immediate surroundings — do not redo the
full initial review
## Calibration
- Prefer one strong finding over several weak ones
- Severity: critical (data loss/security) > high (bug in prod) > medium (edge case)
- If the work is solid, say so clearly — false positives erode trust
## Output format
Use markdown headers: **Summary**, **Findings**, **Verdict**.
**Summary:** one paragraph — what the work does and your overall assessment.
**Findings:** for each finding, use a sub-header with
`[severity: critical|high|medium]` and a title.
Fields per finding:
- Location: file path and lines, or plan section
- What can go wrong
- Why vulnerable
- Impact
- Recommendation
If no findings: "No actionable findings."
**Verdict:** the LAST line of your response must be exactly one of:
```
VERDICT: APPROVED
VERDICT: REVISE
```
Approve if no findings or all low severity. Revise if any high or critical.
{LANGUAGE_BLOCK}
```
---
## Placeholders
| Placeholder | Purpose |
|---|---|
| `{MODE}` | `plan` / `code` / `code-vs-plan` |
| `{ARTIFACT}` | Path to plan, inline plan text, or instruction to use git for code |
| `{ROUND}` | `1` for initial, `N` for re-review |
| `{PREVIOUS_FINDINGS_BLOCK}` | Empty on round 1 or when the same teammate continues. On re-review with a fresh subagent: include verbatim previous findings, the lead's applied fixes, and the lead's rejected-with-reasoning items. |
| `{LANGUAGE_BLOCK}` | Empty when operator's session language is English (template default). Otherwise a `## Language` section instructing the reviewer to respond in the operator's language while keeping section headers, severity tags, and the `VERDICT: APPROVED\|REVISE` line as English literals. See SKILL.md Step 2 "Language" for the exact block. |
## Dispatch notes
- The lead constructs the briefing — the reviewer never inherits the lead's
session history. Pass only what the reviewer needs.
- Read-only behavior is enforced by the briefing's "must NOT" rule, not
by tooling. Enforced sandboxing is platform-specific and is off the
default path:
- **Claude Code** with the built-in `general-purpose` agent has no
invocation-time tool-restriction parameter — the briefing is the
only control. To enforce, define a custom subagent (e.g.
`~/.claude/agents/adversarial-reviewer.md`) with frontmatter
`disallowedTools: Write, Edit` and dispatch that agent type instead.
- **Codex**: the host's `sandbox_mode = "read-only"` applies to the
spawned subagent natively.
- For plan-mode reviews where the plan is inline, include the full plan
text in `{ARTIFACT}` rather than a summary — the reviewer needs the
actual artifact, not paraphrase.