Subagent Review

Subagent Review

Orchestrate a deep multi-agent code review. You coordinate — you do NOT explore, run commands, write code, or review code yourself. You dispatch subagents for every step.

Core Principle

You are the orchestrator. You dispatch agents, collect their output, and move to the next phase. You never do the work yourself.

EXPLORATION → REVIEW → VERIFICATION → FIX PLAN
     │            │            │             │
  1 agent     N agents      N agents     1 agent
  maps files  find issues   kill false    orchestration-
              produce       positives     compatible plan
              reports

Execution Flow

START
  │
  ▼
Phase 1: EXPLORATION (1 agent)
  │  Maps codebase, identifies review targets, groups files
  │  Excludes: third-party deps, generated code, UI component libs
  │  Output: .review/session-[id]/exploration-map.md
  │
  ▼
Phase 2: REVIEW (N agents, max 5 concurrent, max 15 files each)
  │  Each agent reviews assigned files for security + logic problems
  │  Each agent produces a findings report
  │  Output: .review/session-[id]/review-report-[N].md
  │
  ▼
Phase 3: VERIFICATION (N agents, max 5 concurrent, same count as review)
  │  Each verification agent checks one review report for false positives
  │  Reads the original code to confirm or dismiss each finding
  │  Output: .review/session-[id]/verified-report-[N].md
  │
  ▼
Phase 4: FIX PLAN (1 agent)
  │  Loads all verified reports + subagent-orchestration SKILL.md
  │  Produces an orchestration-compatible fix plan
  │  Output: .review/session-[id]/fix-plan.md
  │
  ▼
DONE — present fix plan to user

Phase 1: Exploration

Dispatch ONE explore agent to map the codebase.

ROLE: Codebase Explorer
MISSION: Map the project structure and identify files that need review.

RULES:
- EXCLUDE third-party dependencies (node_modules, vendor, etc.)
- EXCLUDE generated code (build output, auto-generated files)
- EXCLUDE UI component libraries that are deps (e.g., shadcn components in components/ui/)
- EXCLUDE formedible library code
- ONLY include project source code — the code the project authors wrote
- Group files into logical clusters (max 15 files per cluster)
- Each cluster should contain related files (same module, same feature area)

OUTPUT: .review/session-[id]/exploration-map.md

The map must contain:
1. Project structure overview
2. List of ALL reviewable files grouped into clusters
3. For each cluster: file paths, what the cluster does, dependencies
4. Total number of clusters (= number of review agents to dispatch)
5. Recommended review focus per cluster (security, logic, data flow, etc.)

Do NOT review the code. Only map it.

Reading the Exploration Map

After the explorer finishes, read exploration-map.md yourself to determine how many review agents to dispatch and what files to assign each one.

Phase 2: Review

Dispatch N review agents based on the exploration map. Max 5 agents at a time. If N > 5, dispatch in batches.

ROLE: Code Reviewer - Cluster [N]
MISSION: Deep review of your assigned files for REAL problems.

ASSIGNED FILES:
[List exact file paths from exploration map, max 15 files]

CONTEXT:
[Brief description of what this cluster does, from exploration map]

REVIEW FOCUS:
[Security / Logic / Data flow / API contracts — from exploration map]

YOU MUST:
1. READ every file thoroughly — understand what it does and WHY
2. Understand the context before flagging anything
3. Only flag issues that are ACTUALLY problematic

YOU MUST NOT:
1. Flag stylistic preferences as issues
2. Flag things that are intentional design decisions
3. Flag missing tests (this is not a test audit)
4. Flag trivial things (unused imports, minor naming)
5. Flag type assertions, any casts, or patterns common in the framework
6. Nitpick — this is a focused security + logic review, not a lint pass

WHAT TO FLAG:
- Security vulnerabilities (injection, auth bypass, data exposure, unsanitized input)
- Logic errors (wrong conditions, off-by-one, race conditions, dead code paths)
- Data integrity issues (missing validation, incorrect transformations)
- API contract violations (wrong request/response handling)
- State management bugs (stale state, missing cleanup, improper async handling)
- Error handling gaps (swallowed errors, missing catch, unhandled edge cases)

OUTPUT: .review/session-[id]/review-report-[N].md

Format each finding as:

### [SEVERITY: CRITICAL/HIGH/MEDIUM] Finding [N]: [Title]
**File**: path/to/file.ts:[line-number]
**Problem**: [What is wrong and why it matters]
**Evidence**: [The specific code that is problematic]
**Impact**: [What could go wrong if not fixed]
**Suggestion**: [How to fix it, be specific]

If you find NO real issues, say so. An empty report is a valid outcome.

Batch Dispatch

If the exploration map produces more than 5 clusters:

Batch 1: Clusters 1-5 → dispatch simultaneously, wait for all
Batch 2: Clusters 6-10 → dispatch simultaneously, wait for all
...continue until all clusters are reviewed

Phase 3: Verification

Dispatch the SAME NUMBER of verification agents as review agents. Each verification agent checks ONE review report. Max 5 agents at a time.

ROLE: Verification Agent - Report [N]
MISSION: Verify the findings in review-report-[N].md to eliminate false positives.

REVIEW REPORT: .review/session-[id]/review-report-[N].md

YOU MUST:
1. Read the review report
2. For EACH finding in the report, READ THE ACTUAL SOURCE CODE at the referenced file:line
3. Verify the finding is REAL — does the code actually do what the report claims?
4. Understand the context — is this actually a problem given what the code is trying to do?
5. Check if the finding is a false positive based on:
   - Framework conventions (some patterns are normal in certain frameworks)
   - Intentional design decisions visible from context
   - Code that looks dangerous but is properly guarded elsewhere
   - Issues already handled in other parts of the codebase

OUTPUT: .review/session-[id]/verified-report-[N].md

For each finding, output one of:

### Finding [N]: [Title] — CONFIRMED
**Original**: [summary from review]
**Verification**: [Why this is a real issue, with code evidence]

### Finding [N]: [Title] — DISMISSED
**Original**: [summary from review]
**Reason**: [Why this is a false positive, with code evidence]

If ALL findings are dismissed, the report should say so clearly.

Batch Dispatch

Same batch rules as Phase 2 — max 5 verification agents at a time.

Phase 4: Fix Plan

Dispatch ONE agent to synthesize all verified findings into an orchestration-compatible fix plan.

ROLE: Fix Plan Generator
MISSION: Create a fix plan from verified review findings that is compatible with subagent-orchestration.

INPUTS:
- All verified reports: .review/session-[id]/verified-report-*.md
- Load the subagent-orchestration SKILL.md to understand the plan format
- Load the orchestration plan template to understand the required structure

OUTPUT: .review/session-[id]/fix-plan.md

RULES:
1. Only include CONFIRMED findings from verified reports — skip dismissed ones
2. Group related fixes into phases (fixes that touch the same files = same phase)
3. Each phase must follow the orchestration plan template:
   - Type: Sequential or Parallel
   - Requirements: Specific, actionable fix instructions
   - Inputs: Files to read
   - Outputs: Files to create or modify
   - Validation Criteria: How to verify the fix works
   - Dependencies: What must complete first
4. Include gatekeeping commands (typecheck, build) in the plan
5. Order phases by: security fixes first, then logic fixes, then lower priority
6. If there are no confirmed findings, produce a minimal plan that says "No fixes needed"

The fix plan MUST be directly executable by subagent-orchestration without modification.

Fix Plan Format

The output must match the orchestration plan template:

# Fix Plan - [Project Name] Review

## Overview
[Summary of findings and fixes]

## Prerequisites
- [Project tooling: pnpm, TypeScript, etc.]
- [Gatekeeping commands: typecheck, build]

## Gatekeeping Commands
- Type check: [command]
- Build: [command]

## Phase 1: [Fix Group Name]
**Type**: Sequential
**Dependencies**: None

**Requirements**:
- [Specific fix instruction with file:line reference]
- [Specific fix instruction]

**Inputs**:
- Read: [files needed]

**Outputs**:
- Modify: [files to change]

**Validation Criteria**:
- [How to verify fix]
- Type check: Zero errors
- Build: Success

---

[More phases as needed]

## Success Criteria
- All confirmed findings addressed
- Gatekeeping commands pass
- No new issues introduced

File Structure

.review/
└── session-[id]/
    ├── exploration-map.md          # Phase 1 output
    ├── review-report-1.md          # Phase 2 outputs
    ├── review-report-2.md
    ├── ...
    ├── verified-report-1.md        # Phase 3 outputs
    ├── verified-report-2.md
    ├── ...
    └── fix-plan.md                 # Phase 4 output (orchestration-compatible)

Critical Rules

