feat: Enhance exploration schema and introduce automated review-fix workflow

- Added new fields to the exploration JSON schema: exploration_angle, exploration_index, and total_explorations for better tracking of exploration parameters. - Created a comprehensive review-fix command documentation to automate code review findings fixing, detailing the workflow, execution flow, agent roles, and error handling. - Introduced fix-plan-template.json for structured planning output, including execution strategy, group definitions, and risk assessments. - Added fix-progress-template.json to track progress for each group during the execution phase, ensuring real-time updates and status management.
2026-02-05 01:50:27 +08:00 · 2025-11-25 22:01:01 +08:00
parent 4bd732c4db
commit a6561a7d01
5 changed files with 1644 additions and 11 deletions
--- a/.claude/commands/workflow/review-fix.md
+++ b/.claude/commands/workflow/review-fix.md
@@ -0,0 +1,429 @@
+---
+name: review-fix
+description: Automated fixing of code review findings with AI-powered planning and coordinated execution. Uses intelligent grouping, multi-stage timeline coordination, and test-driven verification.
+argument-hint: "<export-file|review-dir> [--resume] [--max-iterations=N]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*), Edit(*), Write(*)
+---
+
+# Workflow Review-Fix Command
+
+## Quick Start
+
+```bash
+# Fix from exported findings file
+/workflow:review-fix .workflow/.reviews/session-WFS-123/fix-export-1706184622000.json
+
+# Fix from review directory (auto-discovers latest export)
+/workflow:review-fix .workflow/.reviews/session-WFS-123/
+
+# Resume interrupted fix session
+/workflow:review-fix --resume
+
+# Custom max retry attempts per finding
+/workflow:review-fix .workflow/.reviews/session-WFS-123/ --max-iterations=5
+```
+
+**Fix Source**: Exported findings from review cycle dashboard
+**Output Directory**: `{review-dir}/fixes/{fix-session-id}/` (fixed location)
+**Default Max Iterations**: 3 (per finding, adjustable)
+**CLI Tools**: @cli-planning-agent (planning), @cli-execute-agent (fixing)
+
+## What & Why
+
+### Core Concept
+Automated fix orchestrator with **two-phase architecture**: AI-powered planning followed by coordinated parallel/serial execution. Generates fix timeline with intelligent grouping and dependency analysis, then executes fixes with conservative test verification.
+
+**Fix Process**:
+- **Planning Phase**: AI analyzes findings, generates fix plan with grouping and execution strategy
+- **Execution Phase**: Main orchestrator coordinates agents per timeline stages
+- **No rigid structure**: Adapts to task requirements, not bound to fixed JSON format
+
+**vs Manual Fixing**:
+- **Manual**: Developer reviews findings one-by-one, fixes sequentially
+- **Automated**: AI groups related issues, executes in optimal parallel/serial order with automatic test verification
+
+### Value Proposition
+1. **Intelligent Planning**: AI-powered analysis identifies optimal grouping and execution strategy
+2. **Multi-stage Coordination**: Supports complex parallel + serial execution with dependency management
+3. **Conservative Safety**: Mandatory test verification with automatic rollback on failure
+4. **Real-time Visibility**: Dashboard shows planning progress, stage timeline, and active agents
+5. **Resume Support**: Checkpoint-based recovery for interrupted sessions
+
+### Orchestrator Boundary (CRITICAL)
+- **ONLY command** for automated review finding fixes
+- Manages: Planning phase coordination, stage-based execution, agent scheduling, progress tracking
+- Delegates: Fix planning to @cli-planning-agent, fix execution to @cli-execute-agent
+
+
+### Execution Flow 
+
+```
+1. Discovery & Initialization
+   └─ Validate export file, create fix session structure, initialize state files → Update dashboard
+
+2. Phase 2: Planning (@cli-planning-agent):
+   ├─ Analyze findings for patterns and dependencies
+   ├─ Group by file + dimension + root cause similarity
+   ├─ Determine execution strategy (parallel/serial/hybrid)
+   ├─ Generate fix timeline with stages
+   └─ Output: fix-plan.json → Update dashboard to execution phase
+
+3. Phase 3: Execution (Stage-based):
+   For each timeline stage:
+   ├─ Load groups for this stage
+   ├─ If parallel: Launch all group agents simultaneously
+   ├─ If serial: Execute groups sequentially
+   ├─ Each agent:
+   │  ├─ Analyze code context
+   │  ├─ Apply fix per strategy
+   │  ├─ Run affected tests
+   │  ├─ On test failure: Rollback, retry up to max_iterations
+   │  └─ On success: Commit, write completion JSON
+   ├─ Update fix-progress.json after each finding
+   └─ Advance to next stage
+
+4. Phase 4: Completion
+   └─ Aggregate results → Generate fix-summary.md → Update history → Output summary
+```
+
+### Agent Roles
+
+| Agent | Responsibility |
+|-------|---------------|
+| **Orchestrator** | Input validation, session management, planning coordination, stage-based execution scheduling, progress tracking, aggregation |
+| **@cli-planning-agent** | Findings analysis, intelligent grouping (file+dimension+root cause), execution strategy determination (parallel/serial/hybrid), timeline generation with dependency mapping |
+| **@cli-execute-agent** | Fix execution per group, code context analysis, Edit tool operations, test verification, git rollback on failure, completion JSON generation |
+
+## Enhanced Features
+
+### 1. Two-Phase Architecture
+
+**Phase Separation**:
+
+| Phase | Agent | Output | Purpose |
+|-------|-------|--------|---------|
+| **Planning** | @cli-planning-agent | fix-plan.json | Analyze findings, group intelligently, determine optimal execution strategy |
+| **Execution** | @cli-execute-agent | completions/*.json | Execute fixes per plan with test verification and rollback |
+
+**Benefits**:
+- Clear separation of concerns (analysis vs execution)
+- Reusable plans (can re-execute without re-planning)
+- Better error isolation (planning failures vs execution failures)
+
+### 2. Intelligent Grouping Strategy
+
+**Three-Level Grouping**:
+
+```javascript
+// Level 1: Primary grouping by file + dimension
+{file: "auth.ts", dimension: "security"} → Group A
+{file: "auth.ts", dimension: "quality"} → Group B
+{file: "query-builder.ts", dimension: "security"} → Group C
+
+// Level 2: Secondary grouping by root cause similarity
+Group A findings → Semantic similarity analysis (threshold 0.7)
+  → Sub-group A1: "missing-input-validation" (findings 1, 2)
+  → Sub-group A2: "insecure-crypto" (finding 3)
+
+// Level 3: Dependency analysis
+Sub-group A1 creates validation utilities
+Sub-group C4 depends on those utilities
+→ A1 must execute before C4 (serial stage dependency)
+```
+
+**Similarity Computation**:
+- Combine: `description + recommendation + category`
+- Vectorize: TF-IDF or LLM embedding
+- Cluster: Greedy algorithm with cosine similarity > 0.7
+
+### 3. Execution Strategy Determination
+
+**Strategy Types**:
+
+| Strategy | When to Use | Stage Structure |
+|----------|-------------|-----------------|
+| **Parallel** | All groups independent, different files | Single stage, all groups in parallel |
+| **Serial** | Strong dependencies, shared resources | Multiple stages, one group per stage |
+| **Hybrid** | Mixed dependencies | Multiple stages, parallel within stages |
+
+**Dependency Detection**:
+- Shared file modifications
+- Utility creation + usage patterns
+- Test dependency chains
+- Risk level clustering (high-risk groups isolated)
+
+### 4. Conservative Test Verification
+
+**Test Strategy** (per fix):
+
+```javascript
+// 1. Identify affected tests
+const testPattern = identifyTestPattern(finding.file);
+// e.g., "tests/auth/**/*.test.*" for src/auth/service.ts
+
+// 2. Run tests
+const result = await runTests(testPattern);
+
+// 3. Evaluate
+if (result.passRate < 100%) {
+  // Rollback
+  await gitCheckout(finding.file);
+
+  // Retry with failure context
+  if (attempts < maxIterations) {
+    const fixContext = analyzeFailure(result.stderr);
+    regenerateFix(finding, fixContext);
+    retry();
+  } else {
+    markFailed(finding.id);
+  }
+} else {
+  // Commit
+  await gitCommit(`Fix: ${finding.title} [${finding.id}]`);
+  markFixed(finding.id);
+}
+```
+
+**Pass Criteria**: 100% test pass rate (no partial fixes)
+
+## Core Responsibilities
+
+### Orchestrator
+
+**Phase 1: Discovery & Initialization**
+- Input validation: Check export file exists and is valid JSON
+- Auto-discovery: If review-dir provided, find latest `*-fix-export.json`
+- Session creation: Generate fix-session-id (`fix-{timestamp}`)
+- Directory structure: Create `{review-dir}/fixes/{fix-session-id}/` with subdirectories
+- State files: Initialize fix-state.json, fix-progress.json, active-fix-session.json
+- TodoWrite initialization: Set up 4-phase tracking
+
+**Phase 2: Planning Coordination**
+- Launch @cli-planning-agent with findings data and project context
+- Monitor planning progress (dashboard shows "Planning fixes..." indicator)
+- Validate fix-plan.json output (schema conformance)
+- Load plan into memory for execution phase
+- Update fix-state.json with plan_file reference
+- TodoWrite update: Mark planning complete, start execution
+
+**Phase 3: Execution Orchestration**
+- Load fix-plan.json timeline stages
+- For each stage:
+  - If parallel mode: Launch all group agents via `Promise.all()`
+  - If serial mode: Execute groups sequentially with `await`
+  - Assign agent IDs (agents update their fix-progress-{N}.json)
+- Handle agent failures gracefully (mark group as failed, continue)
+- Advance to next stage only when current stage complete
+- Dashboard polls and aggregates fix-progress-{N}.json files for display
+
+**Phase 4: Completion & Aggregation**
+- Collect final status from all fix-progress-{N}.json files
+- Generate fix-summary.md with timeline and results
+- Update fix-history.json with new session entry
+- Remove active-fix-session.json
+- TodoWrite completion: Mark all phases done
+- Output summary to user with dashboard link
+
+### Planning Agent (@cli-planning-agent)
+
+**Role**: Analyze findings, create execution strategy, initialize progress tracking
+
+**Orchestrator Provides**:
+- Review findings data (id, title, severity, file, description, recommendations)
+- Project context (structure, test framework, git status)
+- Output directory and template paths
+
+**Agent Outputs**:
+- fix-plan.json (groups, timeline, execution strategy)
+- fix-progress-{N}.json (one per group, initial state)
+
+### Execution Agent (@cli-execute-agent)
+
+**Role**: Execute fixes for assigned group, update progress in real-time
+
+**Orchestrator Provides**:
+- Group assignment (from fix-plan.json)
+- Fix strategy and risk assessment (from fix-plan.json)
+- Progress file path (fix-progress-{N}.json)
+
+**Agent Responsibilities**:
+- Read/update assigned progress file
+- Apply fixes with flow control tracking
+- Run tests and verify
+- Commit successful fixes to git
+
+## Reference
+
+### CLI Tool Configuration
+
+**Planning Agent**:
+```javascript
+{
+  subagent_type: "cli-planning-agent",
+  timeout: 300000, // 5 minutes for planning
+  description: "Generate fix plan for N code review findings"
+}
+```
+
+**Execution Agent**:
+```javascript
+{
+  subagent_type: "cli-execute-agent",
+  timeout: 3600000, // 60 minutes per group (adjustable)
+  description: "Fix M issues: {group_name}"
+}
+```
+
+### Output File Structure
+
+```
+.workflow/.reviews/{review-id}/
+├── fix-export-{timestamp}.json     # Exported findings (input)
+└── fixes/{fix-session-id}/
+    ├── fix-plan.json               # Planning agent output (execution plan)
+    ├── fix-progress-1.json         # Group 1 progress (planning agent init → agent updates)
+    ├── fix-progress-2.json         # Group 2 progress (planning agent init → agent updates)
+    ├── fix-progress-3.json         # Group 3 progress (planning agent init → agent updates)
+    ├── fix-summary.md              # Final report (orchestrator generates)
+    ├── active-fix-session.json     # Active session marker
+    └── fix-history.json            # All sessions history
+```
+
+**File Producers**:
+- **Planning Agent**: `fix-plan.json`, all `fix-progress-*.json` (initial state)
+- **Execution Agents**: Update assigned `fix-progress-{N}.json` in real-time
+- **Dashboard**: Reads `fix-plan.json` + all `fix-progress-*.json`, aggregates in-memory every 3 seconds
+
+### Agent Output Files
+
+**fix-plan.json**:
+- **Generated by**: @cli-planning-agent
+- **Template**: `~/.claude/workflows/cli-templates/fix-plan-template.json`
+- **Purpose**: Execution strategy, group definitions, timeline stages
+- **Orchestrator uses**: Load groups, determine execution order, assign agents
+
+**fix-progress-{N}.json** (one per group):
+- **Generated by**: @cli-planning-agent (initial) → @cli-execute-agent (updates)
+- **Template**: `~/.claude/workflows/cli-templates/fix-progress-template.json`
+- **Purpose**: Track individual group progress with flow control steps
+- **Consumed by**: Dashboard (reads all, aggregates in-memory)
+
+### Agent Invocation Template
+
+**Planning Agent**:
+```javascript
+Task({
+  subagent_type: "cli-planning-agent",
+  description: `Generate fix plan and initialize progress files for ${findings.length} findings`,
+  prompt: `
+    Analyze ${findings.length} code review findings and generate:
+    - fix-plan.json (execution strategy, groups, timeline)
+    - fix-progress-{N}.json for each group (initial state)
+
+    Input: ${JSON.stringify(findings, null, 2)}
+    Templates: @~/.claude/workflows/cli-templates/fix-plan-template.json
+              @~/.claude/workflows/cli-templates/fix-progress-template.json
+    Output Dir: ${sessionDir}
+  `
+})
+```
+
+**Execution Agent** (per group):
+```javascript
+Task({
+  subagent_type: "cli-execute-agent",
+  description: `Fix ${group.findings.length} issues: ${group.group_name}`,
+  prompt: `
+    Execute fixes for findings in ${group.progress_file}.
+    Read initial state, apply fixes, run tests, commit changes.
+    Update progress file in real-time with flow_control steps.
+
+    Group: ${group.group_id} (${group.group_name})
+    Progress File: ${group.progress_file}
+    Fix Strategy: ${JSON.stringify(group.fix_strategy, null, 2)}
+  `
+})
+```
+
+### Completion Conditions
+
+**Success Criteria**:
+- ✅ All findings processed (fixed or failed)
+- ✅ Success rate ≥ 70% (configurable threshold)
+- ✅ All fixed code has passing tests
+- ✅ All changes committed to git
+- ✅ All fix-progress-{N}.json files have status = "completed"
+- ✅ fix-summary.md generated
+- ✅ fix-history.json updated
+
+**Trigger Next Phase**:
+- Planning complete → Start execution
+- Stage complete → Advance to next stage
+- All stages complete → Generate completion report
+
+### Error Handling
+
+**Planning Failures**:
+- Invalid template → Abort with error message
+- Insufficient findings data → Request complete export
+- Planning timeout → Retry once, then fail gracefully
+
+**Execution Failures**:
+- Agent crash → Mark group as failed, continue with other groups
+- Test command not found → Skip test verification, warn user
+- Git operations fail → Abort with error, preserve state
+
+**Rollback Scenarios**:
+- Test failure after fix → Automatic `git checkout` rollback
+- Max iterations reached → Leave file unchanged, mark as failed
+- Unrecoverable error → Rollback entire group, save checkpoint
+
+### TodoWrite Structure
+
+**Initialization**:
+```javascript
+TodoWrite({
+  todos: [
+    {content: "Phase 1: Discovery & Initialization", status: "completed"},
+    {content: "Phase 2: Planning", status: "in_progress"},
+    {content: "Phase 3: Execution", status: "pending"},
+    {content: "Phase 4: Completion", status: "pending"}
+  ]
+});
+```
+
+**During Execution**:
+```javascript
+TodoWrite({
+  todos: [
+    {content: "Phase 1: Discovery & Initialization", status: "completed"},
+    {content: "Phase 2: Planning", status: "completed"},
+    {content: "Phase 3: Execution", status: "in_progress"},
+    {content: "  → Stage 1: Parallel execution (3 groups)", status: "completed"},
+    {content: "    • Group G1: Auth validation (2 findings)", status: "completed"},
+    {content: "    • Group G2: Query security (3 findings)", status: "completed"},
+    {content: "    • Group G3: Config quality (1 finding)", status: "completed"},
+    {content: "  → Stage 2: Serial execution (1 group)", status: "in_progress"},
+    {content: "    • Group G4: Dependent fixes (2 findings)", status: "in_progress"},
+    {content: "Phase 4: Completion", status: "pending"}
+  ]
+});
+```
+
+**Update Rules**:
+- Add stage items dynamically based on fix-plan.json timeline
+- Add group items per stage
+- Mark completed immediately after each group finishes
+- Update parent phase status when all child items complete
+
+## Best Practices
+
+1. **Trust AI Planning**: Planning agent's grouping and execution strategy are based on dependency analysis
+2. **Conservative Approach**: Test verification is mandatory - no fixes kept without passing tests
+3. **Parallel Efficiency**: Default 3 concurrent agents balances speed and resource usage
+4. **Monitor Dashboard**: Real-time stage timeline and agent status provide execution visibility
+5. **Resume Support**: Fix sessions can resume from checkpoints after interruption
+6. **Manual Review**: Always review failed fixes manually - may require architectural changes
+7. **Incremental Fixing**: Start with small batches (5-10 findings) before large-scale fixes
+
+
--- a/.claude/templates/review-cycle-dashboard.html
+++ b/.claude/templates/review-cycle-dashboard.html
--- a/.claude/workflows/cli-templates/fix-plan-template.json
+++ b/.claude/workflows/cli-templates/fix-plan-template.json
@@ -0,0 +1,75 @@
+{
+  "_template_description": "Template for fix planning output. Planning agent reads this template and generates actual fix-plan.json",
+  "_usage": "Planning agent should follow this structure when analyzing findings and creating fix plan",
+
+  "plan_id": "<string: plan-{timestamp}>",
+  "created_at": "<string: ISO8601 timestamp>",
+  "total_findings": "<number: total findings to fix>",
+
+  "execution_strategy": {
+    "approach": "<string: hybrid|parallel|serial>",
+    "parallel_limit": "<number: max concurrent agents, default 3>",
+    "total_stages": "<number: how many stages in timeline>",
+    "rationale": "<string: explain why this strategy was chosen>"
+  },
+
+  "groups": [
+    {
+      "group_id": "<string: unique group identifier like G1, G2, ...>",
+      "group_name": "<string: descriptive name for this group>",
+      "findings": ["<array of finding IDs>"],
+
+      "fix_strategy": {
+        "approach": "<string: high-level fix approach>",
+        "rationale": "<string: why these findings were grouped together>",
+        "complexity": "<string: low|medium|high>",
+        "estimated_duration_minutes": "<number: estimated time>",
+        "test_pattern": "<string: test file glob pattern like tests/auth/**/*.test.*>",
+        "rollback_plan": "<string: what to do if fix fails>"
+      },
+
+      "risk_assessment": {
+        "level": "<string: low|medium|high|critical>",
+        "concerns": ["<array of strings: potential risks>"],
+        "mitigation": "<string: how to mitigate risks>"
+      }
+    }
+  ],
+
+  "timeline": [
+    {
+      "stage": "<number: stage number 1-indexed>",
+      "groups": ["<array of group IDs to execute in this stage>"],
+      "execution_mode": "<string: parallel|serial>",
+      "depends_on": ["<optional: array of group IDs this stage depends on>"],
+      "rationale": "<string: why these groups are in this stage with this mode>"
+    }
+  ],
+
+  "_instructions": {
+    "grouping_principles": [
+      "Group findings in the same file with same dimension",
+      "Group findings with similar root causes (high semantic similarity)",
+      "Consider file dependencies and execution order",
+      "Balance group sizes for efficient parallel execution"
+    ],
+    "execution_strategy_guidelines": [
+      "Use parallel for independent groups in different files",
+      "Use serial for dependent changes (e.g., shared utilities)",
+      "Limit parallelism to 3 concurrent agents to avoid resource contention",
+      "High-risk groups should be isolated for careful monitoring"
+    ],
+    "test_strategy_guidelines": [
+      "Identify test files related to changed code",
+      "Use specific patterns for faster test execution",
+      "Ensure test coverage captures all fix impacts",
+      "Define clear pass criteria (usually 100% pass rate)"
+    ],
+    "risk_assessment_guidelines": [
+      "Low: Simple fixes with comprehensive test coverage",
+      "Medium: Moderate changes affecting multiple components",
+      "High: Core logic changes or security-critical fixes",
+      "Critical: Database schema changes or breaking API changes"
+    ]
+  }
+}
--- a/.claude/workflows/cli-templates/fix-progress-template.json
+++ b/.claude/workflows/cli-templates/fix-progress-template.json
@@ -0,0 +1,48 @@
+{
+  "$schema": "fix-progress-template.json",
+  "$comment": "Template for fix-progress-{N}.json - one per group, initialized by planning agent, updated by execution agent",
+
+  "progress_id": "fix-progress-N",
+  "group_id": "GN",
+  "group_name": "Group name from fix plan",
+  "status": "pending",
+  "phase": "waiting",
+
+  "assigned_agent": null,
+  "started_at": null,
+  "last_update": "ISO 8601 timestamp",
+
+  "findings": [
+    {
+      "finding_id": "finding-uuid",
+      "finding_title": "Finding title from review",
+      "file": "path/to/file.ts",
+      "line": 0,
+      "status": "pending",
+      "result": null,
+      "attempts": 0,
+      "started_at": null,
+      "completed_at": null,
+      "commit_hash": null,
+      "test_passed": null
+    }
+  ],
+
+  "summary": {
+    "total_findings": 0,
+    "pending": 0,
+    "in_progress": 0,
+    "fixed": 0,
+    "failed": 0,
+    "percent_complete": 0.0
+  },
+
+  "current_finding": null,
+
+  "flow_control": {
+    "implementation_approach": [],
+    "current_step": null
+  },
+
+  "errors": []
+}
--- a/.claude/workflows/cli-templates/schemas/explore-json-schema.json
+++ b/.claude/workflows/cli-templates/schemas/explore-json-schema.json
@@ -80,6 +80,22 @@
          "const": "cli-explore-agent",
          "description": "Agent that performed exploration"
        },
+        "exploration_angle": {
+          "type": "string",
+          "description": "Agent-chosen exploration angle (e.g., 'architecture', 'security', 'dataflow')"
+        },
+        "exploration_index": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 4,
+          "description": "Exploration index (1-4) in parallel exploration set"
+        },
+        "total_explorations": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 4,
+          "description": "Total number of parallel explorations"
+        },
        "duration_seconds": {
          "type": "integer",
          "description": "Exploration duration in seconds"