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..0600a49 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,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: ) + +**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: ) @@ -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) | 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: