Compare commits
10
Commits
d9c78861e2
...
264ce9017f
| Author | SHA1 | Date | |
|---|---|---|---|
 ddadmin
|
264ce9017f | ||
 ddadminandClaude Fable 5
|
2f2f7446a5 | ||
|
ddadmin
|
8a0e5b8879 | ||
|
ddadmin
|
933c48fb3c | ||
|
ddadminandClaude Opus 4.7
|
657e7c3507 | ||
|
ddadminandClaude Opus 4.7
|
a9f8d032f3 | ||
|
ddadmin
|
bb8c9cf0e1 | ||
|
ddadmin
|
2d88edcf52 | ||
|
ddadmin
|
ef97a43791 | ||
|
ddadminandClaude Opus 4.6
|
097808d158 |
@@ -0,0 +1 @@
|
||||
tmp
|
||||
@@ -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
|
||||
установку. Нашли разные проблемы. Этот документ — полный ход
|
||||
эксперимента: от наивного запуска до контролируемого сравнения.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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,111 @@ 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.
|
||||
|
||||
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 <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,112 +202,357 @@ 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:
|
||||
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.
|
||||
|
||||
**For plan review:** update the plan — address each finding.
|
||||
---
|
||||
|
||||
**For code review:** edit files, run tests if applicable.
|
||||
## Step 4: Evaluate findings (do NOT apply yet)
|
||||
|
||||
Show the user:
|
||||
```
|
||||
### Fixes (Round N)
|
||||
- [What was changed and why, one item per finding]
|
||||
```
|
||||
**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).
|
||||
|
||||
**Skip** a fix if it contradicts the user's explicit requirements — note
|
||||
this for the user.
|
||||
**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).
|
||||
|
||||
### Step 5: Request re-review (Rounds 2–5)
|
||||
### Build the evaluation matrix
|
||||
|
||||
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
|
||||
For each finding, fill out:
|
||||
|
||||
If the teammate is reachable, send a message with the list of fixes:
|
||||
| # | 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:
|
||||
|
||||
```
|
||||
I've revised based on your feedback.
|
||||
|
||||
Here's what I changed:
|
||||
[List of fixes from Step 4]
|
||||
|
||||
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.
|
||||
### 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]
|
||||
```
|
||||
|
||||
If the reviewer responds — return to **Step 3**.
|
||||
---
|
||||
|
||||
**If the reviewer does not respond** (teammate is no longer active):
|
||||
## Step 6: Request re-review (Rounds 2–5)
|
||||
|
||||
Compose a structured response and send it to the reviewer.
|
||||
|
||||
### Response format
|
||||
|
||||
1. **Operator available** (interactive session — the conversation was
|
||||
initiated by a human message, not a CI trigger or scheduled run) — ask:
|
||||
```
|
||||
The reviewer is no longer active. Fixes have been applied:
|
||||
[List of fixes from Step 4]
|
||||
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: <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 with this briefing:
|
||||
|
||||
**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:
|
||||
|
||||
```
|
||||
You are reviewing code changes in this repository.
|
||||
|
||||
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.
|
||||
```
|
||||
Continue from Step 3.
|
||||
If the operator chooses (b) — proceed to Step 6.
|
||||
|
||||
2. **Operator not available** (headless, CI, scheduled run) — proceed
|
||||
to Step 6 with status "fixes applied, not re-verified":
|
||||
```
|
||||
## Team Review — Summary (mode: <mode>)
|
||||
|
||||
**Status:** Fixes applied, re-verification not completed
|
||||
(reviewer became inactive after Round N)
|
||||
|
||||
**Applied fixes:**
|
||||
[List of fixes per finding]
|
||||
|
||||
**Note:** First-round findings were addressed but not re-verified
|
||||
by the reviewer. Manual review of fixes is recommended.
|
||||
R1: 3 critical, 6 high, 5 medium (typical)
|
||||
R2: 1 high, 1 medium, 3 low (good)
|
||||
R3: 1 high (closing in)
|
||||
R4: APPROVED (terminal)
|
||||
```
|
||||
|
||||
### Step 6: Final result
|
||||
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: <mode>)
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
**Reviewer:** <mechanism, agent type, model line>
|
||||
|
||||
[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 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
|
||||
**Reviewer:** <mechanism, agent type, model line>
|
||||
|
||||
**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:**
|
||||
@@ -253,6 +560,7 @@ If the reviewer responds — return to **Step 3**.
|
||||
## Team Review — Summary (mode: <mode>)
|
||||
|
||||
**Status:** Maximum reached (5 rounds) — not fully approved
|
||||
**Reviewer:** <mechanism, agent type, model line>
|
||||
|
||||
**Remaining findings:**
|
||||
[Unresolved issues]
|
||||
@@ -261,10 +569,12 @@ If the reviewer responds — return to **Step 3**.
|
||||
**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.
|
||||
|
||||
@@ -272,37 +582,68 @@ 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
|
||||
- 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 `<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. |
|
||||
| "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
|
||||
|
||||
| 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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user