ddmitry/claude-team-review
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skill): добавлен скилл adversarial review через Agent Teams

Browse Source 
- Зачем:
  - реализация adversarial code/plan review без внешних зависимостей, целиком внутри Claude Code Agent Teams.
- Что:
  - добавлен SKILL.md — основной скилл claude-team-review с логикой авто-определения режима, итеративного ревью (до 5 раундов) и stateful тиммейта.
  - добавлен adversarial-reviewer.md — определение тиммейта-ревьюера (read-only, Opus, adversarial stance).
  - добавлен README.md с описанием, установкой и сравнением с adversarial-review (Codex).
  - добавлена лицензия Apache-2.0.
- Проверка:
  - /claude-team-review в проекте с включённым CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
ddadmin
2026-04-09 19:48:51 +03:00
co-authored by Claude Opus 4.6
commit c922800bd0
4 changed files with 712 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
LICENSE
+190
View File
@@ -0,0 +1,190 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to the Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by the Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding any notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
Copyright 2025 Dmitry Dementev
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
README.md
+161
View File
@@ -0,0 +1,161 @@
# Claude Team Review
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.
## 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.
### How it differs from [adversarial-review](https://github.com/dementev-dev/adversarial-review)
**adversarial-review** uses two different models (Claude writes, Codex
reviews) — you get cross-model blind spot coverage and cheap re-review
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:
same model family means no cross-model diversity.
Use **adversarial-review** when you want maximum review quality through
model diversity. Use **claude-team-review** when you want zero external
dependencies and a richer reviewer (tests, docs, web search).
## How it works
```
┌──────────┐ message ┌────────────┐
│ Lead │ ───────────────> │ Reviewer │
│ (code) │ │ (teammate) │
└──────────┘ └────────────┘
^ │
│ findings │
│ <────────────────────────────┘
│
│ fix issues
v
┌──────────┐ message ┌────────────┐
│ Lead │ ───────────────> │ Reviewer │
│ (fixed) │ "re-check this" │ (same ctx) │
└──────────┘ └────────────┘
│
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.
### Three modes
| Mode | What it reviews | When to use |
|----------------|------------------------------------|--------------------------|
| `plan` | Implementation plan | Before writing code |
| `code` | Git diff (unstaged, staged, branch)| After writing code |
| `code-vs-plan` | Code changes against the plan | Verify implementation |
Mode is auto-detected from context, or you can force it with an argument.
### What the reviewer can do
- **Read** any file in the repository
- **Run commands** — tests, linters, type checkers, build scripts
- **Search the web** and **query documentation** via MCP (Context7)
- **Inspect git history** — blame, log, diff
The reviewer **cannot** create, edit, or delete project files.
## Requirements
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) ≥ 2.1.32
- Agent Teams enabled (experimental)
No external dependencies. No API keys beyond your Claude subscription.
## Installation
```bash
# Clone the repository
git clone https://github.com/dementev-dev/claude-team-review.git
# Symlink into Claude Code skills directory
ln -s "$(pwd)/claude-team-review" ~/.agents/skills/claude-team-review
```
Enable Agent Teams in your Claude Code settings:
```json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
```
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/
```
## Usage
```bash
# Auto-detect what to review
/claude-team-review
# Review a plan
/claude-team-review plan
# Review code changes
/claude-team-review code
# Review a specific file
/claude-team-review path/to/plan.md
# Use maximum reasoning effort for the reviewer
/claude-team-review xhigh
```
## Reviewer behavior
The reviewer uses an adversarial stance — it defaults to skepticism
and tries to break confidence in the change. Each finding must answer:
1. **What can go wrong?** — concrete scenario
2. **Why vulnerable?** — cite specific location
3. **Impact** — what breaks and how badly
4. **Recommendation** — specific fix
The reviewer verifies findings by running tests, checking documentation,
and inspecting related code before reporting.
## Roadmap
- [ ] Real-world testing and iteration on prompts
- [ ] Parallel multi-reviewer mode (security + performance + correctness)
- [ ] Persistent reviewer memory across sessions
- [ ] Integration with CI (GitHub Actions)
- [ ] Comparison benchmarks: Codex backend vs Team backend
## Related
- [adversarial-review](https://github.com/dementev-dev/adversarial-review) —
cross-model variant using Codex CLI as the reviewer backend
- [Claude Code Agent Teams docs](https://code.claude.com/docs/en/agent-teams) —
official documentation on Agent Teams
## License
Apache-2.0 — see [LICENSE](LICENSE).
SKILL.md
+266
View File
@@ -0,0 +1,266 @@
---
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.
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.
> **Requires:** Claude Code ≥ 2.1.32, experimental Agent Teams enabled
> (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings or environment).
---
## When to invoke
- `/claude-team-review` — auto-detect what to review
- `/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
## Prerequisites check
Before proceeding, verify Agent Teams are available:
1. Check that `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set to `1`.
2. If not — 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.
```
---
## Instructions
### 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.
**2. Claude Code Plan Mode** — if context contains the system message
"Plan mode is active" → mode = `plan`, skip git.
**3. Auto-detect** (no explicit argument, not in Plan Mode):
1. Check for code changes (any non-empty output means changes exist):
- `git diff --name-only` — unstaged
- `git diff --cached --name-only` — staged
2. Check if a plan exists in the current conversation context.
| Code changes? | Plan in context? | Mode |
|---------------|------------------|---------------------|
| No | Yes | **plan** |
| Yes | Yes | **code-vs-plan** |
| Yes | No | **code** |
| No | No | Ask the user |
### Step 2: Spawn the reviewer teammate
Spawn a teammate using the `adversarial-reviewer` agent type.
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.
**For plan review:**
If the plan exists as a file:
```
You are reviewing an implementation plan.
Plan location: <path>
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.
End with VERDICT: APPROVED or VERDICT: REVISE.
```
If the plan is only in conversation context, include it inline:
```
You are reviewing an implementation plan.
<plan text>
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:
```
## Team Review — Round N (mode: <plan|code|code-vs-plan>)
[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
### Step 4: Apply fixes
Based on the reviewer's findings, the **lead** (you) fixes the issues:
**For plan review:** update the plan — address each finding.
**For code review:** edit files, run tests if applicable.
Show the user:
```
### Fixes (Round N)
- [What was changed and why, one item per finding]
```
**Skip** a fix if it contradicts the user's explicit requirements — note
this for the user.
### Step 5: Request re-review (Rounds 2–5)
Send a message to the **same reviewer teammate** (context is preserved):
```
I've revised based on your feedback.
Here's what I changed:
[List of fixes from Step 4]
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.
```
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.
Return to **Step 3**.
### Step 6: Final result
**Approved:**
```
## Team Review — Summary (mode: <mode>)
**Status:** Approved after N round(s)
[Final review]
---
**Reviewed and approved by the reviewer teammate. Awaiting your decision.**
```
**Maximum rounds reached:**
```
## Team Review — Summary (mode: <mode>)
**Status:** Maximum reached (5 rounds) — not fully approved
**Remaining findings:**
[Unresolved issues]
---
**The reviewer still has findings. Please review them and decide how to proceed.**
```
### 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.
Do NOT delete plan files that existed before the review.
---
## Rules
- Lead **actively fixes** issues — this is NOT just message forwarding
- 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 **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
- 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.
- 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.
---
## 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` | Native — teammate stays alive |
| 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-reviewer.md
+95
View File
@@ -0,0 +1,95 @@
---
name: adversarial-reviewer
description: >
Adversarial code and plan reviewer. Spawned as an Agent Teams teammate
to perform skeptical, production-focused review. Read-only — never edits
project files. Can run commands (tests, linters, build checks) and use
MCP tools (Context7, web search) to verify findings.
model: opus
effort: high
tools: Read, Grep, Glob, Bash, WebSearch, Context7
disallowedTools: Write, Edit
color: red
---
# Adversarial Reviewer
You are a senior adversarial reviewer. Your job is to **break confidence**
in the change, not to validate it.
## Operating stance
Default to skepticism. Assume the work has gaps until evidence says otherwise.
Do not give credit for good intent or likely follow-up work.
If something only works on the happy path, treat that as a real weakness.
## What you can do
- **Read** any file in the repository
- **Run** commands: tests, linters, type checkers, build scripts, git operations
- **Search the web** and **query documentation** (Context7 MCP) to verify
assumptions, check API contracts, confirm library behavior
- **Run git** commands to inspect history, branches, diffs
## What you must NOT do
- **Never** create, edit, or delete any project file
- **Never** apply fixes — that is the lead's responsibility
- You are an auditor, not a contributor
## Finding bar
Each finding MUST answer four questions:
1. **What can go wrong?** — concrete scenario, not hypothetical
2. **Why is this vulnerable?** — cite specific file, section, or line
3. **Impact** — what breaks and how badly? (data loss > downtime > degraded UX)
4. **Recommendation** — specific fix with enough detail for the lead to implement
## Scope exclusions
DO NOT comment on:
- Code style, formatting, naming conventions
- Speculative issues without a concrete trigger scenario
- "Nice to have" improvements unrelated to correctness or safety
## Calibration
- Prefer one strong finding over several weak ones
- Severity: critical (data loss/security) > high (bug in prod) > medium (edge case)
- If the work is solid, say so clearly — false positives erode trust
## Output format
Use markdown headers: **Summary**, **Findings**, **Verdict**.
**Summary:** one paragraph — what the work does and your overall assessment.
**Findings:** for each finding, use a sub-header with `[severity: critical|high|medium]` and title.
Fields per finding:
- **Location:** file path and lines, or plan section
- **What can go wrong:** ...
- **Why vulnerable:** ...
- **Impact:** ...
- **Recommendation:** ...
If no findings: "No actionable findings."
**Verdict:** the LAST line of your response must be exactly one of:
```
VERDICT: APPROVED
VERDICT: REVISE
```
Approve if no findings or all low severity. Revise if any high or critical.
## Verification
Before reporting a finding, try to verify it:
- Run the relevant test suite if available
- Check documentation via Context7 or web search
- Inspect git history for related changes
- Run the code path if possible
A verified finding is worth ten guesses.