| name | review-cycle |
| description | Unified multi-dimensional code review with automated fix orchestration. Supports session-based (git changes) and module-based (path patterns) review modes with 7-dimension parallel analysis, iterative deep-dive, and automated fix pipeline. Triggers on "workflow:review-cycle", "workflow:review-session-cycle", "workflow:review-module-cycle", "workflow:review-cycle-fix". |
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
- 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)
- Pure Orchestrator: Execute phases in sequence, parse outputs, pass context between them
- Progressive Phase Loading: Phase docs are read on-demand when that phase executes, not all at once
- Auto-Continue: All phases run autonomously without user intervention between phases
- Subagent Lifecycle: Explicit lifecycle management with spawn_agent → wait → close_agent
- Role via agent_type: Subagent roles loaded via TOML
agent_type parameter in spawn_agent (e.g., "cli_explore_agent")
- Optional Fix Pipeline: Phase 6-9 triggered only by explicit
--fix flag or user confirmation after Phase 5
- 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
function detectMode(args) {
if (args.includes('--fix')) return 'fix';
if (args.match(/\*|\.ts|\.js|\.py|src\/|lib\//)) return 'module';
if (args.match(/^WFS-/) || args.trim() === '') return 'session';
return 'session';
}
| Input Pattern | Detected Mode | Phase Entry |
|---|
src/auth/** | module | Phase 1 (module branch) |
WFS-payment-integration | session | Phase 1 (session branch) |
| (empty) | session | Phase 1 (session branch, auto-detect) |
--fix .review/ | fix | Phase 6 |
--fix --resume | fix | Phase 6 (resume) |
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
- Start Immediately: First action is progress tracking initialization, second action is Phase 1 execution
- Mode Detection First: Parse input to determine session/module/fix mode before Phase 1
- Parse Every Output: Extract required data from each phase for next phase
- Auto-Continue: Check progress status to execute next pending phase automatically
- Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute
- DO NOT STOP: Continuous multi-phase workflow until all applicable phases complete
- Conditional Phase 4: Only execute if aggregation triggers iteration (critical > 0 OR high > 5 OR critical files)
- Fix Pipeline Optional: Phase 6-9 only execute with explicit --fix flag or user confirmation
- 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}",
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({
timeout_ms: 1800000
})
if (result.timed_out) {
followup_task({ target: agentId, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
const status = wait_agent({ timeout_ms: 180000 })
if (status.timed_out) {
followup_task({ target: agentId, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
const forced = wait_agent({ timeout_ms: 180000 })
if (forced.timed_out) {
close_agent({ target: agentId })
}
}
}
if (result.status[agentId].completed) {
const output = result.status[agentId].completed;
}
followup_task
Assign new work to active subagent (for clarification or follow-up).
followup_task({
target: agentId,
message: `
## CLARIFICATION ANSWERS
${answers}
## NEXT STEP
Continue with analysis generation.
`
})
close_agent
Clean up subagent resources (irreversible).
close_agent({ target: 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
| Phase | Error | Blocking? | Action |
|---|
| Phase 1 | Session not found (session mode) | Yes | Error and exit |
| Phase 1 | No changed files (session mode) | Yes | Error and exit |
| Phase 1 | Invalid path pattern (module mode) | Yes | Error and exit |
| Phase 1 | No files matched (module mode) | Yes | Error and exit |
| Phase 2 | Single dimension fails | No | Log warning, continue other dimensions |
| Phase 2 | All dimensions fail | Yes | Error and exit |
| Phase 3 | Missing dimension JSON | No | Skip in aggregation, log warning |
| Phase 4 | Deep-dive agent fails | No | Skip finding, continue others |
| Phase 4 | Max iterations reached | No | Generate partial report |
Fix Pipeline Errors
| Phase | Error | Blocking? | Action |
|---|
| Phase 6 | Invalid export file | Yes | Abort with error |
| Phase 6 | Empty batches | No | Warn and skip empty |
| Phase 7 | Planning agent timeout | No | Mark batch failed, continue others |
| Phase 7 | All agents fail | Yes | Abort fix session |
| Phase 8 | Test failure after fix | No | Rollback, retry up to max_iterations |
| Phase 8 | Git operations fail | Yes | Abort, preserve state |
| Phase 9 | Aggregation error | No | Generate partial summary |
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
review-cycle src/auth/**
review-cycle --fix ${projectRoot}/.workflow/active/WFS-{session-id}/.review/
Session Sync
$session-sync -y "Review cycle complete: {findings} findings, {fixed} fixed"
