/fleet-review

gistfile1.txt

---
name: fleet-review
description: |
  Multi-agent code review pipeline inspired by Claude Code's ultrareview. Analyzes the diff
  to dynamically pick the most relevant review angles from a catalog of 10+ specializations,
  then spawns matched Claude + Codex agents in parallel. Cross-model verification eliminates
  false positives. Use when the user says "fleet review", "multi-agent review",
  "review my code with multiple agents", "fleet-review", "deep review", or wants a thorough
  multi-perspective code review. Also triggers on "review this PR with everything" or
  "full review pipeline".
---

# /fleet-review — Multi-Agent Code Review Pipeline

You are running the `/fleet-review` skill. This orchestrates parallel review agents
(Claude + Codex) followed by cross-model verification to find bugs that single-pass
reviews miss.

The core insight: different agents loading files in different orders build different mental
models of the code, which means different bugs surface. Adding model diversity (Claude + GPT)
compounds this effect. Then verification eliminates false positives.

**What makes this version different:** instead of always running the same 3 fixed angles,
a triage step analyzes the diff and selects the most relevant review angles from a catalog.
A CSS-only change gets different reviewers than a database migration.

---

## Review Angle Catalog

Below are the available review specializations. The triage step (Step 2) selects which
ones to run based on the diff content. Each angle is identified by a short `id`.

### `logic` — Logic & Correctness
**When relevant:** Always relevant for any code change. Core default.
**Prompt focus:**
- Off-by-one errors, wrong comparisons, inverted conditions
- State mutations that could cause unexpected behavior
- Broken invariants, missing null checks on critical paths
- Incorrect algorithm implementations
- Data flow issues where values could be wrong

### `security` — Security & Input Validation
**When relevant:** Changes that handle user input, authentication, authorization, API endpoints,
database queries, file operations, or configuration. Changes touching routes, middleware, or
request handlers.
**Prompt focus:**
- Injection vectors (SQL, command, XSS, template)
- Authentication/authorization bypasses
- Sensitive data exposure (secrets, PII, tokens in logs)
- Missing input validation or sanitization
- SSRF, path traversal, insecure deserialization
- Race conditions that could be exploited
- Insecure defaults or configurations

### `edge-cases` — Edge Cases & Error Handling
**When relevant:** Changes with I/O operations, network calls, parsing, resource management,
or complex control flow. Always relevant when error handling patterns change.
**Prompt focus:**
- Missing error handling on I/O, network, or parsing operations
- Unhandled promise rejections or uncaught exceptions
- Resource leaks (file handles, connections, memory)
- Boundary conditions (empty arrays, zero values, max int)
- Timeout handling and retry logic gaps
- Graceful degradation failures
- Error messages that leak internal details

### `perf` — Performance & Scalability
**When relevant:** Changes touching database queries, loops over collections, caching logic,
rendering hot paths, bundle-affecting imports, or data structures. Also relevant for changes
in request handlers that could affect latency.
**Prompt focus:**
- N+1 queries, missing indexes, full table scans
- Unbounded loops or recursion
- Memory allocation in hot paths
- Missing or broken caching
- Unnecessary re-renders or re-computations
- Bundle size impact from new imports
- Algorithmic complexity issues (O(n^2) where O(n) is possible)

### `api-contract` — API Contract & Backwards Compatibility
**When relevant:** Changes to API routes, tRPC procedures, GraphQL schemas, REST endpoints,
response shapes, request validation schemas, or public function signatures. Also relevant
for database schema changes that affect API responses.
**Prompt focus:**
- Breaking changes to request/response shapes
- Missing versioning or migration path for existing clients
- Changed default values that alter behavior for existing callers
- Removed or renamed fields without deprecation
- Changed error codes or error response formats
- SDK/client library compatibility issues

