Review Cycle

Review Cycle

Unified multi-dimensional code review orchestrator with dual-mode (session/module) file discovery, 7-dimension parallel analysis, iterative deep-dive on critical findings, and optional automated fix pipeline with intelligent batching and parallel planning.

Architecture Overview

┌──────────────────────────────────────────────────────────────────────┐
│  Review Cycle Orchestrator (SKILL.md)                                │
│  → Pure coordinator: mode detection, phase dispatch, state tracking  │
└───────────────────────────────┬──────────────────────────────────────┘
                                │
  ┌─────────────────────────────┼─────────────────────────────────┐
  │           Review Pipeline (Phase 1-5)                          │
  │                                                                │
  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
  │  │ Phase 1 │→ │ Phase 2 │→ │ Phase 3 │→ │ Phase 4 │→ │ Phase 5 │
  │  │Discovery│  │Parallel │  │Aggregate│  │Deep-Dive│  │Complete │
  │  │  Init   │  │ Review  │  │         │  │(cond.)  │  │         │
  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘
  │   session|      7 agents     severity     N agents     finalize
  │   module        ×cli-explore  calc        ×cli-explore  state
  │                                  ↕ loop
  └────────────────────────────────────────────────────────────────┘
                                │
                          (optional --fix)
                                │
  ┌─────────────────────────────┼─────────────────────────────────┐
  │           Fix Pipeline (Phase 6-9)                             │
  │                                                                │
  │  ┌─────────┐  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌─────────┐
  │  │ Phase 6 │→ │ Phase 7 │→ │Phase 7.5 │→ │ Phase 8 │→ │ Phase 9 │
  │  │Discovery│  │Parallel │  │Export to │  │Execution│  │Complete │
  │  │Batching │  │Planning │  │Task JSON │  │Orchestr.│  │         │
  │  └─────────┘  └─────────┘  └──────────┘  └─────────┘  └─────────┘
  │   grouping     N agents     fix-plan →    M agents     aggregate
  │   + batch      ×cli-plan    .task/FIX-*   ×cli-exec    + summary
  └────────────────────────────────────────────────────────────────────┘

Key Design Principles

1. Dual-Mode Review: Session-based (git changes) and module-based (path patterns) share the same review pipeline (Phase 2-5), differing only in file discovery (Phase 1)
2. Pure Orchestrator: Execute phases in sequence, parse outputs, pass context between them
3. Progressive Phase Loading: Phase docs are read on-demand when that phase executes, not all at once
4. Auto-Continue: All phases run autonomously without user intervention between phases
5. Subagent Lifecycle: Explicit lifecycle management with spawn_agent → wait → close_agent
6. Role via agent_type: Subagent roles loaded via TOML agent_type parameter in spawn_agent (e.g., "cli_explore_agent")
7. Optional Fix Pipeline: Phase 6-9 triggered only by explicit --fix flag or user confirmation after Phase 5
8. Content Preservation: All agent prompts, code, schemas preserved verbatim from source commands

Usage

# Review Pipeline (Phase 1-5)
review-cycle <path-pattern>                                    # Module mode
review-cycle [session-id]                                      # Session mode
review-cycle [session-id|path-pattern] [FLAGS]                 # With flags

# Fix Pipeline (Phase 6-9)
review-cycle --fix <review-dir|export-file>                    # Fix mode
review-cycle --fix <review-dir> [FLAGS]                        # Fix with flags

# Flags
--dimensions=dim1,dim2,...    Custom dimensions (default: all 7)
--max-iterations=N           Max deep-dive iterations (default: 3)
--fix                        Enter fix pipeline after review or standalone
--resume                     Resume interrupted fix session
--batch-size=N               Findings per planning batch (default: 5, fix mode only)
--export-tasks               Export fix-plan findings to .task/FIX-*.json (auto-enabled with --fix)

# Examples
review-cycle src/auth/**                                       # Module: review auth
review-cycle src/auth/**,src/payment/**                        # Module: multiple paths
review-cycle src/auth/** --dimensions=security,architecture    # Module: custom dims
review-cycle WFS-payment-integration                           # Session: specific
review-cycle                                                   # Session: auto-detect
review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/           # Fix: from review dir
review-cycle --fix --resume                                    # Fix: resume session

Mode Detection

// Input parsing logic (orchestrator responsibility)
function detectMode(args) {
  if (args.includes('--fix')) return 'fix';
  if (args.match(/\*|\.ts|\.js|\.py|src\/|lib\//)) return 'module';  // glob/path patterns
  if (args.match(/^WFS-/) || args.trim() === '') return 'session';   // session ID or empty
  return 'session';  // default
}

Execution Flow

Input Parsing:
   └─ Detect mode (session|module|fix) → route to appropriate phase entry

Review Pipeline (session or module mode):

Phase 1: Discovery & Initialization
   └─ Ref: phases/01-discovery-initialization.md
      ├─ Session mode: session discovery → git changed files → resolve
      ├─ Module mode: path patterns → glob expand → resolve
      └─ Common: create session, output dirs, review-state.json, review-progress.json

Phase 2: Parallel Review Coordination
   └─ Ref: phases/02-parallel-review.md
      ├─ Spawn 7 cli-explore-agent instances (Deep Scan mode)
      ├─ Each produces dimensions/{dimension}.json + reports/{dimension}-analysis.md
      ├─ Lifecycle: spawn_agent → batch wait → close_agent
      └─ CLI fallback: Gemini → Qwen → Codex

Phase 3: Aggregation
   └─ Ref: phases/03-aggregation.md
      ├─ Load dimension JSONs, calculate severity distribution
      ├─ Identify cross-cutting concerns (files in 3+ dimensions)
      └─ Decision: critical > 0 OR high > 5 OR critical files → Phase 4
                   Else → Phase 5

Phase 4: Iterative Deep-Dive (conditional)
   └─ Ref: phases/04-iterative-deep-dive.md
      ├─ Select critical findings (max 5 per iteration)
      ├─ Spawn deep-dive agents for root cause analysis
      ├─ Re-assess severity → loop back to Phase 3 aggregation
      └─ Exit when: no critical findings OR max iterations reached

Phase 5: Review Completion
   └─ Ref: phases/05-review-completion.md
      ├─ Finalize review-state.json + review-progress.json
      ├─ Prompt user: "Run automated fixes? [Y/n]"
      └─ If yes → Continue to Phase 6

Fix Pipeline (--fix mode or after Phase 5):

Phase 6: Fix Discovery & Batching
   └─ Ref: phases/06-fix-discovery-batching.md
      ├─ Validate export file, create fix session
      └─ Intelligent grouping by file+dimension similarity → batches

Phase 7: Fix Parallel Planning
   └─ Ref: phases/07-fix-parallel-planning.md
      ├─ Spawn N cli-planning-agent instances (≤10 parallel)
      ├─ Each outputs partial-plan-{batch-id}.json
      ├─ Lifecycle: spawn_agent → batch wait → close_agent
      └─ Orchestrator aggregates → fix-plan.json

Phase 7.5: Export to Task JSON (auto with --fix, or explicit --export-tasks)
   └─ Convert fix-plan.json findings → .task/FIX-{seq}.json
      ├─ For each finding in fix-plan.json:
      │   ├─ finding.file          → files[].path (action: "modify")
      │   ├─ finding.severity      → priority (critical|high|medium|low)
      │   ├─ finding.fix_description → description
      │   ├─ finding.dimension     → scope
      │   ├─ finding.verification  → convergence.verification
      │   ├─ finding.changes[]     → convergence.criteria[]
      │   └─ finding.fix_steps[]   → implementation[]
      ├─ Output path: {projectRoot}/.workflow/active/WFS-{id}/.review/.task/FIX-{seq}.json
      ├─ Each file follows task-schema.json (IDENTITY + CONVERGENCE + FILES required)
      └─ source.tool = "review-cycle", source.session_id = WFS-{id}
      │
      ├─ Generate plan.json (plan-overview-fix-schema) after FIX task export:
      │   ```javascript
      │   const fixTaskFiles = Glob(`${reviewDir}/.task/FIX-*.json`)
      │   const taskIds = fixTaskFiles.map(f => JSON.parse(Read(f)).id).sort()
      │
      │   // Guard: skip plan.json if no fix tasks generated
      │   if (taskIds.length === 0) {
      │     console.warn('No fix tasks generated; skipping plan.json')
      │   } else {
      │
      │   const planOverview = {
      │     summary: `Fix plan from review cycle: ${reviewSummary}`,
      │     approach: "Review-driven fix pipeline",
      │     task_ids: taskIds,
      │     task_count: taskIds.length,
      │     complexity: taskIds.length > 5 ? "High" : taskIds.length > 2 ? "Medium" : "Low",
      │     fix_context: {
      │       root_cause: "Multiple review findings",
      │       strategy: "comprehensive_fix",
      │       severity: aggregatedFindings.maxSeverity || "Medium",  // Derived from max finding severity
      │       risk_level: aggregatedFindings.overallRisk || "medium" // Derived from combined risk assessment
      │     },
      │     test_strategy: {
      │       scope: "unit",
      │       specific_tests: [],
      │       manual_verification: ["Verify all review findings addressed"]
      │     },
      │     _metadata: {
      │       timestamp: getUtc8ISOString(),
      │       source: "review-cycle-agent",
      │       planning_mode: "agent-based",
      │       plan_type: "fix",
      │       schema_version: "2.0"
      │     }
      │   }
      │   Write(`${reviewDir}/plan.json`, JSON.stringify(planOverview, null, 2))
      │
      │   } // end guard
      │   ```
      └─ Output path: {reviewDir}/plan.json

Phase 8: Fix Execution
   └─ Ref: phases/08-fix-execution.md
      ├─ Stage-based execution per aggregated timeline
      ├─ Each group: analyze → fix → test → commit/rollback
      ├─ Lifecycle: spawn_agent → wait → close_agent per group
      └─ 100% test pass rate required

Phase 9: Fix Completion
   └─ Ref: phases/09-fix-completion.md
      ├─ Aggregate results → fix-summary.md
      ├─ Sync session state: $session-sync -y "Review cycle complete: {findings} findings, {fixed} fixed"
      └─ Optional: complete workflow session if all fixes successful

Complete: Review reports + optional fix results

Phase Reference Documents (read on-demand when phase executes):

Core Rules

1. Start Immediately: First action is progress tracking initialization, second action is Phase 1 execution
2. Mode Detection First: Parse input to determine session/module/fix mode before Phase 1
3. Parse Every Output: Extract required data from each phase for next phase
4. Auto-Continue: Check progress status to execute next pending phase automatically
5. Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute
6. DO NOT STOP: Continuous multi-phase workflow until all applicable phases complete
7. Conditional Phase 4: Only execute if aggregation triggers iteration (critical > 0 OR high > 5 OR critical files)
8. Fix Pipeline Optional: Phase 6-9 only execute with explicit --fix flag or user confirmation
9. Explicit Lifecycle: Always close_agent after wait completes to free resources

Data Flow

User Input (path-pattern | session-id | --fix export-file)
    ↓
[Mode Detection: session | module | fix]
    ↓
Phase 1: Discovery & Initialization
    ↓ Output: sessionId, reviewId, resolvedFiles, reviewMode, outputDir
    ↓         review-state.json, review-progress.json
Phase 2: Parallel Review Coordination
    ↓ Output: dimensions/*.json, reports/*-analysis.md
Phase 3: Aggregation
    ↓ Output: severityDistribution, criticalFiles, deepDiveFindings
    ↓ Decision: iterate? → Phase 4 : Phase 5
Phase 4: Iterative Deep-Dive (conditional, loops with Phase 3)
    ↓ Output: iterations/*.json, reports/deep-dive-*.md
    ↓ Loop: re-aggregate → check criteria → iterate or exit
Phase 5: Review Completion
    ↓ Output: final review-state.json, review-progress.json
    ↓ Decision: fix? → Phase 6 : END
Phase 6: Fix Discovery & Batching
    ↓ Output: finding batches (in-memory)
Phase 7: Fix Parallel Planning
    ↓ Output: partial-plan-*.json → fix-plan.json (aggregated)
Phase 7.5: Export to Task JSON
    ↓ Output: .task/FIX-{seq}.json (per finding, follows task-schema.json)
Phase 8: Fix Execution
    ↓ Output: fix-progress-*.json, git commits
Phase 9: Fix Completion
    ↓ Output: fix-summary.md, fix-history.json

Subagent API Reference

spawn_agent

Create a new subagent with task assignment.

const agentId = spawn_agent({
  agent_type: "{agent_type}",  // TOML agent definition name (e.g., "cli_explore_agent")
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. Execute: ccw spec load --category "exploration execution"

---

## TASK CONTEXT
${taskContext}

## DELIVERABLES
${deliverables}
`
})

wait_agent

Get results from subagent (only way to retrieve results).

const result = wait_agent({
  targets: [agentId],
  timeout_ms: 600000  // 10 minutes
})

if (result.timed_out) {
  // Handle timeout - can use assign_task to prompt completion
}

// Check completion status
if (result.status[agentId].completed) {
  const output = result.status[agentId].completed;
}

assign_task

Assign new work to active subagent (for clarification or follow-up).

assign_task({
  target: agentId,
  items: [{ type: "text", text: `
## CLARIFICATION ANSWERS
${answers}

## NEXT STEP
Continue with analysis generation.
` }]
})

close_agent

Clean up subagent resources (irreversible).

close_agent({ id: agentId })

Progress Tracking Pattern

Review Pipeline Initialization (before Phase 1):

functions.update_plan([
  { id: "phase-1", title: "Phase 1: Discovery & Initialization", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Parallel Reviews (7 dimensions)", status: "pending" },
  { id: "phase-3", title: "Phase 3: Aggregation", status: "pending" },
  { id: "phase-4", title: "Phase 4: Deep-dive (conditional)", status: "pending" },
  { id: "phase-5", title: "Phase 5: Review Completion", status: "pending" }
])

Phase Transitions:

• Phase 1 complete: functions.update_plan([{id: "phase-1", status: "completed"}, {id: "phase-2", status: "in_progress"}])
• Phase 2 complete: functions.update_plan([{id: "phase-2", status: "completed"}, {id: "phase-3", status: "in_progress"}])
• Phase 3 → Phase 4 (iteration needed): functions.update_plan([{id: "phase-3", status: "completed"}, {id: "phase-4", status: "in_progress"}])
• Phase 3 → Phase 5 (no iteration): functions.update_plan([{id: "phase-3", status: "completed"}, {id: "phase-4", status: "completed"}, {id: "phase-5", status: "in_progress"}])
• Phase 4 complete: functions.update_plan([{id: "phase-4", status: "completed"}, {id: "phase-5", status: "in_progress"}])
• Phase 5 complete: functions.update_plan([{id: "phase-5", status: "completed"}])

During Phase 2 (sub-tasks for each dimension):

  → Security review       → in_progress / completed
  → Architecture review   → in_progress / completed
  → Quality review        → in_progress / completed
  ... other dimensions

Fix Pipeline (added after Phase 5 if --fix triggered):

functions.update_plan([
  { id: "phase-6", title: "Phase 6: Fix Discovery & Batching", status: "in_progress" },
  { id: "phase-7", title: "Phase 7: Parallel Planning", status: "pending" },
  { id: "phase-7.5", title: "Phase 7.5: Export to Task JSON", status: "pending" },
  { id: "phase-8", title: "Phase 8: Execution", status: "pending" },
  { id: "phase-9", title: "Phase 9: Fix Completion", status: "pending" }
])

Fix Pipeline Transitions:

• Phase 6 complete: functions.update_plan([{id: "phase-6", status: "completed"}, {id: "phase-7", status: "in_progress"}])
• Phase 7 complete: functions.update_plan([{id: "phase-7", status: "completed"}, {id: "phase-7.5", status: "in_progress"}])
• Phase 7.5 complete: functions.update_plan([{id: "phase-7.5", status: "completed"}, {id: "phase-8", status: "in_progress"}])
• Phase 8 complete: functions.update_plan([{id: "phase-8", status: "completed"}, {id: "phase-9", status: "in_progress"}])
• Phase 9 complete: functions.update_plan([{id: "phase-9", status: "completed"}])

Error Handling

Review Pipeline Errors

Fix Pipeline Errors

CLI Fallback Chain

Gemini → Qwen → Codex → degraded mode

Fallback Triggers: HTTP 429/5xx, connection timeout, invalid JSON output, low confidence < 0.4, analysis too brief (< 100 words)

Output File Structure

{projectRoot}/.workflow/active/WFS-{session-id}/.review/
├── review-state.json                    # Orchestrator state machine
├── review-progress.json                 # Real-time progress
├── dimensions/                          # Per-dimension results (Phase 2)
│   ├── security.json
│   ├── architecture.json
│   ├── quality.json
│   ├── action-items.json
│   ├── performance.json
│   ├── maintainability.json
│   └── best-practices.json
├── iterations/                          # Deep-dive results (Phase 4)
│   ├── iteration-1-finding-{uuid}.json
│   └── iteration-2-finding-{uuid}.json
├── reports/                             # Human-readable reports
│   ├── security-analysis.md
│   ├── security-cli-output.txt
│   ├── deep-dive-1-{uuid}.md
│   └── ...
├── .task/                              # Task JSON exports (Phase 7.5)
│   ├── FIX-001.json                    # Per-finding task (task-schema.json)
│   ├── FIX-002.json
│   └── ...
├── plan.json                           # Plan overview (plan-overview-fix-schema, Phase 7.5)
└── fixes/{fix-session-id}/             # Fix results (Phase 6-9)
    ├── partial-plan-*.json
    ├── fix-plan.json
    ├── fix-progress-*.json
    ├── fix-summary.md
    ├── active-fix-session.json
    └── fix-history.json

Related Commands

View Progress

ccw view

Workflow Pipeline

# Step 1: Review (this skill)
review-cycle src/auth/**

# Step 2: Fix (continue or standalone)
review-cycle --fix ${projectRoot}/.workflow/active/WFS-{session-id}/.review/

Session Sync

# Auto-synced at Phase 9 (fix completion)
$session-sync -y "Review cycle complete: {findings} findings, {fixed} fixed"

Converted and distributed by TomeVault — claim your Tome and manage your conversions.