Merge branch 'feat/cross-platform-receiving-review'
This commit is contained in:
@@ -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
|
Opus и GPT-5.4 получили одинаковый план и одинаковую adversarial
|
||||||
установку. Нашли разные проблемы. Этот документ — полный ход
|
установку. Нашли разные проблемы. Этот документ — полный ход
|
||||||
эксперимента: от наивного запуска до контролируемого сравнения.
|
эксперимента: от наивного запуска до контролируемого сравнения.
|
||||||
|
|||||||
@@ -1,70 +1,100 @@
|
|||||||
# Claude Team Review
|
# 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
|
## What is this
|
||||||
|
|
||||||
A [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code) that
|
A skill that spawns an adversarial reviewer as a subagent on the host
|
||||||
spawns an adversarial reviewer as an Agent Teams teammate. The reviewer
|
of your choice. The reviewer reads your project, runs tests, checks
|
||||||
reads your project, runs tests, checks documentation, and delivers findings
|
documentation, and delivers findings with a skeptical stance.
|
||||||
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
|
The lead (your main session) **does not blindly apply findings**. It
|
||||||
active, the lead decides how to proceed — re-spawn or conclude.
|
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)
|
### How it differs from [adversarial-review](https://github.com/dementev-dev/adversarial-review)
|
||||||
|
|
||||||
**adversarial-review** uses two different models (Claude writes, Codex
|
**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.
|
via `codex exec resume`. It requires Codex CLI and an OpenAI API key.
|
||||||
|
|
||||||
**claude-team-review** stays within the Claude ecosystem. No external
|
**claude-team-review** stays inside whichever host you're using. No
|
||||||
dependencies. The reviewer is a Claude Code teammate with its own context
|
external dependencies. The reviewer is a subagent with its own context
|
||||||
window, MCP access, and the ability to run commands. For re-review, the
|
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
|
lead tries continuation when the host supports it (e.g. Claude Code
|
||||||
active, the lead can re-spawn or conclude based on context. The trade-off:
|
Agent Teams), and otherwise spawns a fresh subagent with the previous-
|
||||||
same model family means no cross-model diversity.
|
rounds context block.
|
||||||
|
|
||||||
Use **adversarial-review** when you want maximum review quality through
|
Use **adversarial-review** when you want maximum review quality through
|
||||||
model diversity. Use **claude-team-review** when you want zero external
|
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
|
## How it works
|
||||||
|
|
||||||
```
|
```
|
||||||
┌──────────┐ spawn ┌────────────┐
|
┌──────────┐ spawn ┌────────────┐
|
||||||
│ Lead │ ───────────────> │ Reviewer │
|
│ Lead │ ───────────────> │ Reviewer │
|
||||||
│ (code) │ │ (teammate) │
|
│ (code) │ │ (subagent) │
|
||||||
└──────────┘ └────────────┘
|
└──────────┘ └────────────┘
|
||||||
^ │
|
^ │
|
||||||
│ findings │
|
│ findings │
|
||||||
│ <────────────────────────────┘
|
│ <────────────────────────────┘
|
||||||
│
|
│
|
||||||
│ fix issues
|
│ evaluate (matrix, verify)
|
||||||
|
│ apply / re-scope / reject
|
||||||
v
|
v
|
||||||
┌──────────┐ message ┌────────────┐
|
┌──────────┐ re-review ┌────────────┐
|
||||||
│ Lead │ ───────────────> │ Reviewer │
|
│ Lead │ ───────────────> │ Reviewer │
|
||||||
│ (fixed) │ "re-check this" │ (same / new)│
|
│ (fixed) │ "applied A, │(same / new)│
|
||||||
└──────────┘ └────────────┘
|
│ │ rejected B └────────────┘
|
||||||
│
|
│ │ with reason" │
|
||||||
|
└──────────┘ │
|
||||||
VERDICT: APPROVED
|
VERDICT: APPROVED
|
||||||
```
|
```
|
||||||
|
|
||||||
The lead tries to continue the **same teammate** for re-review. If the
|
The lead tries to **continue the same reviewer** for re-review when the
|
||||||
teammate is no longer active (Agent Teams limitation), the lead can
|
host supports it (cheaper — context is preserved). Codex supports
|
||||||
re-spawn with a full briefing or conclude without re-verification.
|
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
|
### Three modes
|
||||||
|
|
||||||
| Mode | What it reviews | When to use |
|
| Mode | What it reviews | When to use |
|
||||||
|----------------|------------------------------------|--------------------------|
|
|----------------|------------------------------------------|--------------------------|
|
||||||
| `plan` | Implementation plan | Before writing code |
|
| `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 |
|
| `code-vs-plan` | Code changes against the plan | Verify implementation |
|
||||||
|
|
||||||
Mode is auto-detected from context, or you can force it with an argument.
|
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
|
### What the reviewer can do
|
||||||
|
|
||||||
- **Read** any file in the repository
|
- **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)
|
- **Search the web** and **query documentation** via MCP (Context7)
|
||||||
- **Inspect git history** — blame, log, diff
|
- **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
|
## Requirements
|
||||||
|
|
||||||
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) ≥ 2.1.32
|
- A host that supports subagents — Claude Code or Codex
|
||||||
- Agent Teams enabled (experimental)
|
- 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
|
## Installation
|
||||||
|
|
||||||
|
### Claude Code
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
|
||||||
git clone https://github.com/dementev-dev/claude-team-review.git
|
git clone https://github.com/dementev-dev/claude-team-review.git
|
||||||
cd claude-team-review
|
cd claude-team-review
|
||||||
|
|
||||||
# Symlink the skill
|
# Symlink the skill into the personal skills directory
|
||||||
ln -s "$(pwd)" ~/.agents/skills/claude-team-review
|
mkdir -p ~/.claude/skills
|
||||||
|
ln -s "$(pwd)" ~/.claude/skills/claude-team-review
|
||||||
# Symlink the reviewer agent definition
|
|
||||||
mkdir -p ~/.claude/agents
|
|
||||||
ln -s "$(pwd)/adversarial-reviewer.md" ~/.claude/agents/adversarial-reviewer.md
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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
|
```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
|
## Usage
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Auto-detect what to review
|
# Auto-detect what to review (from git state + conversation context)
|
||||||
/claude-team-review
|
/claude-team-review
|
||||||
|
|
||||||
# Review a plan
|
# Force a specific mode
|
||||||
/claude-team-review plan
|
/claude-team-review plan
|
||||||
|
|
||||||
# Review code changes
|
|
||||||
/claude-team-review code
|
/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
|
/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 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
|
## Reviewer behavior
|
||||||
|
|
||||||
The reviewer uses an adversarial stance — it defaults to skepticism
|
The reviewer uses an adversarial stance — it defaults to skepticism and
|
||||||
and tries to break confidence in the change. Each finding must answer:
|
tries to break confidence in the change. Each finding must answer:
|
||||||
|
|
||||||
1. **What can go wrong?** — concrete scenario
|
1. **What can go wrong?** — concrete scenario
|
||||||
2. **Why vulnerable?** — cite specific location
|
2. **Why vulnerable?** — cite specific location
|
||||||
@@ -142,22 +249,23 @@ and inspecting related code before reporting.
|
|||||||
|
|
||||||
## Roadmap
|
## 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)
|
- [ ] 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
|
- [ ] Persistent reviewer memory across sessions
|
||||||
- [ ] Integration with CI (GitHub Actions)
|
- [ ] Integration with CI (GitHub Actions)
|
||||||
- [ ] Comparison benchmarks: Codex backend vs Team backend
|
- [ ] Comparison benchmarks: Codex backend vs Team backend
|
||||||
|
|
||||||
## Эксперимент: сравнение ревьюеров
|
## Experiment: comparing reviewers
|
||||||
|
|
||||||
Мы запустили оба ревьюера (Opus и GPT-5.4) на одном и том же плане
|
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
|
||||||
разных парадигм — Opus как архитектор ("сработает ли этот дизайн?"),
|
fundamentally different paradigms — Opus as an architect ("will this
|
||||||
Codex как security/ops инженер ("что сломается в продакшене?").
|
design work?"), Codex as a security/ops engineer ("what will break in
|
||||||
Ноль полных совпадений, ~30% частичных пересечений.
|
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
|
## Related
|
||||||
|
|
||||||
@@ -165,6 +273,8 @@ Codex как security/ops инженер ("что сломается в прод
|
|||||||
cross-model variant using Codex CLI as the reviewer backend
|
cross-model variant using Codex CLI as the reviewer backend
|
||||||
- [Claude Code Agent Teams docs](https://code.claude.com/docs/en/agent-teams) —
|
- [Claude Code Agent Teams docs](https://code.claude.com/docs/en/agent-teams) —
|
||||||
official documentation on Agent Teams
|
official documentation on Agent Teams
|
||||||
|
- [Codex Subagents docs](https://developers.openai.com/codex/subagents) —
|
||||||
|
official documentation on Codex subagents
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|||||||
@@ -1,53 +1,87 @@
|
|||||||
---
|
---
|
||||||
name: claude-team-review
|
name: claude-team-review
|
||||||
description: >
|
description: >
|
||||||
Adversarial code/plan review using Claude Code Agent Teams. Spawns
|
Use when user says /claude-team-review, requests adversarial review of a
|
||||||
a reviewer teammate that reads the project, runs tests, checks docs,
|
plan or code change, wants peer review without external API dependencies,
|
||||||
and delivers findings. Lead fixes issues and requests re-review from
|
or needs to verify implementation against a plan before merging.
|
||||||
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.
|
|
||||||
user_invocable: true
|
user_invocable: true
|
||||||
---
|
---
|
||||||
|
|
||||||
# Claude Team Review
|
# Claude Team Review
|
||||||
|
|
||||||
Spawns an adversarial reviewer **teammate** (Agent Teams) to review plans
|
Adversarial review of plans and code through a peer-reviewer subagent.
|
||||||
or code. The lead fixes issues and requests re-review from the same
|
The reviewer reads the project, runs tests and docs lookups, and delivers
|
||||||
teammate. If the teammate is no longer active, the lead decides how
|
findings. The lead **evaluates** those findings (not blindly applies them),
|
||||||
to proceed based on context. Maximum 5 rounds.
|
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
|
Works on **any host that supports subagents** — Claude Code (via Task tool
|
||||||
> (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings or environment).
|
or Agent Teams) and Codex (native subagents) are both fine. The skill is
|
||||||
|
platform-agnostic; the platform decides how to spawn.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## When to invoke
|
## 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` — auto-detect what to review
|
||||||
- `/claude-team-review plan` — force plan review
|
- `/claude-team-review plan` — force plan review
|
||||||
- `/claude-team-review code` — force code review
|
- `/claude-team-review code` — force code review
|
||||||
- `/claude-team-review <file-path>` — review a specific file (argument contains `/` or `.`)
|
- `/claude-team-review code-vs-plan` — force code-vs-plan review (uses the plan most recently shown in this conversation)
|
||||||
- `/claude-team-review xhigh` — use max effort for the reviewer
|
- `/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.
|
**1. Explicit argument** (`plan`, `code`, `code-vs-plan`,
|
||||||
- For `plan` → skip all git checks, proceed to step 2.
|
`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
|
**2. Plan Mode active** (Claude Code) — if context contains the system
|
||||||
"Plan mode is active" → mode = `plan`, skip git.
|
message "Plan mode is active" → mode = `plan`, skip git.
|
||||||
|
|
||||||
**3. Auto-detect** (no explicit argument, not in Plan Mode):
|
**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 --name-only` — unstaged
|
||||||
- `git diff --cached --name-only` — staged
|
- `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 |
|
| Code changes? | Plan in context? | Mode |
|
||||||
|---------------|------------------|---------------------|
|
|---------------|------------------|---------------------|
|
||||||
@@ -56,83 +90,106 @@ Check in priority order:
|
|||||||
| Yes | No | **code** |
|
| Yes | No | **code** |
|
||||||
| No | No | Ask the user |
|
| 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
|
## Step 2: Spawn the reviewer
|
||||||
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.
|
**Spawn a reviewer subagent using your host's standard mechanism**, and
|
||||||
Do not pre-collect diffs or file lists for it.
|
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:
|
## Language
|
||||||
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
|
||||||
Then restart Claude Code.
|
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:
|
**Tool restrictions.** The briefing's "must NOT modify files" rule is
|
||||||
```
|
the primary control on both hosts and the default. **Do not reach for
|
||||||
You are reviewing an implementation plan.
|
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,
|
- **Claude Code:** define a custom subagent (e.g.
|
||||||
explore the project structure and relevant code to assess feasibility,
|
`~/.claude/agents/adversarial-reviewer.md`) with frontmatter
|
||||||
and deliver your findings.
|
`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:
|
## Step 3: Show findings
|
||||||
```
|
|
||||||
You are reviewing an implementation plan.
|
|
||||||
|
|
||||||
<plan text>
|
When the reviewer responds, show the user the response **verbatim** — do
|
||||||
|
not rephrase, summarize, or reorder:
|
||||||
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:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
## Team Review — Round N (mode: <plan|code|code-vs-plan>)
|
## Team Review — Round N (mode: <plan|code|code-vs-plan>)
|
||||||
@@ -140,120 +197,313 @@ When the reviewer responds with findings:
|
|||||||
[Reviewer's response — verbatim]
|
[Reviewer's response — verbatim]
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Check the verdict:
|
Then check the verdict line:
|
||||||
- **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
|
|
||||||
|
|
||||||
### 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:
|
**Use `superpowers:receiving-code-review` when available** — it has the
|
||||||
```
|
full discipline for this step. The key principles are inlined below as
|
||||||
### Fixes (Round N)
|
the always-available fallback (so the matrix step works on any host,
|
||||||
- [What was changed and why, one item per finding]
|
even where Superpowers is not installed).
|
||||||
```
|
|
||||||
|
|
||||||
**Skip** a fix if it contradicts the user's explicit requirements — note
|
### Build the evaluation matrix
|
||||||
this for the user.
|
|
||||||
|
|
||||||
### Step 5: Request re-review (Rounds 2–5)
|
For each finding, fill out:
|
||||||
|
|
||||||
Before sending, check that the teammate is still reachable:
|
| # | Severity | Verified? | Type | Action |
|
||||||
- Verify that SendMessage is available as a tool
|
|---|----------|-----------|------|--------|
|
||||||
- If the tool is missing or the call returns an error — the teammate
|
| 1 | high | ✓ Context7 confirms behavior | arch | accept |
|
||||||
is no longer active, skip to the fallback below
|
| 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:
|
**Action** options are equal — `accept`, `reject with reasoning`, and
|
||||||
- **Reviewer's response** (review content, findings, VERDICT) — the
|
`re-scope` (apply a narrower fix). Reject and re-scope are not
|
||||||
teammate is alive. Proceed to Step 3.
|
exceptions; they are first-class outcomes.
|
||||||
- **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.
|
|
||||||
|
|
||||||
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
|
| Finding type | What constitutes verification |
|
||||||
original plan in context, but a fix summary alone is not enough —
|
|---|---|
|
||||||
include the full text of the current revised plan in your message
|
| Architectural / design | Reasoning + codebase grep, plus pattern check against existing code |
|
||||||
so the reviewer verifies the actual artifact. This works in Plan Mode
|
| Tool-mechanic (DSL syntax, config parser, API contract, library behavior) | **Empirical test on the real system** — reasoning is not enough |
|
||||||
(SendMessage is communication, not file writing).
|
| 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
|
## Current revised plan
|
||||||
[Full text of the 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
|
The cheap path is **continuation** — the same reviewer keeps context
|
||||||
human message earlier in this conversation, not just an automated
|
between rounds. Fresh-spawn is expensive: the new subagent must re-read
|
||||||
trigger or scheduled run; when in doubt, default to presenting
|
the project from scratch. Because of that cost, **fresh-spawn is always
|
||||||
options) — ask:
|
operator-gated**, regardless of platform.
|
||||||
```
|
|
||||||
The reviewer is no longer active. Fixes have been applied:
|
|
||||||
[List of fixes from Step 4]
|
|
||||||
|
|
||||||
Options:
|
```dot
|
||||||
(a) Spawn a new reviewer to verify fixes (expensive — full project re-read)
|
digraph re_review {
|
||||||
(b) Conclude the review — fixes applied, verification is on you
|
"Continuation supported by host\nand previous reviewer alive?" [shape=diamond];
|
||||||
```
|
"Continue same reviewer" [shape=box style=filled fillcolor=lightgreen];
|
||||||
If the operator chooses (a) — spawn a new reviewer. Use the same
|
"Operator available?" [shape=diamond];
|
||||||
mode-appropriate briefing from **Step 2** (plan, code, or code-vs-plan),
|
"Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" [shape=box];
|
||||||
and append the previous findings and fixes sections.
|
"Spawn fresh subagent\nwith PREVIOUS_FINDINGS block" [shape=box];
|
||||||
|
"Step 7 — NOT VERIFIED terminal state" [shape=box style=filled fillcolor=lightyellow];
|
||||||
|
|
||||||
**For plan mode with inline plans:** include the full text of the
|
"Continuation supported by host\nand previous reviewer alive?" -> "Continue same reviewer" [label="yes"];
|
||||||
current revised plan in the briefing (same approach as Step 2 for
|
"Continuation supported by host\nand previous reviewer alive?" -> "Operator available?" [label="no"];
|
||||||
initial inline plans). The new reviewer has no prior context — it
|
"Operator available?" -> "Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" [label="yes"];
|
||||||
must see the actual artifact, not just a fix summary.
|
"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
|
||||||
[Mode-appropriate briefing from Step 2; for inline plans — include
|
relying on this):**
|
||||||
the full revised plan text, not the original]
|
|
||||||
|
|
||||||
This is a re-review (Round N). A previous reviewer found issues
|
| Host | Continuation | Mechanism |
|
||||||
that have been addressed.
|
|---|---|---|
|
||||||
|
| 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) |
|
||||||
|
|
||||||
## Previous findings
|
Two routes lead to the "ask operator" step:
|
||||||
[Verbatim findings from Round N-1]
|
- 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)
|
||||||
|
|
||||||
## Fixes applied
|
**Detecting a dead reviewer (continuation-supporting hosts).** The send
|
||||||
[List of fixes from Step 4]
|
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:
|
||||||
|
|
||||||
Verify whether fixes resolve the findings. Check for new issues.
|
- 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).
|
||||||
|
|
||||||
End with VERDICT: APPROVED or VERDICT: REVISE.
|
When unreachable is confirmed, fall through to the operator question.
|
||||||
```
|
|
||||||
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
|
**Detecting an operator.** Treat the run as **interactive** (operator
|
||||||
to Step 6, use the **"Not re-verified"** terminal state.
|
available) only if both conditions hold:
|
||||||
|
|
||||||
### Step 6: Final result
|
1. The current conversation has a direct human message — not just an
|
||||||
|
automated trigger, hook, scheduled run, or CI invocation
|
||||||
|
2. The host exposes a user-facing channel to surface the question
|
||||||
|
|
||||||
|
When in doubt, default to **presenting the choice** — pausing once is
|
||||||
|
cheaper than concluding unverified by mistake.
|
||||||
|
|
||||||
|
**Asking the operator.** Present the choice plainly:
|
||||||
|
|
||||||
|
```
|
||||||
|
The reviewer cannot be continued from the previous round
|
||||||
|
(reason: <no continuation on this host | previous reviewer ended>).
|
||||||
|
|
||||||
|
Fixes applied:
|
||||||
|
[List from Step 5]
|
||||||
|
|
||||||
|
Options:
|
||||||
|
(a) Spawn a new reviewer to verify fixes (expensive — full project re-read)
|
||||||
|
(b) Conclude the review — fixes applied, verification is on you
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fresh subagent re-review (if operator chose re-spawn).** Fill the
|
||||||
|
`{PREVIOUS_FINDINGS_BLOCK}` placeholder in `reviewer-prompt.md` with:
|
||||||
|
1. Verbatim previous findings
|
||||||
|
2. The Applied / Re-scoped / Rejected-with-reasoning sections
|
||||||
|
3. For plan mode with inline plans: the full revised plan text
|
||||||
|
|
||||||
|
The fresh reviewer has zero prior context — it must see the actual artifact,
|
||||||
|
not a paraphrase.
|
||||||
|
|
||||||
|
When the reviewer responds — return to **Step 3** with N+1.
|
||||||
|
|
||||||
|
### Severity declination (soft signal)
|
||||||
|
|
||||||
|
Expect severity of findings to decline across rounds:
|
||||||
|
|
||||||
|
```
|
||||||
|
R1: 3 critical, 6 high, 5 medium (typical)
|
||||||
|
R2: 1 high, 1 medium, 3 low (good)
|
||||||
|
R3: 1 high (closing in)
|
||||||
|
R4: APPROVED (terminal)
|
||||||
|
```
|
||||||
|
|
||||||
|
If severity **stays flat** (e.g. high → high → high), something is
|
||||||
|
structurally off — the lead may not understand the technology, the reviewer
|
||||||
|
may be looping on the same misunderstanding, or the artifact has a deep
|
||||||
|
problem that surface fixes can't reach. Pause and surface to the user.
|
||||||
|
This is a soft signal, not a hard gate.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 7: Final result
|
||||||
|
|
||||||
**Approved:**
|
**Approved:**
|
||||||
```
|
```
|
||||||
@@ -261,14 +511,14 @@ If the reviewer responds — return to **Step 3**.
|
|||||||
|
|
||||||
**Status:** Approved after N round(s)
|
**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
|
**Not re-verified** (reviewer became unreachable mid-loop and the operator
|
||||||
or headless mode):
|
chose to conclude, or the run is headless):
|
||||||
```
|
```
|
||||||
## Team Review — Summary (mode: <mode>)
|
## Team Review — Summary (mode: <mode>)
|
||||||
|
|
||||||
@@ -277,8 +527,8 @@ or headless mode):
|
|||||||
**Round N findings:**
|
**Round N findings:**
|
||||||
[Verbatim findings from the last reviewer round]
|
[Verbatim findings from the last reviewer round]
|
||||||
|
|
||||||
**Applied fixes:**
|
**Applied / Re-scoped / Rejected:**
|
||||||
[List of fixes per finding]
|
[The three sections from the last round]
|
||||||
|
|
||||||
---
|
---
|
||||||
**WARNING: This is NOT an approval. Fixes were applied but never verified
|
**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.**
|
**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.
|
## Step 8: Cleanup
|
||||||
Failures are non-blocking — teammates are cleaned up when the session ends.
|
|
||||||
|
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.
|
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
|
## 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
|
- Reviewer findings shown **verbatim** — do not rephrase or shorten
|
||||||
- Auto-detect mode from context; user arguments take priority
|
- 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**
|
- The reviewer **can run commands** (tests, linters, git) and **use MCP**
|
||||||
(Context7, web search) to verify findings
|
(Context7, web search) to verify findings
|
||||||
- Maximum 5 rounds to protect against infinite loops
|
- Maximum 5 rounds to protect against infinite loops
|
||||||
- Show the user reviews and fixes for each round
|
- Show the user findings and the applied/rejected breakdown for each round
|
||||||
- If Agent Teams are not enabled — tell the user how to enable them
|
|
||||||
- Avoid creating auxiliary files (memory files, state files, logs, temporary
|
- Avoid creating auxiliary files (memory files, state files, logs, temporary
|
||||||
markdown) — prefer working within the conversation context
|
markdown) — prefer working within the conversation context
|
||||||
- If a fix contradicts user requirements — skip and explain why
|
- If a fix contradicts user requirements — skip it and explain why
|
||||||
- For re-review rounds, try to continue the existing reviewer teammate
|
- For re-review, prefer continuation (cheap). Fresh-spawn is the
|
||||||
first. If the teammate is no longer active, decide by context: ask the
|
expensive path — always confirm with the operator before doing it.
|
||||||
operator when available, or conclude without re-verification in headless
|
In headless runs without operator access, conclude unverified rather
|
||||||
mode. Re-spawning a new reviewer is expensive (full project re-read) —
|
than auto-respawning.
|
||||||
offer it as an option, not as the default.
|
|
||||||
- The ultimate goal is **higher quality** of plans, code, and other
|
- The ultimate goal is **higher quality** of plans, code, and other
|
||||||
artifacts. Token economy is a means, not an end — never skip a
|
artifacts. Token economy is a means, not an end — never skip a
|
||||||
verification step or cut a round short just to save tokens.
|
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
|
## Comparison with adversarial-review
|
||||||
|
|
||||||
| Aspect | adversarial-review (Codex) | claude-team-review (Teams) |
|
`adversarial-review` is a related but distinct skill (different repo):
|
||||||
|------------------------|--------------------------------|--------------------------------|
|
Claude writes, Codex reviews — cross-model coverage.
|
||||||
| Reviewer model | External (GPT via Codex CLI) | Claude (same model family) |
|
|
||||||
| Cross-model blind spots| Yes — different model biases | No — same model, different context |
|
| Aspect | adversarial-review (cross-model) | claude-team-review (same-host) |
|
||||||
| 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 |
|
| Reviewer model | External (GPT via Codex CLI from Claude) | Whatever the host runs |
|
||||||
| Reviewer capabilities | Read-only sandbox | Read + execute + MCP + web |
|
| Cross-model blind spots | Yes — different model biases | No — same model family |
|
||||||
| Context isolation | Full (different model) | Full (separate context window) |
|
| Session persistence | Via `codex exec resume` | Continuation if host supports it; otherwise operator-gated fresh-spawn |
|
||||||
| Token cost per round | External API (OpenAI pricing) | Claude tokens (Max plan) |
|
| External dependencies | Codex CLI + OpenAI API key (from Claude) | None — uses host's native subagent mechanism |
|
||||||
|
| Reviewer capabilities | Read-only sandbox | Read + execute + MCP + web |
|
||||||
|
| Host compatibility | Designed for Claude Code as lead | Claude Code AND Codex as lead |
|
||||||
|
|
||||||
|
Use `adversarial-review` for cross-model diversity. Use `claude-team-review`
|
||||||
|
when you want zero external dependencies and a richer reviewer (tests, docs,
|
||||||
|
web), regardless of which host is the lead.
|
||||||
|
|||||||
@@ -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