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

feat(skill): поддержка Codex и интеграция с receiving-code-review

Browse Source 
- Зачем:
  - Скилл был привязан к Claude Code Agent Teams, в Codex приходилось
    вручную комбинировать /receiving-code-review и /claude-team-review.
    В реальной L4-сессии lead применял findings без верификации, что
    привело к большой структурной правке на основе неверной цитаты
    из upstream-issue.
- Что:
  - SKILL.md: platform-agnostic спавн (Claude Code Task/Agent Teams,
    Codex native subagents). Новые шаги Evaluate findings (matrix +
    verification-by-type, REQUIRED SUB-SKILL на receiving-code-review)
    и Apply/push-back (three-section response — applied / re-scoped /
    rejected-with-reasoning). Fresh-spawn теперь operator-gated на
    любой платформе. Добавлена Red Flags table.
  - reviewer-prompt.md: новый briefing template с placeholders,
    заменяет Claude Code-specific agent definition.
  - README.md: пути установки исправлены на ~/.claude/skills/ и
    ~/.codex/skills/, формулировка cross-platform смягчена, секция
    эксперимента переведена в английский для единого языка.
  - adversarial-reviewer.md: удалён (содержимое переехало в
    reviewer-prompt.md).
  - .gitignore: tmp/ для локальных рабочих заметок.
- Проверка:
  - Прогнать /claude-team-review на этих же изменениях в отдельной
    ветке для self-review.
This commit is contained in:
ddadmin
2026-05-15 14:01:04 +03:00
parent ef97a43791
commit 2d88edcf52
5 changed files with 568 additions and 359 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+114 -50
View File
@@ -1,59 +1,73 @@
# Claude Team Review
Adversarial code and plan review using Claude Code Agent Teams.
Adversarial code and plan review through a peer-reviewer subagent.
One teammate reviews. The lead fixes. Iterate until approved.
One subagent reviews. The lead evaluates findings, fixes what holds up,
pushes back on what doesn't, and asks for re-review. Up to 5 rounds.
**Designed for Claude Code and Codex.** The skill is platform-agnostic
in its instructions, so it can potentially work on other hosts that
support subagents — but Claude Code and Codex are the verified targets.
## What is this
A [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code) that
spawns an adversarial reviewer as an Agent Teams teammate. The reviewer
reads your project, runs tests, checks documentation, and delivers findings
with a skeptical stance. The lead (your main session) fixes issues and
requests re-review from the same teammate. If the teammate is no longer
active, the lead decides how to proceed — re-spawn or conclude.
A skill that spawns an adversarial reviewer as a subagent on the host
of your choice. The reviewer reads your project, runs tests, checks
documentation, and delivers findings with a skeptical stance.
The lead (your main session) **does not blindly apply findings**. It
builds an evaluation matrix, verifies the technical claims, and replies
with applied / re-scoped / rejected-with-reasoning sections. The reviewer
gets a chance to contest the rejections in the next round.
### How it differs from [adversarial-review](https://github.com/dementev-dev/adversarial-review)
**adversarial-review** uses two different models (Claude writes, Codex
reviews) — you get cross-model blind spot coverage and cheap re-review
reviews) — you get cross-model blind-spot coverage and cheap re-review
via `codex exec resume`. It requires Codex CLI and an OpenAI API key.
**claude-team-review** stays within the Claude ecosystem. No external
dependencies. The reviewer is a Claude Code teammate with its own context
**claude-team-review** stays inside whichever host you're using. No
external dependencies. The reviewer is a subagent with its own context
window, MCP access, and the ability to run commands. For re-review, the
lead tries to continue the same teammate; if the teammate is no longer
active, the lead can re-spawn or conclude based on context. The trade-off:
same model family means no cross-model diversity.
lead tries continuation when the host supports it (e.g. Claude Code
Agent Teams), and otherwise spawns a fresh subagent with the previous-
rounds context block.
Use **adversarial-review** when you want maximum review quality through
model diversity. Use **claude-team-review** when you want zero external
dependencies and a richer reviewer (tests, docs, web search).
dependencies and a richer reviewer (tests, docs, web search) running on
the same host as the lead.
## How it works
```
┌──────────┐ spawn ┌────────────┐
│ Lead │ ───────────────> │ Reviewer │
│ (code) │ │ (teammate) │
│ Lead │ ───────────────> │ Reviewer │
│ (code) │ │ (subagent) │
└──────────┘ └────────────┘
^ │
│ findings │
│ <────────────────────────────┘
│
│ fix issues
│ evaluate (matrix, verify)
│ apply / re-scope / reject
v
┌──────────┐ message ┌────────────┐
│ Lead │ ───────────────> │ Reviewer │
│ (fixed) │ "re-check this" │ (same / new)│
└──────────┘ └────────────┘
│
┌──────────┐ re-review ┌────────────┐
│ Lead │ ───────────────> │ Reviewer │
│ (fixed) │ "applied A, │(same / new)│
│ │ rejected B └────────────┘
│ │ with reason" │
└──────────┘ │
VERDICT: APPROVED
```
The lead tries to continue the **same teammate** for re-review. If the
teammate is no longer active (Agent Teams limitation), the lead can
re-spawn with a full briefing or conclude without re-verification.
The lead tries to **continue the same reviewer** for re-review when the
host supports it (cheaper — context is preserved). When continuation is
unavailable (Codex, or Claude Code without Agent Teams), 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
@@ -72,31 +86,51 @@ Mode is auto-detected from context, or you can force it with an argument.
- **Search the web** and **query documentation** via MCP (Context7)
- **Inspect git history** — blame, log, diff
The reviewer **cannot** create, edit, or delete project files.
The reviewer **must not** create, edit, or delete project files. The
briefing forbids it. 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
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) ≥ 2.1.32
- Agent Teams enabled (experimental)
- A host that supports subagents — Claude Code or Codex
- Optional: Claude Code with Agent Teams enabled, for cheaper re-review
via continuation
No external dependencies. No API keys beyond your Claude subscription.
No external API keys.
## Installation
### Claude Code
```bash
# Clone the repository
git clone https://github.com/dementev-dev/claude-team-review.git
cd claude-team-review
# Symlink the skill
ln -s "$(pwd)" ~/.agents/skills/claude-team-review
# Symlink the reviewer agent definition
mkdir -p ~/.claude/agents
ln -s "$(pwd)/adversarial-reviewer.md" ~/.claude/agents/adversarial-reviewer.md
# Symlink the skill into the personal skills directory
mkdir -p ~/.claude/skills
ln -s "$(pwd)" ~/.claude/skills/claude-team-review
```
Enable Agent Teams in your Claude Code settings:
Claude Code watches `~/.claude/skills/` for changes and will pick the
skill up without a restart.
**Optional — enable Agent Teams for cheaper re-review** (continuation
between rounds instead of fresh-spawn). Add to your Claude Code settings:
```json
{
@@ -106,7 +140,26 @@ Enable Agent Teams in your Claude Code settings:
}
```
Restart Claude Code after installation for the skill to be recognized.
The skill works fine without Agent Teams — it falls back to a fresh
subagent each round, with the previous-rounds context block packed into
the briefing.
### 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 spawns subagents without context continuation across spawns. The
skill treats every re-review on Codex as an operator-gated decision —
the lead asks whether to spawn a fresh subagent (full project re-read,
expensive) or conclude without verification. Continuation can be added
later if Codex grows that feature.
## Usage
@@ -127,10 +180,18 @@ Restart Claude Code after installation for the skill to be recognized.
/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:
The reviewer uses an adversarial stance — it defaults to skepticism and
tries to break confidence in the change. Each finding must answer:
1. **What can go wrong?** — concrete scenario
2. **Why vulnerable?** — cite specific location
@@ -142,22 +203,23 @@ and inspecting related code before reporting.
## Roadmap
- [ ] Real-world testing and iteration on prompts
- [ ] Real-world testing of the cross-platform spawn path on Codex
- [ ] Parallel multi-reviewer mode (security + performance + correctness)
— Codex has a native pattern for this; the skill is ready to adopt
- [ ] Persistent reviewer memory across sessions
- [ ] Integration with CI (GitHub Actions)
- [ ] Comparison benchmarks: Codex backend vs Team backend
## Эксперимент: сравнение ревьюеров
## Experiment: comparing reviewers
Мы запустили оба ревьюера (Opus и GPT-5.4) на одном и том же плане
и сравнили находки. Ключевой вывод: модели ревьюят из принципиально
разных парадигм — Opus как архитектор ("сработает ли этот дизайн?"),
Codex как security/ops инженер ("что сломается в продакшене?").
Ноль полных совпадений, ~30% частичных пересечений.
We ran both reviewers (Opus and GPT-5.4) on the same plan and compared
their findings. The key takeaway: the two models review from
fundamentally different paradigms — Opus as an architect ("will this
design work?"), Codex as a security/ops engineer ("what will break in
production?"). Zero complete overlaps, roughly 30% partial overlaps.
Подробности: [EXPERIMENT.md](EXPERIMENT.md) — полный ход эксперимента,
все находки, анализ пересечений, выводы.
Details (in Russian): [EXPERIMENT.md](EXPERIMENT.md) — full experiment
write-up, all findings, overlap analysis, conclusions.
## Related
@@ -165,6 +227,8 @@ Codex как security/ops инженер ("что сломается в прод
cross-model variant using Codex CLI as the reviewer backend
- [Claude Code Agent Teams docs](https://code.claude.com/docs/en/agent-teams) —
official documentation on Agent Teams
- [Codex Subagents docs](https://developers.openai.com/codex/subagents) —
official documentation on Codex subagents
## License