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.

### 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. If your host supports an enforced read-only sandbox
(Claude Code `disallowedTools`, Codex `sandbox_mode = "read-only"`), the
skill recommends applying it on top.

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

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 can send
follow-up instructions to a running subagent thread (use `/agent` to
switch between active threads). The skill uses this for cheap re-review.
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
/claude-team-review

# Review a plan
/claude-team-review plan

# Review code changes
/claude-team-review code

# Review a specific file
/claude-team-review path/to/plan.md

# Use maximum reasoning effort for the reviewer
/claude-team-review 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).