From d9c78861e27b157764bfd6084523697c3888a085 Mon Sep 17 00:00:00 2001 From: Dmitrii Date: Thu, 16 Apr 2026 12:18:52 +0300 Subject: [PATCH] =?UTF-8?q?fix(skill):=20=D1=83=D1=81=D1=82=D0=BE=D0=B9?= =?UTF-8?q?=D1=87=D0=B8=D0=B2=D0=BE=D1=81=D1=82=D1=8C=20multi-round=20?= =?UTF-8?q?=D1=80=D0=B5=D0=B2=D1=8C=D1=8E=20=D0=BF=D1=80=D0=B8=20=D0=BD?= =?UTF-8?q?=D0=B5=D1=81=D1=82=D0=B0=D0=B1=D0=B8=D0=BB=D1=8C=D0=BD=D0=BE?= =?UTF-8?q?=D0=BC=20Agent=20Teams?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SendMessage для тиммейтов Agent Teams работает нестабильно: может быть недоступен как инструмент или создавать нового агента без контекста. Step 5 теперь проверяет доступность тиммейта перед отправкой. Если тиммейт неактивен — спрашивает оператора (interactive) или завершает со статусом "fixes applied, not re-verified" (headless). Re-spawn доступен как опция, не как дефолт. Также: multi-round секция в adversarial-reviewer.md, исправленные пути установки в README, убраны ложные утверждения о statefulness. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 41 +++++++++---------- SKILL.md | 90 +++++++++++++++++++++++++++++++---------- adversarial-reviewer.md | 18 +++++++++ 3 files changed, 106 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 105b441..2afa265 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,16 @@ Adversarial code and plan review using Claude Code Agent Teams. -One teammate reviews. The lead fixes. Iterate until approved — with -full context preserved between rounds. +One teammate reviews. The lead fixes. Iterate until approved. ## 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, then -asks the same reviewer to re-check — no context loss, no re-reading the -entire project. +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. ### How it differs from [adversarial-review](https://github.com/dementev-dev/adversarial-review) @@ -22,8 +21,9 @@ 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 -window, MCP access, and the ability to run commands. Context persists -natively — the teammate simply receives the next message. The trade-off: +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. Use **adversarial-review** when you want maximum review quality through @@ -33,7 +33,7 @@ dependencies and a richer reviewer (tests, docs, web search). ## How it works ``` -┌──────────┐ message ┌────────────┐ +┌──────────┐ spawn ┌────────────┐ │ Lead │ ───────────────> │ Reviewer │ │ (code) │ │ (teammate) │ └──────────┘ └────────────┘ @@ -45,15 +45,15 @@ dependencies and a richer reviewer (tests, docs, web search). v ┌──────────┐ message ┌────────────┐ │ Lead │ ───────────────> │ Reviewer │ -│ (fixed) │ "re-check this" │ (same ctx) │ +│ (fixed) │ "re-check this" │ (same / new)│ └──────────┘ └────────────┘ │ VERDICT: APPROVED ``` -The reviewer teammate **keeps its context** across rounds. It already -knows the project structure, the original findings, and the discussion -history. Re-review is cheap. +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. ### Three modes @@ -86,9 +86,14 @@ No external dependencies. No API keys beyond your Claude subscription. ```bash # Clone the repository git clone https://github.com/dementev-dev/claude-team-review.git +cd claude-team-review -# Symlink into Claude Code skills directory -ln -s "$(pwd)/claude-team-review" ~/.agents/skills/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 ``` Enable Agent Teams in your Claude Code settings: @@ -101,13 +106,7 @@ Enable Agent Teams in your Claude Code settings: } ``` -The skill also includes a subagent definition at -`.claude/agents/adversarial-reviewer.md`. Copy it to your project's -`.claude/agents/` or to `~/.claude/agents/` for global availability: - -```bash -cp claude-team-review/.claude/agents/adversarial-reviewer.md ~/.claude/agents/ -``` +Restart Claude Code after installation for the skill to be recognized. ## Usage diff --git a/SKILL.md b/SKILL.md index 94c0bbb..0f674cc 100644 --- a/SKILL.md +++ b/SKILL.md @@ -3,19 +3,19 @@ name: claude-team-review description: > Adversarial code/plan review using Claude Code Agent Teams. Spawns a reviewer teammate that reads the project, runs tests, checks docs, - and delivers findings. Lead fixes issues, teammate re-reviews — stateful, - no context loss between rounds. Use when user says /claude-team-review, - asks for team review, team-based code review, or wants a stateful - adversarial review without external dependencies. + and delivers findings. Lead fixes issues and requests re-review from + the same teammate. Use when user says /claude-team-review, asks for + team review, team-based code review, or wants an adversarial review + without external dependencies. user_invocable: true --- # Claude Team Review Spawns an adversarial reviewer **teammate** (Agent Teams) to review plans -or code. The reviewer keeps its context across rounds — no re-reading the -project on every iteration. The lead fixes issues; the reviewer re-checks. -Maximum 5 rounds. +or code. The lead fixes issues and requests re-review from the same +teammate. If the teammate is no longer active, the lead decides how +to proceed based on context. Maximum 5 rounds. > **Requires:** Claude Code ≥ 2.1.32, experimental Agent Teams enabled > (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings or environment). @@ -165,7 +165,12 @@ this for the user. ### Step 5: Request re-review (Rounds 2–5) -Send a message to the **same reviewer teammate** (context is preserved): +Before sending, check that the teammate is still reachable: +- Verify that SendMessage is available as a tool +- If the tool is missing or the call returns an error — the teammate + is no longer active, skip to the fallback below + +If the teammate is reachable, send a message with the list of fixes: ``` I've revised based on your feedback. @@ -180,11 +185,54 @@ Re-review with the same adversarial stance. Focus on: End with VERDICT: APPROVED or VERDICT: REVISE. ``` -The reviewer still has the full context from the previous round — it -already knows the project structure, the plan, the original findings. -It only needs to verify the fixes and check for new issues. +If the reviewer responds — return to **Step 3**. -Return to **Step 3**. +**If the reviewer does not respond** (teammate is no longer active): + +1. **Operator available** (interactive session — the conversation was + initiated by a human message, not a CI trigger or scheduled run) — ask: + ``` + The reviewer is no longer active. Fixes have been applied: + [List of fixes from Step 4] + + Options: + (a) Spawn a new reviewer to verify fixes (expensive — full project re-read) + (b) Conclude the review — fixes applied, verification is on you + ``` + If the operator chooses (a) — spawn a new reviewer with this briefing: + ``` + You are reviewing code changes in this repository. + + This is a re-review (Round N). A previous reviewer found issues + that have been addressed. + + ## Previous findings + [Verbatim findings from Round N-1] + + ## Fixes applied + [List of fixes from Step 4] + + Verify whether fixes resolve the findings. Check for new issues. + + End with VERDICT: APPROVED or VERDICT: REVISE. + ``` + Continue from Step 3. + If the operator chooses (b) — proceed to Step 6. + +2. **Operator not available** (headless, CI, scheduled run) — proceed + to Step 6 with status "fixes applied, not re-verified": + ``` + ## Team Review — Summary (mode: ) + + **Status:** Fixes applied, re-verification not completed + (reviewer became inactive after Round N) + + **Applied fixes:** + [List of fixes per finding] + + **Note:** First-round findings were addressed but not re-verified + by the reviewer. Manual review of fixes is recommended. + ``` ### Step 6: Final result @@ -215,10 +263,8 @@ Return to **Step 3**. ### Step 7: Cleanup -Ask the reviewer teammate to shut down. Then clean up the team. - -If cleanup fails or the user declines — continue without error. Teammates -will be cleaned up when the session ends. +If the Agent Teams runtime provides a team cleanup mechanism, use it. +Failures are non-blocking — teammates are cleaned up when the session ends. Do NOT delete plan files that existed before the review. @@ -238,11 +284,11 @@ Do NOT delete plan files that existed before the review. - Avoid creating auxiliary files (memory files, state files, logs, temporary markdown) — prefer working within the conversation context - If a fix contradicts user requirements — skip and explain why -- The reviewer teammate is stateful — use message, not re-spawn, for - subsequent rounds. Re-spawning wastes tokens on re-reading the project - tree, re-building context, and re-discovering architecture. Messaging - the existing teammate preserves all of that. Save tokens where it - doesn't cost quality — spend them where it does. +- For re-review rounds, try to continue the existing reviewer teammate + first. If the teammate is no longer active, decide by context: ask the + operator when available, or conclude without re-verification in headless + mode. Re-spawning a new reviewer is expensive (full project re-read) — + offer it as an option, not as the default. - The ultimate goal is **higher quality** of plans, code, and other artifacts. Token economy is a means, not an end — never skip a verification step or cut a round short just to save tokens. @@ -255,7 +301,7 @@ Do NOT delete plan files that existed before the review. |------------------------|--------------------------------|--------------------------------| | Reviewer model | External (GPT via Codex CLI) | Claude (same model family) | | Cross-model blind spots| Yes — different model biases | No — same model, different context | -| Session persistence | Via `codex exec resume` | Native — teammate stays alive | +| 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 capabilities | Read-only sandbox | Read + execute + MCP + web | | Context isolation | Full (different model) | Full (separate context window) | diff --git a/adversarial-reviewer.md b/adversarial-reviewer.md index ab269ad..87c0621 100644 --- a/adversarial-reviewer.md +++ b/adversarial-reviewer.md @@ -84,6 +84,24 @@ 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: