fix(skill): устойчивость multi-round ревью при нестабильном Agent Teams

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) <noreply@anthropic.com>
2026-04-16 12:18:52 +03:00
parent a1e20f9c84
commit d9c78861e2
3 changed files with 106 additions and 43 deletions
@@ -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

@@ -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: <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) |
@@ -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: