claude-team-review/README.md

# Claude Team Review

Adversarial code and plan review through a peer-reviewer subagent.

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 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
via `codex exec resume`. It requires Codex CLI and an OpenAI API key.

**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 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) running on
the same host as the lead.

## How it works

```
┌──────────┐     spawn        ┌────────────┐
│   Lead   │ ───────────────> │  Reviewer  │
│  (code)  │                  │ (subagent) │
└──────────┘                  └────────────┘
     ^                              │
     │          findings            │
     │ <────────────────────────────┘
     │
     │  evaluate (matrix, verify)
     │  apply / re-scope / reject
     v
┌──────────┐     re-review    ┌────────────┐
│   Lead   │ ───────────────> │  Reviewer  │
│  (fixed) │   "applied A,    │(same / new)│
│          │    rejected B    └────────────┘
│          │    with reason"        │
└──────────┘                        │
                              VERDICT: APPROVED
```

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-vs-plan` | Code changes against the plan      | Verify implementation    |

Mode is auto-detected from context, or you can force it with an argument.

### 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
- **Run commands** — tests, linters, type checkers, build scripts
- **Search the web** and **query documentation** via MCP (Context7)
- **Inspect git history** — blame, log, diff

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

- A host that supports subagents — Claude Code or Codex
- Optional: Claude Code with Agent Teams enabled, for cheaper re-review
  via continuation

No external API keys.

## Installation

### Claude Code

```bash
git clone https://github.com/dementev-dev/claude-team-review.git
cd claude-team-review

# Symlink the skill into the personal skills directory
mkdir -p ~/.claude/skills
ln -s "$(pwd)" ~/.claude/skills/claude-team-review
```

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
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

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 (from git state + conversation context)
/claude-team-review

# Force a specific mode
/claude-team-review plan
/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

# A bare file path is treated as a plan to review
/claude-team-review path/to/plan.md

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

1. **What can go wrong?** — concrete scenario
2. **Why vulnerable?** — cite specific location
3. **Impact** — what breaks and how badly
4. **Recommendation** — specific fix

The reviewer verifies findings by running tests, checking documentation,
and inspecting related code before reporting.

## Roadmap

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

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.

Details (in Russian): [EXPERIMENT.md](EXPERIMENT.md) — full experiment
write-up, all findings, overlap analysis, conclusions.

## Related

- [adversarial-review](https://github.com/dementev-dev/adversarial-review) —
  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

Apache-2.0 — see [LICENSE](LICENSE).