Multi-Review

A portable, multi-agent code review orchestrator. Reviews changed code in diffs/PRs or full file contents by path. Carries no domain knowledge — relies on the project's AGENTS.md and CLAUDE.md for rules.

Step 1: Determine the Review Mode

STOP. Do NOT run git diff, gh pr diff, gh pr view, git log, or ANY command until you complete this section.

Parse the user's argument to determine whether this is a diff review or a path review:

Path review — if the argument is a file path or glob pattern that does not match a diff pattern (see below). Indicators: ends in a file extension, matches existing files/directories, or is a glob with *.

Precedence rule: Check diff patterns first. If the argument starts with #, is a URL (starts with http), or resolves as a git ref (git rev-parse --verify <arg> succeeds), treat it as a diff review — even if it contains /. Only treat as a path review if none of those match.

For path reviews, read the full contents of the file(s) — this is NOT a diff review. The scope rule changes: review the entire file for quality, not just "changed lines." Skip PR Comment Check agent entirely for path reviews.

Diff review — all other arguments:

Extra instructions with -: Anything after a - is a focus area. Apply it as additional emphasis on top of the standard review.

Auto-detect sequence (no argument):

1. Check for an open PR — Run gh pr view --json number,baseRefName -q '.baseRefName' (using remote resolution below). If this succeeds, use git diff <baseRefName>...HEAD.
2. Fall back to primary branch — Run git rev-parse --verify main. If main exists, use git diff main...HEAD. If main does not exist, try git rev-parse --verify master; if that exists, use git diff master...HEAD. If neither exists, stop and ask the user which branch to diff against.

Remote resolution: Check if an upstream remote exists (git remote get-url upstream); if it does, use -R <upstream-url>. Otherwise use origin.

Run the diff command. Also capture the PR description if reviewing a PR (gh pr view <number> --json body).

If the diff is empty, stop and report — no changes to review.

If the diff exceeds ~3000 lines, warn the user and suggest narrowing scope.

Step 1.5: Gather Context for Agents

Before dispatching agents, gather context they'll need:

1. Extract file paths under review:
   • For diff reviews: parse diff --git a/... b/... headers from the diff
   • For path reviews: use the file paths provided by the user

2. Find all AGENTS.md and CLAUDE.md files in the directory hierarchy of each file under review. For a file at driver-kotlin-sync/src/main/kotlin/Foo.kt, collect:

   • ./AGENTS.md, ./CLAUDE.md (root)
   • ./driver-kotlin-sync/AGENTS.md, ./driver-kotlin-sync/CLAUDE.md (module)
   • Any deeper AGENTS.md/CLAUDE.md files along the path

   Use: find . \( -name "AGENTS.md" -o -name "CLAUDE.md" \) | sort then filter to paths that are ancestors of files under review.

3. Read all found AGENTS.md/CLAUDE.md files and concatenate their contents into a single context block (label each with its path).
4. Follow references — if any AGENTS.md points to reference docs (e.g., .agents/references/), read those too and include them.

This context block is passed to ALL agents below as **Project Context:**.

For path reviews: also read the full contents of all files under review and include them as **File Contents:** (labelled by path) instead of **Diff:**.

Step 2: Dispatch Parallel Review Agents

Run agents in parallel (single message with multiple Agent calls). Use this decision table to determine which agents to dispatch:

If an agent fails or times out, proceed with findings from successful agents and note the gap in the summary.

Every agent receives:

• The full diff text OR file contents (depending on review mode)
• PR description (if available, diff reviews only)
• User's focus area (the - focus suffix)
• The project context block (all AGENTS.md/CLAUDE.md content gathered in Step 1.5)
• The severity labels and scope rule (defined at bottom of this skill)

Scope rule adaptation for path reviews: Replace the diff-focused scope rule with:

Review the entire file contents for quality, correctness, and adherence to project standards. All code is in scope.

Domain Agent

Dispatch one Agent with these instructions:

You are a domain-specific code reviewer. Your job is to review the diff using this project's own coding standards and guidelines.

Steps:

1. Read the Project Context below carefully — it contains all AGENTS.md, CLAUDE.md, and reference documents relevant to the changed files
2. If any referenced documents were not included (e.g., a module AGENTS.md references a file not shown), use the Read tool to fetch them
3. Apply ALL rules from these documents to review the code
4. Apply the Scope Rule below (differs for diff vs path reviews)
5. Report findings using the severity labels and output format provided

Project Context: (include the full context block from Step 1.5)

Diff: (include full diff text)

PR Description: (if available)

Focus area: (if provided by user)

Scope Rule (for diff reviews):

• In scope: Changed lines, new files, deleted code, pre-existing code made worse by the change
• Out of scope: Style in unchanged lines, pre-existing tech debt, unrelated code

Scope Rule (for path reviews):

• Review the entire file contents for quality, correctness, and adherence to project standards. All code is in scope.

(Include only the applicable scope rule based on the review mode.)

Severity Labels (use these exact Unicode emoji, never shortcodes like :bulb:):

• 🔴 [blocking] — Must fix before merge
• 🟡 [important] — Should fix, discuss if disagree
• 🟢 [nit] — Nice to have, not blocking
• 💡 [suggestion] — Alternative approach to consider
• 📚 [learning] — Educational comment, no action needed
• 🎉 [praise] — Good work, keep it up!

Output format: Group findings by file path. For each finding, prefix the severity with its Unicode emoji (e.g., - 🔴 [blocking] **L42:** ...). Include line numbers, one-line summary, and detail/suggested fix.

Structured Review Agent

Dispatch one Agent with these instructions:

You are performing a structured code review focused on architecture, design patterns, and correctness. Review the code for:

1. Correctness — Logic errors, off-by-one, null safety, race conditions
2. Architecture — Does the change fit the existing patterns? Does it introduce unnecessary coupling or break separation of concerns?
3. API design — Are public interfaces clear, consistent, and hard to misuse?
4. Error handling — Are failure modes handled? Are errors informative?
5. Testing — Are changes adequately tested? Are edge cases covered?
6. Security — Input validation, injection risks, credential exposure

Project Context: (include the full context block from Step 1.5 — the agent needs project rules to assess whether changes fit existing patterns and architecture)

Diff: / File Contents: (include full diff text or file contents)

PR Description: (if available)

Focus area: (if provided by user)

Scope Rule (for diff reviews):

• In scope: Changed lines, new files, deleted code, pre-existing code made worse by the change
• Out of scope: Style in unchanged lines, pre-existing tech debt, unrelated code

Scope Rule (for path reviews):

• Review the entire file contents for quality, correctness, and adherence to project standards. All code is in scope.

(Include only the applicable scope rule based on the review mode.)

Severity Labels (use these exact Unicode emoji, never shortcodes like :bulb:):

• 🔴 [blocking] — Must fix before merge
• 🟡 [important] — Should fix, discuss if disagree
• 🟢 [nit] — Nice to have, not blocking
• 💡 [suggestion] — Alternative approach to consider
• 📚 [learning] — Educational comment, no action needed
• 🎉 [praise] — Good work, keep it up!

Output format: Group findings by file path. For each finding, prefix the severity with its Unicode emoji (e.g., - 🔴 [blocking] **L42:** ...). Include line numbers, one-line summary, and detail/suggested fix. End with a 2-3 sentence summary and a decision: Approve | Comment | Request Changes.

/code-review Agent

Dispatch one Agent and instruct it to invoke the /code-review skill. The agent's prompt must include:

You are performing a code quality review. Invoke the /code-review skill to guide your review process.

Project Context: (include the full context block from Step 1.5 — the agent needs this to check whether code follows or deviates from existing project patterns)

Diff: / File Contents: (include full diff text or file contents)

PR Description: (if available)

Focus area: (if provided by user)

Scope Rule (for diff reviews):

• In scope: Changed lines, new files, deleted code, pre-existing code made worse by the change
• Out of scope: Style in unchanged lines, pre-existing tech debt, unrelated code

Scope Rule (for path reviews):

• Review the entire file contents for quality, correctness, and adherence to project standards. All code is in scope.

(Include only the applicable scope rule based on the review mode.)

Severity Labels (use these exact Unicode emoji, never shortcodes like :bulb:):

• 🔴 [blocking] — Must fix before merge
• 🟡 [important] — Should fix, discuss if disagree
• 🟢 [nit] — Nice to have, not blocking
• 💡 [suggestion] — Alternative approach to consider
• 📚 [learning] — Educational comment, no action needed
• 🎉 [praise] — Good work, keep it up!

Output format: Group findings by file path. For each finding, prefix the severity with its Unicode emoji (e.g., - 🔴 [blocking] **L42:** ...). Include line numbers, one-line summary, and detail/suggested fix. End with a 2-3 sentence summary and a decision: Approve | Comment | Request Changes.

PR Comment Check Agent (PR reviews only)

Only spawn this agent when reviewing a PR that has existing review comments. Before spawning, extract owner/repo from the remote URL (gh repo view -R <remote> --json nameWithOwner -q '.nameWithOwner'), then check: gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments | jq length. If the count is 0, skip this agent. Skip entirely for branch diffs and path reviews.

Dispatch one Agent with these instructions:

You are checking whether prior PR review comments have been addressed.

Steps:

1. Fetch PR comments:
   • gh pr view <PR_NUMBER> --json comments,reviews -R <remote>
   • gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments
2. Dismiss outdated comments (resolved conversations, references to deleted code, purely conversational messages like "thanks" or "LGTM").
3. For each remaining comment, check the current diff:
   • Addressed — code satisfies the concern
   • Partially addressed — some aspects handled, not all
   • Unaddressed — concern remains in current code
   • Disputed — code intentionally takes a different approach
4. Format output:
   • Addressed comments: list briefly as resolved (use [praise])
   • Partially addressed / Unaddressed: use [blocking] or [important] based on the original comment's urgency
   • Disputed: use [suggestion] with context for the reviewer

Group findings by file. Use the severity labels provided.

PR Number: <PR_NUMBER> Remote: <remote> Diff: (include full diff text)

Step 3: Synthesize

After all agents complete, produce one consolidated review.

Important: Always use literal Unicode emoji characters (🔴 🟡 🟢 💡 📚 🎉 ✅ ⚠️), never GitHub/Slack-style shortcodes like :red_circle: or :bulb:. Shortcodes do not render in the terminal.

1. Deduplicate — If multiple agents flagged the same issue, keep the better-written version and note agreement
2. Resolve conflicts — If agents disagree on severity, higher severity wins
3. Incorporate PR comments (PR reviews only) — Add a "Prior Review Comments" section after per-file findings. Addressed comments listed briefly as resolved. Unaddressed/partially addressed comments included at their assigned severity. If an unaddressed comment overlaps with another finding, merge them.
4. Organize by file — Group all findings by file path, then severity within each file
5. Include praise — Merge positive findings from all agents
6. Present as a single voice — Do NOT attribute findings to specific agents

Output Template

Use this exact format with literal Unicode emoji (not shortcodes):

Findings

path/to/File.java

• 🔴 [blocking] L42-48: One-line summary Detail: explanation and suggested fix
• 🟡 [important] L15: One-line summary Detail: explanation

path/to/Other.kt

• 🟢 [nit] L7: One-line summary

Prior Review Comments (PR reviews only)

• ✅ Addressed: brief list
• ⚠️ Unaddressed: with severity and detail

Summary

2-3 sentence overview of the change quality and key concerns.

Decision: Approve | Comment | Request Changes

Severity Labels

• 🔴 [blocking] — Must fix before merge
• 🟡 [important] — Should fix, discuss if disagree
• 🟢 [nit] — Nice to have, not blocking
• 💡 [suggestion] — Alternative approach to consider
• 📚 [learning] — Educational comment, no action needed
• 🎉 [praise] — Good work, keep it up!