mgiovani/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 requires the experimental agent teams flag. Add to your environment or settings.json:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Lite mode (--lite flag or automatic fallback) works without this flag — uses Task subagents instead of the Teammate API. Fewer agents, lower cost, still comprehensive.

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

Known Limitations

• No session resumption: /resume does not restore teammates. If a session is interrupted, teammates are lost
• One team per session: Cannot run multiple team-review invocations simultaneously
• Analysis only: Identifies issues without modifying code. Use /implement-feature or /fix-bug for fixes
• Task status can lag: Teammates sometimes forget to mark tasks complete; orchestrator should monitor
• Teammates load CLAUDE.md: Project conventions apply automatically to all reviewers (this is a benefit)

Anti-Hallucination Guidelines

CRITICAL: All reviewers must follow these rules:

1. Read before claiming - Never report issues in code that has not been read
2. Evidence-based findings - Every finding must reference specific file paths and line numbers
3. Verify in context - Confirm each pattern is actually problematic, not an intentional choice
4. No false positives - When uncertain, flag as "Needs manual verification" rather than asserting
5. Scope enforcement - Only review files within the specified scope (PR/commit/all)
6. Respect project conventions - Understand existing patterns before flagging style issues

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:

| Pattern | Source Type | Ingestion | |---------|-----------|-----------| | 123 or #123 | PR number | gh pr view 123 --json files,title,body,labels,comments + gh pr diff 123 | | abc123 | Commit SHA | git show abc123 + git diff-tree --no-commit-id --name-only -r abc123 | | --all or no args | Entire codebase | git ls-files (respects .gitignore) | | --lite | Force lite mode | Use Task subagents instead of Teammate API | | --focus <area> | Focus area | Spawn only relevant reviewers |

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

Assess Complexity

Evaluate complexity to determine full vs. lite mode:

| Signal | Full Mode (+2) | Medium (+1) | Lite Mode (0) | |--------|----------------|-------------|----------------| | Files changed | 15+ files | 5-14 files | <5 files | | Security sensitivity | Auth, payments, PII | Permission checks | No sensitive data | | Architectural impact | New patterns, schema changes | Modifying existing patterns | Localized changes | | Cross-cutting concerns | Multiple modules/services | 2 components | Single component |

Thresholds:

• Score 0-2: Use lite mode automatically
• Score 3-4: Ask user (recommend lite for cost efficiency)
• Score 5+: Use full mode automatically

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

Full Mode Team Spawn

Teammate({ operation: "spawnTeam", team_name: "review-<pr_or_scope>" })

Spawn 7 reviewer agents. For complete prompt templates, see references/agent-catalog.md.

| Role | Agent Name | Model | Focus | |------|-----------|-------|-------| | Architecture Reviewer | arch-reviewer | opus | System design, API contracts, data modeling, dependency graph | | Security Reviewer | security-reviewer | sonnet | OWASP Top 10, auth/authz, input validation, secrets | | Performance Reviewer | perf-reviewer | sonnet | Algorithmic complexity, queries, caching, memory | | Testing Reviewer | test-reviewer | sonnet | Coverage gaps, assertion quality, test architecture | | Style & Patterns Reviewer | style-reviewer | sonnet | Naming, DRY/SOLID, framework idioms, readability | | Docs & UX Reviewer | docs-reviewer | haiku | API ergonomics, error messages, documentation, changelog | | Adversary Reviewer | adversary-reviewer | sonnet | Challenges assumptions, finds edge cases, stress-tests design |

Lite Mode (Task Subagents)

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

| Combined Role | Covers | Model | |---------------|--------|-------| | Architecture & Security | arch-reviewer + security-reviewer | sonnet | | Performance & Style | perf-reviewer + style-reviewer | sonnet | | Testing & Error Handling | test-reviewer + edge cases | sonnet | | Adversary | adversary-reviewer + docs-reviewer | sonnet |

Focus Mode

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

| Focus | Agents Spawned | |-------|---------------| | architecture | arch-reviewer, adversary-reviewer | | security | security-reviewer, adversary-reviewer | | performance | perf-reviewer, adversary-reviewer | | testing | test-reviewer, adversary-reviewer | | style | style-reviewer, docs-reviewer |

---

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. Send shutdown_request to all reviewer agents
2. Wait for shutdown_response from each
3. Run Teammate({ operation: "cleanup" })
4. Present final report to user

Lite Mode

1. Collect all subagent results
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

---

Quality Gates

| Gate | Between | Pass Criteria | On Failure | |------|---------|---------------|------------| | Scope Validation | 0 → 1 | Files exist and are readable | Error + abort | | Discovery Complete | 1 → 2 | Tech stack identified | Proceed with defaults | | All Reviews Complete | 3 → 4 | All reviewer tasks marked complete | Wait (timeout: 10 min) | | Adversary Complete | 3 → 4 | Adversary findings received | Proceed without adversary | | Report Generated | 5 → 6 | All findings have file:line refs | Verify and fix gaps |

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

| Scenario | Use | |----------|-----| | Standard PR review | /review-code (faster, cheaper) | | Security-sensitive changes (auth, payments, PII) | /team-review | | Architectural changes (new patterns, schema) | /team-review | | Large PRs (15+ files) | /team-review | | Quick check before merging | /review-code | | Compliance or audit requirements | /team-review | | Re-review after fixes | Either (both support diff-only) |

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