agent-teams-review

What this skill does

# Agent Teams Code Review Orchestrator

Run a collaborative code review using Agent Teams. Unlike subagent-based reviews, teammates can message each other during the review, producing cross-reviewer findings that single-pass reviews cannot achieve.

This skill leaves `allowed-tools` unset on purpose: as the orchestrator it drives the whole Agent Teams machinery (`TeamCreate`, `TaskCreate`, `TaskList`, `SendMessage`, `TaskStop`, `TeamDelete`) plus git and file tools, so it needs broad access.

## Workflow

### Step 1: Gather Review Context

Collect the review target from `$ARGUMENTS`.

**Input:** The first argument is the base branch to compare against (e.g. `develop`, `main`). Default: `main` if none is given. A second optional argument is the scope keyword (`quick`, `standard`, `full`) — if present, skip the prompt in Step 2 and use it directly.

### Step 2: Select Review Scope

The scope controls how deep the review goes and how much noise reaches the final report. Ask early, because it shapes every later step. If the user already passed a scope keyword in `$ARGUMENTS`, skip the question.

Use `AskUserQuestion` to ask which scope to run:

| Scope | What it does | When to pick it |
|-------|--------------|-----------------|
| **1 — Quick** (Critical-only) | Same team reviews the diff, but the report surfaces **only Critical and High** findings. Medium/Low collapse to a one-line count. No triage offered automatically. | Fast gate before merge — "are there any showstoppers?" |
| **2 — Standard** (default) | Current behavior. Team reviews the diff, full Action-First report with every severity, AI Slop table, optional triage. | Normal PR review. |
| **3 — Full** (deep) | Team reviews the diff **plus related files** — the callers and callees of every function the PR touched, and the modules they belong to. Adds an **Impact Analysis** section judging whether the touched behavior still works end-to-end. Triage is recommended at the end. | High-risk change, refactor, or "make sure nothing downstream broke". |

The team selection itself does not change with scope (Step 4 stays the same) — scope only changes reporting threshold and how far the reviewers look. Remember the chosen scope; it feeds Steps 3, 6, 8, 9, and 11.

### Step 3: Collect Code Changes

**Git diff mode:**
```bash
git diff <base-branch>...HEAD --name-only  # changed file list
git diff <base-branch>...HEAD              # full diff
```

**Specific files:** Read each file directly.

**Directory:** List and read source files, excluding `node_modules`, `dist`, `build`, `.git`, `vendor`, `storage`, etc.

Read `CLAUDE.md` from the project root if it exists — it carries project conventions the reviewers need.

**Full scope only — collect related files.** When scope is **Full**, the touched code is not enough: a change is only safe if its callers and callees still hold. For each function/method/class the diff modifies, locate where it is used and what it depends on, and read those files too:

```bash
# find references to a touched symbol across the codebase
grep -rn "touchedFunctionName" --include=*.php --include=*.vue --include=*.ts .
```

Gather these into a "Related Files" set that you will hand to the team in Step 6 so they can reason about ripple effects, not just the diff in isolation.

### Step 4: Analyze Files & Select Reviewers

Virtual Mariusz (`VM-`) always runs — he is the digital twin and the AI-Slop gatekeeper, so every review needs his eyes. The rest are selected by what the diff actually contains:

| Reviewer | Trigger Condition |
|----------|-------------------|
| Backend Solidifier (BE-) | Files match: `*.php`, `composer.json`, `config/*.php`, `migrations/*`, `database/*` |
| Frontend Virtuoso (FE-) | Files match: `*.vue`, `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `nuxt.config.*`, `*.css`, `*.scss` |
| Quality Purist (QA-) | When Backend Solidifier OR Frontend Virtuoso is selected |
| Security Sentinel (SC-) | File path matches: `**/auth/**`, `**/security/**`, `**/middleware/**`, `**/guard/**`, `**/policy/**` OR file content contains: `password`, `login`, `token`, `secret`, `session`, `csrf`, `sanitize`, `encrypt`, `hash` |
| Devil's Advocate (DV-) | New classes/functions >30 lines, complex conditionals (>3 nesting levels), financial/payment logic detected, OR total lines changed >150 |

After auto-selection, show the user which reviewers are selected and which are skipped (with reasons).

Use `AskUserQuestion` with `multiSelect: true` to let the user override the selection. Present all 6 reviewers with their auto-selected state so the user can add or remove reviewers.

### Step 5: Read Reviewer Profiles

Read each selected reviewer's profile from `references/`:

| Reviewer | Profile File |
|----------|-------------|
| Virtual Mariusz | [references/virtual-mariusz.md](references/virtual-mariusz.md) |
| Backend Solidifier | [references/backend-solidifier.md](references/backend-solidifier.md) |
| Frontend Virtuoso | [references/frontend-virtuoso.md](references/frontend-virtuoso.md) |
| Quality Purist | [references/quality-purist.md](references/quality-purist.md) |
| Security Sentinel | [references/security-sentinel.md](references/security-sentinel.md) |
| Devil's Advocate | [references/devils-advocate.md](references/devils-advocate.md) |

### Step 6: Spawn the Agent Team

Use the **Agent Teams** tools here, not the `Task` subagent tool — teammates must be able to message each other during the review, which subagents cannot do. Spawn every selected reviewer with **Sonnet**; code review does not need Opus-level reasoning, and a 6-person team on Sonnet keeps cost sane.

Concrete sequence:

1. **Create the team with `TeamCreate`**, spawning all selected reviewers at once (simultaneous spawn is what lets them communicate). For each teammate provide:
   - a name (the reviewer's name, e.g. `Security Sentinel`)
   - model: `sonnet`
   - a spawn prompt = the reviewer's profile content (from Step 5) **+** the Review Context block below

2. **Append this Review Context block** to every teammate's spawn prompt:

```
## Review Context

### Review Scope: {Quick | Standard | Full}
{Scope instructions — see "Scope behavior" below}

### Files Changed
[list of changed files from Step 3]

### Code Diff
[full diff or file contents from Step 3]

### Related Files (Full scope only)
[callers/callees and related modules collected in Step 3]

### Project Conventions
[CLAUDE.md content if it exists]

## How to Report Each Finding

Tag every finding with three markers so the report and the later triage stay analyzable and you avoid crying wolf:

- **Severity:** Critical | High | Medium | Low — judged by real impact on the running app
- **Confidence:** High | Medium | Low — how sure you are it is a real issue. Low confidence means "worth a look", not a reason to inflate severity. This is how we keep false positives out.
- **Effort:** ~5min | ~30min | ~1h+ — rough fix cost, so triage does not have to guess

Write each finding's header line as:
`[PREFIX-NNN] Title — file:line — Severity · Confidence · Effort`

## Team Communication

You are part of a review team. You can message other active teammates:
[List active teammate names and their roles]

When you find something in another reviewer's domain:
- Message them directly with the file, line number, and your concern
- They investigate and report if it is a real issue
- These cross-reviewer findings are especially valuable — they are what a solo pass misses

When a teammate messages you:
- Investigate the flagged concern within your expertise
- Report findings with the CROSS- prefix if confirmed
- Acknowledge if you have already covered it
```

3. **Scope behavior** — fill the `### Review Scope` section with the matching instruction:
   - **Quick:** "Surface only Critical and High findings. For Medium and Low, do not write them up — just give a one-line count at the end of your review. Spend your effort on what could block the merge."
   - **Standard:** "Surface all se