Dynamic Code Review Orchestrator

Relies on BDK foundation (STARTUP_INSTRUCTIONS.md) for project context and MCP tool preference.

Code review orchestrator. Determine change scope, dispatch specialized agents parallel, collect results, merge into unified report.

Terminal Output

On Start:

┌─────────────────────────────────────────────────┐
│  👁️  ORCHESTRATOR: code-review                   │
│  📋 Task: {brief description}                   │
│  ⚡ Model: sonnet                                │
└─────────────────────────────────────────────────┘

During Execution:

[cr] Step 1: Determining scope...
[cr] Scope: {N} files changed, {N} lines total → {tiny|small|large|massive}
[cr] Step 2: Dispatching {N} agents...
[cr]   - {N}× layer-group reviewers (sonnet)
[cr]   - 1× architecture reviewer (opus)
[cr]   - 1× test reviewer (opus)
[cr]   - {N}× duplicate detectors (haiku)
[cr]   - 1× dead code detector (haiku)
[cr]   - 1× static analyse (haiku)
[cr]   - 1× test runner (haiku)
[cr] Step 3: Waiting for agents...
[cr] Step 4: Merging results...
[cr] ✓ Complete ({N} findings: {critical}C/{high}H/{medium}M/{low}L)

Safety Rules (MANDATORY)

• MUST NOT modify files. No Edit, Write, NotebookEdit tools.
• All sub-agents read-only.

Process

Step 1: Determine Scope

!python3 ${CLAUDE_PLUGIN_ROOT}/scripts/inject.py --chain ${CLAUDE_PLUGIN_ROOT}/fragments/tool-tiers/review.chain.json

1. Get risk-scored changed file list with severity ratings
2. Identify which changed files are architectural choke points (flag these for architecture-reviewer)
3. Identify which execution paths are impacted (pass to test-reviewer as scope context)
4. Fallback if graph unavailable: git diff --name-only HEAD~1 + git diff --stat HEAD~1
5. Classify changed files by directory/module (based on project structure)
6. For each source file, find corresponding test file per project conventions

Step 2: Plan Dispatch

Based on total changed lines:

Tiny (< 50 lines):

• 1× layer-group reviewer (sonnet) — reviews ALL code, checks architecture, duplicates, dead code inline
• 1× test-reviewer (opus)
• 1× static-analyse (haiku)
• 1× test-runner (haiku)
• Total: 4 agents

Small (50–1000 lines):

• 1× layer-group reviewer (sonnet) — all changed files + tests
• 1× architecture-reviewer (opus)
• 1× test-reviewer (opus)
• 1× duplicate-detector (haiku)
• 1× dead-code-detector (haiku)
• 1× static-analyse (haiku)
• 1× test-runner (haiku)
• Total: 7 agents

Large (1000–3000 lines):

• N× layer-group reviewers (sonnet), N = ceil(total_lines / 1000), capped at 5
• 1× architecture-reviewer (opus)
• 1× test-reviewer (opus)
• N× duplicate-detectors (haiku)
• 1× dead-code-detector (haiku)
• 1× static-analyse (haiku)
• 1× test-runner (haiku)
• Total: 2N + 5 agents

Massive (3000+ lines): Same as Large, N capped at 5.

Step 2.5: Resolve Quality Rule Placeholders

Before dispatching agents, read references/reviewer-prompt-template.md. For each <!-- INJECT: <name> --> marker, run:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/inject-rules.py <name>

Substitute the script's stdout in place of the marker. If exit is non-zero, surface the stderr message and stop dispatch — quality rules are mandatory context for reviewers.

The resolved template is what each layer-group reviewer, architecture-reviewer, and test-reviewer receives in their prompt.

Step 3: Dispatch ALL Agents in Parallel

Launch ALL planned agents in SINGLE message using Agent tool with run_in_background: true.

When a reviewer's report needs clarification on a specific finding, prefer SendMessage(to: "<agentId>", ...) over re-spawning — the reviewer keeps its scan context. See STARTUP "Continuing a Spawned Agent".

For each layer-group reviewer (use references/reviewer-prompt-template.md for dispatch structure):

• List source files assigned to group
• List test files paired with source files

For architecture-reviewer:

• List ALL changed source files
• Pass detect_changes output and get_bridge_nodes_tool results as initial context

For test-reviewer:

• List ALL test files AND corresponding source files
• Pass get_affected_flows results as scope context

For each duplicate-detector:

• List symbols in its partition

For dead-code-detector:

• List ALL changed files

For static-analyse:

• Run project's static analysis command (read project context to determine it)

For test-runner:

• Pass relevant test file paths based on changed source files

Step 4: Collect & Merge Results

1. Collect all agent outputs
2. Deduplicate: keep more detailed finding when duplicates appear
3. Assign severity: CRITICAL > HIGH > MEDIUM > LOW
4. Map findings to report sections
5. Produce final 13-section report (see below)
6. Write report to artifact: .bdk/cr/[TDP - dynamic path here] — see IDEAS.md for dynamic path pattern

Report Format

See references/report-format.md for detailed 13-section structure and templates.

1. Summary

≤ 5 sentences: overall assessment, severity distribution, key wins/gaps.

2. Style & Conventions

Naming, formatting, import organization, code consistency.

3. Functionality & Logic

Correctness, error handling, edge cases, logic errors.

4. Performance

Algorithm choices, unnecessary iterations, hot path issues.

5. Tests

Test existence, coverage, edge cases, isolation, assertion quality.

6. Type Hints & SOLID

Type annotations, single responsibility, notable SOLID violations.

7. Object-Oriented Design

Classes, SRP, composition, DI, god classes, anemic models.

8. Duplicate Code & Pattern Extraction

Repeated blocks, structural patterns, extractable logic.

9. Dead Code Detection

Paste dead-code-detector output verbatim.

10. Security

SQL injection, unsafe deserialization, secrets in code.

11. Architecture

Layer boundaries, dependency injection, design patterns, data flow, directory structure.

12. Positive Observations

Good patterns worth reinforcing.

13. All Issues

All findings sorted by severity: CRITICAL → HIGH → MEDIUM → LOW.

Each issue: [SEVERITY] category → file:line → problem → 1-sentence fix.

Error Handling

• No changed files: Output "No changes to review" and stop
• Agent timeout: Include partial results, note timeout in Summary
• Agent failure: Report failure, continue with other agents' results

Rules

• Always print terminal output on start and complete