Merge branch 'fix/multi-round-resilience'

Устойчивость multi-round ревью: детекция мёртвого тиммейта, fallback-логика, NOT VERIFIED state, исправлена установка в README.
2026-04-16 17:07:02 +03:00
parent a1e20f9c84 097808d158
commit ef97a43791
3 changed files with 143 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,27 @@ 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
+
+After sending, check what SendMessage actually returned:
+- **Reviewer's response** (review content, findings, VERDICT) — the
+  teammate is alive. Proceed to Step 3.
+- **Routing acknowledgment only** (e.g. `{"success": true, "message":
+  "Message sent to reviewer's inbox"}` without review content) — the
+  teammate's process has ended. The message was delivered to a dead
+  inbox. Do not wait for a response — proceed to the fallback below
+  immediately.
+
+If the teammate is reachable, send a message with the list of fixes.
+
+**For plan mode with inline plans:** the reviewer already has the
+original plan in context, but a fix summary alone is not enough —
+include the full text of the current revised plan in your message
+so the reviewer verifies the actual artifact. This works in Plan Mode
+(SendMessage is communication, not file writing).

 ```
 I've revised based on your feedback.
@@ -173,6 +193,10 @@ I've revised based on your feedback.
 Here's what I changed:
 [List of fixes from Step 4]

+[For plan mode with inline plans only — include full revised plan text:]
+## Current revised plan
+[Full text of the revised plan]
+
 Re-review with the same adversarial stance. Focus on:
 1. Whether my fixes actually resolve the reported issues
 2. Any NEW issues introduced by the fixes
@@ -180,11 +204,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 — you received a direct
+   human message earlier in this conversation, not just an automated
+   trigger or scheduled run; when in doubt, default to presenting
+   options) — 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. Use the same
+   mode-appropriate briefing from **Step 2** (plan, code, or code-vs-plan),
+   and append the previous findings and fixes sections.
+
+   **For plan mode with inline plans:** include the full text of the
+   current revised plan in the briefing (same approach as Step 2 for
+   initial inline plans). The new reviewer has no prior context — it
+   must see the actual artifact, not just a fix summary.
+
+   ```
+   [Mode-appropriate briefing from Step 2; for inline plans — include
+   the full revised plan text, not the original]
+
+   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, use the
+   **"Not re-verified"** terminal state.
+
+2. **Operator not available** (headless, CI, scheduled run) — proceed
+   to Step 6, use the **"Not re-verified"** terminal state.

 ### Step 6: Final result

@@ -200,6 +267,24 @@ Return to **Step 3**.
 **Reviewed and approved by the reviewer teammate. Awaiting your decision.**
 ```

+**Not re-verified** (reviewer became inactive, operator chose to conclude
+or headless mode):
+```
+## Team Review — Summary (mode: <mode>)
+
+**Status:** NOT VERIFIED — fixes applied, reviewer did not re-verify
+
+**Round N findings:**
+[Verbatim findings from the last reviewer round]
+
+**Applied fixes:**
+[List of fixes per finding]
+
+---
+**WARNING: This is NOT an approval. Fixes were applied but never verified
+by the reviewer. Manual review of the fixes is required before merging.**
+```
+
 **Maximum rounds reached:**
 ```
 ## Team Review — Summary (mode: <mode>)
@@ -215,10 +300,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 +321,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 +338,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: