team-review

Team Review

Multi-agent team orchestration for comprehensive PR code review. Spawns 6 specialized reviewer agents plus 1 adversary reviewer as a coordinated team. Designed for security-sensitive, architectural, or high-impact code changes where a single-agent review is insufficient.

For simpler reviews, use /review-code (single-agent with parallel Explore subagents).

Prerequisites

Full mode spawns 7 named reviewer agents that message each other directly via SendMessage (the adversary needs this to cross-examine the other 6). Named agent-team spawning requires the experimental flag. Add to your environment or settings.json:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Lite mode (--lite flag, or automatic fallback when the flag is unset) needs no flag: it spawns 4 combined-role Task subagents that report results back to the orchestrator instead of talking to each other directly. Fewer agents, lower cost, still covers all 7 dimensions.

No Task/subagent tools at all? Run the review yourself, sequentially, as the lead: the 7 dimensions are the methodology, parallel agents are just how Claude Code speeds it up:

1. Read every file in scope (for PR/commit reviews: the diff, plus surrounding code for context).
2. Work each checklist in turn, logging findings as you go: architecture → security → performance → testing → style → docs/UX (checklists are in references/agent-catalog.md, one per dimension).
3. Re-read your own findings as the adversary would: which look like false positives? What's a blind spot across dimensions? What breaks at 10x scale or under adversarial input?
4. Consolidate and write the report: Phases 4-5 below apply unchanged regardless of how the findings were gathered.

Delegate mode (recommended for full mode): Press Shift+Tab to enable delegate mode, which restricts the lead to coordination-only tools and prevents it from reviewing code itself.

Input

$ARGUMENTS

Notes

• /resume does not restore teammates: an interrupted full-mode session loses the team; re-run from scratch.
• Only one team-review can run per session.
• Analysis only: it finds issues but never edits code; use /implement-feature or /fix-bug for the actual fixes.
• Teammates sometimes forget to mark tasks complete, so the orchestrator should poll task status rather than assume completion.
• Every reviewer must ground findings in code it actually read (file:line, real snippet) and flag uncertain cases as "needs manual verification" instead of asserting, a false positive here costs more than a missed finding, since it erodes trust in the whole report.
• Abort early if the requested scope (PR/commit) doesn't exist or isn't readable, don't let reviewers spin on a bad input. If reviewer tasks stall past ~10 min, or the adversary doesn't report back, proceed to consolidation with what's in hand rather than blocking the whole review.

Workflow Overview

Phase 0: Scope Detection & Input Ingestion
Phase 1: Project Discovery
Phase 2: Team Composition & Spawn
Phase 3: Parallel Specialist Review (6 reviewers + 1 adversary)
Phase 4: Consolidation & Cross-Reference
Phase 5: Report Generation
Phase 6: Teardown

Optional: Iterative re-review after fixes

Phase 0: Scope Detection & Input Ingestion

Parse $ARGUMENTS to determine what to review:

Retrieve full diff context for PR/commit reviews. Reviewers must focus findings on changed lines while using surrounding code for context.

Phase 1: Project Discovery

Spawn an Explore/haiku agent to understand the project:

Task tool (Explore, haiku):
"Discover the project's technology stack, coding conventions, and quality standards:
  1. Read CLAUDE.md and README.md for project context and conventions
  2. Check package.json, pyproject.toml, pom.xml, go.mod for languages/frameworks
  3. Identify linting/formatting configs: .eslintrc, .prettierrc, ruff.toml, .editorconfig
  4. Identify test frameworks and patterns
  5. Check for CI/CD quality gates in .github/workflows
  6. Note architectural patterns: MVC, Clean Architecture, DDD, etc.
  7. Identify security tools: SAST, dependency scanning, pre-commit hooks
  Return: Technology stack, conventions, quality standards, and security tooling summary."

Phase 2: Team Composition & Spawn

Choose Full vs Lite Mode

Default to full mode when any of these hold: the same signals named in this skill's description:

• Security-sensitive: touches auth, payments, or PII
• Architectural: introduces a new pattern or changes a schema
• Large: 15+ files changed
• Explicit ask: user requests compliance/audit sign-off, or says "thorough"/"full team"/"multi-agent"

Default to lite mode otherwise: a localized, single-component change with no sensitive data.

Ambiguous (e.g. a schema change touching only 3 files, or a small change near auth code)? Ask instead of guessing:

AskUserQuestion:
  question: "This PR touches [signal] but is otherwise small — full team review or lite mode?"
  options:
    - "Lite mode (4 agents, faster/cheaper)"
    - "Full mode (7 agents, more thorough)"

Override: --lite flag forces lite mode regardless of signals.

Full Mode Team Spawn

Spawn each reviewer as a separate, named agent via the Task tool (one call per reviewer, so they run in parallel). The name is what later SendMessage and TaskStop calls address: pick short, stable handles like arch-reviewer, security-reviewer. For complete prompt templates, see references/agent-catalog.md.

Lite Mode (Task Subagents)

Spawn 4 Task subagents (combined roles) instead of full team:

Focus Mode

When --focus is specified, spawn only relevant reviewers:

Phase 3: Parallel Specialist Review

All reviewers work simultaneously on the same file set. Each reviewer follows its specialized prompt from references/agent-catalog.md.

Task Assignment

Create tasks for each reviewer via TaskCreate, then assign:

TaskCreate:
  subject: "Architecture review of PR #[N]"
  description: "Review changed files for architectural issues, API design, data modeling..."
  activeForm: "Reviewing architecture"

TaskCreate:
  subject: "Security review of PR #[N]"
  description: "Review changed files for OWASP vulnerabilities, auth issues..."
  activeForm: "Reviewing security"

# ... repeat for each reviewer

# Assign to agents
TaskUpdate: { taskId: "arch-task", owner: "arch-reviewer" }
TaskUpdate: { taskId: "security-task", owner: "security-reviewer" }
# ... etc.

Reviewer Instructions (Common Preamble)

Each reviewer receives:

1. The list of files in scope
2. The full diff (for PR/commit reviews)
3. Project discovery results from Phase 1
4. Their specialized review prompt from references/agent-catalog.md

Each reviewer must:

1. Read each file in scope
2. For PRs: focus analysis on changed lines, use surrounding code for context
3. Grep for dimension-specific patterns
4. Verify each finding by reading the code in context
5. Classify severity: Critical / Major / Minor / Nit
6. Write findings to a structured format with file:line references, code snippets, explanations, and fix suggestions
7. Mark their review task as completed via TaskUpdate
8. Send findings summary to the orchestrator via SendMessage

Adversary Reviewer (Special Role)

The adversary reviewer operates differently:

1. Waits for initial findings from at least 3 other reviewers (orchestrator forwards summaries)
2. Challenges the findings: Are any false positives? Are severity ratings accurate?
3. Finds gaps: What did the other reviewers miss? What assumptions are untested?
4. Stress-tests: What happens at 10x scale? What if inputs are malicious? What if dependencies fail?
5. Reports: Additional findings + challenges to existing findings

Phase 4: Consolidation & Cross-Reference

After all reviewers complete, the orchestrator:

1. Collects all findings from 7 reviewers (6 specialists + 1 adversary)
2. Deduplicates - Merge findings flagged by multiple reviewers (e.g., same function flagged by security AND performance)
3. Incorporates adversary feedback - Adjust severity ratings, remove confirmed false positives, add adversary's unique findings
4. Cross-references - Note findings that span multiple dimensions
5. Prioritizes by severity:
   • Critical: Data loss, security holes, crashes, incorrect business logic
   • Major: Performance degradation, reliability risks, significant test gaps
   • Minor: Readability, consistency, minor improvements
   • Nit: Style preferences, optional enhancements
6. Computes statistics: Total findings, by severity, by reviewer, files with issues

Phase 5: Report Generation

Generate a comprehensive review report following the template in references/report-template.md.

Report sections:

1. Executive summary with overall assessment and team consensus
2. Severity breakdown with counts
3. Findings by reviewer dimension, each with file:line, code snippet, explanation, and fix suggestion
4. Adversary findings and challenges
5. Cross-cutting concerns (findings spanning multiple dimensions)
6. Positive observations - highlight well-written code and good patterns
7. Prioritized action items

Phase 6: Teardown

Full Mode

1. Once a reviewer has sent its findings via SendMessage, call TaskStop with its name (e.g. TaskStop({ task_id: "security-reviewer" })) to free it.
2. Repeat for each of the 7 reviewers as they report in.
3. Present final report to user.

Lite Mode

1. Collect all subagent results (they return directly to the orchestrator; no explicit stop needed).
2. Present final report to user.

Iterative Re-Review

After the initial review, if fixes are made and a re-review is requested:

1. Detect changes: git diff --name-only <last_reviewed_commit>..HEAD
2. Scope to changed files only - Do NOT re-review the entire codebase
3. Re-spawn only relevant reviewers - If fixes addressed security findings, re-spawn security-reviewer and adversary-reviewer only
4. Verify fixes - Check that previously reported Critical/Major issues are resolved
5. Report delta - Show resolved, remaining, and new findings

Worked Examples

Full report structure lives in references/report-template.md: these show what a real, filled-in entry looks like (never fabricate the file:line or snippet; it must come from a file the reviewer actually read).

A Critical security finding:

#### [SEC-1]: SQL built via string interpolation in order lookup
- Severity: Critical | OWASP: A05 (Injection)
- File: `api/orders.py:142-145`
- Code: `query = f"SELECT * FROM orders WHERE user_id = {user_id}"`
- Attack scenario: `user_id` comes from an unvalidated query param, a value like
  `1 OR 1=1` returns every user's orders.
- Fix: parameterize: `cursor.execute("SELECT * FROM orders WHERE user_id = %s", (user_id,))`

An adversary challenge (downgrading a false positive, adding a miss):

Finding [PERF-2]: Disagree, flagged `O(n²)` loop only runs at startup over a
config list capped at 12 entries; downgrade Critical → Nit.

New finding [ADV-1]: The new `retry_payment()` in `billing.py:88` has no
idempotency key, a network retry after a successful charge double-bills.
Missed because it's outside the diff's changed lines but is called by them.

Lite mode's combined-role finding (Architecture & Security agent, one merged list, security-first priority):

#### [ARCH-SEC-1]: Missing ownership check before role update
- Severity: Critical (security takes priority over the architectural nit below)
- File: `handlers/admin.py:51`
- Any authenticated user can PATCH another user's role, no ownership or
  admin-role check before the write. Also note: this handler duplicates the
  permission logic in `handlers/users.py:30` (Minor, DRY).

Re-review delta after fixes (Phase: Iterative Re-Review):

Resolved (2): ~~[SEC-1] SQL injection~~: parameterized in orders.py:142 ✅
Remaining (1): [ARCH-1] still present, pagination not added to /orders
New (1): [NEW-1] fix for SEC-1 left an unused import in orders.py (Nit)

Usage

# Full team review of a PR (auto-detects complexity)
/team-review 123

# Force lite mode for cost efficiency
/team-review 123 --lite

# Focus on specific dimension
/team-review 123 --focus security

# Review a specific commit
/team-review abc123def

# Review entire codebase
/team-review --all

# Re-review after fixes
/team-review 123

When to Use team-review vs review-code

Additional Resources

• references/agent-catalog.md - Complete prompt templates for all 7 reviewer agents
• references/report-template.md - Review report template with all sections

What This Skill Does

• Orchestrates 7 specialized reviewer agents working in parallel
• Provides deep, multi-dimensional code review with expert-level analysis
• Includes adversary review to challenge assumptions and find blind spots
• Generates comprehensive report with cross-referenced findings
• Supports iterative diff-only re-review after fixes

What This Skill Does NOT Do

• Does not modify any code
• Does not automatically fix issues
• Does not commit changes
• Does not run tests or benchmarks
• Does not replace human review for compliance sign-off