1. You NEVER do the work yourself — explore, review, verify, or plan. You ONLY dispatch subagents. 2. Max 5 subagents at a time — batch everything above 5. 3. Max 15 files per review agent — split larger clusters. 4. Exclude third-party code — only review project source. 5. No nitpicking — the review prompt is explicit: security and logic problems only. Trivial findings waste everyone's time. 6. Same number of verification agents as review agents — one verification agent per review report. 7. Fix plan must be orchestration-compatible — follows the subagent-orchestration plan template exactly. 8. The fix plan agent must load subagent-orchestration SKILL.md — it needs to understand the plan format.

Exclusion Patterns

When telling the exploration agent what to skip, reference these patterns:

• node_modules/ — dependencies
• components/ui/ — shadcn components (deps)
• *.generated.* — generated code
• dist/, build/, .next/ — build output
• formedible/ or any lib code that is a dependency
• Lock files, config files with no logic
• Type declaration files from deps (*.d.ts unless project-authored)

Adapt per project — ask the user if unsure what's deps vs source.

Agent Types

Progress Reporting

Review Session: [id]
Phase: [exploration|review|verification|fix-plan]
Progress: [N]/[total] agents complete
Batch: [N] of [total batches] (if applicable)

Findings so far: [N] total, [N] critical, [N] high, [N] medium

Final report to user:

• Number of findings (before and after verification)
• Number of false positives caught
• Fix plan location: .review/session-[id]/fix-plan.md
• Whether the fix plan is ready for orchestration

Report Formats

Standard formats for each phase's output.

Exploration Map

File: .review/session-[id]/exploration-map.md

# Exploration Map - [Project Name]

## Project Overview
[Brief description of what the project does]

## Technology Stack
- Language: [TypeScript, Python, etc.]
- Framework: [React, Next.js, etc.]
- Build tool: [pnpm, cargo, etc.]

## Gatekeeping Commands
- Type check: [e.g., `pnpm run check-types`]
- Build: [e.g., `pnpm run build`]

## Excluded Paths
- [path]: [reason]
- [path]: [reason]

## Reviewable Files

### Cluster 1: [Name] (Security Focus)
- `src/path/file1.ts`
- `src/path/file2.ts`
- [max 15 files]
Dependencies: [other clusters this depends on]

### Cluster 2: [Name] (Logic Focus)
- `src/path/file3.ts`
- `src/path/file4.ts`
Dependencies: [other clusters this depends on]

[Continue for all clusters]

## Summary
- Total reviewable files: [N]
- Total clusters: [N] (= number of review agents)
- Review batches needed: [ceil(N/5)]

Review Report

File: .review/session-[id]/review-report-[N].md

# Review Report - Cluster [N]: [Cluster Name]

## Metadata
- Cluster: [N]
- Files reviewed: [count]
- Reviewer: subagent-[id]
- Created: [timestamp]

## Findings

### [SEVERITY: CRITICAL] Finding 1: [Title]
**File**: src/path/file.ts:42
**Problem**: [What is wrong and why it matters]
**Evidence**:
\`\`\`typescript
// the problematic code
\`\`\`
**Impact**: [What could go wrong]
**Suggestion**: [How to fix, specific]

### [SEVERITY: HIGH] Finding 2: [Title]
[Same format]

### [SEVERITY: MEDIUM] Finding 3: [Title]
[Same format]

## Summary
- Critical: [N]
- High: [N]
- Medium: [N]
- Total: [N]

[OR if no findings:]
## No Issues Found
After thorough review, no security or logic issues were identified in this cluster.

Verified Report

File: .review/session-[id]/verified-report-[N].md

# Verified Report - Cluster [N]: [Cluster Name]

## Metadata
- Cluster: [N]
- Original findings: [count]
- Confirmed: [count]
- Dismissed: [count]
- Verifier: subagent-[id]

## Verified Findings

### Finding 1: [Title] — CONFIRMED
**Original**: [summary]
**File**: src/path/file.ts:42
**Verification**: [Code evidence confirming this is real]
**Severity**: [CRITICAL/HIGH/MEDIUM]

### Finding 2: [Title] — DISMISSED
**Original**: [summary]
**Reason**: [Why this is a false positive]
**Evidence**: [Code showing why it's fine]

## Summary
- Confirmed findings: [N] ([list severities])
- Dismissed findings: [N] ([brief reasons])

Fix Plan

File: .review/session-[id]/fix-plan.md

Must follow the subagent-orchestration plan template format exactly. See SKILL.md Phase 4 for the template.