team-review

/team-review

You are orchestrating a parallel multi-perspective code review using agent teams. Multiple reviewers work simultaneously, each with a specialized lens, then findings are synthesized into a single report.

---

Input

$ARGUMENTS

If $ARGUMENTS specifies a PR number, branch, or file paths, review those changes. If empty, review all uncommitted changes.

---

Step 1 — Gather the scope

Determine what to review:

# For uncommitted changes
git diff
git diff --staged
git status

# For a branch
git diff main...HEAD
git log main..HEAD --oneline

# For a PR
gh pr diff <number>

Read every changed file in full. Count the number of changed files and lines to determine team size.

---

Step 2 — Create the review team

Create an agent team with specialized reviewers. Adjust the number based on change scope:

For small-to-medium changes (< 500 lines): 3 teammates

Create an agent team to review these changes with three specialized reviewers:

1. **Security reviewer** — Focus on input validation, authentication, authorization,
   secrets exposure, injection vulnerabilities, and OWASP top 10.

2. **Correctness & performance reviewer** — Focus on logic errors, race conditions,
   off-by-one errors, null access, N+1 queries, unbounded loops, and missing indexes.

3. **Tests & conventions reviewer** — Focus on test coverage gaps, flaky test patterns,
   adherence to project conventions, and dead code.

For large changes (> 500 lines): 4-5 teammates, splitting security from correctness from performance.

Spawn prompt template

Each reviewer must receive:

• The list of changed files
• The diff or PR number
• Their specific review focus area
• Instruction to read full files, not just diffs
• Instruction to report findings with severity, file:line, problem, and fix

Require plan approval

For critical codepaths (auth, payments, data mutations), require plan approval:

Require plan approval before the security reviewer starts.
Only approve plans that include checks for all OWASP top 10 categories.

---

Step 3 — Let reviewers work

Allow all reviewers to complete their analysis. Do NOT start synthesizing until all teammates report their findings.

Wait for all teammates to complete their review before proceeding.

If a reviewer gets stuck, redirect their approach or spawn a replacement.

---

Step 4 — Synthesize the review

Once all reviewers finish, the lead produces a unified report:

Team Code Review

Scope: [files reviewed] Reviewers: [list of reviewer roles] Verdict: Clean / Minor Issues / Needs Changes / Blocking Issues

Blocking Issues

Issues that must be fixed before shipping. Numbered, with:

• Severity: Blocking
• Domain: Security / Correctness / Performance / Tests
• File: path/to/file:line
• Found by: [reviewer role]
• Problem: What's wrong
• Fix: How to fix it

Major Issues

Should be fixed. Same format as above.

Minor Issues / Nits

Nice to fix. Same format.

Cross-cutting Findings

Issues identified by multiple reviewers or that span domains.

What Looks Good

Patterns done well, noted by reviewers.

Summary

Overall assessment. Ship as-is, fix and ship, or rework needed.

---

Step 5 — Clean up

After synthesizing the report:

Ask all reviewers to shut down, then clean up the team.

---

When to use /team-review vs /review

Situation	Use
Quick review of small changes	/review
Large PR with many files	/team-review
Security-critical changes	/team-review
Pre-release audit	/team-review
Routine bug fix	/review
Changes spanning multiple domains	/team-review

---

Gotchas

These are common failure modes during team reviews. Watch for them:

• Reviewers editing code. Reviewers report findings — they do NOT fix code. If a reviewer starts writing patches, redirect them. The fix happens after the review.
• Duplicate findings inflating severity. Two reviewers flag the same null check. The lead merges them into one finding — don't count it twice when assessing overall severity.
• Reviewers rubber-stamping their domain. A security reviewer that says "no security issues found" in 300 lines of user-input handling is not doing their job. Push reviewers to dig deeper when their initial pass is clean.
• Too many teammates for small changes. Spawning 5 reviewers for a 50-line change wastes tokens and produces thin findings. 3 is usually enough; 5 only for large or security-critical PRs.
• Forgetting to clean up the team. Orphaned teammates consume resources. Always shut down all teammates and clean up after synthesizing the report.

---

Important constraints

• Read the full file, not just the diff. Every reviewer must understand context.
• Do NOT let reviewers edit code. This is review only — findings go in the report.
• Deduplicate findings. If two reviewers flag the same issue, merge into one entry.
• Severity must be actionable. "Blocking" means it must be fixed. Don't overuse it.
• Clean up the team when done. Do not leave orphaned teammates.