feat(skill): поддержка Codex и интеграция с receiving-code-review
- Зачем:
- Скилл был привязан к 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:
@@ -1,24 +1,23 @@
|
||||
---
|
||||
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 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.
|
||||
Use when user says /claude-team-review, requests adversarial review of a
|
||||
plan or code change, wants peer review without external API dependencies,
|
||||
or needs to verify implementation against a plan before merging.
|
||||
user_invocable: true
|
||||
---
|
||||
|
||||
# Claude Team Review
|
||||
|
||||
Spawns an adversarial reviewer **teammate** (Agent Teams) to review plans
|
||||
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.
|
||||
Adversarial review of plans and code through a peer-reviewer subagent.
|
||||
The reviewer reads the project, runs tests and docs lookups, and delivers
|
||||
findings. The lead **evaluates** those findings (not blindly applies them),
|
||||
fixes what holds up, pushes back with reasoning on what doesn't, and asks
|
||||
for re-review. Up to 5 rounds.
|
||||
|
||||
> **Requires:** Claude Code ≥ 2.1.32, experimental Agent Teams enabled
|
||||
> (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings or environment).
|
||||
Works on **any host that supports subagents** — Claude Code (via Task tool
|
||||
or Agent Teams) and Codex (native subagents) are both fine. The skill is
|
||||
platform-agnostic; the platform decides how to spawn.
|
||||
|
||||
---
|
||||
|
||||
@@ -28,19 +27,19 @@ to proceed based on context. Maximum 5 rounds.
|
||||
- `/claude-team-review plan` — force plan review
|
||||
- `/claude-team-review code` — force code review
|
||||
- `/claude-team-review <file-path>` — review a specific file (argument contains `/` or `.`)
|
||||
- `/claude-team-review xhigh` — use max effort for the reviewer
|
||||
- `/claude-team-review xhigh` — use max reasoning effort for the reviewer
|
||||
|
||||
## Instructions
|
||||
---
|
||||
|
||||
### Step 1: Determine review mode
|
||||
## Step 1: Determine review mode
|
||||
|
||||
Check in priority order:
|
||||
|
||||
**1. Explicit argument** (`plan`, `code`, file path) → use it.
|
||||
- For `plan` → skip all git checks, proceed to step 2.
|
||||
**1. Explicit argument** (`plan`, `code`, file path) → use it. For `plan`,
|
||||
skip all git checks and proceed to Step 2.
|
||||
|
||||
**2. Claude Code Plan Mode** — if context contains the system message
|
||||
"Plan mode is active" → mode = `plan`, skip git.
|
||||
**2. Plan Mode active** (Claude Code) — if context contains the system
|
||||
message "Plan mode is active" → mode = `plan`, skip git.
|
||||
|
||||
**3. Auto-detect** (no explicit argument, not in Plan Mode):
|
||||
|
||||
@@ -56,83 +55,46 @@ Check in priority order:
|
||||
| Yes | No | **code** |
|
||||
| No | No | Ask the user |
|
||||
|
||||
### Step 2: Spawn the reviewer teammate
|
||||
---
|
||||
|
||||
Spawn a teammate using the `adversarial-reviewer` agent type.
|
||||
## Step 2: Spawn the reviewer
|
||||
|
||||
Include in the spawn prompt a **briefing** with the review mode and
|
||||
enough context to start. The reviewer is a full Claude Code session —
|
||||
it will explore the repo, run git commands, and read files on its own.
|
||||
Do not pre-collect diffs or file lists for it.
|
||||
**Spawn a reviewer subagent using your host's standard mechanism**, and
|
||||
pass it the briefing assembled from `reviewer-prompt.md`.
|
||||
|
||||
If spawning the teammate fails (Agent Teams not available), tell the user:
|
||||
```
|
||||
Agent Teams are not enabled. Add this to your settings.json or environment:
|
||||
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
||||
Then restart Claude Code.
|
||||
```
|
||||
- **Claude Code:** Task tool with `general-purpose` type, OR — if Agent
|
||||
Teams is enabled — spawn a teammate. Teammates support continuation
|
||||
between rounds, which makes re-review cheaper. Both work; pick what's
|
||||
available.
|
||||
- **Codex:** native subagent spawn (host orchestrates spawn/wait/consolidate).
|
||||
- **Other hosts:** equivalent subagent mechanism.
|
||||
|
||||
**For plan review:**
|
||||
The reviewer is a full agent session — it explores the repo, runs git
|
||||
commands, and reads files on its own. **Do not pre-collect diffs or file
|
||||
lists for it.** Pass mode-specific context only:
|
||||
|
||||
If the plan exists as a file:
|
||||
```
|
||||
You are reviewing an implementation plan.
|
||||
- For `plan` — path to plan file, or inline plan text
|
||||
- For `code` — instruct it to use git status / git diff
|
||||
- For `code-vs-plan` — pass the plan and instruct git lookup for changes
|
||||
|
||||
Plan location: <path>
|
||||
Fill the placeholders in `reviewer-prompt.md` and pass the result as the
|
||||
subagent's prompt. The template includes operating stance, finding bar,
|
||||
scope exclusions, and required output format.
|
||||
|
||||
Review this plan with your full adversarial stance. Read the plan,
|
||||
explore the project structure and relevant code to assess feasibility,
|
||||
and deliver your findings.
|
||||
**Effort override:** if the user passed `xhigh`, route the spawn through
|
||||
a maximum-reasoning configuration if the host supports it.
|
||||
|
||||
End with VERDICT: APPROVED or VERDICT: REVISE.
|
||||
```
|
||||
**Tool restrictions:** the briefing explicitly forbids file modification.
|
||||
If the host supports enforced read-only sandboxing (Claude Code
|
||||
`disallowedTools: Write, Edit`, Codex `sandbox_mode = "read-only"`), apply
|
||||
it on top — it's defense in depth, not the primary control.
|
||||
|
||||
If the plan is only in conversation context, include it inline:
|
||||
```
|
||||
You are reviewing an implementation plan.
|
||||
---
|
||||
|
||||
<plan text>
|
||||
## Step 3: Show findings
|
||||
|
||||
Explore the project structure and relevant code to assess feasibility.
|
||||
Deliver your findings.
|
||||
|
||||
End with VERDICT: APPROVED or VERDICT: REVISE.
|
||||
```
|
||||
|
||||
**For code review:**
|
||||
```
|
||||
You are reviewing code changes in this repository.
|
||||
|
||||
Use git status, git diff, and any other git commands to find and
|
||||
understand all changes. Read the surrounding code for context.
|
||||
Run tests if available.
|
||||
|
||||
End with VERDICT: APPROVED or VERDICT: REVISE.
|
||||
```
|
||||
|
||||
**For code-vs-plan review:**
|
||||
|
||||
Include the plan (path or inline text) and let the reviewer find
|
||||
the code changes:
|
||||
```
|
||||
You are reviewing code changes against an implementation plan.
|
||||
|
||||
Plan: <path or inline text>
|
||||
|
||||
Use git to find all changes. Check: does the implementation cover
|
||||
all plan steps? Where does it deviate? What is missing?
|
||||
|
||||
End with VERDICT: APPROVED or VERDICT: REVISE.
|
||||
```
|
||||
|
||||
**Effort override:** if the user passed `xhigh`, use the appropriate
|
||||
effort setting for the teammate.
|
||||
|
||||
### Step 3: Show findings
|
||||
|
||||
When the reviewer responds with findings:
|
||||
|
||||
1. Show the user the reviewer's response **verbatim** — do not rephrase:
|
||||
When the reviewer responds, show the user the response **verbatim** — do
|
||||
not rephrase, summarize, or reorder:
|
||||
|
||||
```
|
||||
## Team Review — Round N (mode: <plan|code|code-vs-plan>)
|
||||
@@ -140,120 +102,231 @@ When the reviewer responds with findings:
|
||||
[Reviewer's response — verbatim]
|
||||
```
|
||||
|
||||
2. Check the verdict:
|
||||
- **VERDICT: APPROVED** → proceed to Step 6 (Done)
|
||||
- **VERDICT: REVISE** → proceed to Step 4 (Fixes)
|
||||
- No clear verdict → message the reviewer asking for a clear verdict
|
||||
- Maximum reached (5 rounds) → proceed to Step 6 with a note
|
||||
Then check the verdict line:
|
||||
|
||||
### Step 4: Apply fixes
|
||||
| Verdict | Next step |
|
||||
|---------------------|------------------------------------------------------|
|
||||
| `VERDICT: APPROVED` | Step 7 (final result) |
|
||||
| `VERDICT: REVISE` | Step 4 (evaluate findings) |
|
||||
| Unclear / missing | Send a message back asking for a clear verdict line |
|
||||
| Round 5 reached | Step 7 with the "Max rounds reached" terminal state |
|
||||
|
||||
Based on the reviewer's findings, the **lead** (you) fixes the issues:
|
||||
---
|
||||
|
||||
**For plan review:** update the plan — address each finding.
|
||||
## Step 4: Evaluate findings (do NOT apply yet)
|
||||
|
||||
**For code review:** edit files, run tests if applicable.
|
||||
**External feedback = suggestions to evaluate, not orders to follow.**
|
||||
This step exists because the reviewer may be technically wrong — and
|
||||
applying its findings blindly causes real damage (large structural edits
|
||||
based on cited issues that turn out to be feature requests, not bugs).
|
||||
|
||||
Show the user:
|
||||
```
|
||||
### Fixes (Round N)
|
||||
- [What was changed and why, one item per finding]
|
||||
```
|
||||
**REQUIRED SUB-SKILL:** Use `superpowers:receiving-code-review` if it's
|
||||
available on the host. The key principles are inlined below for portability;
|
||||
the full skill has more depth.
|
||||
|
||||
**Skip** a fix if it contradicts the user's explicit requirements — note
|
||||
this for the user.
|
||||
### Build the evaluation matrix
|
||||
|
||||
### Step 5: Request re-review (Rounds 2–5)
|
||||
For each finding, fill out:
|
||||
|
||||
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
|
||||
| # | Severity | Verified? | Type | Action |
|
||||
|---|----------|-----------|------|--------|
|
||||
| 1 | high | ✓ Context7 confirms behavior | arch | accept |
|
||||
| 2 | critical | ✗ cited issue is feature request, not bug | tool-mechanic | reject with reasoning |
|
||||
| 3 | medium | ✓ quick repro confirms | tool-mechanic | accept |
|
||||
|
||||
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.
|
||||
**Action** options are equal — `accept`, `reject with reasoning`, and
|
||||
`re-scope` (apply a narrower fix). Reject and re-scope are not
|
||||
exceptions; they are first-class outcomes.
|
||||
|
||||
If the teammate is reachable, send a message with the list of fixes.
|
||||
### Verification methods by finding type
|
||||
|
||||
**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).
|
||||
| Finding type | What constitutes verification |
|
||||
|---|---|
|
||||
| Architectural / design | Reasoning + codebase grep, plus pattern check against existing code |
|
||||
| Tool-mechanic (DSL syntax, config parser, API contract, library behavior) | **Empirical test on the real system** — reasoning is not enough |
|
||||
| Style / convention | Match against actual codebase conventions |
|
||||
| Security | Reasoning + concrete threat model |
|
||||
|
||||
**Tool-mechanic findings are the most dangerous to accept on reasoning
|
||||
alone.** Mental models of obscure tools are often wrong. If the reviewer
|
||||
cites an upstream issue or doc — **open it**. Do not trust the citation
|
||||
by number; issues get reclassified, closed, or turn out to describe a
|
||||
different case.
|
||||
|
||||
### Receiving feedback — key principles
|
||||
|
||||
Inlined from `superpowers:receiving-code-review` for portability:
|
||||
|
||||
- Read all findings end-to-end before reacting
|
||||
- Restate the technical claim in your own words (or ask)
|
||||
- Verify against codebase / docs / a quick run before accepting
|
||||
- Push back when wrong — with technical reasoning, not deference
|
||||
- No performative agreement ("you're absolutely right" is a violation)
|
||||
- Skip thanks. Just state the fix or the reasoning.
|
||||
|
||||
### Show the matrix to the user
|
||||
|
||||
If an operator is present, show the matrix before applying. In headless
|
||||
or autonomous runs, proceed but be ready to explain each decision in
|
||||
the final summary.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Apply or push back
|
||||
|
||||
For findings marked **accept** — fix them:
|
||||
|
||||
- **Plan review:** update the plan to address the finding
|
||||
- **Code review:** edit files, run tests if applicable
|
||||
- **Code-vs-plan:** either update the plan or the code, depending on
|
||||
which is wrong
|
||||
|
||||
**Verify your own technical claims before publishing them.** This is the
|
||||
reverse direction of receiving-code-review — not "don't accept someone
|
||||
else's unverified claim", but "don't publish your own".
|
||||
|
||||
When a fix or a reply to the reviewer makes a claim about tool mechanics
|
||||
(DSL syntax, config parser behavior, API contract, library behavior),
|
||||
verify it empirically:
|
||||
|
||||
- If a quick test is possible — run it (`docker run …`, a real database
|
||||
container, a small repro script, whatever maps to the claim)
|
||||
- If a quick test is not possible — frame the claim as a hypothesis
|
||||
("seems to", "needs verification") rather than as fact
|
||||
|
||||
Skip a fix that contradicts the user's explicit requirements — note this
|
||||
in the response to the reviewer.
|
||||
|
||||
Show the user a brief account:
|
||||
|
||||
```
|
||||
I've revised based on your feedback.
|
||||
### Round N fixes
|
||||
- Applied: [#1 — what changed, 1 line]
|
||||
- Re-scoped: [#3 — what changed, why narrower]
|
||||
- Rejected: [#2 — short reason; full reasoning goes to the reviewer]
|
||||
```
|
||||
|
||||
Here's what I changed:
|
||||
[List of fixes from Step 4]
|
||||
---
|
||||
|
||||
[For plan mode with inline plans only — include full revised plan text:]
|
||||
## Step 6: Request re-review (Rounds 2–5)
|
||||
|
||||
Compose a structured response and send it to the reviewer.
|
||||
|
||||
### Response format
|
||||
|
||||
```
|
||||
I've evaluated the findings. Here's the state:
|
||||
|
||||
## Applied
|
||||
- [#N]: [what was changed and why, 1–2 lines]
|
||||
- ...
|
||||
|
||||
## Re-scoped
|
||||
- [#N]: [scope/tone adjustment, with reasoning]
|
||||
- ...
|
||||
|
||||
## Rejected with reasoning
|
||||
- [#N]: [technical reason for not applying — not just "I disagree"]
|
||||
- ...
|
||||
|
||||
## Specific asks for re-review
|
||||
1. Are my rejections technically valid?
|
||||
2. Any new issues introduced by the applied fixes?
|
||||
3. [Any specific question about a high-risk fix]
|
||||
|
||||
[For plan mode with inline plans — append the 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
|
||||
|
||||
End with VERDICT: APPROVED or VERDICT: REVISE.
|
||||
```
|
||||
|
||||
If the reviewer responds — return to **Step 3**.
|
||||
The three-section format gives the reviewer a chance to **contest the
|
||||
rejections**. A re-review that says "your rejection of #2 is valid; here's
|
||||
why" is just as useful as one that fixes new issues — both keep the
|
||||
loop honest.
|
||||
|
||||
**If the reviewer does not respond** (teammate is no longer active):
|
||||
### Continuation vs fresh subagent
|
||||
|
||||
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]
|
||||
The cheap path is **continuation** — the same reviewer keeps context
|
||||
between rounds. Fresh-spawn is expensive: the new subagent must re-read
|
||||
the project from scratch. Because of that cost, **fresh-spawn is always
|
||||
operator-gated**, regardless of platform.
|
||||
|
||||
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.
|
||||
```dot
|
||||
digraph re_review {
|
||||
"Continuation supported by host\nand previous reviewer alive?" [shape=diamond];
|
||||
"Continue same reviewer" [shape=box style=filled fillcolor=lightgreen];
|
||||
"Operator available?" [shape=diamond];
|
||||
"Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" [shape=box];
|
||||
"Spawn fresh subagent\nwith PREVIOUS_FINDINGS block" [shape=box];
|
||||
"Step 7 — NOT VERIFIED terminal state" [shape=box style=filled fillcolor=lightyellow];
|
||||
|
||||
**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.
|
||||
"Continuation supported by host\nand previous reviewer alive?" -> "Continue same reviewer" [label="yes"];
|
||||
"Continuation supported by host\nand previous reviewer alive?" -> "Operator available?" [label="no"];
|
||||
"Operator available?" -> "Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" [label="yes"];
|
||||
"Operator available?" -> "Step 7 — NOT VERIFIED terminal state" [label="no — headless"];
|
||||
"Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" -> "Spawn fresh subagent\nwith PREVIOUS_FINDINGS block" [label="re-spawn"];
|
||||
"Ask operator:\nspawn fresh (full re-read),\nor conclude unverified?" -> "Step 7 — NOT VERIFIED terminal state" [label="conclude"];
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
[Mode-appropriate briefing from Step 2; for inline plans — include
|
||||
the full revised plan text, not the original]
|
||||
Two routes lead to the "ask operator" step:
|
||||
- The host has no continuation mechanism (e.g. Codex) — every round
|
||||
after Round 1 lands here
|
||||
- The host has continuation but the previous reviewer is no longer
|
||||
reachable (process ended, inbox dead)
|
||||
|
||||
This is a re-review (Round N). A previous reviewer found issues
|
||||
that have been addressed.
|
||||
**Detecting a dead reviewer (continuation-supporting hosts).** When the
|
||||
send call returns only a routing acknowledgment (e.g. `{"success": true,
|
||||
"message": "Message sent to reviewer's inbox"}`) without review content —
|
||||
the reviewer process has ended; the message went to a dead inbox. Do not
|
||||
wait. Treat the reviewer as unreachable, fall through to the operator
|
||||
question.
|
||||
|
||||
## Previous findings
|
||||
[Verbatim findings from Round N-1]
|
||||
**Asking the operator.** Present the choice plainly:
|
||||
|
||||
## Fixes applied
|
||||
[List of fixes from Step 4]
|
||||
```
|
||||
The reviewer cannot be continued from the previous round
|
||||
(reason: <no continuation on this host | previous reviewer ended>).
|
||||
|
||||
Verify whether fixes resolve the findings. Check for new issues.
|
||||
Fixes applied:
|
||||
[List from Step 5]
|
||||
|
||||
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.
|
||||
Options:
|
||||
(a) Spawn a new reviewer to verify fixes (expensive — full project re-read)
|
||||
(b) Conclude the review — fixes applied, verification is on you
|
||||
```
|
||||
|
||||
2. **Operator not available** (headless, CI, scheduled run) — proceed
|
||||
to Step 6, use the **"Not re-verified"** terminal state.
|
||||
**Fresh subagent re-review (if operator chose re-spawn).** Fill the
|
||||
`{PREVIOUS_FINDINGS_BLOCK}` placeholder in `reviewer-prompt.md` with:
|
||||
1. Verbatim previous findings
|
||||
2. The Applied / Re-scoped / Rejected-with-reasoning sections
|
||||
3. For plan mode with inline plans: the full revised plan text
|
||||
|
||||
### Step 6: Final result
|
||||
The fresh reviewer has zero prior context — it must see the actual artifact,
|
||||
not a paraphrase.
|
||||
|
||||
When the reviewer responds — return to **Step 3** with N+1.
|
||||
|
||||
### Severity declination (soft signal)
|
||||
|
||||
Expect severity of findings to decline across rounds:
|
||||
|
||||
```
|
||||
R1: 3 critical, 6 high, 5 medium (typical)
|
||||
R2: 1 high, 1 medium, 3 low (good)
|
||||
R3: 1 high (closing in)
|
||||
R4: APPROVED (terminal)
|
||||
```
|
||||
|
||||
If severity **stays flat** (e.g. high → high → high), something is
|
||||
structurally off — the lead may not understand the technology, the reviewer
|
||||
may be looping on the same misunderstanding, or the artifact has a deep
|
||||
problem that surface fixes can't reach. Pause and surface to the user.
|
||||
This is a soft signal, not a hard gate.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Final result
|
||||
|
||||
**Approved:**
|
||||
```
|
||||
@@ -261,14 +334,14 @@ If the reviewer responds — return to **Step 3**.
|
||||
|
||||
**Status:** Approved after N round(s)
|
||||
|
||||
[Final review]
|
||||
[Final review verbatim]
|
||||
|
||||
---
|
||||
**Reviewed and approved by the reviewer teammate. Awaiting your decision.**
|
||||
**Reviewed and approved by the reviewer. Awaiting your decision.**
|
||||
```
|
||||
|
||||
**Not re-verified** (reviewer became inactive, operator chose to conclude
|
||||
or headless mode):
|
||||
**Not re-verified** (reviewer became unreachable mid-loop and the operator
|
||||
chose to conclude, or the run is headless):
|
||||
```
|
||||
## Team Review — Summary (mode: <mode>)
|
||||
|
||||
@@ -277,8 +350,8 @@ or headless mode):
|
||||
**Round N findings:**
|
||||
[Verbatim findings from the last reviewer round]
|
||||
|
||||
**Applied fixes:**
|
||||
[List of fixes per finding]
|
||||
**Applied / Re-scoped / Rejected:**
|
||||
[The three sections from the last round]
|
||||
|
||||
---
|
||||
**WARNING: This is NOT an approval. Fixes were applied but never verified
|
||||
@@ -298,10 +371,12 @@ by the reviewer. Manual review of the fixes is required before merging.**
|
||||
**The reviewer still has findings. Please review them and decide how to proceed.**
|
||||
```
|
||||
|
||||
### Step 7: Cleanup
|
||||
---
|
||||
|
||||
If the Agent Teams runtime provides a team cleanup mechanism, use it.
|
||||
Failures are non-blocking — teammates are cleaned up when the session ends.
|
||||
## Step 8: Cleanup
|
||||
|
||||
If the host provides a subagent / teammate cleanup mechanism, use it.
|
||||
Failures are non-blocking — subagents are reclaimed when the session ends.
|
||||
|
||||
Do NOT delete plan files that existed before the review.
|
||||
|
||||
@@ -309,37 +384,62 @@ Do NOT delete plan files that existed before the review.
|
||||
|
||||
## Rules
|
||||
|
||||
- Lead **actively fixes** issues — this is NOT just message forwarding
|
||||
- Lead **actively evaluates and acts** on findings — this is NOT
|
||||
message forwarding, and it is NOT blind acceptance
|
||||
- Reviewer findings shown **verbatim** — do not rephrase or shorten
|
||||
- Auto-detect mode from context; user arguments take priority
|
||||
- The reviewer **never writes files** — enforced by agent definition
|
||||
- The reviewer **never writes files** — enforced by the briefing rule,
|
||||
and by the host's sandbox if available
|
||||
- The reviewer **can run commands** (tests, linters, git) and **use MCP**
|
||||
(Context7, web search) to verify findings
|
||||
- Maximum 5 rounds to protect against infinite loops
|
||||
- Show the user reviews and fixes for each round
|
||||
- If Agent Teams are not enabled — tell the user how to enable them
|
||||
- Show the user findings and the applied/rejected breakdown for each round
|
||||
- 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
|
||||
- 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.
|
||||
- If a fix contradicts user requirements — skip it and explain why
|
||||
- For re-review, prefer continuation (cheap). Fresh-spawn is the
|
||||
expensive path — always confirm with the operator before doing it.
|
||||
In headless runs without operator access, conclude unverified rather
|
||||
than auto-respawning.
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
## Red Flags — STOP and reconsider
|
||||
|
||||
When you catch yourself thinking any of these, you are about to violate
|
||||
the skill. Stop, re-read Steps 4–5.
|
||||
|
||||
| Thought | Reality |
|
||||
|---|---|
|
||||
| "Reviewer flagged this as critical — apply right away" | Build the matrix first. Verify before apply. |
|
||||
| "The reviewer cites issue #N, I'll trust the number" | Open the issue. Citations age; issues get reclassified. |
|
||||
| "I know how `<tool>` works, no need to test the fix" | Tool-mechanic claims need empirical verification, not reasoning. Run it or hedge it. |
|
||||
| "I disagree with #2 but I'll just stay silent about it" | Reject with reasoning. The reviewer needs the chance to contest. |
|
||||
| "You're absolutely right, applying now" | Performative agreement. Restate the requirement, then act. |
|
||||
| "5 rounds is a lot, let me wrap this up at round 3" | Don't compress the loop to save tokens. Run it until terminal. |
|
||||
| "Just paraphrase the findings to save space" | Verbatim. Always verbatim. Paraphrase loses signal. |
|
||||
| "Severity hasn't dropped in 3 rounds, but I'll push through" | Pause. Surface to operator. Something is structurally off. |
|
||||
| "Continuation isn't available — let me just spawn a fresh reviewer" | Ask the operator first. Fresh-spawn is expensive; the operator may prefer to conclude unverified. |
|
||||
|
||||
---
|
||||
|
||||
## Comparison with adversarial-review
|
||||
|
||||
| Aspect | adversarial-review (Codex) | claude-team-review (Teams) |
|
||||
|------------------------|--------------------------------|--------------------------------|
|
||||
| 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` | 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) |
|
||||
| Token cost per round | External API (OpenAI pricing) | Claude tokens (Max plan) |
|
||||
`adversarial-review` is a related but distinct skill (different repo):
|
||||
Claude writes, Codex reviews — cross-model coverage.
|
||||
|
||||
| Aspect | adversarial-review (cross-model) | claude-team-review (same-host) |
|
||||
|-------------------------|------------------------------------------|-----------------------------------|
|
||||
| Reviewer model | External (GPT via Codex CLI from Claude) | Whatever the host runs |
|
||||
| Cross-model blind spots | Yes — different model biases | No — same model family |
|
||||
| Session persistence | Via `codex exec resume` | Continuation if host supports it; otherwise operator-gated fresh-spawn |
|
||||
| External dependencies | Codex CLI + OpenAI API key (from Claude) | None — uses host's native subagent mechanism |
|
||||
| Reviewer capabilities | Read-only sandbox | Read + execute + MCP + web |
|
||||
| Host compatibility | Designed for Claude Code as lead | Claude Code AND Codex as lead |
|
||||
|
||||
Use `adversarial-review` for cross-model diversity. Use `claude-team-review`
|
||||
when you want zero external dependencies and a richer reviewer (tests, docs,
|
||||
web), regardless of which host is the lead.
|
||||
|
||||
Reference in New Issue
Block a user