Multi-Review: Parallel Specialized Code Review

You are orchestrating a comprehensive code review using multiple specialized review agents in parallel.

Argument Parsing

Check if

--plan <path>

• Set

  $PLAN_MODE = true

  and

  $PLAN_PATH = <path>

• Verify the plan file exists. If not, error: "Plan file not found:

  <path>

  "
• In plan mode, you are reviewing an implementation plan (not code). The goal is to catch issues that would surface during code review if the plan is implemented as written.

Check if

--codex

$CODEX_ENABLED = true

--codex-adversarial

$CODEX_ENABLED = true

$CODEX_ADVERSARIAL = true

If

--plan

$PLAN_MODE = false

Workflow

Step 1: Identify Changes

If

$PLAN_MODE

$PLAN_PATH

Otherwise (code mode):

Determine what code to review:

# If in a PR/branch context
git diff main...HEAD --name-only

# Or for staged changes
git diff --cached --name-only

# Or recent changes
git diff HEAD~5 --name-only

List the changed files and their types (e.g.,

.py

.ts

.go

Step 1.5: Load Review Configuration

If

$PLAN_MODE

Check for a project-level review configuration:

# Prefer review.json, fall back to risk-tiers.json for backward compatibility
cat .claude/review.json 2>/dev/null || cat .claude/risk-tiers.json 2>/dev/null || echo "No review config found"

If found, parse the configuration:

• tiers

  : Maps risk levels (critical, high, medium, low) to file glob patterns

• reviewers

  (v2): Optional object with

  exclude

  and

  include

  arrays for reviewer control

Codex config: If the config contains a

codex

• "codex": { "enabled": true }

  → set

  $CODEX_ENABLED = true

  (unless already set by

  --codex

  flag)

• "codex": { "adversarial": true }

  → set

  $CODEX_ADVERSARIAL = true

  (unless already set by

  --codex-adversarial

  flag)
• CLI flags override config values.

Backward compatibility: If the config contains a v1

frameworks

frameworks

Risk tier resolution: For each changed file, match against tier patterns (most specific match wins). If a file matches multiple tiers, use the highest tier. If no match, default to

medium

Determine the overall PR risk tier = the highest tier among all changed files.

If no review config exists, fall back to the keyword-based behavior in Step 2.

Step 2: Analyze Change Types

If

$PLAN_MODE

Skip to Step 3 after scanning.

Otherwise (code mode):

Categorize the changes to select appropriate reviewers:

Step 2.5: Framework Auto-Detection

If

$PLAN_MODE

Map changed files to framework reviewers. A framework reviewer is activated when at least one changed file matches its patterns. No config required.

*.tsx

*.jsx

next.config.*

middleware.ts

nextjs

nextjs-reviewer

*.css

tailwind.*

components/ui/**

tailwind

tailwind-reviewer

*.py

alembic/**

python-backend

python-backend-reviewer

routes/**

api/**

endpoints/**

controllers/**

api

api-security-reviewer

**/tools/**

**/agents/**

**/prompts/**

**/skills/**

*.tool.*

agent-native

agent-native-reviewer

*.tsx

*.jsx

*.vue

*.svelte

components/**

pages/**

ux

ux-reviewer

*.tsx

*.jsx

*.css

next.config.*

package.json

frontend-perf

frontend-performance-reviewer

Reviewer overrides (v2 config):

• reviewers.exclude

  : Suppress auto-detected reviewers (e.g.,

  ["tailwind-reviewer"]

  to prevent false positives)

• reviewers.include

  : Force always-on reviewers regardless of changed files (e.g.,

  ["security-sentinel"]

  )

Backward compatibility: If a v1 config with a

frameworks

frameworks

Step 3: Select Reviewers

If

$PLAN_MODE

Always include:

• architecture-strategist

  — structural gaps, boundary violations

• pattern-recognition-specialist

  — anti-patterns in proposed approach

Conditionally include based on keyword scan from Step 2. Select 3-7 reviewers total. Skip to Step 4.

Otherwise (code mode):

Always include:

• code-simplicity-reviewer

  (YAGNI, complexity)

• pattern-recognition-specialist

  (anti-patterns, conventions)

Conditionally include (keyword-based):

• security-sentinel

  — if auth, input handling, secrets, or user data

• performance-oracle

  — if database queries, loops, caching, or data operations

• architecture-strategist

  — if structural changes, new modules, or interface changes

• agent-native-reviewer

  — if agent definitions, skill files, system prompts, tool configurations, new UI actions/views, API endpoints, forms, routes, new entity models/schemas, or context injection code (any change that adds user-facing capabilities, new data entities, or modifies agent context)

• data-integrity-guardian

  — if database migrations, schema changes, or data model modifications

• data-migration-expert

  — if data backfills, ID mappings, enum conversions, or column renames

Tier-based reviewer selection (when review config exists):

Use the overall PR risk tier from Step 1.5 to adjust reviewer selection:

security-sentinel

performance-oracle

code-simplicity-reviewer

pattern-recognition-specialist

code-simplicity-reviewer

Always include

code-simplicity-reviewer

pattern-recognition-specialist

Select 3-7 reviewers based on the change types identified.

Step 3b: Conditional Migration Reviewers

If

$PLAN_MODE

data-integrity-guardian

Run migration-specific agents when the PR matches ANY of these criteria:

• Files matching

  db/migrate/*

  ,

  migrations/*

  , or

  alembic/versions/*

• Modifications to columns that store IDs, enums, or mappings
• Data backfill scripts or management commands
• Changes to how data is read/written (e.g., FK to string column)
• PR title/body mentions: migration, backfill, data transformation, ID mapping

What these agents check:

• data-integrity-guardian

  : Transaction boundaries, reversibility, constraint safety, ACID compliance, regulatory considerations (GDPR/CCPA)

• data-migration-expert

  : Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns, provides SQL verification queries

Step 3c: Codex Prerequisites Check

If

$CODEX_ENABLED

$PLAN_MODE

Verify the codex CLI is available:

which codex && codex --version

If the command fails:

• Log: "Codex CLI not found — skipping codex review. Install:

  npm install -g @openai/codex

  "
• Set

  $CODEX_ENABLED = false

• Continue with remaining reviewers

If

$PLAN_MODE

$CODEX_ENABLED = false

codex review

Step 4: Read Agent Definitions

For each selected reviewer, read the agent definition:

cat ~/.claude/agents/review/<agent-name>.md

Step 4.5: SAST Artifact Consumption (Hybrid Verification)

If

$PLAN_MODE

Before launching reviewers, check if CI/CD SAST results are available:

# Check for SARIF artifacts from the security-checks workflow
gh run download --name semgrep-sarif --dir /tmp/sarif 2>/dev/null

If SARIF results are found, parse them and include in the

security-sentinel

"The following SAST findings were reported by Semgrep. For each finding, verify it in context: confirm as a real vulnerability, dismiss as a false positive with explanation, or escalate with additional context that amplifies the severity. Do not simply repeat SAST output — add the reasoning that automated tools cannot."

Append the SARIF finding summaries (file, rule ID, message) to the security-sentinel agent's prompt. This creates the hybrid approach: deterministic tools catch patterns, the AI agent reasons about whether they are real vulnerabilities in this specific codebase.

If no SARIF artifacts exist (CI hasn't run, or the project doesn't use the security-checks workflow), skip this step silently.

Step 5: Launch Parallel Reviews

If

$PLAN_MODE

Use the Task tool to spawn parallel review agents.

Model selection: Default to Sonnet for efficiency. When review config exists and the PR risk tier is critical, use Opus for

security-sentinel

architecture-strategist

Launch these agents in parallel:

1. Task: code-simplicity-reviewer
   - Subagent type: general-purpose
   - Model: sonnet
   - Prompt: [agent definition] + [files to review]

2. Task: pattern-recognition-specialist
   - Subagent type: general-purpose
   - Model: sonnet
   - Prompt: [agent definition] + [files to review]

3. Task: security-sentinel (if critical tier)
   - Subagent type: general-purpose
   - Model: opus (critical tier) or sonnet (other tiers)
   - Prompt: [agent definition] + [files to review]

4. Task: [additional selected reviewer]
   ...

Codex reviewer (if

$CODEX_ENABLED

Launch an additional Agent in parallel with the Claude reviewers above:

N+1. Agent: codex-reviewer
   - Subagent type: general-purpose
   - Model: sonnet
   - Prompt:
     You are a review output normalizer. Your job:
     1. Run codex to perform a code review via Bash (timeout: 300000ms):
        codex review --base <base-branch> "<review prompt>"
        (use --uncommitted if reviewing staged/unstaged changes with no branch comparison)
     2. Capture the stdout output.
     3. Parse each finding and normalize into this exact format:

        ## Codex Reviewer Findings

        ### Critical Issues
        - [file:line] [CODEX] Issue description - Confidence: X%

        ### Important Issues
        - [file:line] [CODEX] Issue description - Confidence: X%

        ### Suggestions
        - [file:line] [CODEX] Issue description - Confidence: X%

     4. Map codex severity to the standard format:
        - Critical/Blocker/Bug/Security → Critical Issues
        - Warning/Should-fix/Improvement → Important Issues
        - Suggestion/Nit/Style/Nice-to-have → Suggestions
     5. If codex does not provide confidence percentages, assign:
        Critical: 90%, Important: 80%, Suggestions: 70%
     6. If codex does not provide file:line references, use file path only.
     7. Return ONLY the normalized findings.

If

$CODEX_ADVERSARIAL

"Perform an adversarial review. Challenge design decisions, surface hidden assumptions, question tradeoffs, and pressure-test the approach. Don't just find bugs — challenge whether this is the right solution."

Otherwise use a standard review prompt:

"Review for security vulnerabilities, correctness bugs, performance issues, and code quality. Format findings by severity."

Each agent should return findings in this format:

## [Agent Name] Findings

### Critical Issues
- [Issue with file:line] - Confidence: X%

### Important Issues
- [Issue with file:line] - Confidence: X%

### Suggestions
- [Issue with file:line] - Confidence: X%

Step 5.5: Checklist Augmentation

When constructing prompts for review agents in Step 5, append the following checklist categories as additional review guidance. These supplement each agent's core focus area.

For all agents — check these universal categories:

LLM-specific (high priority if PR touches prompts, tools, or AI integrations):

• 0-indexed lists in prompts (LLMs reliably return 1-indexed)
• Prompt text listing available tools/capabilities that don't match what's actually wired up
• LLM trust boundary: hallucinated values (emails, URLs, names) persisted without format validation
• Structured tool output accepted without type/shape checks before DB writes
• Word/token limits stated in multiple places that could drift

Race conditions (include for security-sentinel and performance-oracle):

• TOCTOU: check-then-set without atomic operation
• find-or-create without unique constraint (concurrent duplicates)
• Non-atomic status transitions (concurrent updates skip/double-apply)

Niche categories (include for pattern-recognition-specialist):

• Conditional side effects: branch that forgets a side effect on one path
• Type coercion at language boundaries (cross-language type changes, hash input normalization)
• Time window safety: mismatched windows between related features
• Crypto entropy: truncation vs hashing, rand() for security values, non-constant-time comparisons

Step 6: Aggregate Findings

Combine results from all reviewers, sorted by severity:

## Multi-Review Summary

### Reviewers
- [x] reviewer-name
- [x] codex-reviewer (if enabled)
...

### CRITICAL Findings (blocking — require action)
Security, data safety, race conditions, correctness bugs.
| File:Line | Issue | Reviewer | Confidence | Gate |
|-----------|-------|----------|------------|------|
| ... | ... | ... | ...% | CRITICAL |

### IMPORTANT Findings (should fix — non-blocking but significant)
Performance issues, error handling gaps, non-trivial anti-patterns, meaningful code quality issues.
| File:Line | Issue | Reviewer | Confidence | Gate |
|-----------|-------|----------|------------|------|
| ... | ... | ... | ...% | IMPORTANT |

### INFORMATIONAL Findings (surface, don't block)
Style, suggestions, minor improvements, nice-to-haves.
| File:Line | Issue | Reviewer | Confidence | Gate |
|-----------|-------|----------|------------|------|
| ... | ... | ... | ...% | INFO |

Gate classification rules:

• CRITICAL: Security vulnerabilities, data loss risks, race conditions, correctness bugs, missing error handling on critical paths, broken functionality
• IMPORTANT: Performance issues, error handling gaps on non-critical paths, non-trivial anti-patterns, meaningful code quality issues
• INFORMATIONAL: Code style, naming, minor refactoring opportunities, test coverage suggestions, documentation gaps, performance micro-optimizations

Note: Reviewer agents already output in

Critical Issues / Important Issues / Suggestions

Resolution Ledger: Every finding that enters aggregation (post-suppression) must end the review in one of:

fixed[]

dropped[]

deferred[]

Step 6.5: Suppressions

When aggregating findings in Step 6, suppress (do not surface) these categories of findings:

• "X is redundant with Y" when the redundancy is harmless and aids readability
• "Add a comment explaining why this threshold/constant was chosen" — thresholds change during tuning, comments rot
• "This assertion could be tighter" when the assertion already covers the behavior
• Consistency-only changes (wrapping a value to match how another is guarded)
• "Regex doesn't handle edge case X" when the input is constrained and X never occurs in practice
• Anything already addressed in the diff being reviewed — agents must read the FULL diff before commenting

These suppressions reduce noise from low-value suggestions that waste review cycles.

Step 7: Filter Results

Only surface findings with confidence >= 80%. Findings below 80% confidence are entered into the resolution ledger as

dropped[reason: "below confidence threshold (N%)"]

Security exception: All

security-sentinel

api-security-reviewer

[SEC]

Step 8: Resolve Findings

If

$PLAN_MODE

$PLAN_PATH

Verification discipline (from

/verify

): Before proposing any fix, read the actual code at the file:line the reviewer flagged. Reviewers hallucinate. Confirm the issue exists, then fix. If it doesn't exist, drop it — don't implement phantom fixes.

This step resolves ALL findings through a 5-phase process. No finding may remain unresolved.

Phase 1: Verify and Classify (agent acts alone)

For each CRITICAL and IMPORTANT finding, before presenting anything:

1. Read actual code at file:line (verification discipline — keeps this)
2. False positive or speculative →

   dropped[]

   with reason
3. Clear fix exists →

   auto-fixable

   (agent will apply)
4. Genuinely requires human decision →

   deferred

Strict defer criteria:

The bar for

deferred

is HIGH. These are NOT valid reasons to defer:

• "This is complex" — complexity isn't a reason to punt
• "This might have side effects" — verify whether it does, then fix or drop
• "This could be done multiple ways" — pick the approach matching existing codebase patterns
• "I'm not sure about the intent" — read surrounding code and git blame
• "This is a style/taste issue" — match existing patterns, or drop

These ARE valid reasons to defer:

• Fix requires choosing between two valid architectural approaches with real tradeoffs
• Fix involves a product/business decision (e.g., "should this error be user-visible or silent?")
• Fix requires production knowledge the agent cannot verify (e.g., "is this table too large for this migration?")

Phase 2: Auto-fix with preview (agent acts, does NOT ask permission)

Present the resolution plan, then apply fixes:

## Resolution Plan

### Auto-fixing (N findings):
1. [file:line] - [issue] - [fix description]
2. ...

### Dropped (M findings):
3. [file:line] - [issue] - DROPPED: [reason]
4. ...

### Deferred — requires your decision (P findings):
5. [file:line] - [issue] - DEFERRED: [specific decision needed]
6. ...

Applying auto-fixes...

The agent applies all auto-fixable changes to the working tree without asking. It does NOT commit — that's the caller's job (finish-task commits, or the user commits manually). The user can review the diff afterward.

Phase 3: Mandatory adjudication of deferred items

After auto-fixes are applied, present ALL deferred findings in a SINGLE

AskUserQuestion

## N Deferred Findings Require Your Decision

1. **[file:line]** - [issue] — [reviewer]
   Decision needed: [specific question, e.g., "extract to service vs inline guard?"]
   Options: (a) approach A, (b) approach B, (c) dismiss, (d) create task

2. **[file:line]** - [issue] — [reviewer]
   Decision needed: [specific question]
   Options: (a) approach A, (b) approach B, (c) dismiss, (d) create task

Reply with your choices (e.g., "1a, 2c"):

Each response moves the finding to

fixed[]

dropped[]

deferred[task: <id>]

Autonomous context (when multi-review runs inside

/finish-task

AskUserQuestion

Phase 4: INFORMATIONAL batch resolution

Present INFORMATIONAL findings as a batch:

## Informational Findings (N items)

1. [file:line] - [issue]
2. [file:line] - [issue]
...

Options:
1. Fix all informational items
2. Fix specific items (provide numbers)
3. Acknowledge all (mark as reviewed, no action)

User must pick one. "Acknowledge all" is fine — the point is explicit accounting, not forced action. All items move to

fixed[]

dropped[acknowledged]

Autonomous context: auto-fix INFORMATIONAL items that have clear fixes, drop the rest as

dropped[informational — auto-acknowledged]

Phase 5: Re-review cycles (refined)

After fixes are applied, re-review modified files with escalating thresholds:

• Previous-cycle ledger entries are DONE — never re-evaluated
• Escalating thresholds apply only to NET-NEW findings from re-review of modified files:
  • Cycle 2: Re-run only affected reviewers on fix-modified files. Net-new findings >= 85% confidence only.
  • Cycle 3: Only Critical findings >= 90% confidence on fix-modified files.
• New findings from Cycle 2/3 enter the ledger and go through the same Verify → Classify → Fix → Adjudicate flow
• The ledger accumulates across cycles

Exit conditions (stop the loop when ANY is met):

• Clean: Zero findings this iteration → EXIT
• Diminishing returns: <3 net-new findings AND zero Critical → EXIT
• Plateau: Net-new count >= previous iteration (not converging) → EXIT
• Limit: 3 iterations → EXIT

Log exit reason so the final report explains why the loop stopped.

Final Report

After all phases complete, output the resolution ledger summary:

═══════════════════════════════════════════
MULTI-REVIEW COMPLETE
═══════════════════════════════════════════
Reviewers: [list]
Cycles: N (exit reason: [reason])
Findings: X | Fixed: Y | Dropped: Z | Deferred: W

FIXED:
- [file:line] issue — fix applied

DROPPED:
- [file:line] issue — [reason]

DEFERRED (tasks created):
- [file:line] issue — task <id>

INFORMATIONAL (acknowledged):
- [file:line] issue
═══════════════════════════════════════════

Step 9: Browser Workflow Testing

If

$PLAN_MODE

When the PR includes frontend/UI changes, run workflow-based browser testing.

Detect frontend changes by checking for files matching:

• *.tsx

  ,

  *.jsx

  ,

  *.vue

  ,

  *.svelte

  ,

  *.html

• *.css

  ,

  *.scss

  ,

  *.less

• templates/**

  ,

  views/**

  ,

  components/**

  ,

  pages/**

If no frontend changes detected, skip this step.

Read

docs/browser-testing-protocol.md

1. Pre-flight checks — verify Playwright MCP available, dev server running (Phase 1)
2. Infer workflows from diff — classify changed files, propose to user via

   AskUserQuestion

   for confirmation (Phase 2)
3. Navigate → clear cache/storage → reload — ensures fresh state, not stale cache (Phase 3)
4. Handle auth if page redirects to login (Phase 4)
5. Execute workflow-type checklists — interact, verify outcomes, verify persistence via reload (Phase 5)
6. Responsive check at desktop (1280x800) + mobile (375x812) and report findings (Phase 6)

Multi-review specific: Browser findings enter the same aggregation pipeline as code review findings (Step 6). Classify as Critical/Important/Minor per the protocol's Phase 6 severity table.

Agent Reference

Always Included

code-simplicity-reviewer

Focus: YAGNI, complexity reduction, unnecessary code Path:

agents/review/code-simplicity-reviewer.md

pattern-recognition-specialist

Focus: Anti-patterns, code conventions, consistency Path:

agents/review/pattern-recognition-specialist.md

Conditionally Included

security-sentinel

Focus: CWE-enriched OWASP review, business logic vulnerabilities (IDOR, auth bypass), absence detection, self-verification loop Include when: Auth code, user input, API endpoints, secrets handling, new routes/handlers Path:

agents/review/security-sentinel.md

performance-oracle

Focus: N+1 queries, memory leaks, caching, async patterns Include when: Database operations, loops over data, caching changes Path:

agents/review/performance-oracle.md

architecture-strategist

Focus: SOLID principles, design patterns, module structure Include when: New files, interface changes, structural refactoring Path:

agents/review/architecture-strategist.md

agent-native-reviewer

Focus: Action/context parity, tool design, agent capability gaps Include when: Agent definitions, skill files, system prompts, MCP configs, new UI actions/views, API endpoints, forms, routes — any change that adds user-facing capabilities Path:

agents/review/agent-native-reviewer.md

data-integrity-guardian

Focus: Migration safety, ACID compliance, transaction boundaries, GDPR/CCPA Include when: Database migrations, schema changes, data model modifications Path:

agents/review/data-integrity-guardian.md

data-migration-expert

Focus: Mapping validation, rollback safety, production data verification Include when: Data backfills, ID mappings, enum conversions, column renames Path:

agents/review/data-migration-expert.md

Framework-Specific Reviewers (Auto-detected from changed files)

nextjs-reviewer

Focus: App Router conventions, Server vs Client Components, Server Actions security, metadata, routing Auto-detected when: Changed files match

*.tsx

*.jsx

next.config.*

middleware.ts

agents/review/nextjs-reviewer.md

tailwind-reviewer

Focus: Tailwind/shadcn patterns, accessibility, responsive design, dark mode, WCAG 2.1 AA Auto-detected when: Changed files match

*.css

tailwind.*

components/ui/**

agents/review/tailwind-reviewer.md

python-backend-reviewer

Focus: FastAPI, SQLAlchemy 2.0, Alembic, async Python, Pydantic v2, pytest Auto-detected when: Changed files match

*.py

alembic/**

agents/review/python-backend-reviewer.md

api-security-reviewer

Focus: Rate limiting, pagination bounds, response data filtering, CORS, request size limits, security logging Auto-detected when: Changed files match

routes/**

api/**

endpoints/**

controllers/**

agents/review/api-security-reviewer.md

ux-reviewer

Focus: Interaction flows, state completeness, form UX patterns, component API consistency, screen reader narrative, cognitive load Auto-detected when: Changed files match

*.tsx

*.jsx

*.vue

*.svelte

components/**

pages/**

agents/review/ux-reviewer.md

frontend-performance-reviewer

Focus: Core Web Vitals (LCP, CLS, INP), bundle size, request waterfalls, rendering efficiency, image optimization Auto-detected when: Changed files match

*.tsx

*.jsx

*.css

next.config.*

package.json

agents/review/frontend-performance-reviewer.md

External Reviewers (Optional, CLI-based)

codex-reviewer

Focus: Second-opinion code review via OpenAI Codex CLI. Provides a review from a different AI model. Requires:

codex

npm install -g @openai/codex

codex login

--codex

"codex": { "enabled": true }

--codex-adversarial

"codex": { "adversarial": true }

Important Notes

• Parallel execution is key — don't run reviewers sequentially
• Filter to >= 80% confidence to reduce noise
• Security findings should always be surfaced even at lower confidence
• Maximum 3 review cycles for auto-fix iterations
• Migration reviewers should always run together (integrity + migration expert)
• Browser testing uses workflow-based verification (not just screenshots) and requires user consent
• Framework reviewers auto-detect from changed files. Use

  reviewers.exclude

  in

  review.json

  to suppress false positives.