agent-team-review

Agent Team Review

Overview

Parallel code review using agent teams. The lead spawns 2-4 reviewer teammates, each with a different review lens. Reviewers investigate independently, then the lead synthesizes findings into a unified review report.

Prerequisite: Implementation must be complete (all tasks marked done). Activates for larger implementations (5+ files changed).

Sizing Rule

Condition	Action
< 5 files changed	Use single-agent requesting-code-review
5+ files changed	Spawn reviewer team

Reviewer Composition

Teammate	Lens	Focus
security-reviewer	Security	Auth flows, input validation, secrets, OWASP risks
quality-reviewer	Code quality	Patterns, maintainability, test coverage, edge cases
spec-reviewer	Spec compliance	Does implementation match the design doc and plan?
adversarial-reviewer	Governance	HITL bypass, scope expansion, safety gate weakening, permission escalation

Protocol

1. Preparation

TeamCreate("code-review")

Gather context:
- Design doc from docs/plans/*-design.md
- Implementation plan from docs/plans/*-plan.md
- Acceptance spec from docs/plans/*-spec.md (if exists)
- Legacy fallback: docs/superpowers/specs/*-design.md
- Git diff: git diff {base_sha}...HEAD
- List of files changed

2. Spawn Reviewers

Each reviewer gets:

• The full diff
• The design doc
• Their specific review lens instructions
• The communication contract

3. Parallel Review

Reviewers work independently using Read, Grep, and analysis tools. They do NOT modify any files.

4. Lead Synthesis

After all reviewers report findings:

1. Group findings by severity (blocking → warning → suggestion)
2. Deduplicate overlapping findings
3. Present unified report to user

5. Verdict Routing

Verdict	Action
blocking_issues	TeamDelete → return to IMPLEMENT → fix issues → re-review
suggestions_only	TeamDelete → proceed to SHIP
clean	TeamDelete → proceed to SHIP

Communication Contract

All messages use plain text via SendMessage. No structured JSON.

Reviewer → Lead: Individual Finding

FINDING: [blocking | warning | suggestion]
File: src/auth.ts:42
Category: security | quality | spec | governance
Issue: SQL injection via unsanitized input
Suggestion: Use parameterized queries

Lead → User: Review Summary

REVIEW SUMMARY

Blocking:
- (list issues or "none")

Warnings:
- (list issues or "none")

Suggestions:
- (list issues or "none")

Verdict: blocking_issues | clean | suggestions_only

Reviewer Spawn Templates

Security Reviewer

Task tool (general-purpose):
  name: "security-reviewer"
  team_name: "code-review"
  prompt: |
    You are a security reviewer examining code changes.

    ## Your Lens: Security

    Focus on:
    - Authentication and authorization flows
    - Input validation and sanitization
    - Secrets management (hardcoded keys, tokens, passwords)
    - OWASP Top 10 risks
    - SQL/NoSQL injection
    - XSS and CSRF vulnerabilities
    - Dependency vulnerabilities
    - Error messages leaking sensitive information

    ## Context
    Design doc: {design_doc}
    Diff: {diff}
    Files changed: {files}

    ## Rules
    - Read-only: do NOT modify any files
    - Report each finding using the plain-text FINDING format
    - Send all findings to the lead via SendMessage
    - Be specific: include file path, line number, and remediation

Quality Reviewer

Task tool (general-purpose):
  name: "quality-reviewer"
  team_name: "code-review"
  prompt: |
    You are a code quality reviewer examining code changes.

    ## Your Lens: Code Quality

    Focus on:
    - Code patterns and consistency
    - Naming clarity and accuracy
    - Error handling completeness
    - Test coverage and test quality
    - Edge cases not covered
    - DRY violations
    - YAGNI violations (over-engineering)
    - Performance concerns
    - Maintainability

    ## Context
    Design doc: {design_doc}
    Diff: {diff}
    Files changed: {files}

    ## Rules
    - Read-only: do NOT modify any files
    - Report each finding using the plain-text FINDING format
    - Send all findings to the lead via SendMessage
    - Distinguish between blocking issues and suggestions

Spec Compliance Reviewer

Task tool (general-purpose):
  name: "spec-reviewer"
  team_name: "code-review"
  prompt: |
    You are a spec compliance reviewer examining code changes.

    ## Your Lens: Spec Compliance

    Focus on:
    - Does implementation match the design doc?
    - Does implementation match the plan tasks?
    - Are all planned features implemented?
    - Are there unplanned features (scope creep)?
    - Do interfaces match the specified contracts?
    - Are edge cases from the spec handled?

    ## Context
    Design doc: {design_doc}
    Plan: {plan}
    Diff: {diff}
    Files changed: {files}

    ## Rules
    - Read-only: do NOT modify any files
    - Report each finding using the plain-text FINDING format
    - Send all findings to the lead via SendMessage
    - Flag both missing features AND unplanned additions

Adversarial Reviewer

Task tool (general-purpose):
  name: "adversarial-reviewer"
  team_name: "code-review"
  prompt: |
    You are a governance reviewer examining code changes for safety regressions.

    ## Your Lens: Governance & Safety

    Focus on:
    - HITL (human-in-the-loop) requirements weakened or removed
    - Autonomous action scope expanded without corresponding safety gate
    - Safety gates, approval steps, or confirmation prompts bypassed or removed
    - Permission escalation (new outbound actions, broader tool access)
    - Hook behavior or composition routing changes that reduce guardrails
    - Bypass patterns: dangerouslyDisableSandbox, --no-verify, force push, auto-approve
    - Destructive operations added without confirmation gates

    ## Context
    Design doc: {design_doc}
    Diff: {diff}
    Files changed: {files}

    ## Rules
    - Read-only: do NOT modify any files
    - Report each finding using the plain-text FINDING format
    - Send all findings to the lead via SendMessage
    - A finding is blocking if it removes or weakens an existing safety constraint
    - A finding is warning if it adds new autonomous capability without explicit safety design
    - A finding is suggestion if it could be made safer but isn't actively dangerous

Integration

• Falls back to: requesting-code-review for < 5 files
• Protected by: cozempic (auto-installed at SessionStart)
• Heartbeat: teammate-idle-guard.sh prevents false idle nudges
• Follows: agent-team-execution or single-agent implementation