### `data-integrity` — Database & Data Integrity
**When relevant:** Changes to schema files, migrations, ORM models, transaction logic,
seed data, or any code that writes to the database. Also relevant for changes to
background jobs that process data.
**Prompt focus:**
- Missing or incorrect foreign key constraints
- Unsafe migrations (data loss, long locks, missing backfill)
- Transaction boundaries (writes that should be atomic but aren't)
- Inconsistent state from partial failures
- Missing cascade deletes or orphaned records
- Type mismatches between schema and application code
- Concurrent write conflicts

### `concurrency` — Concurrency & Race Conditions
**When relevant:** Changes involving async operations, shared state, queues, background jobs,
cron tasks, distributed locks, or optimistic updates. Also relevant when multiple request
handlers could modify the same resource.
**Prompt focus:**
- TOCTOU (time-of-check-to-time-of-use) races
- Missing locks or overly broad locks
- Deadlock potential from lock ordering
- Lost updates from concurrent modifications
- Queue processing ordering assumptions
- Stale reads in eventually-consistent contexts
- Promise/async pitfalls (missing await, unhandled concurrent errors)

### `types` — Type Safety & Type Correctness
**When relevant:** TypeScript/Flow changes with complex generics, type assertions (`as`),
`any` usage, union/intersection types, or changes to shared type definitions. Also relevant
for changes to serialization/deserialization boundaries.
**Prompt focus:**
- Unsafe type assertions (`as any`, `as unknown as X`)
- Type narrowing gaps (missing discriminant checks)
- Generic constraints that are too loose or too tight
- Runtime values that could violate compile-time types
- Serialization boundaries where types lie (JSON.parse, API responses)
- Enum exhaustiveness gaps (missing switch cases)
- Incorrect type exports that affect downstream consumers

### `ui-ux` — UI/UX & Accessibility
**When relevant:** Changes to React components, CSS/styling, HTML templates, form handling,
client-side state management, or user-facing text. Also relevant for changes that affect
loading states, error displays, or navigation.
**Prompt focus:**
- Missing loading/error/empty states
- Broken keyboard navigation or focus management
- Missing ARIA attributes or semantic HTML
- Layout shifts from async content
- Inconsistent responsive behavior
- Form validation UX (timing, messaging, field states)
- Internationalization issues (hardcoded strings, RTL, pluralization)

### `config-deploy` — Configuration & Deployment
**When relevant:** Changes to environment variables, CI/CD files, Docker/container configs,
build scripts, package.json scripts, infrastructure-as-code, or deployment manifests.
**Prompt focus:**
- Missing environment variables in deployment configs
- Build-time vs runtime config confusion
- Secrets accidentally hardcoded or logged
- Feature flags with incorrect defaults
- Incompatible dependency versions
- Missing health checks or readiness probes
- Rollback safety (can this deploy be safely reverted?)

### `test-coverage` — Test Coverage Gaps
**When relevant:** Changes that add new behavior, modify existing behavior, or touch
code paths that have corresponding test files. Especially relevant when tests are NOT
included alongside behavioral changes.
**Prompt focus:**
- New code paths with no corresponding tests
- Modified behavior where existing tests weren't updated
- Test assertions that don't actually verify the changed behavior
- Missing edge case test coverage for new logic
- Integration test gaps for cross-module changes
- Mocked dependencies that hide real integration issues

### `migration-safety` — Migration & Schema Safety
**When relevant:** Database migration files, schema changes, data backfill scripts,
or changes that modify the shape of persisted data (including config files, cache formats,
or local storage schemas).
**Prompt focus:**
- Migrations that require downtime (large table locks)
- Missing backward-compatible deploy ordering (code-first vs schema-first)
- Data loss from column drops or type changes without backfill
- Non-reversible migrations without rollback scripts
- Foreign key additions on large tables without index consideration
- DEFAULT values that don't match application assumptions

---

## Step 0: Preflight checks

### Check codex binary
```bash
which codex 2>/dev/null || echo "NOT_FOUND"
```
If `NOT_FOUND`: tell the user "Codex CLI not found. Install: `npm install -g @openai/codex`"
and offer to run the review with Claude subagents only (skip all Codex steps).

### Detect base branch
```bash
BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || \
       gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || \
       echo "main")
echo "$BASE"
```

### Get the diff stats
```bash
git diff origin/$BASE --stat 2>/dev/null | tail -5
```
If no diff exists, tell the user: "No changes against $BASE. Make some commits first."

### Capture the diff early (needed for triage)
```bash
DIFF_FILE=$(mktemp /tmp/fleet-review-diff-XXXXXX.patch)
git diff origin/$BASE > "$DIFF_FILE"
echo "$DIFF_FILE"
```

Also capture a file list:
```bash
git diff origin/$BASE --name-only
```

---

## Step 1: Triage — Select review angles

Spawn a **haiku** subagent (fast, cheap) to analyze the diff and select the most relevant
review angles. This is the key intelligence step.

**Triage agent prompt:**
```
You are a code review triage agent. Analyze this diff and select the most relevant review
angles from the catalog below.

Diff file: $DIFF_FILE
Changed files:
$FILE_LIST

REVIEW ANGLE CATALOG (pick from these IDs):
  logic          — Logic & Correctness (off-by-one, wrong comparisons, broken invariants)
  security       — Security & Input Validation (injection, auth bypass, data exposure)
  edge-cases     — Edge Cases & Error Handling (missing error handling, resource leaks, boundaries)
  perf           — Performance & Scalability (N+1 queries, unbounded loops, missing caching)
  api-contract   — API Contract & Backwards Compatibility (breaking changes, response shape changes)
  data-integrity — Database & Data Integrity (schema safety, transaction boundaries, concurrent writes)
  concurrency    — Concurrency & Race Conditions (TOCTOU, missing locks, async pitfalls)
  types          — Type Safety & Type Correctness (unsafe assertions, generic gaps, serialization boundaries)
  ui-ux          — UI/UX & Accessibility (missing states, keyboard nav, a11y, responsive)
  config-deploy  — Configuration & Deployment (env vars, build scripts, secrets, rollback safety)
  test-coverage  — Test Coverage Gaps (untested new paths, stale tests, integration gaps)
  migration-safety — Migration & Schema Safety (downtime risk, data loss, rollback)

RULES:
1. Read the diff file to understand what changed
2. Select exactly 3 angles (unless the diff is very large or spans many domains — then up to 5)
3. `logic` is almost always relevant — include it unless the change is purely config/styling
4. Prioritize angles where bugs are LIKELY given this specific diff, not just theoretically possible
5. Consider file types: .sql/.migration → data-integrity/migration-safety, .css/.tsx with JSX → ui-ux,
   routes/middleware → security, package.json/Dockerfile → config-deploy, etc.

OUTPUT FORMAT (strict — no other text):
ANGLES: id1, id2, id3
REASONING: one sentence per angle explaining why it's relevant to THIS diff
```

Use `model: "haiku"` for this agent. Parse the `ANGLES:` line to get the selected IDs.

If the user specified custom focus areas in their request, override the triage result:
- Map their request to catalog IDs where possible
- If they mention something not in the catalog, create an ad-hoc angle with a custom prompt
- Still limit to 3-5 angles unless the user explicitly asks for more

---

## Step 2: Ask for confirmation

Show the user what was selected and ask for approval. Use AskUserQuestion:

```
Fleet Review — Triage Complete

Based on your diff, these review angles were selected:

  REVIEW FLEET (parallel, N angles x 2 models):
    Claude 1 — [Selected Angle 1 name]
    Claude 2 — [Selected Angle 2 name]
    Claude 3 — [Selected Angle 3 name]
    Codex 1  — [Selected Angle 1 name]
    Codex 2  — [Selected Angle 2 name]
    Codex 3  — [Selected Angle 3 name]

  TRIAGE REASONING:
    - angle1: why it was selected
    - angle2: why it was selected
    - angle3: why it was selected

  VERIFICATION (after fleet completes):
    Claude verifier — cross-checks all findings
    Codex verifier  — cross-checks all findings

  Base branch: $BASE
  Files changed: N

Proceed? (yes / no / adjust angles)
```

If the user says no, stop. If they want to adjust angles (add, remove, or swap), update
the selection and re-confirm. They can also say "add perf" or "drop ui-ux" to modify.

---

## Step 3: Launch the review fleet (all agents in parallel)

Launch all agents in a SINGLE response — do not wait for any to finish before launching
the others. The whole point is parallel, independent exploration.

For each selected angle, spawn one Claude subagent and one Codex agent (or two Claude
subagents if Codex is unavailable).

### Building the prompt for each angle

For each selected angle ID, construct the review prompt by pulling from the catalog above.
Every agent prompt follows this template:

```
Review the code changes in $DIFF_FILE against the source files in this repo.
Focus ONLY on [ANGLE NAME]:
[bullet list from the angle's "Prompt focus" section in the catalog]

Do NOT comment on style, naming, or issues outside your focus area.
Read the surrounding code — not just the diff — to understand the full context.

For each finding, output this exact format:
FINDING:
  severity: P0|P1|P2|P3
  file: <path>
  line: <number or range>
  title: <one-line summary>
  detail: <2-3 sentences explaining the bug and why it matters>
  evidence: <the specific code pattern that's wrong>

If you find nothing, output: NO_FINDINGS

Severity guide:
  P0 = will cause data loss, crash, or security breach in production
  P1 = will cause incorrect behavior for some users
  P2 = could cause issues under specific conditions
  P3 = minor issue, unlikely to cause problems but worth noting
```

### Claude subagents (via Agent tool, all run_in_background: true)

Spawn one Agent per selected angle. Each should:
- Read the diff file
- Explore the actual source files (not just the diff) to understand context
- Report findings in the structured format

### Codex agents (via Bash, all run_in_background: true)

For each selected angle, run a Codex process:
```bash
codex exec "[condensed prompt for this angle, referencing $DIFF_FILE]" \
  -s read-only \
  -c 'model_reasoning_effort="xhigh"' \
  --enable web_search_cached \
  2>/dev/null
```

Use `timeout: 900000` (15 minutes) on each Bash call.

### Total agents

If 3 angles selected: 3 Claude + 3 Codex = 6 agents (default)
If 4 angles selected: 4 Claude + 4 Codex = 8 agents
If 5 angles selected: 5 Claude + 5 Codex = 10 agents

---

## Step 4: Collect and parse findings

As each agent completes, parse its output for FINDING blocks. Collect all findings into
a single list. If an agent returned NO_FINDINGS, note that.

Create a consolidated findings document:

```
FLEET REVIEW — RAW FINDINGS
════════════════════════════════════════════════════════════
Base branch: $BASE
Files changed: N
Angles: [list selected angle names]
Agents completed: X/Y

[For each angle:]
CLAUDE ([Angle Name]): N findings
CODEX ([Angle Name]): N findings

TOTAL RAW FINDINGS: N
════════════════════════════════════════════════════════════

[list each finding with its source agent and angle]
```

Show this summary to the user before proceeding to verification.

---

## Step 5: Verification (cross-model)

If there are zero findings across all agents, skip verification and report clean.

If there ARE findings, run two verification agents — one Claude, one Codex.
Each verifier independently reviews every finding against the actual source code
and the diff.

### Claude verifier (Agent tool):
```
You are a verification agent. Below are code review findings from a fleet of reviewers.
Your job is to independently verify each one by reading the actual source code.

For each finding:
1. Read the file and line referenced
2. Trace the logic to confirm or refute the claim
3. Verdict: CONFIRMED, REFUTED, or LIKELY (can't fully confirm but plausible)

Findings to verify:
[paste all findings]

Output format for each:
VERDICT:
  original_title: <title from finding>
  status: CONFIRMED|REFUTED|LIKELY
  confidence: HIGH|MEDIUM|LOW
  reasoning: <1-2 sentences explaining why you confirmed or refuted>
```

### Codex verifier (Bash):
```bash
codex exec "You are a verification agent. These findings were reported by code reviewers. Read the actual source files and verify each one. For each: read the file/line, trace the logic, verdict: CONFIRMED/REFUTED/LIKELY with reasoning.

Findings:
[paste all findings]

Output format: VERDICT: original_title, status(CONFIRMED/REFUTED/LIKELY), confidence(HIGH/MEDIUM/LOW), reasoning" \
  -s read-only \
  -c 'model_reasoning_effort="xhigh"' \
  --enable web_search_cached \
  2>/dev/null
```

Use `timeout: 900000` (15 minutes) on the Codex verifier.

---

## Step 6: Cross-reference and produce final report

Match up the two verifiers' verdicts for each finding:

- **Both CONFIRMED** -> HIGH confidence, include in final report
- **One CONFIRMED, one LIKELY** -> MEDIUM confidence, include with note
- **Both LIKELY** -> LOW confidence, include as "possible issue"
- **One CONFIRMED, one REFUTED** -> DISPUTED, include with both perspectives
- **Both REFUTED** -> Drop from final report (false positive)
- **One LIKELY, one REFUTED** -> Drop (probably false positive)

Present the final report:

```
FLEET REVIEW — FINAL REPORT
════════════════════════════════════════════════════════════
Base branch: $BASE | Files changed: N | Duration: Xm Ys
Review angles: [list selected angles with reasoning]

CONFIRMED FINDINGS (high confidence):
  [P0] Title — file:line
        Detail...
        Angle: [angle name] | Found by: Claude, Codex | Verified by: both

  [P1] Title — file:line
        Detail...
        Angle: [angle name] | Found by: Codex | Verified by: Claude + Codex(LIKELY)

POSSIBLE FINDINGS (lower confidence):
  [P2] Title — file:line
        Detail...
        Angle: [angle name] | Found by: Claude | Verified by: Claude(LIKELY), Codex(LIKELY)

DISPUTED:
  [P1] Title — file:line
        Claude verifier: CONFIRMED — reasoning
        Codex verifier: REFUTED — reasoning

STATS:
  Review angles:     N
  Total agents:      N review + 2 verification
  Raw findings:      N
  After verification: N confirmed, N possible, N disputed, N refuted
  False positive rate: X%
════════════════════════════════════════════════════════════
```

---

## Step 7: Cleanup

```bash
rm -f "$DIFF_FILE"
```

---

## Fallback: Codex unavailable

If Codex CLI is not installed, run the pipeline with Claude subagents only — double the
Claude agents per angle. Use different model configurations if available (e.g., mix of
Opus and Sonnet) to get some model diversity. The verification stage becomes 2 Claude
verifiers — one using extended thinking, one without — to get perspective diversity.

---

## Important rules

- **Never modify code.** This skill is read-only. All agents run in read-only mode.
- **All reviewers launch in parallel.** Do not serialize them.
- **Triage first.** Always run the triage step to select angles — never hardcode angles.
- **Always ask confirmation first.** The user must approve the selected angles before agents spawn.
- **Present findings verbatim.** Show raw findings before verification, then the final report.
- **Respect timeouts.** 15 minutes per agent. If one times out, proceed with the others.
- **Clean up temp files.** Remove the diff file when done.
- **User overrides win.** If the user specifies angles, those override triage selection.