Multi specialist review

Multi-Specialist Review

Team-based code review that spawns 3-5 parallel specialist sub-agents to examine a diff through different perspectives (correctness, security, performance, architecture, etc.), mechanically verifies every finding against the actual source files, and synthesizes a single prioritized review artifact.

When to Use

This skill is user-triggered. It is not part of routine agent workflows — the cost and authority profile warrants explicit user invocation. Use when:

• PR-level changes (5+ modified files)
• Multi-commit ranges (main..feature-branch) rather than atomic commits
• Security-sensitive paths (auth, crypto, payments, input validation)
• Single-turn specialist-review flagged quality concerns that need deeper scrutiny

For atomic-commit review, use the baseline specialist-review.sh from the agent-loops skill instead — it's 4-6x cheaper and sufficient for small diffs.

Prerequisites — Claude Code Only

This skill requires the Claude Code Agent tool with the code-reviewer subagent type available. It cannot be invoked from Codex or Gemini sessions, or from external shells. Parallelism comes from issuing multiple Agent calls in a single assistant message — no team API is needed.

Cost

Approximately $2-3 per review vs ~$2.00 for single-turn specialist-review. The premium buys multi-perspective coverage, grounded findings (sub-agents read source files, not just diffs), and mechanical citation verification.

CRITICAL — How specialists are spawned

Spawn specialists with one-shot Agent() calls only. Do NOT use TeamCreate, team_name=, or TaskCreate to spawn them.

Team-spawned subagents inherit a restricted runtime tool set (SendMessage, Task* only) — no Read, Grep, Glob, Write, or Bash. The observable failure is specialists narrating "I'll read the files" in plain text and idling between turns without invoking any tool. This has burned this skill twice. The fix is structural: use one-shot Agent() calls in a single message, which inherit the code-reviewer agent type's full toolset and have no between-turn idle state. Phase 1 below codifies this; the anti-pattern section at the bottom repeats the rule with the diagnostic signal so it can't be missed.

Orchestration Procedure

Follow these phases exactly. You are the orchestrator — do not delegate orchestration. Each phase is run by you in-context; only Phase 1 spawns sub-agents, and they are one-shot Agent calls that return and exit.

Phase 0 — Triage (deterministic, no API cost)

Generate the diff you want reviewed, then select perspectives:

# Generate the diff
git diff main..HEAD -- src/ > /tmp/review-diff.patch

# Select perspectives (3-5 from the catalog based on file types and content signals)
python3 skills/multi-specialist-review/scripts/triage_perspectives.py /tmp/review-diff.patch

This outputs JSON with perspectives, display_names, focus_areas, and changed_files. Save the output — you'll use it to parameterize each specialist.

Phase 1 — Spawn specialists as parallel one-shot Agents

Spawn all specialists in a single assistant message with one Agent tool call per perspective. Issuing multiple Agent calls in one message runs them concurrently — that is the parallelism mechanism. Do not use team_name=, TeamCreate, or TaskCreate; see the anti-pattern note below for why.

For each perspective from the triage output:

Agent(
  description="Specialist review: {perspective}",
  subagent_type="code-reviewer",
  model="sonnet",
  prompt=<specialist-prompt-template.md with {{PERSPECTIVE}}, {{FOCUS_AREAS}},
          {{CHANGED_FILES}}, {{DIFF_CONTENT}} filled in>
)

The template is at skills/multi-specialist-review/references/specialist-prompt-template.md. Each specialist:

• Inherits the code-reviewer toolset (Read, Grep, Glob, etc.) because it is a one-shot Agent call, not a team spawn
• Reads actual source files via Read/Grep/Glob (not just inlined diffs)
• Returns its structured JSON object as its final assistant message

When each Agent call returns, you (the orchestrator) write its JSON result to .agents/reviews/specialist-{perspective}-{timestamp}.json. The verifier in Phase 2 reads these files from disk.

Phase 2 — Citation verification (deterministic, no API cost)

Run the citation verifier on all specialist output files:

python3 skills/multi-specialist-review/scripts/verify_citations.py \
  .agents/reviews/specialist-*.json > .agents/reviews/verified-findings.json

This mechanically validates every finding:

• File exists on disk
• Line range is within file length
• Quoted code actually appears near the cited lines (±5 line window, whitespace-normalized)

Findings that fail verification are stripped with documented reasons.

Phase 3 — Synthesis (orchestrator, no extra agent)

Read the verified findings JSON and skills/multi-specialist-review/references/synthesis-prompt.md. Follow the synthesis instructions to:

1. Deduplicate findings that flag the same file+line range from multiple perspectives
2. Merge duplicates using the highest severity
3. Annotate multi-perspective findings as "(multi-perspective)" in the title
4. Renumber all findings sequentially (P0-001, P0-002, P1-001, etc.)
5. Produce the final markdown matching the review output contract

Write the final review to .agents/reviews/review-{timestamp}.md.

Phase 4 — Validate and clean up

# Validate the final output (contract validator lives in agent-loops as shared infra)
python3 skills/agent-loops/scripts/validate-review-contract.py code-review \
  .agents/reviews/review-{timestamp}.md

There is no team to tear down — one-shot Agent calls return and exit on their own. Optionally trash the per-specialist .agents/reviews/specialist-*.json intermediates once the synthesized review is written; keep verified-findings.json and the final markdown.

The output file path is the review artifact — return its path to the user.

Specialist Prompt Template

Located at skills/multi-specialist-review/references/specialist-prompt-template.md. A single parameterized template used for all perspectives. Fill these placeholders before passing to each specialist:

Placeholder	Source
{{PERSPECTIVE}}	Display name from triage output (e.g., "Security")
{{FOCUS_AREAS}}	Focus description from triage output
{{CHANGED_FILES}}	Bullet list of changed file paths
{{DIFF_CONTENT}}	The unified diff

Bundled Assets

Scripts:

• scripts/triage_perspectives.py — Deterministic perspective selection (Phase 0)
• scripts/verify_citations.py — Mechanical citation verification (Phase 2)

References:

• references/specialist-prompt-template.md — Parameterized prompt for each specialist
• references/synthesis-prompt.md — Instructions for Phase 3 synthesis

External dependency:

• skills/agent-loops/scripts/validate-review-contract.py — Shared review contract validator used by both this skill and the single-turn specialist-review.sh flow. Lives in agent-loops because it's baseline review infrastructure used across multiple flows.

Relationship to agent-loops

This skill was extracted from agent-loops when we recognized that team-based review has a different authority profile than routine per-commit review:

• agent-loops single-turn review (via specialist-review.sh) — autonomous, per-atomic-commit, cross-model independence via provider rotation. Runs continuously during implementation work.
• multi-specialist-review (this skill) — user-triggered, PR-level or security-sensitive, within-model multi-perspective diversity, grounded findings via sub-agent source reading.

Implementer agents using agent-loops will flag in their handoff when a change warrants team review, but they do not invoke this skill themselves. The user decides and triggers it.

Anti-Patterns

• Spawning specialists via team_name= / TeamCreate — Team-spawned agents do not inherit the code-reviewer toolset; they get only inter-agent coordination tools (SendMessage, Task*) and no Read/Grep/Glob/Write/Bash. The observable failure is specialists announcing "I'll read the files" in plain text, then idling between turns without ever invoking a tool. Always use one-shot Agent() calls in a single message instead — they get the full inherited toolset and have no idle-between-turns state.
• Spawning specialists sequentially — Launch all in a single message block for parallel execution.
• Skipping citation verification — Always run verify_citations.py. Specialists hallucinate file references.
• Adding synthesis as another agent — The orchestrator does synthesis in-context. No extra spawn needed.
• Using this for small diffs — Single-turn specialist-review.sh is 4-6x cheaper and sufficient for atomic commits.
• Reviewing your own code — The orchestrator must not be the implementer.
• Invoking autonomously from an agent workflow — This skill is user-triggered. Agents should signal in their handoff, not execute.