From 3a9a66aa3bae5e728c7fcf250ecafde9ba421ad8 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 14 Feb 2026 23:09:10 +0800 Subject: [PATCH] Refactor: Remove obsolete TDD coverage analysis, test concept enhancement, context gathering, and task generation commands - Deleted the following command files: - tdd-coverage-analysis.md - test-concept-enhanced.md - test-context-gather.md - test-task-generate.md Enhancement: Update FloatingPanel component styles - Adjusted FloatingPanel backdrop styles for improved layout - Modified height calculation to utilize full viewport height below the toolbar --- .claude/commands/workflow/review-cycle-fix.md | 765 ----------------- .../commands/workflow/review-module-cycle.md | 771 ----------------- .../commands/workflow/review-session-cycle.md | 782 ------------------ .../workflow/tools/code-validation-gate.md | 391 --------- .../workflow/tools/conflict-resolution.md | 604 -------------- .../commands/workflow/tools/context-gather.md | 408 --------- .../workflow/tools/task-generate-agent.md | 731 ---------------- .../workflow/tools/task-generate-tdd.md | 758 ----------------- .../workflow/tools/tdd-coverage-analysis.md | 309 ------- .../workflow/tools/test-concept-enhanced.md | 164 ---- .../workflow/tools/test-context-gather.md | 235 ------ .../workflow/tools/test-task-generate.md | 416 ---------- .../components/cli-viewer/LayoutContainer.tsx | 42 +- .../terminal-dashboard/FloatingPanel.tsx | 6 +- ccw/frontend/src/stores/viewerStore.ts | 12 +- 15 files changed, 49 insertions(+), 6345 deletions(-) delete mode 100644 .claude/commands/workflow/review-cycle-fix.md delete mode 100644 .claude/commands/workflow/review-module-cycle.md delete mode 100644 .claude/commands/workflow/review-session-cycle.md delete mode 100644 .claude/commands/workflow/tools/code-validation-gate.md delete mode 100644 .claude/commands/workflow/tools/conflict-resolution.md delete mode 100644 .claude/commands/workflow/tools/context-gather.md delete mode 100644 .claude/commands/workflow/tools/task-generate-agent.md delete mode 100644 .claude/commands/workflow/tools/task-generate-tdd.md delete mode 100644 .claude/commands/workflow/tools/tdd-coverage-analysis.md delete mode 100644 .claude/commands/workflow/tools/test-concept-enhanced.md delete mode 100644 .claude/commands/workflow/tools/test-context-gather.md delete mode 100644 .claude/commands/workflow/tools/test-task-generate.md diff --git a/.claude/commands/workflow/review-cycle-fix.md b/.claude/commands/workflow/review-cycle-fix.md deleted file mode 100644 index 103a688d..00000000 --- a/.claude/commands/workflow/review-cycle-fix.md +++ /dev/null @@ -1,765 +0,0 @@ ---- -name: review-cycle-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: " [--resume] [--max-iterations=N] [--batch-size=N]" -allowed-tools: Skill(*), TodoWrite(*), Read(*), Bash(*), Task(*), Edit(*), Write(*) ---- - -# Workflow Review-Cycle-Fix Command - -## Quick Start - -```bash -# Fix from exported findings file (session-based path) -/workflow:review-cycle-fix .workflow/active/WFS-123/.review/fix-export-1706184622000.json - -# Fix from review directory (auto-discovers latest export) -/workflow:review-cycle-fix .workflow/active/WFS-123/.review/ - -# Resume interrupted fix session -/workflow:review-cycle-fix --resume - -# Custom max retry attempts per finding -/workflow:review-cycle-fix .workflow/active/WFS-123/.review/ --max-iterations=5 - -# Custom batch size for parallel planning (default: 5 findings per batch) -/workflow:review-cycle-fix .workflow/active/WFS-123/.review/ --batch-size=3 -``` - -**Fix Source**: Exported findings from review cycle dashboard -**Output Directory**: `{review-dir}/fixes/{fix-session-id}/` (within session .review/) -**Default Max Iterations**: 3 (per finding, adjustable) -**Default Batch Size**: 5 (findings per planning batch, adjustable) -**Max Parallel Agents**: 10 (concurrent planning agents) -**CLI Tools**: @cli-planning-agent (planning), @cli-execute-agent (fixing) - -## What & Why - -### Core Concept -Automated fix orchestrator with **parallel planning architecture**: Multiple AI agents analyze findings concurrently in batches, then coordinate parallel/serial execution. Generates fix timeline with intelligent grouping and dependency analysis, executes fixes with conservative test verification. - -**Fix Process**: -- **Batching Phase (1.5)**: Orchestrator groups findings by file+dimension similarity, creates batches -- **Planning Phase (2)**: Up to 10 agents plan batches in parallel, generate partial plans, orchestrator aggregates -- **Execution Phase (3)**: Main orchestrator coordinates agents per aggregated timeline stages -- **Parallel Efficiency**: Customizable batch size (default: 5), MAX_PARALLEL=10 agents -- **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, multiple agents plan in parallel, executes in optimal parallel/serial order with automatic test verification - -### Value Proposition -1. **Parallel Planning**: Multiple agents analyze findings concurrently, reducing planning time for large batches (10+ findings) -2. **Intelligent Batching**: Semantic similarity grouping ensures related findings are analyzed together -3. **Multi-stage Coordination**: Supports complex parallel + serial execution with cross-batch dependency management -4. **Conservative Safety**: Mandatory test verification with automatic rollback on failure -5. **Resume Support**: Checkpoint-based recovery for interrupted sessions - -### Orchestrator Boundary (CRITICAL) -- **ONLY command** for automated review finding fixes -- Manages: Intelligent batching (Phase 1.5), parallel planning coordination (launch N agents), plan aggregation, stage-based execution, agent scheduling, progress tracking -- Delegates: Batch planning to @cli-planning-agent, fix execution to @cli-execute-agent - - -### Execution Flow - -``` -Phase 1: Discovery & Initialization - └─ Validate export file, create fix session structure, initialize state files - -Phase 1.5: Intelligent Grouping & Batching - ├─ Analyze findings metadata (file, dimension, severity) - ├─ Group by semantic similarity (file proximity + dimension affinity) - ├─ Create batches respecting --batch-size (default: 5) - └─ Output: Finding batches for parallel planning - -Phase 2: Parallel Planning Coordination (@cli-planning-agent × N) - ├─ Launch MAX_PARALLEL planning agents concurrently (default: 10) - ├─ Each agent processes one batch: - │ ├─ 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: partial-plan-{batch-id}.json - ├─ Collect results from all agents - └─ Aggregate: Merge partial plans → fix-plan.json (resolve cross-batch dependencies) - -Phase 3: Execution Orchestration (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, update fix-progress-{N}.json - └─ Advance to next stage - -Phase 4: Completion & Aggregation - └─ Aggregate results → Generate fix-summary.md → Update history → Output summary - -Phase 5: Session Completion (Optional) - └─ If all fixes successful → Prompt to complete workflow session -``` - -### Agent Roles - -| Agent | Responsibility | -|-------|---------------| -| **Orchestrator** | Input validation, session management, intelligent batching (Phase 1.5), parallel planning coordination (launch N agents), plan aggregation (merge partial plans, resolve cross-batch dependencies), stage-based execution scheduling, progress tracking, result aggregation | -| **@cli-planning-agent** | Batch findings analysis, intelligent grouping (file+dimension+root cause), execution strategy determination (parallel/serial/hybrid), timeline generation with dependency mapping, partial plan output | -| **@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. Parallel Planning Architecture - -**Batch Processing Strategy**: - -| Phase | Agent Count | Input | Output | Purpose | -|-------|-------------|-------|--------|---------| -| **Batching (1.5)** | Orchestrator | All findings | Finding batches | Semantic grouping by file+dimension, respecting --batch-size | -| **Planning (2)** | N agents (≤10) | 1 batch each | partial-plan-{batch-id}.json | Analyze batch in parallel, generate execution groups and timeline | -| **Aggregation (2)** | Orchestrator | All partial plans | fix-plan.json | Merge timelines, resolve cross-batch dependencies | -| **Execution (3)** | M agents (dynamic) | 1 group each | fix-progress-{N}.json | Execute fixes per aggregated plan with test verification | - -**Benefits**: -- **Speed**: N agents plan concurrently, reducing planning time for large batches -- **Scalability**: MAX_PARALLEL=10 prevents resource exhaustion -- **Flexibility**: Batch size customizable via --batch-size (default: 5) -- **Isolation**: Each planning agent focuses on related findings (semantic grouping) -- **Reusable**: Aggregated plan can be re-executed without re-planning - -### 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 active-fix-session.json (session marker) -- TodoWrite initialization: Set up 5-phase tracking (including Phase 1.5) - -**Phase 1.5: Intelligent Grouping & Batching** -- Load all findings metadata (id, file, dimension, severity, title) -- Semantic similarity analysis: - - Primary: Group by file proximity (same file or related modules) - - Secondary: Group by dimension affinity (same review dimension) - - Tertiary: Analyze title/description similarity (root cause clustering) -- Create batches respecting --batch-size (default: 5 findings per batch) -- Balance workload: Distribute high-severity findings across batches -- Output: Array of finding batches for parallel planning - -**Phase 2: Parallel Planning Coordination** -- Determine concurrency: MIN(batch_count, MAX_PARALLEL=10) -- For each batch chunk (≤10 batches): - - Launch all agents in parallel with run_in_background=true - - Pass batch findings + project context + batch_id to each agent - - Each agent outputs: partial-plan-{batch-id}.json -- Collect results via TaskOutput (blocking until all complete) -- Aggregate partial plans: - - Merge execution groups (renumber group_ids sequentially: G1, G2, ...) - - Merge timelines (detect cross-batch dependencies, adjust stages) - - Resolve conflicts (same file in multiple batches → serialize) -- Generate final fix-plan.json with aggregated metadata -- 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 - -**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 - -**Phase 5: Session Completion (Optional)** -- If all findings fixed successfully (no failures): - - Prompt user: "All fixes complete. Complete workflow session? [Y/n]" - - If confirmed: Execute `/workflow:session:complete` to archive session with lessons learned -- If partial success (some failures): - - Output: "Some findings failed. Review fix-summary.md before completing session." - - Do NOT auto-complete session - -### Output File Structure - -``` -.workflow/active/WFS-{session-id}/.review/ -├── fix-export-{timestamp}.json # Exported findings (input) -└── fixes/{fix-session-id}/ - ├── partial-plan-1.json # Batch 1 partial plan (planning agent 1 output) - ├── partial-plan-2.json # Batch 2 partial plan (planning agent 2 output) - ├── partial-plan-N.json # Batch N partial plan (planning agent N output) - ├── fix-plan.json # Aggregated execution plan (orchestrator merges partials) - ├── 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**: -- **Orchestrator**: Batches findings (Phase 1.5), aggregates partial plans → `fix-plan.json` (Phase 2), launches parallel planning agents -- **Planning Agents (N)**: Each outputs `partial-plan-{batch-id}.json` + initializes `fix-progress-*.json` for assigned groups -- **Execution Agents (M)**: Update assigned `fix-progress-{N}.json` in real-time - - -### Agent Invocation Template - -**Phase 1.5: Intelligent Batching** (Orchestrator): -```javascript -// Load findings -const findings = JSON.parse(Read(exportFile)); -const batchSize = flags.batchSize || 5; - -// Semantic similarity analysis: group by file+dimension -const batches = []; -const grouped = new Map(); // key: "${file}:${dimension}" - -for (const finding of findings) { - const key = `${finding.file || 'unknown'}:${finding.dimension || 'general'}`; - if (!grouped.has(key)) grouped.set(key, []); - grouped.get(key).push(finding); -} - -// Create batches respecting batchSize -for (const [key, group] of grouped) { - while (group.length > 0) { - const batch = group.splice(0, batchSize); - batches.push({ - batch_id: batches.length + 1, - findings: batch, - metadata: { primary_file: batch[0].file, primary_dimension: batch[0].dimension } - }); - } -} - -console.log(`Created ${batches.length} batches (${batchSize} findings per batch)`); -``` - -**Phase 2: Parallel Planning** (Orchestrator launches N agents): -```javascript -const MAX_PARALLEL = 10; -const partialPlans = []; - -// Process batches in chunks of MAX_PARALLEL -for (let i = 0; i < batches.length; i += MAX_PARALLEL) { - const chunk = batches.slice(i, i + MAX_PARALLEL); - const taskIds = []; - - // Launch agents in parallel (run_in_background=true) - for (const batch of chunk) { - const taskId = Task({ - subagent_type: "cli-planning-agent", - run_in_background: true, - description: `Plan batch ${batch.batch_id}: ${batch.findings.length} findings`, - prompt: planningPrompt(batch) // See Planning Agent template below - }); - taskIds.push({ taskId, batch }); - } - - console.log(`Launched ${taskIds.length} planning agents...`); - - // Collect results from this chunk (blocking) - for (const { taskId, batch } of taskIds) { - const result = TaskOutput({ task_id: taskId, block: true }); - const partialPlan = JSON.parse(Read(`${sessionDir}/partial-plan-${batch.batch_id}.json`)); - partialPlans.push(partialPlan); - updateTodo(`Batch ${batch.batch_id}`, 'completed'); - } -} - -// Aggregate partial plans → fix-plan.json -let groupCounter = 1; -const groupIdMap = new Map(); - -for (const partial of partialPlans) { - for (const group of partial.groups) { - const newGroupId = `G${groupCounter}`; - groupIdMap.set(`${partial.batch_id}:${group.group_id}`, newGroupId); - aggregatedPlan.groups.push({ ...group, group_id: newGroupId, progress_file: `fix-progress-${groupCounter}.json` }); - groupCounter++; - } -} - -// Merge timelines, resolve cross-batch conflicts (shared files → serialize) -let stageCounter = 1; -for (const partial of partialPlans) { - for (const stage of partial.timeline) { - aggregatedPlan.timeline.push({ - ...stage, stage_id: stageCounter, - groups: stage.groups.map(gid => groupIdMap.get(`${partial.batch_id}:${gid}`)) - }); - stageCounter++; - } -} - -// Write aggregated plan + initialize progress files -Write(`${sessionDir}/fix-plan.json`, JSON.stringify(aggregatedPlan, null, 2)); -for (let i = 1; i <= aggregatedPlan.groups.length; i++) { - Write(`${sessionDir}/fix-progress-${i}.json`, JSON.stringify(initProgressFile(aggregatedPlan.groups[i-1]), null, 2)); -} -``` - -**Planning Agent (Batch Mode - Partial Plan Only)**: -```javascript -Task({ - subagent_type: "cli-planning-agent", - run_in_background: true, - description: `Plan batch ${batch.batch_id}: ${batch.findings.length} findings`, - prompt: ` -## Task Objective -Analyze code review findings in batch ${batch.batch_id} and generate **partial** execution plan. - -## Input Data -Review Session: ${reviewId} -Fix Session ID: ${fixSessionId} -Batch ID: ${batch.batch_id} -Batch Findings: ${batch.findings.length} - -Findings: -${JSON.stringify(batch.findings, null, 2)} - -Project Context: -- Structure: ${projectStructure} -- Test Framework: ${testFramework} -- Git Status: ${gitStatus} - -## Output Requirements - -### 1. partial-plan-${batch.batch_id}.json -Generate partial execution plan with structure: -{ - "batch_id": ${batch.batch_id}, - "groups": [...], // Groups created from batch findings (use local IDs: G1, G2, ...) - "timeline": [...], // Local timeline for this batch only - "metadata": { - "findings_count": ${batch.findings.length}, - "groups_count": N, - "created_at": "ISO-8601-timestamp" - } -} - -**Key Generation Rules**: -- **Groups**: Create groups with local IDs (G1, G2, ...) using intelligent grouping (file+dimension+root cause) -- **Timeline**: Define stages for this batch only (local dependencies within batch) -- **Progress Files**: DO NOT generate fix-progress-*.json here (orchestrator handles after aggregation) - -## Analysis Requirements - -### Intelligent Grouping Strategy -Group findings using these criteria (in priority order): - -1. **File Proximity**: Findings in same file or related files -2. **Dimension Affinity**: Same dimension (security, performance, etc.) -3. **Root Cause Similarity**: Similar underlying issues -4. **Fix Approach Commonality**: Can be fixed with similar approach - -**Grouping Guidelines**: -- Optimal group size: 2-5 findings per group -- Avoid cross-cutting concerns in same group -- Consider test isolation (different test suites → different groups) -- Balance workload across groups for parallel execution - -### Execution Strategy Determination (Local Only) - -**Parallel Mode**: Use when groups are independent, no shared files -**Serial Mode**: Use when groups have dependencies or shared resources -**Hybrid Mode**: Use for mixed dependency graphs (recommended for most cases) - -**Dependency Analysis**: -- Identify shared files between groups -- Detect test dependency chains -- Evaluate risk of concurrent modifications - -### Risk Assessment - -For each group, evaluate: -- **Complexity**: Based on code structure, file size, existing tests -- **Impact Scope**: Number of files affected, API surface changes -- **Rollback Feasibility**: Ease of reverting changes if tests fail - -### Test Strategy - -For each group, determine: -- **Test Pattern**: Glob pattern matching affected tests -- **Pass Criteria**: All tests must pass (100% pass rate) -- **Test Command**: Infer from project (package.json, pytest.ini, etc.) - -## Output Files - -Write to ${sessionDir}: -- ./partial-plan-${batch.batch_id}.json - -## Quality Checklist - -Before finalizing outputs: -- ✅ All batch findings assigned to exactly one group -- ✅ Group dependencies (within batch) correctly identified -- ✅ Timeline stages respect local dependencies -- ✅ Test patterns are valid and specific -- ✅ Risk assessments are realistic - ` -}) -``` - -**Execution Agent** (per group): -```javascript -Task({ - subagent_type: "cli-execute-agent", - description: `Fix ${group.findings.length} issues: ${group.group_name}`, - prompt: ` -## Task Objective -Execute fixes for code review findings in group ${group.group_id}. Update progress file in real-time with flow control tracking. - -## Assignment -- Group ID: ${group.group_id} -- Group Name: ${group.group_name} -- Progress File: ${sessionDir}/${group.progress_file} -- Findings Count: ${group.findings.length} -- Max Iterations: ${maxIterations} (per finding) - -## Fix Strategy -${JSON.stringify(group.fix_strategy, null, 2)} - -## Risk Assessment -${JSON.stringify(group.risk_assessment, null, 2)} - -## Execution Flow - -### Initialization (Before Starting) - -1. Read ${group.progress_file} to load initial state -2. Update progress file: - - assigned_agent: "${agentId}" - - status: "in-progress" - - started_at: Current ISO 8601 timestamp - - last_update: Current ISO 8601 timestamp -3. Write updated state back to ${group.progress_file} - -### Main Execution Loop - -For EACH finding in ${group.progress_file}.findings: - -#### Step 1: Analyze Context - -**Before Step**: -- Update finding: status→"in-progress", started_at→now() -- Update current_finding: Populate with finding details, status→"analyzing", action→"Reading file and understanding code structure" -- Update phase→"analyzing" -- Update flow_control: Add "analyze_context" step to implementation_approach (status→"in-progress"), set current_step→"analyze_context" -- Update last_update→now(), write to ${group.progress_file} - -**Action**: -- Read file: finding.file -- Understand code structure around line: finding.line -- Analyze surrounding context (imports, dependencies, related functions) -- Review recommendations: finding.recommendations - -**After Step**: -- Update flow_control: Mark "analyze_context" step as "completed" with completed_at→now() -- Update last_update→now(), write to ${group.progress_file} - -#### Step 2: Apply Fix - -**Before Step**: -- Update current_finding: status→"fixing", action→"Applying code changes per recommendations" -- Update phase→"fixing" -- Update flow_control: Add "apply_fix" step to implementation_approach (status→"in-progress"), set current_step→"apply_fix" -- Update last_update→now(), write to ${group.progress_file} - -**Action**: -- Use Edit tool to implement code changes per finding.recommendations -- Follow fix_strategy.approach -- Maintain code style and existing patterns - -**After Step**: -- Update flow_control: Mark "apply_fix" step as "completed" with completed_at→now() -- Update last_update→now(), write to ${group.progress_file} - -#### Step 3: Test Verification - -**Before Step**: -- Update current_finding: status→"testing", action→"Running test suite to verify fix" -- Update phase→"testing" -- Update flow_control: Add "run_tests" step to implementation_approach (status→"in-progress"), set current_step→"run_tests" -- Update last_update→now(), write to ${group.progress_file} - -**Action**: -- Run tests using fix_strategy.test_pattern -- Require 100% pass rate -- Capture test output - -**On Test Failure**: -- Git rollback: \`git checkout -- \${finding.file}\` -- Increment finding.attempts -- Update flow_control: Mark "run_tests" step as "failed" with completed_at→now() -- Update errors: Add entry (finding_id, error_type→"test_failure", message, timestamp) -- If finding.attempts < ${maxIterations}: - - Reset flow_control: implementation_approach→[], current_step→null - - Retry from Step 1 -- Else: - - Update finding: status→"completed", result→"failed", error_message→"Max iterations reached", completed_at→now() - - Update summary counts, move to next finding - -**On Test Success**: -- Update flow_control: Mark "run_tests" step as "completed" with completed_at→now() -- Update last_update→now(), write to ${group.progress_file} -- Proceed to Step 4 - -#### Step 4: Commit Changes - -**Before Step**: -- Update current_finding: status→"committing", action→"Creating git commit for successful fix" -- Update phase→"committing" -- Update flow_control: Add "commit_changes" step to implementation_approach (status→"in-progress"), set current_step→"commit_changes" -- Update last_update→now(), write to ${group.progress_file} - -**Action**: -- Git commit: \`git commit -m "fix(${finding.dimension}): ${finding.title} [${finding.id}]"\` -- Capture commit hash - -**After Step**: -- Update finding: status→"completed", result→"fixed", commit_hash→, test_passed→true, completed_at→now() -- Update flow_control: Mark "commit_changes" step as "completed" with completed_at→now() -- Update last_update→now(), write to ${group.progress_file} - -#### After Each Finding - -- Update summary: Recalculate counts (pending/in_progress/fixed/failed) and percent_complete -- If all findings completed: Clear current_finding, reset flow_control -- Update last_update→now(), write to ${group.progress_file} - -### Final Completion - -When all findings processed: -- Update status→"completed", phase→"done", summary.percent_complete→100.0 -- Update last_update→now(), write final state to ${group.progress_file} - -## Critical Requirements - -### Progress File Updates -- **MUST update after every significant action** (before/after each step) -- **Always maintain complete structure** - never write partial updates -- **Use ISO 8601 timestamps** - e.g., "2025-01-25T14:36:00Z" - -### Flow Control Format -Follow action-planning-agent flow_control.implementation_approach format: -- step: Identifier (e.g., "analyze_context", "apply_fix") -- action: Human-readable description -- status: "pending" | "in-progress" | "completed" | "failed" -- started_at: ISO 8601 timestamp or null -- completed_at: ISO 8601 timestamp or null - -### Error Handling -- Capture all errors in errors[] array -- Never leave progress file in invalid state -- Always write complete updates, never partial -- On unrecoverable error: Mark group as failed, preserve state - -## Test Patterns -Use fix_strategy.test_pattern to run affected tests: -- Pattern: ${group.fix_strategy.test_pattern} -- Command: Infer from project (npm test, pytest, etc.) -- Pass Criteria: 100% pass rate required - ` -}) -``` - - - -### Error Handling - -**Batching Failures (Phase 1.5)**: -- Invalid findings data → Abort with error message -- Empty batches after grouping → Warn and skip empty batches - -**Planning Failures (Phase 2)**: -- Planning agent timeout → Mark batch as failed, continue with other batches -- Partial plan missing → Skip batch, warn user -- Agent crash → Collect available partial plans, proceed with aggregation -- All agents fail → Abort entire fix session with error -- Aggregation conflicts → Apply conflict resolution (serialize conflicting groups) - -**Execution Failures (Phase 3)**: -- 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 (after Phase 1.5 batching)**: -```javascript -TodoWrite({ - todos: [ - {content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Discovering"}, - {content: "Phase 1.5: Intelligent Batching", status: "completed", activeForm: "Batching"}, - {content: "Phase 2: Parallel Planning", status: "in_progress", activeForm: "Planning"}, - {content: " → Batch 1: 4 findings (auth.ts:security)", status: "pending", activeForm: "Planning batch 1"}, - {content: " → Batch 2: 3 findings (query.ts:security)", status: "pending", activeForm: "Planning batch 2"}, - {content: " → Batch 3: 2 findings (config.ts:quality)", status: "pending", activeForm: "Planning batch 3"}, - {content: "Phase 3: Execution", status: "pending", activeForm: "Executing"}, - {content: "Phase 4: Completion", status: "pending", activeForm: "Completing"} - ] -}); -``` - -**During Planning (parallel agents running)**: -```javascript -TodoWrite({ - todos: [ - {content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Discovering"}, - {content: "Phase 1.5: Intelligent Batching", status: "completed", activeForm: "Batching"}, - {content: "Phase 2: Parallel Planning", status: "in_progress", activeForm: "Planning"}, - {content: " → Batch 1: 4 findings (auth.ts:security)", status: "completed", activeForm: "Planning batch 1"}, - {content: " → Batch 2: 3 findings (query.ts:security)", status: "in_progress", activeForm: "Planning batch 2"}, - {content: " → Batch 3: 2 findings (config.ts:quality)", status: "in_progress", activeForm: "Planning batch 3"}, - {content: "Phase 3: Execution", status: "pending", activeForm: "Executing"}, - {content: "Phase 4: Completion", status: "pending", activeForm: "Completing"} - ] -}); -``` - -**During Execution**: -```javascript -TodoWrite({ - todos: [ - {content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Discovering"}, - {content: "Phase 1.5: Intelligent Batching", status: "completed", activeForm: "Batching"}, - {content: "Phase 2: Parallel Planning (3 batches → 5 groups)", status: "completed", activeForm: "Planning"}, - {content: "Phase 3: Execution", status: "in_progress", activeForm: "Executing"}, - {content: " → Stage 1: Parallel execution (3 groups)", status: "completed", activeForm: "Executing stage 1"}, - {content: " • Group G1: Auth validation (2 findings)", status: "completed", activeForm: "Fixing G1"}, - {content: " • Group G2: Query security (3 findings)", status: "completed", activeForm: "Fixing G2"}, - {content: " • Group G3: Config quality (1 finding)", status: "completed", activeForm: "Fixing G3"}, - {content: " → Stage 2: Serial execution (1 group)", status: "in_progress", activeForm: "Executing stage 2"}, - {content: " • Group G4: Dependent fixes (2 findings)", status: "in_progress", activeForm: "Fixing G4"}, - {content: "Phase 4: Completion", status: "pending", activeForm: "Completing"} - ] -}); -``` - -**Update Rules**: -- Add batch items dynamically during Phase 1.5 -- Mark batch items completed as parallel agents return results -- Add stage/group items dynamically after Phase 2 plan aggregation -- Mark completed immediately after each group finishes -- Update parent phase status when all child items complete - -## Post-Completion Expansion - -完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"` - -## Best Practices - -1. **Leverage Parallel Planning**: For 10+ findings, parallel batching significantly reduces planning time -2. **Tune Batch Size**: Use `--batch-size` to control granularity (smaller batches = more parallelism, larger = better grouping context) -3. **Conservative Approach**: Test verification is mandatory - no fixes kept without passing tests -4. **Parallel Efficiency**: MAX_PARALLEL=10 for planning agents, 3 concurrent execution agents per stage -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 - -## Related Commands - -### View Fix Progress -Use `ccw view` to open the workflow dashboard in browser: - -```bash -ccw view -``` \ No newline at end of file diff --git a/.claude/commands/workflow/review-module-cycle.md b/.claude/commands/workflow/review-module-cycle.md deleted file mode 100644 index 8748487a..00000000 --- a/.claude/commands/workflow/review-module-cycle.md +++ /dev/null @@ -1,771 +0,0 @@ ---- -name: review-module-cycle -description: Independent multi-dimensional code review for specified modules/files. Analyzes specific code paths across 7 dimensions with hybrid parallel-iterative execution, independent of workflow sessions. -argument-hint: " [--dimensions=security,architecture,...] [--max-iterations=N]" -allowed-tools: Skill(*), TodoWrite(*), Read(*), Bash(*), Task(*) ---- - -# Workflow Review-Module-Cycle Command - -## Quick Start - -```bash -# Review specific module (all 7 dimensions) -/workflow:review-module-cycle src/auth/** - -# Review multiple modules -/workflow:review-module-cycle src/auth/**,src/payment/** - -# Review with custom dimensions -/workflow:review-module-cycle src/payment/** --dimensions=security,architecture,quality - -# Review specific files -/workflow:review-module-cycle src/payment/processor.ts,src/payment/validator.ts -``` - -**Review Scope**: Specified modules/files only (independent of git history) -**Session Requirement**: Auto-creates workflow session via `/workflow:session:start` -**Output Directory**: `.workflow/active/WFS-{session-id}/.review/` (session-based) -**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices -**Max Iterations**: 3 (adjustable via --max-iterations) -**Default Iterations**: 1 (deep-dive runs once; use --max-iterations=0 to skip) -**CLI Tools**: Gemini → Qwen → Codex (fallback chain) - -## What & Why - -### Core Concept -Independent multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment of **specific modules or files**. - -**Review Scope**: -- **Module-based**: Reviews specified file patterns (e.g., `src/auth/**`, `*.ts`) -- **Session-integrated**: Runs within workflow session context for unified tracking -- **Output location**: `.review/` subdirectory within active session - -**vs Session Review**: -- **Session Review** (`review-session-cycle`): Reviews git changes within a workflow session -- **Module Review** (`review-module-cycle`): Reviews any specified code paths, regardless of git history -- **Common output**: Both use same `.review/` directory structure within session - -### Value Proposition -1. **Module-Focused Review**: Target specific code areas independent of git history -2. **Session-Integrated**: Review results tracked within workflow session for unified management -3. **Comprehensive Coverage**: Same 7 specialized dimensions as session review -4. **Intelligent Prioritization**: Automatic identification of critical issues and cross-cutting concerns -5. **Unified Archive**: Review results archived with session for historical reference - -### Orchestrator Boundary (CRITICAL) -- **ONLY command** for independent multi-dimensional module review -- Manages: dimension coordination, aggregation, iteration control, progress tracking -- Delegates: Code exploration and analysis to @cli-explore-agent, dimension-specific reviews via Deep Scan mode - -## How It Works - -### Execution Flow - -``` -Phase 1: Discovery & Initialization - └─ Resolve file patterns, validate paths, initialize state, create output structure - -Phase 2: Parallel Reviews (for each dimension) - ├─ Launch 7 review agents simultaneously - ├─ Each executes CLI analysis via Gemini/Qwen on specified files - ├─ Generate dimension JSON + markdown reports - └─ Update review-progress.json - -Phase 3: Aggregation - ├─ Load all dimension JSON files - ├─ Calculate severity distribution (critical/high/medium/low) - ├─ Identify cross-cutting concerns (files in 3+ dimensions) - └─ Decision: - ├─ Critical findings OR high > 5 OR critical files → Phase 4 (Iterate) - └─ Else → Phase 5 (Complete) - -Phase 4: Iterative Deep-Dive (optional) - ├─ Select critical findings (max 5 per iteration) - ├─ Launch deep-dive agents for root cause analysis - ├─ Generate remediation plans with impact assessment - ├─ Re-assess severity based on analysis - └─ Loop until no critical findings OR max iterations - -Phase 5: Completion - └─ Finalize review-progress.json -``` - -### Agent Roles - -| Agent | Responsibility | -|-------|---------------| -| **Orchestrator** | Phase control, path resolution, state management, aggregation logic, iteration control | -| **@cli-explore-agent** (Review) | Execute dimension-specific code analysis via Deep Scan mode, generate findings JSON with dual-source strategy (Bash + Gemini), create structured analysis reports | -| **@cli-explore-agent** (Deep-dive) | Focused root cause analysis using dependency mapping, remediation planning with architectural insights, impact assessment, severity re-assessment | - -## Enhanced Features - -### 1. Review Dimensions Configuration - -**7 Specialized Dimensions** with priority-based allocation: - -| Dimension | Template | Priority | Timeout | -|-----------|----------|----------|---------| -| **Security** | 03-assess-security-risks.txt | 1 (Critical) | 60min | -| **Architecture** | 02-review-architecture.txt | 2 (High) | 60min | -| **Quality** | 02-review-code-quality.txt | 3 (Medium) | 40min | -| **Action-Items** | 02-analyze-code-patterns.txt | 2 (High) | 40min | -| **Performance** | 03-analyze-performance.txt | 3 (Medium) | 60min | -| **Maintainability** | 02-review-code-quality.txt* | 3 (Medium) | 40min | -| **Best-Practices** | 03-review-quality-standards.txt | 3 (Medium) | 40min | - -*Custom focus: "Assess technical debt and maintainability" - -**Category Definitions by Dimension**: - -```javascript -const CATEGORIES = { - security: ['injection', 'authentication', 'authorization', 'encryption', 'input-validation', 'access-control', 'data-exposure'], - architecture: ['coupling', 'cohesion', 'layering', 'dependency', 'pattern-violation', 'scalability', 'separation-of-concerns'], - quality: ['code-smell', 'duplication', 'complexity', 'naming', 'error-handling', 'testability', 'readability'], - 'action-items': ['requirement-coverage', 'acceptance-criteria', 'documentation', 'deployment-readiness', 'missing-functionality'], - performance: ['n-plus-one', 'inefficient-query', 'memory-leak', 'blocking-operation', 'caching', 'resource-usage'], - maintainability: ['technical-debt', 'magic-number', 'long-method', 'large-class', 'dead-code', 'commented-code'], - 'best-practices': ['convention-violation', 'anti-pattern', 'deprecated-api', 'missing-validation', 'inconsistent-style'] -}; -``` - -### 2. Path Pattern Resolution - -**Syntax Rules**: -- All paths are **relative** from project root (e.g., `src/auth/**` not `/src/auth/**`) -- Multiple patterns: comma-separated, **no spaces** (e.g., `src/auth/**,src/payment/**`) -- Glob and specific files can be mixed (e.g., `src/auth/**,src/config.ts`) - -**Supported Patterns**: -| Pattern Type | Example | Description | -|--------------|---------|-------------| -| Glob directory | `src/auth/**` | All files under src/auth/ | -| Glob with extension | `src/**/*.ts` | All .ts files under src/ | -| Specific file | `src/payment/processor.ts` | Single file | -| Multiple patterns | `src/auth/**,src/payment/**` | Comma-separated (no spaces) | - -**Resolution Process**: -1. Parse input pattern (split by comma, trim whitespace) -2. Expand glob patterns to file list via `find` command -3. Validate all files exist and are readable -4. Error if pattern matches 0 files -5. Store resolved file list in review-state.json - -### 3. Aggregation Logic - -**Cross-Cutting Concern Detection**: -1. Files appearing in 3+ dimensions = **Critical Files** -2. Same issue pattern across dimensions = **Systemic Issue** -3. Severity clustering in specific files = **Hotspots** - -**Deep-Dive Selection Criteria**: -- All critical severity findings (priority 1) -- Top 3 high-severity findings in critical files (priority 2) -- Max 5 findings per iteration (prevent overwhelm) - -### 4. Severity Assessment - -**Severity Levels**: -- **Critical**: Security vulnerabilities, data corruption risks, system-wide failures, authentication/authorization bypass -- **High**: Feature degradation, performance bottlenecks, architecture violations, significant technical debt -- **Medium**: Code smells, minor performance issues, style inconsistencies, maintainability concerns -- **Low**: Documentation gaps, minor refactoring opportunities, cosmetic issues - -**Iteration Trigger**: -- Critical findings > 0 OR -- High findings > 5 OR -- Critical files count > 0 - -## Core Responsibilities - -### Orchestrator - -**Phase 1: Discovery & Initialization** - -**Step 1: Session Creation** -```javascript -// Create workflow session for this review (type: review) -Skill(skill="workflow:session:start", args="--type review \"Code review for [target_pattern]\"") - -// Parse output -const sessionId = output.match(/SESSION_ID: (WFS-[^\s]+)/)[1]; -``` - -**Step 2: Path Resolution & Validation** -```bash -# Expand glob pattern to file list (relative paths from project root) -find . -path "./src/auth/**" -type f | sed 's|^\./||' - -# Validate files exist and are readable -for file in ${resolvedFiles[@]}; do - test -r "$file" || error "File not readable: $file" -done -``` -- Parse and expand file patterns (glob support): `src/auth/**` → actual file list -- Validation: Ensure all specified files exist and are readable -- Store as **relative paths** from project root (e.g., `src/auth/service.ts`) -- Agents construct absolute paths dynamically during execution - -**Step 3: Output Directory Setup** -- Output directory: `.workflow/active/${sessionId}/.review/` -- Create directory structure: - ```bash - mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports} - ``` - -**Step 4: Initialize Review State** -- State initialization: Create `review-state.json` with metadata, dimensions, max_iterations, resolved_files (merged metadata + state) -- Progress tracking: Create `review-progress.json` for progress tracking - -**Step 5: TodoWrite Initialization** -- Set up progress tracking with hierarchical structure -- Mark Phase 1 completed, Phase 2 in_progress - -**Phase 2: Parallel Review Coordination** -- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode) -- Pass dimension-specific context (template, timeout, custom focus, **target files**) -- Monitor completion via review-progress.json updates -- TodoWrite updates: Mark dimensions as completed -- CLI tool fallback: Gemini → Qwen → Codex (on error/timeout) - -**Phase 3: Aggregation** -- Load all dimension JSON files from dimensions/ -- Calculate severity distribution: Count by critical/high/medium/low -- Identify cross-cutting concerns: Files in 3+ dimensions -- Select deep-dive findings: Critical + high in critical files (max 5) -- Decision logic: Iterate if critical > 0 OR high > 5 OR critical files exist -- Update review-state.json with aggregation results - -**Phase 4: Iteration Control** -- Check iteration count < max_iterations (default 3) -- Launch deep-dive agents for selected findings -- Collect remediation plans and re-assessed severities -- Update severity distribution based on re-assessments -- Record iteration in review-state.json -- Loop back to aggregation if still have critical/high findings - -**Phase 5: Completion** -- Finalize review-progress.json with completion statistics -- Update review-state.json with completion_time and phase=complete -- TodoWrite completion: Mark all tasks done - - - -### Output File Structure - -``` -.workflow/active/WFS-{session-id}/.review/ -├── review-state.json # Orchestrator state machine (includes metadata) -├── review-progress.json # Real-time progress for dashboard -├── dimensions/ # Per-dimension results -│ ├── security.json -│ ├── architecture.json -│ ├── quality.json -│ ├── action-items.json -│ ├── performance.json -│ ├── maintainability.json -│ └── best-practices.json -├── iterations/ # Deep-dive results -│ ├── 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 - └── ... -``` - -**Session Context**: -``` -.workflow/active/WFS-{session-id}/ -├── workflow-session.json -├── IMPL_PLAN.md -├── TODO_LIST.md -├── .task/ -├── .summaries/ -└── .review/ # Review results (this command) - └── (structure above) -``` - -### Review State JSON - -**Purpose**: Unified state machine and metadata (merged from metadata + state) - -```json -{ - "review_id": "review-20250125-143022", - "review_type": "module", - "session_id": "WFS-auth-system", - "metadata": { - "created_at": "2025-01-25T14:30:22Z", - "target_pattern": "src/auth/**", - "resolved_files": [ - "src/auth/service.ts", - "src/auth/validator.ts", - "src/auth/middleware.ts" - ], - "dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"], - "max_iterations": 3 - }, - "phase": "parallel|aggregate|iterate|complete", - "current_iteration": 1, - "dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"], - "selected_strategy": "comprehensive", - "next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete", - "severity_distribution": { - "critical": 2, - "high": 5, - "medium": 12, - "low": 8 - }, - "critical_files": [...], - "iterations": [...], - "completion_criteria": {...} -} -``` - -### Review Progress JSON - -**Purpose**: Real-time dashboard updates via polling - -```json -{ - "review_id": "review-20250125-143022", - "last_update": "2025-01-25T14:35:10Z", - "phase": "parallel|aggregate|iterate|complete", - "current_iteration": 1, - "progress": { - "parallel_review": { - "total_dimensions": 7, - "completed": 5, - "in_progress": 2, - "percent_complete": 71 - }, - "deep_dive": { - "total_findings": 6, - "analyzed": 2, - "in_progress": 1, - "percent_complete": 33 - } - }, - "agent_status": [ - { - "agent_type": "review-agent", - "dimension": "security", - "status": "completed", - "started_at": "2025-01-25T14:30:00Z", - "completed_at": "2025-01-25T15:15:00Z", - "duration_ms": 2700000 - }, - { - "agent_type": "deep-dive-agent", - "finding_id": "sec-001-uuid", - "status": "in_progress", - "started_at": "2025-01-25T14:32:00Z" - } - ], - "estimated_completion": "2025-01-25T16:00:00Z" -} -``` - -### Agent Output Schemas - -**Agent-produced JSON files follow standardized schemas**: - -1. **Dimension Results** (cli-explore-agent output from parallel reviews) - - Schema: `~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json` - - Output: `{output-dir}/dimensions/{dimension}.json` - - Contains: findings array, summary statistics, cross_references - -2. **Deep-Dive Results** (cli-explore-agent output from iterations) - - Schema: `~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json` - - Output: `{output-dir}/iterations/iteration-{N}-finding-{uuid}.json` - - Contains: root_cause, remediation_plan, impact_assessment, reassessed_severity - -### Agent Invocation Template - -**Review Agent** (parallel execution, 7 instances): - -```javascript -Task( - subagent_type="cli-explore-agent", - run_in_background=false, - description=`Execute ${dimension} review analysis via Deep Scan`, - prompt=` - ## Task Objective - Conduct comprehensive ${dimension} code exploration and analysis using Deep Scan mode (Bash + Gemini dual-source strategy) for specified module files - - ## Analysis Mode Selection - Use **Deep Scan mode** for this review: - - Phase 1: Bash structural scan for standard patterns (classes, functions, imports) - - Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns - - Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings) - - ## MANDATORY FIRST STEPS (Execute by Agent) - **You (cli-explore-agent) MUST execute these steps in order:** - 1. Read review state: ${reviewStateJsonPath} - 2. Get target files: Read resolved_files from review-state.json - 3. Validate file access: bash(ls -la ${targetFiles.join(' ')}) - 4. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference) - 5. Read: .workflow/project-tech.json (technology stack and architecture context) - 6. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against) - - ## Review Context - - Review Type: module (independent) - - Review Dimension: ${dimension} - - Review ID: ${reviewId} - - Target Pattern: ${targetPattern} - - Resolved Files: ${resolvedFiles.length} files - - Output Directory: ${outputDir} - - ## CLI Configuration - - Tool Priority: gemini → qwen → codex (fallback chain) - - Custom Focus: ${customFocus || 'Standard dimension analysis'} - - Mode: analysis (READ-ONLY) - - Context Pattern: ${targetFiles.map(f => `@${f}`).join(' ')} - - ## Expected Deliverables - - **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 4, follow schema exactly - - 1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json - - **⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**: - - Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\` - - Required top-level fields: - - dimension, review_id, analysis_timestamp (NOT timestamp/analyzed_at) - - cli_tool_used (gemini|qwen|codex), model, analysis_duration_ms - - summary (FLAT structure), findings, cross_references - - Summary MUST be FLAT (NOT nested by_severity): - \`{ "total_findings": N, "critical": N, "high": N, "medium": N, "low": N, "files_analyzed": N, "lines_reviewed": N }\` - - Finding required fields: - - id: format \`{dim}-{seq}-{uuid8}\` e.g., \`sec-001-a1b2c3d4\` (lowercase) - - severity: lowercase only (critical|high|medium|low) - - snippet (NOT code_snippet), impact (NOT exploit_scenario) - - metadata, iteration (0), status (pending_remediation), cross_references - - 2. Analysis Report: ${outputDir}/reports/${dimension}-analysis.md - - Human-readable summary with recommendations - - Grouped by severity: critical → high → medium → low - - Include file:line references for all findings - - 3. CLI Output Log: ${outputDir}/reports/${dimension}-cli-output.txt - - Raw CLI tool output for debugging - - Include full analysis text - - ## Dimension-Specific Guidance - ${getDimensionGuidance(dimension)} - - ## Success Criteria - - [ ] Schema obtained via cat review-dimension-results-schema.json - - [ ] All target files analyzed for ${dimension} concerns - - [ ] All findings include file:line references with code snippets - - [ ] Severity assessment follows established criteria (see reference) - - [ ] Recommendations are actionable with code examples - - [ ] JSON output follows schema exactly - - [ ] Report is comprehensive and well-organized - ` -) -``` - -**Deep-Dive Agent** (iteration execution): - -```javascript -Task( - subagent_type="cli-explore-agent", - run_in_background=false, - description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`, - prompt=` - ## Task Objective - Perform focused root cause analysis using Dependency Map mode (for impact analysis) + Deep Scan mode (for semantic understanding) to generate comprehensive remediation plan for critical ${dimension} issue - - ## Analysis Mode Selection - Use **Dependency Map mode** first to understand dependencies: - - Build dependency graph around ${file} to identify affected components - - Detect circular dependencies or tight coupling related to this finding - - Calculate change risk scores for remediation impact - - Then apply **Deep Scan mode** for semantic analysis: - - Understand design intent and architectural context - - Identify non-standard patterns or implicit dependencies - - Extract remediation insights from code structure - - ## Finding Context - - Finding ID: ${findingId} - - Original Dimension: ${dimension} - - Title: ${findingTitle} - - File: ${file}:${line} - - Severity: ${severity} - - Category: ${category} - - Original Description: ${description} - - Iteration: ${iteration} - - ## MANDATORY FIRST STEPS (Execute by Agent) - **You (cli-explore-agent) MUST execute these steps in order:** - 1. Read original finding: ${dimensionJsonPath} - 2. Read affected file: ${file} - 3. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts") - 4. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f) - 5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference) - 6. Read: .workflow/project-tech.json (technology stack and architecture context) - 7. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance) - - ## CLI Configuration - - Tool Priority: gemini → qwen → codex - - Template: ~/.ccw/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt - - Mode: analysis (READ-ONLY) - - ## Expected Deliverables - - **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly - - 1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json - - **⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**: - - Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\` - - Required top-level fields: - - finding_id, dimension, iteration, analysis_timestamp - - cli_tool_used, model, analysis_duration_ms - - original_finding, root_cause, remediation_plan - - impact_assessment, reassessed_severity, confidence_score, cross_references - - All nested objects must follow schema exactly - read schema for field names - - 2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${findingId}.md - - Detailed root cause analysis - - Step-by-step remediation plan - - Impact assessment and rollback strategy - - ## Success Criteria - - [ ] Schema obtained via cat review-deep-dive-results-schema.json - - [ ] Root cause clearly identified with supporting evidence - - [ ] Remediation plan is step-by-step actionable with exact file:line references - - [ ] Each step includes specific commands and validation tests - - [ ] Impact fully assessed (files, tests, breaking changes, dependencies) - - [ ] Severity re-evaluation justified with evidence - - [ ] Confidence score accurately reflects certainty of analysis - - [ ] JSON output follows schema exactly - - [ ] References include project-specific and external documentation - ` -) -``` - -### Dimension Guidance Reference - -```javascript -function getDimensionGuidance(dimension) { - const guidance = { - security: ` - Focus Areas: - - Input validation and sanitization - - Authentication and authorization mechanisms - - Data encryption (at-rest and in-transit) - - SQL/NoSQL injection vulnerabilities - - XSS, CSRF, and other web vulnerabilities - - Sensitive data exposure - - Access control and privilege escalation - - Severity Criteria: - - Critical: Authentication bypass, SQL injection, RCE, sensitive data exposure - - High: Missing authorization checks, weak encryption, exposed secrets - - Medium: Missing input validation, insecure defaults, weak password policies - - Low: Security headers missing, verbose error messages, outdated dependencies - `, - architecture: ` - Focus Areas: - - Layering and separation of concerns - - Coupling and cohesion - - Design pattern adherence - - Dependency management - - Scalability and extensibility - - Module boundaries - - API design consistency - - Severity Criteria: - - Critical: Circular dependencies, god objects, tight coupling across layers - - High: Violated architectural principles, scalability bottlenecks - - Medium: Missing abstractions, inconsistent patterns, suboptimal design - - Low: Minor coupling issues, documentation gaps, naming inconsistencies - `, - quality: ` - Focus Areas: - - Code duplication - - Complexity (cyclomatic, cognitive) - - Naming conventions - - Error handling patterns - - Code readability - - Comment quality - - Dead code - - Severity Criteria: - - Critical: Severe complexity (CC > 20), massive duplication (>50 lines) - - High: High complexity (CC > 10), significant duplication, poor error handling - - Medium: Moderate complexity (CC > 5), naming issues, code smells - - Low: Minor duplication, documentation gaps, cosmetic issues - `, - 'action-items': ` - Focus Areas: - - Requirements coverage verification - - Acceptance criteria met - - Documentation completeness - - Deployment readiness - - Missing functionality - - Test coverage gaps - - Configuration management - - Severity Criteria: - - Critical: Core requirements not met, deployment blockers - - High: Significant functionality missing, acceptance criteria not met - - Medium: Minor requirements gaps, documentation incomplete - - Low: Nice-to-have features missing, minor documentation gaps - `, - performance: ` - Focus Areas: - - N+1 query problems - - Inefficient algorithms (O(n²) where O(n log n) possible) - - Memory leaks - - Blocking operations on main thread - - Missing caching opportunities - - Resource usage (CPU, memory, network) - - Database query optimization - - Severity Criteria: - - Critical: Memory leaks, O(n²) in hot path, blocking main thread - - High: N+1 queries, missing indexes, inefficient algorithms - - Medium: Suboptimal caching, unnecessary computations, lazy loading issues - - Low: Minor optimization opportunities, redundant operations - `, - maintainability: ` - Focus Areas: - - Technical debt indicators - - Magic numbers and hardcoded values - - Long methods (>50 lines) - - Large classes (>500 lines) - - Dead code and commented code - - Code documentation - - Test coverage - - Severity Criteria: - - Critical: Massive methods (>200 lines), severe technical debt blocking changes - - High: Large methods (>100 lines), significant dead code, undocumented complex logic - - Medium: Magic numbers, moderate technical debt, missing tests - - Low: Minor refactoring opportunities, cosmetic improvements - `, - 'best-practices': ` - Focus Areas: - - Framework conventions adherence - - Language idioms - - Anti-patterns - - Deprecated API usage - - Coding standards compliance - - Error handling patterns - - Logging and monitoring - - Severity Criteria: - - Critical: Severe anti-patterns, deprecated APIs with security risks - - High: Major convention violations, poor error handling, missing logging - - Medium: Minor anti-patterns, style inconsistencies, suboptimal patterns - - Low: Cosmetic style issues, minor convention deviations - ` - }; - - return guidance[dimension] || 'Standard code review analysis'; -} -``` - -### Completion Conditions - -**Full Success**: -- All dimensions reviewed -- Critical findings = 0 -- High findings ≤ 5 -- Action: Generate final report, mark phase=complete - -**Partial Success**: -- All dimensions reviewed -- Max iterations reached -- Still have critical/high findings -- Action: Generate report with warnings, recommend follow-up - -### Error Handling - -**Phase-Level Error Matrix**: - -| Phase | Error | Blocking? | Action | -|-------|-------|-----------|--------| -| Phase 1 | Invalid path pattern | Yes | Error and exit | -| Phase 1 | No files matched | Yes | Error and exit | -| Phase 1 | Files not readable | 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 | - -**CLI Fallback Chain**: Gemini → Qwen → Codex → degraded mode - -**Fallback Triggers**: -1. HTTP 429, 5xx errors, connection timeout -2. Invalid JSON output (parse error, missing required fields) -3. Low confidence score < 0.4 -4. Analysis too brief (< 100 words in report) - -**Fallback Behavior**: -- On trigger: Retry with next tool in chain -- After Codex fails: Enter degraded mode (skip analysis, log error) -- Degraded mode: Continue workflow with available results - -### TodoWrite Structure - -```javascript -TodoWrite({ - todos: [ - { content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Initializing" }, - { content: "Phase 2: Parallel Reviews (7 dimensions)", status: "in_progress", activeForm: "Reviewing" }, - { content: " → Security review", status: "in_progress", activeForm: "Analyzing security" }, - // ... other dimensions as sub-items - { content: "Phase 3: Aggregation", status: "pending", activeForm: "Aggregating" }, - { content: "Phase 4: Deep-dive", status: "pending", activeForm: "Deep-diving" }, - { content: "Phase 5: Completion", status: "pending", activeForm: "Completing" } - ] -}); -``` - -## Best Practices - -1. **Start Specific**: Begin with focused module patterns for faster results -2. **Expand Gradually**: Add more modules based on initial findings -3. **Use Glob Wisely**: `src/auth/**` is more efficient than `src/**` with lots of irrelevant files -4. **Trust Aggregation Logic**: Auto-selection based on proven heuristics -5. **Monitor Logs**: Check reports/ directory for CLI analysis insights - -## Related Commands - -### View Review Progress -Use `ccw view` to open the review dashboard in browser: - -```bash -ccw view -``` - -### Automated Fix Workflow -After completing a module review, use the generated findings JSON for automated fixing: - -```bash -# Step 1: Complete review (this command) -/workflow:review-module-cycle src/auth/** - -# Step 2: Run automated fixes using dimension findings -/workflow:review-cycle-fix .workflow/active/WFS-{session-id}/.review/ -``` - -See `/workflow:review-cycle-fix` for automated fixing with smart grouping, parallel execution, and test verification. - diff --git a/.claude/commands/workflow/review-session-cycle.md b/.claude/commands/workflow/review-session-cycle.md deleted file mode 100644 index 25003d94..00000000 --- a/.claude/commands/workflow/review-session-cycle.md +++ /dev/null @@ -1,782 +0,0 @@ ---- -name: review-session-cycle -description: Session-based comprehensive multi-dimensional code review. Analyzes git changes from workflow session across 7 dimensions with hybrid parallel-iterative execution, aggregates findings, and performs focused deep-dives on critical issues until quality gates met. -argument-hint: "[session-id] [--dimensions=security,architecture,...] [--max-iterations=N]" -allowed-tools: Skill(*), TodoWrite(*), Read(*), Bash(*), Task(*) ---- - -# Workflow Review-Session-Cycle Command - -## Quick Start - -```bash -# Execute comprehensive session review (all 7 dimensions) -/workflow:review-session-cycle - -# Review specific session with custom dimensions -/workflow:review-session-cycle WFS-payment-integration --dimensions=security,architecture,quality - -# Specify session and iteration limit -/workflow:review-session-cycle WFS-payment-integration --max-iterations=5 -``` - -**Review Scope**: Git changes from session creation to present (via `git log --since`) -**Session Requirement**: Requires active or completed workflow session -**Output Directory**: `.workflow/active/WFS-{session-id}/.review/` (session-based) -**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices -**Max Iterations**: 3 (adjustable via --max-iterations) -**Default Iterations**: 1 (deep-dive runs once; use --max-iterations=0 to skip) -**CLI Tools**: Gemini → Qwen → Codex (fallback chain) - -## What & Why - -### Core Concept -Session-based multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment of **git changes within a workflow session**. - -**Review Scope**: -- **Session-based**: Reviews only files changed during the workflow session (via `git log --since="${sessionCreatedAt}"`) -- **For independent module review**: Use `/workflow:review-module-cycle` command instead - -**vs Standard Review**: -- **Standard**: Sequential manual reviews → Inconsistent coverage → Missed cross-cutting concerns -- **Review-Session-Cycle**: **Parallel automated analysis → Aggregate findings → Deep-dive critical issues** → Comprehensive coverage - -### Value Proposition -1. **Comprehensive Coverage**: 7 specialized dimensions analyze all quality aspects simultaneously -2. **Intelligent Prioritization**: Automatic identification of critical issues and cross-cutting concerns -3. **Actionable Insights**: Deep-dive iterations provide step-by-step remediation plans - -### Orchestrator Boundary (CRITICAL) -- **ONLY command** for comprehensive multi-dimensional review -- Manages: dimension coordination, aggregation, iteration control, progress tracking -- Delegates: Code exploration and analysis to @cli-explore-agent, dimension-specific reviews via Deep Scan mode - -## How It Works - -### Execution Flow (Simplified) - -``` -Phase 1: Discovery & Initialization - └─ Validate session, initialize state, create output structure - -Phase 2: Parallel Reviews (for each dimension) - ├─ Launch 7 review agents simultaneously - ├─ Each executes CLI analysis via Gemini/Qwen - ├─ Generate dimension JSON + markdown reports - └─ Update review-progress.json - -Phase 3: Aggregation - ├─ Load all dimension JSON files - ├─ Calculate severity distribution (critical/high/medium/low) - ├─ Identify cross-cutting concerns (files in 3+ dimensions) - └─ Decision: - ├─ Critical findings OR high > 5 OR critical files → Phase 4 (Iterate) - └─ Else → Phase 5 (Complete) - -Phase 4: Iterative Deep-Dive (optional) - ├─ Select critical findings (max 5 per iteration) - ├─ Launch deep-dive agents for root cause analysis - ├─ Generate remediation plans with impact assessment - ├─ Re-assess severity based on analysis - └─ Loop until no critical findings OR max iterations - -Phase 5: Completion - └─ Finalize review-progress.json -``` - -### Agent Roles - -| Agent | Responsibility | -|-------|---------------| -| **Orchestrator** | Phase control, session discovery, state management, aggregation logic, iteration control | -| **@cli-explore-agent** (Review) | Execute dimension-specific code analysis via Deep Scan mode, generate findings JSON with dual-source strategy (Bash + Gemini), create structured analysis reports | -| **@cli-explore-agent** (Deep-dive) | Focused root cause analysis using dependency mapping, remediation planning with architectural insights, impact assessment, severity re-assessment | - -## Enhanced Features - -### 1. Review Dimensions Configuration - -**7 Specialized Dimensions** with priority-based allocation: - -| Dimension | Template | Priority | Timeout | -|-----------|----------|----------|---------| -| **Security** | 03-assess-security-risks.txt | 1 (Critical) | 60min | -| **Architecture** | 02-review-architecture.txt | 2 (High) | 60min | -| **Quality** | 02-review-code-quality.txt | 3 (Medium) | 40min | -| **Action-Items** | 02-analyze-code-patterns.txt | 2 (High) | 40min | -| **Performance** | 03-analyze-performance.txt | 3 (Medium) | 60min | -| **Maintainability** | 02-review-code-quality.txt* | 3 (Medium) | 40min | -| **Best-Practices** | 03-review-quality-standards.txt | 3 (Medium) | 40min | - -*Custom focus: "Assess technical debt and maintainability" - -**Category Definitions by Dimension**: - -```javascript -const CATEGORIES = { - security: ['injection', 'authentication', 'authorization', 'encryption', 'input-validation', 'access-control', 'data-exposure'], - architecture: ['coupling', 'cohesion', 'layering', 'dependency', 'pattern-violation', 'scalability', 'separation-of-concerns'], - quality: ['code-smell', 'duplication', 'complexity', 'naming', 'error-handling', 'testability', 'readability'], - 'action-items': ['requirement-coverage', 'acceptance-criteria', 'documentation', 'deployment-readiness', 'missing-functionality'], - performance: ['n-plus-one', 'inefficient-query', 'memory-leak', 'blocking-operation', 'caching', 'resource-usage'], - maintainability: ['technical-debt', 'magic-number', 'long-method', 'large-class', 'dead-code', 'commented-code'], - 'best-practices': ['convention-violation', 'anti-pattern', 'deprecated-api', 'missing-validation', 'inconsistent-style'] -}; -``` - -### 2. Aggregation Logic - -**Cross-Cutting Concern Detection**: -1. Files appearing in 3+ dimensions = **Critical Files** -2. Same issue pattern across dimensions = **Systemic Issue** -3. Severity clustering in specific files = **Hotspots** - -**Deep-Dive Selection Criteria**: -- All critical severity findings (priority 1) -- Top 3 high-severity findings in critical files (priority 2) -- Max 5 findings per iteration (prevent overwhelm) - -### 3. Severity Assessment - -**Severity Levels**: -- **Critical**: Security vulnerabilities, data corruption risks, system-wide failures, authentication/authorization bypass -- **High**: Feature degradation, performance bottlenecks, architecture violations, significant technical debt -- **Medium**: Code smells, minor performance issues, style inconsistencies, maintainability concerns -- **Low**: Documentation gaps, minor refactoring opportunities, cosmetic issues - -**Iteration Trigger**: -- Critical findings > 0 OR -- High findings > 5 OR -- Critical files count > 0 - -## Core Responsibilities - -### Orchestrator - -**Phase 1: Discovery & Initialization** - -**Step 1: Session Discovery** -```javascript -// If session ID not provided, auto-detect -if (!providedSessionId) { - // Check for active sessions - const activeSessions = Glob('.workflow/active/WFS-*'); - if (activeSessions.length === 1) { - sessionId = activeSessions[0].match(/WFS-[^/]+/)[0]; - } else if (activeSessions.length > 1) { - // List sessions and prompt user - error("Multiple active sessions found. Please specify session ID."); - } else { - error("No active session found. Create session first with /workflow:session:start"); - } -} else { - sessionId = providedSessionId; -} - -// Validate session exists -Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`); -``` - -**Step 2: Session Validation** -- Ensure session has implementation artifacts (check `.summaries/` or `.task/` directory) -- Extract session creation timestamp from `workflow-session.json` -- Use timestamp for git log filtering: `git log --since="${sessionCreatedAt}"` - -**Step 3: Changed Files Detection** -```bash -# Get files changed since session creation -git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u -``` - -**Step 4: Output Directory Setup** -- Output directory: `.workflow/active/${sessionId}/.review/` -- Create directory structure: - ```bash - mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports} - ``` - -**Step 5: Initialize Review State** -- State initialization: Create `review-state.json` with metadata, dimensions, max_iterations (merged metadata + state) -- Progress tracking: Create `review-progress.json` for progress tracking - -**Step 6: TodoWrite Initialization** -- Set up progress tracking with hierarchical structure -- Mark Phase 1 completed, Phase 2 in_progress - -**Phase 2: Parallel Review Coordination** -- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode) -- Pass dimension-specific context (template, timeout, custom focus) -- Monitor completion via review-progress.json updates -- TodoWrite updates: Mark dimensions as completed -- CLI tool fallback: Gemini → Qwen → Codex (on error/timeout) - -**Phase 3: Aggregation** -- Load all dimension JSON files from dimensions/ -- Calculate severity distribution: Count by critical/high/medium/low -- Identify cross-cutting concerns: Files in 3+ dimensions -- Select deep-dive findings: Critical + high in critical files (max 5) -- Decision logic: Iterate if critical > 0 OR high > 5 OR critical files exist -- Update review-state.json with aggregation results - -**Phase 4: Iteration Control** -- Check iteration count < max_iterations (default 3) -- Launch deep-dive agents for selected findings -- Collect remediation plans and re-assessed severities -- Update severity distribution based on re-assessments -- Record iteration in review-state.json -- Loop back to aggregation if still have critical/high findings - -**Phase 5: Completion** -- Finalize review-progress.json with completion statistics -- Update review-state.json with completion_time and phase=complete -- TodoWrite completion: Mark all tasks done - - - -### Session File Structure - -``` -.workflow/active/WFS-{session-id}/.review/ -├── review-state.json # Orchestrator state machine (includes metadata) -├── review-progress.json # Real-time progress for dashboard -├── dimensions/ # Per-dimension results -│ ├── security.json -│ ├── architecture.json -│ ├── quality.json -│ ├── action-items.json -│ ├── performance.json -│ ├── maintainability.json -│ └── best-practices.json -├── iterations/ # Deep-dive results -│ ├── 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 - └── ... -``` - -**Session Context**: -``` -.workflow/active/WFS-{session-id}/ -├── workflow-session.json -├── IMPL_PLAN.md -├── TODO_LIST.md -├── .task/ -├── .summaries/ -└── .review/ # Review results (this command) - └── (structure above) -``` - -### Review State JSON - -**Purpose**: Unified state machine and metadata (merged from metadata + state) - -```json -{ - "session_id": "WFS-payment-integration", - "review_id": "review-20250125-143022", - "review_type": "session", - "metadata": { - "created_at": "2025-01-25T14:30:22Z", - "git_changes": { - "commit_range": "abc123..def456", - "files_changed": 15, - "insertions": 342, - "deletions": 128 - }, - "dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"], - "max_iterations": 3 - }, - "phase": "parallel|aggregate|iterate|complete", - "current_iteration": 1, - "dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"], - "selected_strategy": "comprehensive", - "next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete", - "severity_distribution": { - "critical": 2, - "high": 5, - "medium": 12, - "low": 8 - }, - "critical_files": [ - { - "file": "src/payment/processor.ts", - "finding_count": 5, - "dimensions": ["security", "architecture", "quality"] - } - ], - "iterations": [ - { - "iteration": 1, - "findings_analyzed": ["uuid-1", "uuid-2"], - "findings_resolved": 1, - "findings_escalated": 1, - "severity_change": { - "before": {"critical": 2, "high": 5, "medium": 12, "low": 8}, - "after": {"critical": 1, "high": 6, "medium": 12, "low": 8} - }, - "timestamp": "2025-01-25T14:30:00Z" - } - ], - "completion_criteria": { - "target": "no_critical_findings_and_high_under_5", - "current_status": "in_progress", - "estimated_completion": "2 iterations remaining" - } -} -``` - -**Field Descriptions**: -- `phase`: Current execution phase (state machine pointer) -- `current_iteration`: Iteration counter (used for max check) -- `next_action`: Next step orchestrator should execute -- `severity_distribution`: Aggregated counts across all dimensions -- `critical_files`: Files appearing in 3+ dimensions with metadata -- `iterations[]`: Historical log for trend analysis - -### Review Progress JSON - -**Purpose**: Real-time dashboard updates via polling - -```json -{ - "review_id": "review-20250125-143022", - "last_update": "2025-01-25T14:35:10Z", - "phase": "parallel|aggregate|iterate|complete", - "current_iteration": 1, - "progress": { - "parallel_review": { - "total_dimensions": 7, - "completed": 5, - "in_progress": 2, - "percent_complete": 71 - }, - "deep_dive": { - "total_findings": 6, - "analyzed": 2, - "in_progress": 1, - "percent_complete": 33 - } - }, - "agent_status": [ - { - "agent_type": "review-agent", - "dimension": "security", - "status": "completed", - "started_at": "2025-01-25T14:30:00Z", - "completed_at": "2025-01-25T15:15:00Z", - "duration_ms": 2700000 - }, - { - "agent_type": "deep-dive-agent", - "finding_id": "sec-001-uuid", - "status": "in_progress", - "started_at": "2025-01-25T14:32:00Z" - } - ], - "estimated_completion": "2025-01-25T16:00:00Z" -} -``` - -### Agent Output Schemas - -**Agent-produced JSON files follow standardized schemas**: - -1. **Dimension Results** (cli-explore-agent output from parallel reviews) - - Schema: `~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json` - - Output: `.review-cycle/dimensions/{dimension}.json` - - Contains: findings array, summary statistics, cross_references - -2. **Deep-Dive Results** (cli-explore-agent output from iterations) - - Schema: `~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json` - - Output: `.review-cycle/iterations/iteration-{N}-finding-{uuid}.json` - - Contains: root_cause, remediation_plan, impact_assessment, reassessed_severity - -### Agent Invocation Template - -**Review Agent** (parallel execution, 7 instances): - -```javascript -Task( - subagent_type="cli-explore-agent", - run_in_background=false, - description=`Execute ${dimension} review analysis via Deep Scan`, - prompt=` - ## Task Objective - Conduct comprehensive ${dimension} code exploration and analysis using Deep Scan mode (Bash + Gemini dual-source strategy) for completed implementation in session ${sessionId} - - ## Analysis Mode Selection - Use **Deep Scan mode** for this review: - - Phase 1: Bash structural scan for standard patterns (classes, functions, imports) - - Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns - - Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings) - - ## MANDATORY FIRST STEPS (Execute by Agent) - **You (cli-explore-agent) MUST execute these steps in order:** - 1. Read session metadata: ${sessionMetadataPath} - 2. Read completed task summaries: bash(find ${summariesDir} -name "IMPL-*.md" -type f) - 3. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u) - 4. Read review state: ${reviewStateJsonPath} - 5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference) - 6. Read: .workflow/project-tech.json (technology stack and architecture context) - 7. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against) - - ## Session Context - - Session ID: ${sessionId} - - Review Dimension: ${dimension} - - Review ID: ${reviewId} - - Implementation Phase: Complete (all tests passing) - - Output Directory: ${outputDir} - - ## CLI Configuration - - Tool Priority: gemini → qwen → codex (fallback chain) - - Template: ~/.ccw/workflows/cli-templates/prompts/analysis/${dimensionTemplate} - - Custom Focus: ${customFocus || 'Standard dimension analysis'} - - Timeout: ${timeout}ms - - Mode: analysis (READ-ONLY) - - ## Expected Deliverables - - **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly - - 1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json - - **⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**: - - Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\` - - Required top-level fields: - - dimension, review_id, analysis_timestamp (NOT timestamp/analyzed_at) - - cli_tool_used (gemini|qwen|codex), model, analysis_duration_ms - - summary (FLAT structure), findings, cross_references - - Summary MUST be FLAT (NOT nested by_severity): - \`{ "total_findings": N, "critical": N, "high": N, "medium": N, "low": N, "files_analyzed": N, "lines_reviewed": N }\` - - Finding required fields: - - id: format \`{dim}-{seq}-{uuid8}\` e.g., \`sec-001-a1b2c3d4\` (lowercase) - - severity: lowercase only (critical|high|medium|low) - - snippet (NOT code_snippet), impact (NOT exploit_scenario) - - metadata, iteration (0), status (pending_remediation), cross_references - - 2. Analysis Report: ${outputDir}/reports/${dimension}-analysis.md - - Human-readable summary with recommendations - - Grouped by severity: critical → high → medium → low - - Include file:line references for all findings - - 3. CLI Output Log: ${outputDir}/reports/${dimension}-cli-output.txt - - Raw CLI tool output for debugging - - Include full analysis text - - ## Dimension-Specific Guidance - ${getDimensionGuidance(dimension)} - - ## Success Criteria - - [ ] Schema obtained via cat review-dimension-results-schema.json - - [ ] All changed files analyzed for ${dimension} concerns - - [ ] All findings include file:line references with code snippets - - [ ] Severity assessment follows established criteria (see reference) - - [ ] Recommendations are actionable with code examples - - [ ] JSON output follows schema exactly - - [ ] Report is comprehensive and well-organized - ` -) -``` - -**Deep-Dive Agent** (iteration execution): - -```javascript -Task( - subagent_type="cli-explore-agent", - run_in_background=false, - description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`, - prompt=` - ## Task Objective - Perform focused root cause analysis using Dependency Map mode (for impact analysis) + Deep Scan mode (for semantic understanding) to generate comprehensive remediation plan for critical ${dimension} issue - - ## Analysis Mode Selection - Use **Dependency Map mode** first to understand dependencies: - - Build dependency graph around ${file} to identify affected components - - Detect circular dependencies or tight coupling related to this finding - - Calculate change risk scores for remediation impact - - Then apply **Deep Scan mode** for semantic analysis: - - Understand design intent and architectural context - - Identify non-standard patterns or implicit dependencies - - Extract remediation insights from code structure - - ## Finding Context - - Finding ID: ${findingId} - - Original Dimension: ${dimension} - - Title: ${findingTitle} - - File: ${file}:${line} - - Severity: ${severity} - - Category: ${category} - - Original Description: ${description} - - Iteration: ${iteration} - - ## MANDATORY FIRST STEPS (Execute by Agent) - **You (cli-explore-agent) MUST execute these steps in order:** - 1. Read original finding: ${dimensionJsonPath} - 2. Read affected file: ${file} - 3. Identify related code: bash(grep -r "import.*${basename(file)}" ${workflowDir}/src --include="*.ts") - 4. Read test files: bash(find ${workflowDir}/tests -name "*${basename(file, '.ts')}*" -type f) - 5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference) - 6. Read: .workflow/project-tech.json (technology stack and architecture context) - 7. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance) - - ## CLI Configuration - - Tool Priority: gemini → qwen → codex - - Template: ~/.ccw/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt - - Timeout: 2400000ms (40 minutes) - - Mode: analysis (READ-ONLY) - - ## Expected Deliverables - - **Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly - - 1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json - - **⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**: - - Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\` - - Required top-level fields: - - finding_id, dimension, iteration, analysis_timestamp - - cli_tool_used, model, analysis_duration_ms - - original_finding, root_cause, remediation_plan - - impact_assessment, reassessed_severity, confidence_score, cross_references - - All nested objects must follow schema exactly - read schema for field names - - 2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${findingId}.md - - Detailed root cause analysis - - Step-by-step remediation plan - - Impact assessment and rollback strategy - - ## Success Criteria - - [ ] Schema obtained via cat review-deep-dive-results-schema.json - - [ ] Root cause clearly identified with supporting evidence - - [ ] Remediation plan is step-by-step actionable with exact file:line references - - [ ] Each step includes specific commands and validation tests - - [ ] Impact fully assessed (files, tests, breaking changes, dependencies) - - [ ] Severity re-evaluation justified with evidence - - [ ] Confidence score accurately reflects certainty of analysis - - [ ] JSON output follows schema exactly - - [ ] References include project-specific and external documentation - ` -) -``` - -### Dimension Guidance Reference - -```javascript -function getDimensionGuidance(dimension) { - const guidance = { - security: ` - Focus Areas: - - Input validation and sanitization - - Authentication and authorization mechanisms - - Data encryption (at-rest and in-transit) - - SQL/NoSQL injection vulnerabilities - - XSS, CSRF, and other web vulnerabilities - - Sensitive data exposure - - Access control and privilege escalation - - Severity Criteria: - - Critical: Authentication bypass, SQL injection, RCE, sensitive data exposure - - High: Missing authorization checks, weak encryption, exposed secrets - - Medium: Missing input validation, insecure defaults, weak password policies - - Low: Security headers missing, verbose error messages, outdated dependencies - `, - architecture: ` - Focus Areas: - - Layering and separation of concerns - - Coupling and cohesion - - Design pattern adherence - - Dependency management - - Scalability and extensibility - - Module boundaries - - API design consistency - - Severity Criteria: - - Critical: Circular dependencies, god objects, tight coupling across layers - - High: Violated architectural principles, scalability bottlenecks - - Medium: Missing abstractions, inconsistent patterns, suboptimal design - - Low: Minor coupling issues, documentation gaps, naming inconsistencies - `, - quality: ` - Focus Areas: - - Code duplication - - Complexity (cyclomatic, cognitive) - - Naming conventions - - Error handling patterns - - Code readability - - Comment quality - - Dead code - - Severity Criteria: - - Critical: Severe complexity (CC > 20), massive duplication (>50 lines) - - High: High complexity (CC > 10), significant duplication, poor error handling - - Medium: Moderate complexity (CC > 5), naming issues, code smells - - Low: Minor duplication, documentation gaps, cosmetic issues - `, - 'action-items': ` - Focus Areas: - - Requirements coverage verification - - Acceptance criteria met - - Documentation completeness - - Deployment readiness - - Missing functionality - - Test coverage gaps - - Configuration management - - Severity Criteria: - - Critical: Core requirements not met, deployment blockers - - High: Significant functionality missing, acceptance criteria not met - - Medium: Minor requirements gaps, documentation incomplete - - Low: Nice-to-have features missing, minor documentation gaps - `, - performance: ` - Focus Areas: - - N+1 query problems - - Inefficient algorithms (O(n²) where O(n log n) possible) - - Memory leaks - - Blocking operations on main thread - - Missing caching opportunities - - Resource usage (CPU, memory, network) - - Database query optimization - - Severity Criteria: - - Critical: Memory leaks, O(n²) in hot path, blocking main thread - - High: N+1 queries, missing indexes, inefficient algorithms - - Medium: Suboptimal caching, unnecessary computations, lazy loading issues - - Low: Minor optimization opportunities, redundant operations - `, - maintainability: ` - Focus Areas: - - Technical debt indicators - - Magic numbers and hardcoded values - - Long methods (>50 lines) - - Large classes (>500 lines) - - Dead code and commented code - - Code documentation - - Test coverage - - Severity Criteria: - - Critical: Massive methods (>200 lines), severe technical debt blocking changes - - High: Large methods (>100 lines), significant dead code, undocumented complex logic - - Medium: Magic numbers, moderate technical debt, missing tests - - Low: Minor refactoring opportunities, cosmetic improvements - `, - 'best-practices': ` - Focus Areas: - - Framework conventions adherence - - Language idioms - - Anti-patterns - - Deprecated API usage - - Coding standards compliance - - Error handling patterns - - Logging and monitoring - - Severity Criteria: - - Critical: Severe anti-patterns, deprecated APIs with security risks - - High: Major convention violations, poor error handling, missing logging - - Medium: Minor anti-patterns, style inconsistencies, suboptimal patterns - - Low: Cosmetic style issues, minor convention deviations - ` - }; - - return guidance[dimension] || 'Standard code review analysis'; -} -``` - -### Completion Conditions - -**Full Success**: -- All dimensions reviewed -- Critical findings = 0 -- High findings ≤ 5 -- Action: Generate final report, mark phase=complete - -**Partial Success**: -- All dimensions reviewed -- Max iterations reached -- Still have critical/high findings -- Action: Generate report with warnings, recommend follow-up - -### Error Handling - -**Phase-Level Error Matrix**: - -| Phase | Error | Blocking? | Action | -|-------|-------|-----------|--------| -| Phase 1 | Session not found | Yes | Error and exit | -| Phase 1 | No completed tasks | Yes | Error and exit | -| Phase 1 | No changed files | 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 | - -**CLI Fallback Chain**: Gemini → Qwen → Codex → degraded mode - -**Fallback Triggers**: -1. HTTP 429, 5xx errors, connection timeout -2. Invalid JSON output (parse error, missing required fields) -3. Low confidence score < 0.4 -4. Analysis too brief (< 100 words in report) - -**Fallback Behavior**: -- On trigger: Retry with next tool in chain -- After Codex fails: Enter degraded mode (skip analysis, log error) -- Degraded mode: Continue workflow with available results - -### TodoWrite Structure - -```javascript -TodoWrite({ - todos: [ - { content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Initializing" }, - { content: "Phase 2: Parallel Reviews (7 dimensions)", status: "in_progress", activeForm: "Reviewing" }, - { content: " → Security review", status: "in_progress", activeForm: "Analyzing security" }, - // ... other dimensions as sub-items - { content: "Phase 3: Aggregation", status: "pending", activeForm: "Aggregating" }, - { content: "Phase 4: Deep-dive", status: "pending", activeForm: "Deep-diving" }, - { content: "Phase 5: Completion", status: "pending", activeForm: "Completing" } - ] -}); -``` - -## Best Practices - -1. **Default Settings Work**: 7 dimensions + 3 iterations sufficient for most cases -2. **Parallel Execution**: ~60 minutes for full initial review (7 dimensions) -3. **Trust Aggregation Logic**: Auto-selection based on proven heuristics -4. **Monitor Logs**: Check reports/ directory for CLI analysis insights - -## Related Commands - -### View Review Progress -Use `ccw view` to open the review dashboard in browser: - -```bash -ccw view -``` - -### Automated Fix Workflow -After completing a review, use the generated findings JSON for automated fixing: - -```bash -# Step 1: Complete review (this command) -/workflow:review-session-cycle - -# Step 2: Run automated fixes using dimension findings -/workflow:review-cycle-fix .workflow/active/WFS-{session-id}/.review/ -``` - -See `/workflow:review-cycle-fix` for automated fixing with smart grouping, parallel execution, and test verification. - diff --git a/.claude/commands/workflow/tools/code-validation-gate.md b/.claude/commands/workflow/tools/code-validation-gate.md deleted file mode 100644 index 96f7daab..00000000 --- a/.claude/commands/workflow/tools/code-validation-gate.md +++ /dev/null @@ -1,391 +0,0 @@ ---- -name: code-validation-gate -description: Validate AI-generated code for common errors (imports, variables, types) before test execution -argument-hint: "--session WFS-test-session-id [--fix] [--strict]" -examples: - - /workflow:tools:code-validation-gate --session WFS-test-auth - - /workflow:tools:code-validation-gate --session WFS-test-auth --fix - - /workflow:tools:code-validation-gate --session WFS-test-auth --strict ---- - -# Code Validation Gate Command - -## Overview - -Pre-test validation gate that checks AI-generated code for common errors before test execution. This prevents wasted test cycles on code with fundamental issues like import errors, variable conflicts, and type mismatches. - -## Core Philosophy - -- **Fail Fast**: Catch fundamental errors before expensive test execution -- **AI-Aware**: Specifically targets common AI code generation mistakes -- **Auto-Remediation**: Attempt safe fixes before failing -- **Clear Feedback**: Provide actionable fix suggestions for manual intervention - -## Target Error Categories - -### L0.1: Compilation Errors -- TypeScript compilation failures -- Syntax errors -- Module resolution failures - -### L0.2: Import Errors -- Unresolved module imports (hallucinated packages) -- Circular dependencies -- Duplicate imports -- Unused imports - -### L0.3: Variable Errors -- Variable redeclaration -- Scope conflicts (shadowing) -- Undefined variable usage -- Unused variables - -### L0.4: Type Errors (TypeScript) -- Type mismatches -- Missing type definitions -- Excessive `any` usage -- Implicit `any` types - -### L0.5: AI-Specific Patterns -- Placeholder code (`// TODO: implement`) -- Hallucinated package imports -- Mock code in production files -- Inconsistent naming patterns - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session (required), --fix, --strict - └─ Load test-quality-config.json - -Phase 1: Context Loading - ├─ Load session metadata - ├─ Identify target files (from IMPL-001 output or context-package) - └─ Detect project configuration (tsconfig, eslint, etc.) - -Phase 2: Validation Execution - ├─ L0.1: Run TypeScript compilation check - ├─ L0.2: Run import validation - ├─ L0.3: Run variable validation - ├─ L0.4: Run type validation - └─ L0.5: Run AI-specific checks - -Phase 3: Result Analysis - ├─ Aggregate all findings by severity - ├─ Calculate pass/fail status - └─ Generate fix suggestions - -Phase 4: Auto-Fix (if --fix enabled) - ├─ Apply safe auto-fixes (imports, formatting) - ├─ Re-run validation - └─ Report remaining issues - -Phase 5: Gate Decision - ├─ PASS: Proceed to IMPL-001.5 - ├─ SOFT_FAIL: Auto-fix applied, needs re-validation - └─ HARD_FAIL: Block with detailed report -``` - -## Execution Lifecycle - -### Phase 1: Context Loading - -**Load session and identify validation targets.** - -```javascript -// Load session metadata -Read(".workflow/active/{session_id}/workflow-session.json") - -// Load context package for target files -Read(".workflow/active/{session_id}/.process/context-package.json") -// OR -Read(".workflow/active/{session_id}/.process/test-context-package.json") - -// Identify files to validate: -// 1. Source files from context.implementation_files -// 2. Test files from IMPL-001 output (if exists) -// 3. All modified files since session start -``` - -**Target File Discovery**: -- Source files: `context.focus_paths` from context-package -- Generated tests: `.workflow/active/{session_id}/.task/IMPL-001-output/` -- All TypeScript/JavaScript in target directories - -### Phase 2: Validation Execution - -**Execute validation checks in order of dependency.** - -#### L0.1: TypeScript Compilation - -```bash -# Primary check - catches most fundamental errors -npx tsc --noEmit --skipLibCheck --project tsconfig.json 2>&1 - -# Parse output for errors -# Critical: Any compilation error blocks further validation -``` - -**Error Patterns**: -``` -error TS2307: Cannot find module 'xxx' -error TS2451: Cannot redeclare block-scoped variable 'xxx' -error TS2322: Type 'xxx' is not assignable to type 'yyy' -``` - -#### L0.2: Import Validation - -```bash -# Check for circular dependencies -npx madge --circular --extensions ts,tsx,js,jsx {target_dirs} - -# ESLint import rules -npx eslint --rule 'import/no-duplicates: error' --rule 'import/no-unresolved: error' {files} -``` - -**Hallucinated Package Check**: -```javascript -// Extract all imports from files -// Verify each package exists in package.json or node_modules -// Flag any unresolvable imports as "hallucinated" -``` - -#### L0.3: Variable Validation - -```bash -# ESLint variable rules -npx eslint --rule 'no-shadow: error' --rule 'no-undef: error' --rule 'no-redeclare: error' {files} -``` - -#### L0.4: Type Validation - -```bash -# TypeScript strict checks -npx tsc --noEmit --strict {files} - -# Check for any abuse -npx eslint --rule '@typescript-eslint/no-explicit-any: warn' {files} -``` - -#### L0.5: AI-Specific Checks - -```bash -# Check for placeholder code -grep -rn "// TODO: implement\|// Add your code here\|throw new Error.*Not implemented" {files} - -# Check for mock code in production files -grep -rn "jest\.mock\|sinon\.\|vi\.mock" {source_files_only} -``` - -### Phase 3: Result Analysis - -**Aggregate and categorize findings.** - -```javascript -const findings = { - critical: [], // Blocks all progress - error: [], // Blocks with threshold - warning: [] // Advisory only -}; - -// Apply thresholds from config -const config = loadConfig("test-quality-config.json"); -const thresholds = config.code_validation.severity_thresholds; - -// Gate decision -if (findings.critical.length > thresholds.critical) { - decision = "HARD_FAIL"; -} else if (findings.error.length > thresholds.error) { - decision = "SOFT_FAIL"; // Try auto-fix -} else { - decision = "PASS"; -} -``` - -### Phase 4: Auto-Fix (Optional) - -**Apply safe automatic fixes when --fix flag provided.** - -```bash -# Safe fixes only -npx eslint --fix --rule 'import/no-duplicates: error' --rule 'unused-imports/no-unused-imports: error' {files} - -# Re-run validation after fixes -# Report what was fixed vs what remains -``` - -**Safe Fix Categories**: -- Remove unused imports -- Remove duplicate imports -- Fix import ordering -- Remove unused variables (with caution) -- Formatting fixes - -**Unsafe (Manual Only)**: -- Missing imports (need to determine correct package) -- Type errors (need to understand intent) -- Variable shadowing (need to understand scope intent) - -### Phase 5: Gate Decision - -**Determine next action based on results.** - -| Decision | Condition | Action | -|----------|-----------|--------| -| **PASS** | critical=0, error<=3, warning<=10 | Proceed to IMPL-001.5 | -| **SOFT_FAIL** | critical=0, error>3 OR fixable issues | Auto-fix and retry (max 2) | -| **HARD_FAIL** | critical>0 OR max retries exceeded | Block with report | - -## Output Artifacts - -### Validation Report - -**File**: `.workflow/active/{session_id}/.process/code-validation-report.md` - -```markdown -# Code Validation Report - -**Session**: {session_id} -**Timestamp**: {timestamp} -**Status**: PASS | SOFT_FAIL | HARD_FAIL - -## Summary -- Files Validated: {count} -- Critical Issues: {count} -- Errors: {count} -- Warnings: {count} - -## Critical Issues (Must Fix) -### Import Errors -- `src/auth/service.ts:5` - Cannot find module 'non-existent-package' - - **Suggestion**: Check if package exists, may be hallucinated by AI - -### Variable Conflicts -- `src/utils/helper.ts:12` - Cannot redeclare block-scoped variable 'config' - - **Suggestion**: Rename one of the variables or merge declarations - -## Errors (Should Fix) -... - -## Warnings (Consider Fixing) -... - -## Auto-Fix Applied -- Removed 3 unused imports in `src/auth/service.ts` -- Fixed import ordering in `src/utils/index.ts` - -## Remaining Issues Requiring Manual Fix -... - -## Next Steps -- [ ] Fix critical issues before proceeding -- [ ] Review error suggestions -- [ ] Re-run validation: `/workflow:tools:code-validation-gate --session {session_id}` -``` - -### JSON Report (Machine-Readable) - -**File**: `.workflow/active/{session_id}/.process/code-validation-report.json` - -```json -{ - "session_id": "WFS-test-xxx", - "timestamp": "2025-01-30T10:00:00Z", - "status": "HARD_FAIL", - "summary": { - "files_validated": 15, - "critical": 2, - "error": 5, - "warning": 8 - }, - "findings": { - "critical": [ - { - "category": "import", - "file": "src/auth/service.ts", - "line": 5, - "message": "Cannot find module 'non-existent-package'", - "suggestion": "Check if package exists in package.json", - "auto_fixable": false - } - ], - "error": [...], - "warning": [...] - }, - "auto_fixes_applied": [...], - "gate_decision": "HARD_FAIL", - "retry_count": 0, - "max_retries": 2 -} -``` - -## Command Options - -| Option | Description | Default | -|--------|-------------|---------| -| `--session` | Test session ID (required) | - | -| `--fix` | Enable auto-fix for safe issues | false | -| `--strict` | Use strict thresholds (0 errors allowed) | false | -| `--files` | Specific files to validate (comma-separated) | All target files | -| `--skip-types` | Skip TypeScript type checks | false | - -## Integration - -### Command Chain - -- **Called By**: `/workflow:test-fix-gen` (after IMPL-001) -- **Requires**: IMPL-001 output OR context-package.json -- **Followed By**: IMPL-001.5 (Test Quality Gate) on PASS - -### Task JSON Integration - -When used in test-fix workflow, generates task: - -```json -{ - "id": "IMPL-001.3-validation", - "meta": { - "type": "code-validation", - "agent": "@test-fix-agent" - }, - "context": { - "depends_on": ["IMPL-001"], - "requirements": "Validate generated code for AI common errors" - }, - "flow_control": { - "validation_config": "~/.ccw/workflows/test-quality-config.json", - "max_retries": 2, - "auto_fix_enabled": true - }, - "acceptance_criteria": [ - "Zero critical issues", - "Maximum 3 error issues", - "All imports resolvable", - "No variable redeclarations" - ] -} -``` - -## Error Handling - -| Error | Resolution | -|-------|------------| -| tsconfig.json not found | Use default compiler options | -| ESLint not installed | Skip ESLint checks, use tsc only | -| madge not installed | Skip circular dependency check | -| No files to validate | Return PASS (nothing to check) | - -## Best Practices - -1. **Run Early**: Execute validation immediately after code generation -2. **Use --fix First**: Let auto-fix resolve trivial issues -3. **Review Suggestions**: AI fix suggestions may need human judgment -4. **Don't Skip Critical**: Never proceed with critical errors -5. **Track Patterns**: Common failures indicate prompt improvement opportunities - -## Related Commands - -- `/workflow:test-fix-gen` - Parent workflow that invokes this command -- `/workflow:tools:test-quality-gate` - Next phase (IMPL-001.5) for test quality -- `/workflow:test-cycle-execute` - Execute tests after validation passes diff --git a/.claude/commands/workflow/tools/conflict-resolution.md b/.claude/commands/workflow/tools/conflict-resolution.md deleted file mode 100644 index 04d80a41..00000000 --- a/.claude/commands/workflow/tools/conflict-resolution.md +++ /dev/null @@ -1,604 +0,0 @@ ---- -name: conflict-resolution -description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen -argument-hint: "[-y|--yes] --session WFS-session-id --context path/to/context-package.json" -examples: - - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/active/WFS-auth/.process/context-package.json - - /workflow:tools:conflict-resolution -y --session WFS-payment --context .workflow/active/WFS-payment/.process/context-package.json ---- - -## Auto Mode - -When `--yes` or `-y`: Auto-select recommended strategy for each conflict, skip clarification questions. - -# Conflict Resolution Command - -## Purpose -Analyzes conflicts between implementation plans and existing codebase, **including module scenario uniqueness detection**, generating multiple resolution strategies with **iterative clarification until boundaries are clear**. - -**Scope**: Detection and strategy generation only - NO code modification or task creation. - -**Trigger**: Auto-executes in `/workflow:plan` Phase 3 when `conflict_risk ≥ medium`. - -## Core Responsibilities - -| Responsibility | Description | -|---------------|-------------| -| **Detect Conflicts** | Analyze plan vs existing code inconsistencies | -| **Scenario Uniqueness** | Search and compare new modules with existing modules for functional overlaps | -| **Generate Strategies** | Provide 2-4 resolution options per conflict | -| **Iterative Clarification** | Ask unlimited questions until scenario boundaries are clear and unique | -| **Agent Re-analysis** | Dynamically update strategies based on user clarifications | -| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) | -| **User Decision** | Present options ONE BY ONE, never auto-apply | -| **Direct Text Output** | Output questions via text directly, NEVER use bash echo/printf | -| **Structured Data** | JSON output for programmatic processing, NO file generation | - -## Conflict Categories - -### 1. Architecture Conflicts -- Incompatible design patterns -- Module structure changes -- Pattern migration requirements - -### 2. API Conflicts -- Breaking contract changes -- Signature modifications -- Public interface impacts - -### 3. Data Model Conflicts -- Schema modifications -- Type breaking changes -- Data migration needs - -### 4. Dependency Conflicts -- Version incompatibilities -- Setup conflicts -- Breaking updates - -### 5. Module Scenario Overlap -- Functional overlap between new and existing modules -- Scenario boundary ambiguity -- Duplicate responsibility detection -- Module merge/split decisions -- **Requires iterative clarification until uniqueness confirmed** - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session, --context - └─ Validation: Both REQUIRED, conflict_risk >= medium - -Phase 1: Validation - ├─ Step 1: Verify session directory exists - ├─ Step 2: Load context-package.json - ├─ Step 3: Check conflict_risk (skip if none/low) - └─ Step 4: Prepare agent task prompt - -Phase 2: CLI-Powered Analysis (Agent) - ├─ Execute Gemini analysis (Qwen fallback) - ├─ Detect conflicts including ModuleOverlap category - └─ Generate 2-4 strategies per conflict with modifications - -Phase 3: Iterative User Interaction - └─ FOR each conflict (one by one): - ├─ Display conflict with overlap_analysis (if ModuleOverlap) - ├─ Display strategies (2-4 + custom option) - ├─ User selects strategy - └─ IF clarification_needed: - ├─ Collect answers - ├─ Agent re-analysis - └─ Loop until uniqueness_confirmed (max 10 rounds) - -Phase 4: Apply Modifications - ├─ Step 1: Extract modifications from resolved strategies - ├─ Step 2: Apply using Edit tool - ├─ Step 3: Update context-package.json (mark resolved) - └─ Step 4: Output custom conflict summary (if any) -``` - -## Execution Flow - -### Phase 1: Validation -``` -1. Verify session directory exists -2. Load context-package.json -3. Check conflict_risk (skip if none/low) -4. Prepare agent task prompt -``` - -### Phase 2: CLI-Powered Analysis - -**Agent Delegation**: -```javascript -Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=` - ## Context - - Session: {session_id} - - Risk: {conflict_risk} - - Files: {existing_files_list} - - ## Exploration Context (from context-package.exploration_results) - - Exploration Count: ${contextPackage.exploration_results?.exploration_count || 0} - - Angles Analyzed: ${JSON.stringify(contextPackage.exploration_results?.angles || [])} - - Pre-identified Conflict Indicators: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.conflict_indicators || [])} - - Critical Files: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.critical_files?.map(f => f.path) || [])} - - All Patterns: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_patterns || [])} - - All Integration Points: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_integration_points || [])} - - ## Analysis Steps - - ### 0. Load Output Schema (MANDATORY) - Execute: cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json - - ### 1. Load Context - - Read existing files from conflict_detection.existing_files - - Load plan from .workflow/active/{session_id}/.process/context-package.json - - Load exploration_results and use aggregated_insights for enhanced analysis - - Extract role analyses and requirements - - ### 2. Execute CLI Analysis (Enhanced with Exploration + Scenario Uniqueness) - - Primary (Gemini): - ccw cli -p " - PURPOSE: Detect conflicts between plan and codebase, using exploration insights - TASK: - • **Review pre-identified conflict_indicators from exploration results** - • Compare architectures (use exploration key_patterns) - • Identify breaking API changes - • Detect data model incompatibilities - • Assess dependency conflicts - • **Analyze module scenario uniqueness** - - Use exploration integration_points for precise locations - - Cross-validate with exploration critical_files - - Generate clarification questions for boundary definition - MODE: analysis - CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @.workflow/active/{session_id}/**/* - EXPECTED: Conflict list with severity ratings, including: - - Validation of exploration conflict_indicators - - ModuleOverlap conflicts with overlap_analysis - - Targeted clarification questions - CONSTRAINTS: Focus on breaking changes, migration needs, and functional overlaps | Prioritize exploration-identified conflicts | analysis=READ-ONLY - " --tool gemini --mode analysis --rule analysis-code-patterns --cd {project_root} - - Fallback: Qwen (same prompt) → Claude (manual analysis) - - ### 3. Generate Strategies (2-4 per conflict) - - Template per conflict: - - Severity: Critical/High/Medium - - Category: Architecture/API/Data/Dependency/ModuleOverlap - - Affected files + impact - - **For ModuleOverlap**: Include overlap_analysis with existing modules and scenarios - - Options with pros/cons, effort, risk - - **For ModuleOverlap strategies**: Add clarification_needed questions for boundary definition - - Recommended strategy + rationale - - ### 4. Return Structured Conflict Data - - ⚠️ Output to conflict-resolution.json (generated in Phase 4) - - **Schema Reference**: Execute \`cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json\` to get full schema - - Return JSON following the schema above. Key requirements: - - Minimum 2 strategies per conflict, max 4 - - All text in Chinese for user-facing fields (brief, name, pros, cons, modification_suggestions) - - modifications.old_content: 20-100 chars for unique Edit tool matching - - modifications.new_content: preserves markdown formatting - - modification_suggestions: 2-5 actionable suggestions for custom handling - - ### 5. Planning Notes Record (REQUIRED) - After analysis complete, append a brief execution record to planning-notes.md: - - **File**: .workflow/active/{session_id}/planning-notes.md - **Location**: Under "## Conflict Decisions (Phase 3)" section - **Format**: - \`\`\` - ### [Conflict-Resolution Agent] YYYY-MM-DD - - **Note**: [智能补充：简短总结冲突类型、解决策略、关键决策等] - \`\`\` -`) -``` - -### Phase 3: User Interaction Loop - -```javascript -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') - -FOR each conflict: - round = 0, clarified = false, userClarifications = [] - - WHILE (!clarified && round++ < 10): - // 1. Display conflict info (text output for context) - displayConflictSummary(conflict) // id, brief, severity, overlap_analysis if ModuleOverlap - - // 2. Strategy selection - if (autoYes) { - console.log(`[--yes] Auto-selecting recommended strategy`) - selectedStrategy = conflict.strategies[conflict.recommended || 0] - clarified = true // Skip clarification loop - } else { - AskUserQuestion({ - questions: [{ - question: formatStrategiesForDisplay(conflict.strategies), - header: "策略选择", - multiSelect: false, - options: [ - ...conflict.strategies.map((s, i) => ({ - label: `${s.name}${i === conflict.recommended ? ' (推荐)' : ''}`, - description: `${s.complexity}复杂度 | ${s.risk}风险${s.clarification_needed?.length ? ' | ⚠️需澄清' : ''}` - })), - { label: "自定义修改", description: `建议: ${conflict.modification_suggestions?.slice(0,2).join('; ')}` } - ] - }] - }) - - // 3. Handle selection - if (userChoice === "自定义修改") { - customConflicts.push({ id, brief, category, suggestions, overlap_analysis }) - break - } - - selectedStrategy = findStrategyByName(userChoice) - } - - // 4. Clarification (if needed) - batched max 4 per call - if (!autoYes && selectedStrategy.clarification_needed?.length > 0) { - for (batch of chunk(selectedStrategy.clarification_needed, 4)) { - AskUserQuestion({ - questions: batch.map((q, i) => ({ - question: q, header: `澄清${i+1}`, multiSelect: false, - options: [{ label: "详细说明", description: "提供答案" }] - })) - }) - userClarifications.push(...collectAnswers(batch)) - } - - // 5. Agent re-analysis - reanalysisResult = Task({ - subagent_type: "cli-execution-agent", - run_in_background: false, - prompt: `Conflict: ${conflict.id}, Strategy: ${selectedStrategy.name} -User Clarifications: ${JSON.stringify(userClarifications)} -Output: { uniqueness_confirmed, rationale, updated_strategy, remaining_questions }` - }) - - if (reanalysisResult.uniqueness_confirmed) { - selectedStrategy = { ...reanalysisResult.updated_strategy, clarifications: userClarifications } - clarified = true - } else { - selectedStrategy.clarification_needed = reanalysisResult.remaining_questions - } - } else { - clarified = true - } - - if (clarified) resolvedConflicts.push({ conflict, strategy: selectedStrategy }) - END WHILE -END FOR - -selectedStrategies = resolvedConflicts.map(r => ({ - conflict_id: r.conflict.id, strategy: r.strategy, clarifications: r.strategy.clarifications || [] -})) -``` - -**Key Points**: -- AskUserQuestion: max 4 questions/call, batch if more -- Strategy options: 2-4 strategies + "自定义修改" -- Clarification loop: max 10 rounds, agent判断 uniqueness_confirmed -- Custom conflicts: 记录 overlap_analysis 供后续手动处理 - -### Phase 4: Apply Modifications - -```javascript -// 1. Extract modifications from resolved strategies -const modifications = []; -selectedStrategies.forEach(item => { - if (item.strategy && item.strategy.modifications) { - modifications.push(...item.strategy.modifications.map(mod => ({ - ...mod, - conflict_id: item.conflict_id, - clarifications: item.clarifications - }))); - } -}); - -console.log(`\n正在应用 ${modifications.length} 个修改...`); - -// 2. Apply each modification using Edit tool (with fallback to context-package.json) -const appliedModifications = []; -const failedModifications = []; -const fallbackConstraints = []; // For files that don't exist - -modifications.forEach((mod, idx) => { - try { - console.log(`[${idx + 1}/${modifications.length}] 修改 ${mod.file}...`); - - // Check if target file exists (brainstorm files may not exist in lite workflow) - if (!file_exists(mod.file)) { - console.log(` ⚠️ 文件不存在，写入 context-package.json 作为约束`); - fallbackConstraints.push({ - source: "conflict-resolution", - conflict_id: mod.conflict_id, - target_file: mod.file, - section: mod.section, - change_type: mod.change_type, - content: mod.new_content, - rationale: mod.rationale - }); - return; // Skip to next modification - } - - if (mod.change_type === "update") { - Edit({ - file_path: mod.file, - old_string: mod.old_content, - new_string: mod.new_content - }); - } else if (mod.change_type === "add") { - // Handle addition - append or insert based on section - const fileContent = Read(mod.file); - const updated = insertContentAfterSection(fileContent, mod.section, mod.new_content); - Write(mod.file, updated); - } else if (mod.change_type === "remove") { - Edit({ - file_path: mod.file, - old_string: mod.old_content, - new_string: "" - }); - } - - appliedModifications.push(mod); - console.log(` ✓ 成功`); - } catch (error) { - console.log(` ✗ 失败: ${error.message}`); - failedModifications.push({ ...mod, error: error.message }); - } -}); - -// 2b. Generate conflict-resolution.json output file -const resolutionOutput = { - session_id: sessionId, - resolved_at: new Date().toISOString(), - summary: { - total_conflicts: conflicts.length, - resolved_with_strategy: selectedStrategies.length, - custom_handling: customConflicts.length, - fallback_constraints: fallbackConstraints.length - }, - resolved_conflicts: selectedStrategies.map(s => ({ - conflict_id: s.conflict_id, - strategy_name: s.strategy.name, - strategy_approach: s.strategy.approach, - clarifications: s.clarifications || [], - modifications_applied: s.strategy.modifications?.filter(m => - appliedModifications.some(am => am.conflict_id === s.conflict_id) - ) || [] - })), - custom_conflicts: customConflicts.map(c => ({ - id: c.id, - brief: c.brief, - category: c.category, - suggestions: c.suggestions, - overlap_analysis: c.overlap_analysis || null - })), - planning_constraints: fallbackConstraints, // Constraints for files that don't exist - failed_modifications: failedModifications -}; - -const resolutionPath = `.workflow/active/${sessionId}/.process/conflict-resolution.json`; -Write(resolutionPath, JSON.stringify(resolutionOutput, null, 2)); -console.log(`\n📄 冲突解决结果已保存: ${resolutionPath}`); - -// 3. Update context-package.json with resolution details (reference to JSON file) -const contextPackage = JSON.parse(Read(contextPath)); -contextPackage.conflict_detection.conflict_risk = "resolved"; -contextPackage.conflict_detection.resolution_file = resolutionPath; // Reference to detailed JSON -contextPackage.conflict_detection.resolved_conflicts = selectedStrategies.map(s => s.conflict_id); -contextPackage.conflict_detection.custom_conflicts = customConflicts.map(c => c.id); -contextPackage.conflict_detection.resolved_at = new Date().toISOString(); -Write(contextPath, JSON.stringify(contextPackage, null, 2)); - -// 4. Output custom conflict summary with overlap analysis (if any) -if (customConflicts.length > 0) { - console.log(`\n${'='.repeat(60)}`); - console.log(`需要自定义处理的冲突 (${customConflicts.length})`); - console.log(`${'='.repeat(60)}\n`); - - customConflicts.forEach(conflict => { - console.log(`【${conflict.category}】${conflict.id}: ${conflict.brief}`); - - // Show overlap analysis for ModuleOverlap conflicts - if (conflict.category === 'ModuleOverlap' && conflict.overlap_analysis) { - console.log(`\n场景重叠信息:`); - console.log(` 新模块: ${conflict.overlap_analysis.new_module.name}`); - console.log(` 场景: ${conflict.overlap_analysis.new_module.scenarios.join(', ')}`); - console.log(`\n 与以下模块重叠:`); - conflict.overlap_analysis.existing_modules.forEach(mod => { - console.log(` - ${mod.name} (${mod.file})`); - console.log(` 重叠场景: ${mod.overlap_scenarios.join(', ')}`); - }); - } - - console.log(`\n修改建议:`); - conflict.suggestions.forEach(suggestion => { - console.log(` - ${suggestion}`); - }); - console.log(); - }); -} - -// 5. Output failure summary (if any) -if (failedModifications.length > 0) { - console.log(`\n⚠️ 部分修改失败 (${failedModifications.length}):`); - failedModifications.forEach(mod => { - console.log(` - ${mod.file}: ${mod.error}`); - }); -} - -// 6. Return summary -return { - total_conflicts: conflicts.length, - resolved_with_strategy: selectedStrategies.length, - custom_handling: customConflicts.length, - modifications_applied: appliedModifications.length, - modifications_failed: failedModifications.length, - modified_files: [...new Set(appliedModifications.map(m => m.file))], - custom_conflicts: customConflicts, - clarification_records: selectedStrategies.filter(s => s.clarifications.length > 0) -}; -``` - -**Validation**: -``` -✓ Agent returns valid JSON structure with ModuleOverlap conflicts -✓ Conflicts processed ONE BY ONE (not in batches) -✓ ModuleOverlap conflicts include overlap_analysis field -✓ Strategies with clarification_needed display questions -✓ User selections captured correctly per conflict -✓ Clarification loop continues until uniqueness confirmed -✓ Agent re-analysis returns uniqueness_confirmed and updated_strategy -✓ Maximum 10 rounds per conflict safety limit enforced -✓ Edit tool successfully applies modifications -✓ guidance-specification.md updated -✓ Role analyses (*.md) updated -✓ context-package.json marked as resolved with clarification records -✓ Custom conflicts display overlap_analysis for manual handling -✓ Agent log saved to .workflow/active/{session_id}/.chat/ -``` - -## Output Format - -### Primary Output: conflict-resolution.json - -**Path**: `.workflow/active/{session_id}/.process/conflict-resolution.json` - -**Schema**: -```json -{ - "session_id": "WFS-xxx", - "resolved_at": "ISO timestamp", - "summary": { - "total_conflicts": 3, - "resolved_with_strategy": 2, - "custom_handling": 1, - "fallback_constraints": 0 - }, - "resolved_conflicts": [ - { - "conflict_id": "CON-001", - "strategy_name": "策略名称", - "strategy_approach": "实现方法", - "clarifications": [], - "modifications_applied": [] - } - ], - "custom_conflicts": [ - { - "id": "CON-002", - "brief": "冲突摘要", - "category": "ModuleOverlap", - "suggestions": ["建议1", "建议2"], - "overlap_analysis": null - } - ], - "planning_constraints": [], - "failed_modifications": [] -} -``` - -### Secondary: Agent JSON Response (stdout) - -**Focus**: Structured conflict data with actionable modifications for programmatic processing. - -**Structure**: Defined in Phase 2, Step 4 (agent prompt) - -### Key Requirements -| Requirement | Details | -|------------|---------| -| **Conflict batching** | Max 10 conflicts per round (no total limit) | -| **Strategy count** | 2-4 strategies per conflict | -| **Modifications** | Each strategy includes file paths, old_content, new_content | -| **User-facing text** | Chinese (brief, strategy names, pros/cons) | -| **Technical fields** | English (severity, category, complexity, risk) | -| **old_content precision** | 20-100 chars for unique Edit tool matching | -| **File targets** | guidance-specification.md, role analyses (*.md) | - -## Error Handling - -### Recovery Strategy -``` -1. Pre-check: Verify conflict_risk ≥ medium -2. Monitor: Track agent via Task tool -3. Validate: Parse agent JSON output -4. Recover: - - Agent failure → check logs + report error - - Invalid JSON → retry once with Claude fallback - - CLI failure → fallback to Claude analysis - - Edit tool failure → report affected files + rollback option - - User cancels → mark as "unresolved", continue to task-generate -5. Degrade: If all fail, generate minimal conflict report and skip modifications -``` - -### Rollback Handling -``` -If Edit tool fails mid-application: -1. Log all successfully applied modifications -2. Output rollback option via text interaction -3. If rollback selected: restore files from git or backups -4. If continue: mark partial resolution in context-package.json -``` - -## Integration - -### Interface -**Input**: -- `--session` (required): WFS-{session-id} -- `--context` (required): context-package.json path -- Requires: `conflict_risk ≥ medium` - -**Output**: -- Generated file: - - `.workflow/active/{session_id}/.process/conflict-resolution.json` (primary output) -- Modified files (if exist): - - `.workflow/active/{session_id}/.brainstorm/guidance-specification.md` - - `.workflow/active/{session_id}/.brainstorm/{role}/analysis.md` - - `.workflow/active/{session_id}/.process/context-package.json` (conflict_risk → resolved, resolution_file reference) - -**User Interaction**: -- **Iterative conflict processing**: One conflict at a time, not in batches -- Each conflict: 2-4 strategy options + "自定义修改" option (with suggestions) -- **Clarification loop**: Unlimited questions per conflict until uniqueness confirmed (max 10 rounds) -- **ModuleOverlap conflicts**: Display overlap_analysis with existing modules -- **Agent re-analysis**: Dynamic strategy updates based on user clarifications - -### Success Criteria -``` -✓ CLI analysis returns valid JSON structure with ModuleOverlap category -✓ Agent performs scenario uniqueness detection (searches existing modules) -✓ Conflicts processed ONE BY ONE with iterative clarification -✓ Min 2 strategies per conflict with modifications -✓ ModuleOverlap conflicts include overlap_analysis with existing modules -✓ Strategies requiring clarification include clarification_needed questions -✓ Each conflict includes 2-5 modification_suggestions -✓ Text output displays conflict with overlap analysis (if ModuleOverlap) -✓ User selections captured per conflict -✓ Clarification loop continues until uniqueness confirmed (unlimited rounds, max 10) -✓ Agent re-analysis with user clarifications updates strategy -✓ Uniqueness confirmation based on clear scenario boundaries -✓ Edit tool applies modifications successfully -✓ Custom conflicts displayed with overlap_analysis for manual handling -✓ guidance-specification.md updated with resolved conflicts -✓ Role analyses (*.md) updated with resolved conflicts -✓ context-package.json marked as "resolved" with clarification records -✓ conflict-resolution.json generated with full resolution details -✓ Modification summary includes: - - Total conflicts - - Resolved with strategy (count) - - Custom handling (count) - - Clarification records - - Overlap analysis for custom ModuleOverlap conflicts -✓ Agent log saved to .workflow/active/{session_id}/.chat/ -✓ Error handling robust (validate/retry/degrade) -``` - diff --git a/.claude/commands/workflow/tools/context-gather.md b/.claude/commands/workflow/tools/context-gather.md deleted file mode 100644 index c93ab012..00000000 --- a/.claude/commands/workflow/tools/context-gather.md +++ /dev/null @@ -1,408 +0,0 @@ ---- -name: gather -description: Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON -argument-hint: "--session WFS-session-id \"task description\"" -examples: - - /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system" - - /workflow:tools:context-gather --session WFS-payment "Refactor payment module API" - - /workflow:tools:context-gather --session WFS-bugfix "Fix login validation error" -allowed-tools: Task(*), Read(*), Glob(*) ---- - -# Context Gather Command (/workflow:tools:context-gather) - -## Overview - -Orchestrator command that invokes `context-search-agent` to gather comprehensive project context for implementation planning. Generates standardized `context-package.json` with codebase analysis, dependencies, and conflict detection. - - -## Core Philosophy - -- **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution -- **Detection-First**: Check for existing context-package before executing -- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode) -- **Standardized Output**: Generate `.workflow/active/{session}/.process/context-package.json` - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session - └─ Parse: task_description (required) - -Step 1: Context-Package Detection - └─ Decision (existing package): - ├─ Valid package exists → Return existing (skip execution) - └─ No valid package → Continue to Step 2 - -Step 2: Complexity Assessment & Parallel Explore - ├─ Analyze task_description → classify Low/Medium/High - ├─ Select exploration angles (1-4 based on complexity) - ├─ Launch N cli-explore-agents in parallel - │ └─ Each outputs: exploration-{angle}.json - └─ Generate explorations-manifest.json - -Step 3: Invoke Context-Search Agent (with exploration input) - ├─ Phase 1: Initialization & Pre-Analysis - ├─ Phase 2: Multi-Source Discovery - │ ├─ Track 0: Exploration Synthesis (prioritize & deduplicate) - │ ├─ Track 1-4: Existing tracks - └─ Phase 3: Synthesis & Packaging - └─ Generate context-package.json with exploration_results - -Step 4: Output Verification - └─ Verify context-package.json contains exploration_results -``` - -## Execution Flow - -### Step 1: Context-Package Detection - -**Execute First** - Check if valid package already exists: - -```javascript -const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`; - -if (file_exists(contextPackagePath)) { - const existing = Read(contextPackagePath); - - // Validate package belongs to current session - if (existing?.metadata?.session_id === session_id) { - console.log("✅ Valid context-package found for session:", session_id); - console.log("📊 Stats:", existing.statistics); - console.log("⚠️ Conflict Risk:", existing.conflict_detection.risk_level); - return existing; // Skip execution, return existing - } else { - console.warn("⚠️ Invalid session_id in existing package, re-generating..."); - } -} -``` - -### Step 2: Complexity Assessment & Parallel Explore - -**Only execute if Step 1 finds no valid package** - -```javascript -// 2.1 Complexity Assessment -function analyzeTaskComplexity(taskDescription) { - const text = taskDescription.toLowerCase(); - if (/architect|refactor|restructure|modular|cross-module/.test(text)) return 'High'; - if (/multiple|several|integrate|migrate|extend/.test(text)) return 'Medium'; - return 'Low'; -} - -const ANGLE_PRESETS = { - architecture: ['architecture', 'dependencies', 'modularity', 'integration-points'], - security: ['security', 'auth-patterns', 'dataflow', 'validation'], - performance: ['performance', 'bottlenecks', 'caching', 'data-access'], - bugfix: ['error-handling', 'dataflow', 'state-management', 'edge-cases'], - feature: ['patterns', 'integration-points', 'testing', 'dependencies'], - refactor: ['architecture', 'patterns', 'dependencies', 'testing'] -}; - -function selectAngles(taskDescription, complexity) { - const text = taskDescription.toLowerCase(); - let preset = 'feature'; - if (/refactor|architect|restructure/.test(text)) preset = 'architecture'; - else if (/security|auth|permission/.test(text)) preset = 'security'; - else if (/performance|slow|optimi/.test(text)) preset = 'performance'; - else if (/fix|bug|error|issue/.test(text)) preset = 'bugfix'; - - const count = complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1); - return ANGLE_PRESETS[preset].slice(0, count); -} - -const complexity = analyzeTaskComplexity(task_description); -const selectedAngles = selectAngles(task_description, complexity); -const sessionFolder = `.workflow/active/${session_id}/.process`; - -// 2.2 Launch Parallel Explore Agents -const explorationTasks = selectedAngles.map((angle, index) => - Task( - subagent_type="cli-explore-agent", - run_in_background=false, - description=`Explore: ${angle}`, - prompt=` -## Task Objective -Execute **${angle}** exploration for task planning context. Analyze codebase from this specific angle to discover relevant structure, patterns, and constraints. - -## Assigned Context -- **Exploration Angle**: ${angle} -- **Task Description**: ${task_description} -- **Session ID**: ${session_id} -- **Exploration Index**: ${index + 1} of ${selectedAngles.length} -- **Output File**: ${sessionFolder}/exploration-${angle}.json - -## MANDATORY FIRST STEPS (Execute by Agent) -**You (cli-explore-agent) MUST execute these steps in order:** -1. Run: ccw tool exec get_modules_by_depth '{}' (project structure) -2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files) -3. Execute: cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference) - -## Exploration Strategy (${angle} focus) - -**Step 1: Structural Scan** (Bash) -- get_modules_by_depth.sh → identify modules related to ${angle} -- find/rg → locate files relevant to ${angle} aspect -- Analyze imports/dependencies from ${angle} perspective - -**Step 2: Semantic Analysis** (Gemini CLI) -- How does existing code handle ${angle} concerns? -- What patterns are used for ${angle}? -- Where would new code integrate from ${angle} viewpoint? - -**Step 3: Write Output** -- Consolidate ${angle} findings into JSON -- Identify ${angle}-specific clarification needs - -## Expected Output - -**File**: ${sessionFolder}/exploration-${angle}.json - -**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly - -**Required Fields** (all ${angle} focused): -- project_structure: Modules/architecture relevant to ${angle} -- relevant_files: Files affected from ${angle} perspective - **MANDATORY**: Every file MUST use structured object format with ALL required fields: - \`[{path: "src/file.ts", relevance: 0.85, rationale: "Contains AuthService.login() - entry point for JWT token generation", role: "modify_target", discovery_source: "bash-scan", key_symbols: ["AuthService", "login"]}]\` - - **rationale** (required): Specific selection basis tied to ${angle} topic (>10 chars, not generic) - - **role** (required): modify_target|dependency|pattern_reference|test_target|type_definition|integration_point|config|context_only - - **discovery_source** (recommended): bash-scan|cli-analysis|ace-search|dependency-trace|manual - - **key_symbols** (recommended): Key functions/classes/types in the file relevant to the task - - Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low -- patterns: ${angle}-related patterns to follow -- dependencies: Dependencies relevant to ${angle} -- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations) -- constraints: ${angle}-specific limitations/conventions -- clarification_needs: ${angle}-related ambiguities (options array + recommended index) -- _metadata.exploration_angle: "${angle}" - -## Success Criteria -- [ ] Schema obtained via cat explore-json-schema.json -- [ ] get_modules_by_depth.sh executed -- [ ] At least 3 relevant files identified with ${angle} rationale -- [ ] Patterns are actionable (code examples, not generic advice) -- [ ] Integration points include file:line locations -- [ ] Constraints are project-specific to ${angle} -- [ ] JSON output follows schema exactly -- [ ] clarification_needs includes options + recommended - -## Output -Write: ${sessionFolder}/exploration-${angle}.json -Return: 2-3 sentence summary of ${angle} findings -` - ) -); - -// 2.3 Generate Manifest after all complete -const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`).split('\n').filter(f => f.trim()); -const explorationManifest = { - session_id, - task_description, - timestamp: new Date().toISOString(), - complexity, - exploration_count: selectedAngles.length, - angles_explored: selectedAngles, - explorations: explorationFiles.map(file => { - const data = JSON.parse(Read(file)); - return { angle: data._metadata.exploration_angle, file: file.split('/').pop(), path: file, index: data._metadata.exploration_index }; - }) -}; -Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2)); -``` - -### Step 3: Invoke Context-Search Agent - -**Only execute after Step 2 completes** - -```javascript -// Load user intent from planning-notes.md (from Phase 1) -const planningNotesPath = `.workflow/active/${session_id}/planning-notes.md`; -let userIntent = { goal: task_description, key_constraints: "None specified" }; - -if (file_exists(planningNotesPath)) { - const notesContent = Read(planningNotesPath); - const goalMatch = notesContent.match(/\*\*GOAL\*\*:\s*(.+)/); - const constraintsMatch = notesContent.match(/\*\*KEY_CONSTRAINTS\*\*:\s*(.+)/); - if (goalMatch) userIntent.goal = goalMatch[1].trim(); - if (constraintsMatch) userIntent.key_constraints = constraintsMatch[1].trim(); -} - -Task( - subagent_type="context-search-agent", - run_in_background=false, - description="Gather comprehensive context for plan", - prompt=` -## Execution Mode -**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution with priority sorting - -## Session Information -- **Session ID**: ${session_id} -- **Task Description**: ${task_description} -- **Output Path**: .workflow/${session_id}/.process/context-package.json - -## User Intent (from Phase 1 - Planning Notes) -**GOAL**: ${userIntent.goal} -**KEY_CONSTRAINTS**: ${userIntent.key_constraints} - -This is the PRIMARY context source - all subsequent analysis must align with user intent. - -## Exploration Input (from Step 2) -- **Manifest**: ${sessionFolder}/explorations-manifest.json -- **Exploration Count**: ${explorationManifest.exploration_count} -- **Angles**: ${explorationManifest.angles_explored.join(', ')} -- **Complexity**: ${complexity} - -## Mission -Execute complete context-search-agent workflow for implementation planning: - -### Phase 1: Initialization & Pre-Analysis -1. **Project State Loading**: - - Read and parse `.workflow/project-tech.json`. Use its `overview` section as the foundational `project_context`. This is your primary source for architecture, tech stack, and key components. - - Read and parse `.workflow/project-guidelines.json`. Load `conventions`, `constraints`, and `learnings` into a `project_guidelines` section. - - If files don't exist, proceed with fresh analysis. -2. **Detection**: Check for existing context-package (early exit if valid) -3. **Foundation**: Initialize CodexLens, get project structure, load docs -4. **Analysis**: Extract keywords, determine scope, classify complexity based on task description and project state - -### Phase 2: Multi-Source Context Discovery -Execute all discovery tracks (WITH USER INTENT INTEGRATION): -- **Track -1**: User Intent & Priority Foundation (EXECUTE FIRST) - - Load user intent (GOAL, KEY_CONSTRAINTS) from session input - - Map user requirements to codebase entities (files, modules, patterns) - - Establish baseline priority scores based on user goal alignment - - Output: user_intent_mapping.json with preliminary priority scores - -- **Track 0**: Exploration Synthesis (load ${sessionFolder}/explorations-manifest.json, prioritize critical_files, deduplicate patterns/integration_points) -- **Track 1**: Historical archive analysis (query manifest.json for lessons learned) -- **Track 2**: Reference documentation (CLAUDE.md, architecture docs) -- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs) -- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests) - -### Phase 3: Synthesis, Assessment & Packaging -1. Apply relevance scoring and build dependency graph -2. **Synthesize 5-source data** (including Track -1): Merge findings from all sources - - Priority order: User Intent > Archive > Docs > Exploration > Code > Web - - **Prioritize the context from `project-tech.json`** for architecture and tech stack unless code analysis reveals it's outdated -3. **Context Priority Sorting**: - a. Combine scores from Track -1 (user intent alignment) + relevance scores + exploration critical_files - b. Classify files into priority tiers: - - **Critical** (score ≥ 0.85): Directly mentioned in user goal OR exploration critical_files - - **High** (0.70-0.84): Key dependencies, patterns required for goal - - **Medium** (0.50-0.69): Supporting files, indirect dependencies - - **Low** (< 0.50): Contextual awareness only - c. Generate dependency_order: Based on dependency graph + user goal sequence - d. Document sorting_rationale: Explain prioritization logic - -4. **Populate `project_context`**: Directly use the `overview` from `project-tech.json` to fill the `project_context` section. Include description, technology_stack, architecture, and key_components. -5. **Populate `project_guidelines`**: Load conventions, constraints, and learnings from `project-guidelines.json` into a dedicated section. -6. Integrate brainstorm artifacts (if .brainstorming/ exists, read content) -7. Perform conflict detection with risk assessment -8. **Inject historical conflicts** from archive analysis into conflict_detection -9. **Generate prioritized_context section**: - ```json - { - "prioritized_context": { - "user_intent": { - "goal": "...", - "scope": "...", - "key_constraints": ["..."] - }, - "priority_tiers": { - "critical": [{ "path": "...", "relevance": 0.95, "rationale": "..." }], - "high": [...], - "medium": [...], - "low": [...] - }, - "dependency_order": ["module1", "module2", "module3"], - "sorting_rationale": "Based on user goal alignment (Track -1), exploration critical files, and dependency graph analysis" - } - } - ``` -10. Generate and validate context-package.json with prioritized_context field - -## Output Requirements -Complete context-package.json with: -- **metadata**: task_description, keywords, complexity, tech_stack, session_id -- **project_context**: description, technology_stack, architecture, key_components (sourced from `project-tech.json`) -- **project_guidelines**: {conventions, constraints, quality_rules, learnings} (sourced from `project-guidelines.json`) -- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores -- **dependencies**: {internal[], external[]} with dependency graph -- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content -- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]} -- **exploration_results**: {manifest_path, exploration_count, angles, explorations[], aggregated_insights} (from Track 0) -- **prioritized_context**: {user_intent, priority_tiers{critical, high, medium, low}, dependency_order[], sorting_rationale} - -## Quality Validation -Before completion verify: -- [ ] Valid JSON format with all required fields -- [ ] File relevance accuracy >80% -- [ ] Dependency graph complete (max 2 transitive levels) -- [ ] Conflict risk level calculated correctly -- [ ] No sensitive data exposed -- [ ] Total files ≤50 (prioritize high-relevance) - -## Planning Notes Record (REQUIRED) -After completing context-package.json, append a brief execution record to planning-notes.md: - -**File**: .workflow/active/${session_id}/planning-notes.md -**Location**: Under "## Context Findings (Phase 2)" section -**Format**: -\`\`\` -### [Context-Search Agent] YYYY-MM-DD -- **Note**: [智能补充：简短总结关键发现，如探索角度、关键文件、冲突风险等] -\`\`\` - -Execute autonomously following agent documentation. -Report completion with statistics. -` -) -``` - -### Step 4: Output Verification - -After agent completes, verify output: - -```javascript -// Verify file was created -const outputPath = `.workflow/${session_id}/.process/context-package.json`; -if (!file_exists(outputPath)) { - throw new Error("❌ Agent failed to generate context-package.json"); -} - -// Verify exploration_results included -const pkg = JSON.parse(Read(outputPath)); -if (pkg.exploration_results?.exploration_count > 0) { - console.log(`✅ Exploration results aggregated: ${pkg.exploration_results.exploration_count} angles`); -} -``` - -## Parameter Reference - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `--session` | string | ✅ | Workflow session ID (e.g., WFS-user-auth) | -| `task_description` | string | ✅ | Detailed task description for context extraction | - -## Output Schema - -Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json` schema. - -**Key Sections**: -- **metadata**: Session info, keywords, complexity, tech stack -- **project_context**: Architecture patterns, conventions, tech stack (populated from `project-tech.json`) -- **project_guidelines**: Conventions, constraints, quality rules, learnings (populated from `project-guidelines.json`) -- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests) -- **dependencies**: Internal and external dependency graphs -- **brainstorm_artifacts**: Brainstorm documents with full content (if exists) -- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts -- **exploration_results**: Aggregated exploration insights (from parallel explore phase) -- **prioritized_context**: Pre-sorted context with user intent and priority tiers (critical/high/medium/low) - -## Notes - -- **Detection-first**: Always check for existing package before invoking agent -- **User intent integration**: Load user intent from planning-notes.md (Phase 1 output) -- **Output**: Generates `context-package.json` with `prioritized_context` field -- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call diff --git a/.claude/commands/workflow/tools/task-generate-agent.md b/.claude/commands/workflow/tools/task-generate-agent.md deleted file mode 100644 index 0749c1b7..00000000 --- a/.claude/commands/workflow/tools/task-generate-agent.md +++ /dev/null @@ -1,731 +0,0 @@ ---- -name: task-generate-agent -description: Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation -argument-hint: "[-y|--yes] --session WFS-session-id" -examples: - - /workflow:tools:task-generate-agent --session WFS-auth - - /workflow:tools:task-generate-agent -y --session WFS-auth ---- - -## Auto Mode - -When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor, Codex CLI tool). - -# Generate Implementation Plan Command - -## Overview -Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent. This command produces **planning artifacts only** - it does NOT execute code implementation. Actual code implementation requires separate execution command (e.g., /workflow:execute). - -## Core Philosophy -- **Planning Only**: Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - does NOT implement code -- **Agent-Driven Document Generation**: Delegate plan generation to action-planning-agent -- **NO Redundant Context Sorting**: Context priority sorting is ALREADY completed in context-gather Phase 2/3 - - Use `context-package.json.prioritized_context` directly - - DO NOT re-sort files or re-compute priorities - - `priority_tiers` and `dependency_order` are pre-computed and ready-to-use -- **N+1 Parallel Planning**: Auto-detect multi-module projects, enable parallel planning (2+1 or 3+1 mode) -- **Progressive Loading**: Load context incrementally (Core → Selective → On-Demand) due to analysis.md file size -- **Memory-First**: Reuse loaded documents from conversation memory -- **Smart Selection**: Load synthesis_output OR guidance + relevant role analyses, NOT all role analyses -- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research -- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`) - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session - └─ Validation: session_id REQUIRED - -Phase 0: User Configuration (Interactive) - ├─ Question 1: Supplementary materials/guidelines? - ├─ Question 2: Execution method preference (Agent/CLI/Hybrid) - ├─ Question 3: CLI tool preference (if CLI selected) - └─ Store: userConfig for agent prompt - -Phase 1: Context Preparation & Module Detection (Command) - ├─ Assemble session paths (metadata, context package, output dirs) - ├─ Provide metadata (session_id, execution_mode, mcp_capabilities) - ├─ Auto-detect modules from context-package + directory structure - └─ Decision: - ├─ modules.length == 1 → Single Agent Mode (Phase 2A) - └─ modules.length >= 2 → Parallel Mode (Phase 2B + Phase 3) - -Phase 2A: Single Agent Planning (Original Flow) - ├─ Load context package (progressive loading strategy) - ├─ Generate Task JSON Files (.task/IMPL-*.json) - ├─ Create IMPL_PLAN.md - └─ Generate TODO_LIST.md - -Phase 2B: N Parallel Planning (Multi-Module) - ├─ Launch N action-planning-agents simultaneously (one per module) - ├─ Each agent generates module-scoped tasks (IMPL-{prefix}{seq}.json) - ├─ Task ID format: IMPL-A1, IMPL-A2... / IMPL-B1, IMPL-B2... - └─ Each module limited to ≤9 tasks - -Phase 3: Integration (+1 Coordinator, Multi-Module Only) - ├─ Collect all module task JSONs - ├─ Resolve cross-module dependencies (CROSS::{module}::{pattern} → actual ID) - ├─ Generate unified IMPL_PLAN.md (grouped by module) - └─ Generate TODO_LIST.md (hierarchical: module → tasks) -``` - -## Document Generation Lifecycle - -### Phase 0: User Configuration (Interactive) - -**Purpose**: Collect user preferences before task generation to ensure generated tasks match execution expectations. - -**Auto Mode Check**: -```javascript -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') - -if (autoYes) { - console.log(`[--yes] Using defaults: No materials, Agent executor, Codex CLI`) - userConfig = { - supplementaryMaterials: { type: "none", content: [] }, - executionMethod: "agent", - preferredCliTool: "codex", - enableResume: true - } - // Skip to Phase 1 -} -``` - -**User Questions** (skipped if autoYes): -```javascript -if (!autoYes) AskUserQuestion({ - questions: [ - { - question: "Do you have supplementary materials or guidelines to include?", - header: "Materials", - multiSelect: false, - options: [ - { label: "No additional materials", description: "Use existing context only" }, - { label: "Provide file paths", description: "I'll specify paths to include" }, - { label: "Provide inline content", description: "I'll paste content directly" } - ] - }, - { - question: "Select execution method for generated tasks:", - header: "Execution", - multiSelect: false, - options: [ - { label: "Agent (Recommended)", description: "Claude agent executes tasks directly" }, - { label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps" }, - { label: "CLI Only", description: "All execution via CLI tools (codex/gemini/qwen)" } - ] - }, - { - question: "If using CLI, which tool do you prefer?", - header: "CLI Tool", - multiSelect: false, - options: [ - { label: "Codex (Recommended)", description: "Best for implementation tasks" }, - { label: "Gemini", description: "Best for analysis and large context" }, - { label: "Qwen", description: "Alternative analysis tool" }, - { label: "Auto", description: "Let agent decide per-task" } - ] - } - ] -}) - -**Handle Materials Response** (skipped if autoYes): -```javascript -if (!autoYes && userConfig.materials === "Provide file paths") { - // Follow-up question for file paths - const pathsResponse = AskUserQuestion({ - questions: [{ - question: "Enter file paths to include (comma-separated or one per line):", - header: "Paths", - multiSelect: false, - options: [ - { label: "Enter paths", description: "Provide paths in text input" } - ] - }] - }) - userConfig.supplementaryPaths = parseUserPaths(pathsResponse) -} -``` - -**Build userConfig**: -```javascript -const userConfig = { - supplementaryMaterials: { - type: "none|paths|inline", - content: [...], // Parsed paths or inline content - }, - executionMethod: "agent|hybrid|cli", - preferredCliTool: "codex|gemini|qwen|auto", - enableResume: true // Always enable resume for CLI executions -} -``` - -**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2A/2B. - -### Phase 1: Context Preparation & Module Detection (Command Responsibility) - -**Command prepares session paths, metadata, detects module structure. Context priority sorting is NOT performed here - it's already completed in context-gather Phase 2/3.** - -**Session Path Structure**: -``` -.workflow/active/WFS-{session-id}/ -├── workflow-session.json # Session metadata -├── planning-notes.md # Consolidated planning notes -├── .process/ -│ └── context-package.json # Context package with artifact catalog -├── .task/ # Output: Task JSON files -│ ├── IMPL-A1.json # Multi-module: prefixed by module -│ ├── IMPL-A2.json -│ ├── IMPL-B1.json -│ └── ... -├── plan.json # Output: Structured plan overview -├── IMPL_PLAN.md # Output: Implementation plan (grouped by module) -└── TODO_LIST.md # Output: TODO list (hierarchical) -``` - -**Command Preparation**: -1. **Assemble Session Paths** for agent prompt: - - `session_metadata_path` - - `context_package_path` - - Output directory paths - -2. **Provide Metadata** (simple values): - - `session_id` - - `mcp_capabilities` (available MCP tools) - -3. **Auto Module Detection** (determines single vs parallel mode): - ```javascript - function autoDetectModules(contextPackage, projectRoot) { - // === Complexity Gate: Only parallelize for High complexity === - const complexity = contextPackage.metadata?.complexity || 'Medium'; - if (complexity !== 'High') { - // Force single agent mode for Low/Medium complexity - // This maximizes agent context reuse for related tasks - return [{ name: 'main', prefix: '', paths: ['.'] }]; - } - - // Priority 1: Explicit frontend/backend separation - if (exists('src/frontend') && exists('src/backend')) { - return [ - { name: 'frontend', prefix: 'A', paths: ['src/frontend'] }, - { name: 'backend', prefix: 'B', paths: ['src/backend'] } - ]; - } - - // Priority 2: Monorepo structure - if (exists('packages/*') || exists('apps/*')) { - return detectMonorepoModules(); // Returns 2-3 main packages - } - - // Priority 3: Context-package dependency clustering - const modules = clusterByDependencies(contextPackage.dependencies?.internal); - if (modules.length >= 2) return modules.slice(0, 3); - - // Default: Single module (original flow) - return [{ name: 'main', prefix: '', paths: ['.'] }]; - } - ``` - -**Decision Logic**: -- `complexity !== 'High'` → Force Phase 2A (Single Agent, maximize context reuse) -- `modules.length == 1` → Phase 2A (Single Agent, original flow) -- `modules.length >= 2 && complexity == 'High'` → Phase 2B + Phase 3 (N+1 Parallel) - -**Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description, not by flags. - -### Phase 2A: Single Agent Planning (Original Flow) - -**Condition**: `modules.length == 1` (no multi-module detected) - -**Purpose**: Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT code implementation. - -**Agent Invocation**: -```javascript -Task( - subagent_type="action-planning-agent", - run_in_background=false, - description="Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)", - prompt=` -## TASK OBJECTIVE -Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session - -IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code. - -CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size) - -## PLANNING NOTES (PHASE 1-3 CONTEXT) -Load: .workflow/active/{session-id}/planning-notes.md - -This document contains: -- User Intent: Original GOAL and KEY_CONSTRAINTS from Phase 1 -- Context Findings: Critical files, architecture, and constraints from Phase 2 -- Conflict Decisions: Resolved conflicts and planning constraints from Phase 3 -- Consolidated Constraints: All constraints from all phases - -**USAGE**: Read planning-notes.md FIRST. Use Consolidated Constraints list to guide task sequencing and dependencies. - -## SESSION PATHS -Input: - - Session Metadata: .workflow/active/{session-id}/workflow-session.json - - Planning Notes: .workflow/active/{session-id}/planning-notes.md - - Context Package: .workflow/active/{session-id}/.process/context-package.json - -Output: - - Task Dir: .workflow/active/{session-id}/.task/ - - IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md - - TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md - -## CONTEXT METADATA -Session ID: {session-id} -MCP Capabilities: {exa_code, exa_web, code_index} - -## FEATURE SPECIFICATIONS (conditional) -If context-package has brainstorm_artifacts.feature_index_path: - Feature Index: ${contextPackage.brainstorm_artifacts.feature_index_path} - Feature Spec Dir: ${contextPackage.brainstorm_artifacts.feature_index_path.replace('/feature-index.json', '/')} -Else if .workflow/active/{session-id}/.brainstorming/feature-specs/ exists: - Feature Index: .workflow/active/{session-id}/.brainstorming/feature-specs/feature-index.json - Feature Spec Dir: .workflow/active/{session-id}/.brainstorming/feature-specs/ - -Use feature-index.json to: -- Map features to implementation tasks (feature_id → task alignment) -- Reference individual feature spec files (spec_path) for detailed requirements -- Identify cross-cutting concerns (cross_cutting_specs) that span multiple tasks -- Align task priorities with feature priorities - -If the directory does not exist, skip this section (backward compatible with non-brainstorm workflows). - -## USER CONFIGURATION (from Phase 0) -Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli -Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto -Supplementary Materials: ${userConfig.supplementaryMaterials} - -## EXECUTION METHOD MAPPING -Based on userConfig.executionMethod, set task-level meta.execution_config: - -"agent" → - meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false } - Agent executes implementation steps directly - -"cli" → - meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true } - Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt() - -"hybrid" → - Per-task decision: Analyze task complexity, set method to "agent" OR "cli" per task - - Simple tasks (≤3 files, straightforward logic) → method: "agent" - - Complex tasks (>3 files, complex logic, refactoring) → method: "cli" - CLI tool: userConfig.preferredCliTool, enable_resume: true - -IMPORTANT: Do NOT add command field to implementation steps. Execution routing is controlled by task-level meta.execution_config.method only. - -## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED -Context sorting is ALREADY COMPLETED in context-gather Phase 2/3. DO NOT re-sort. -Direct usage: -- **user_intent**: Use goal/scope/key_constraints for task alignment -- **priority_tiers.critical**: These files are PRIMARY focus for task generation -- **priority_tiers.high**: These files are SECONDARY focus -- **dependency_order**: Use this for task sequencing - already computed -- **sorting_rationale**: Reference for understanding priority decisions - -## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY -If prioritized_context is incomplete, fall back to exploration_results: -- Load exploration_results from context-package.json -- Use aggregated_insights.critical_files for focus_paths generation -- Apply aggregated_insights.constraints to acceptance criteria -- Reference aggregated_insights.all_patterns for implementation approach -- Use aggregated_insights.all_integration_points for precise modification locations -- Use conflict_indicators for risk-aware task sequencing - -## CONFLICT RESOLUTION CONTEXT (if exists) -- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path -- If exists, load .process/conflict-resolution.json: - - Apply planning_constraints as task constraints (for brainstorm-less workflows) - - Reference resolved_conflicts for implementation approach alignment - - Handle custom_conflicts with explicit task notes - -## EXPECTED DELIVERABLES -1. Task JSON Files (.task/IMPL-*.json) - - Unified flat schema (task-schema.json) - - Quantified requirements with explicit counts - - Artifacts integration from context package - - **focus_paths generated directly from prioritized_context.priority_tiers (critical + high)** - - NO re-sorting or re-prioritization - use pre-computed tiers as-is - - Critical files are PRIMARY focus, High files are SECONDARY - - Pre-analysis steps (use prioritized_context.dependency_order for task sequencing) - - **CLI Execution IDs and strategies (MANDATORY)** - -2. Implementation Plan (IMPL_PLAN.md) - - Context analysis and artifact references - - Task breakdown and execution strategy - - Complete structure per agent definition - -3. Plan Overview (plan.json) - - Structured plan overview (plan-overview-base-schema) - - Machine-readable task IDs, shared context, metadata - -4. TODO List (TODO_LIST.md) - - Hierarchical structure (containers, pending, completed markers) - - Links to task JSONs and summaries - - Matches task JSON hierarchy - -## CLI EXECUTION ID REQUIREMENTS (MANDATORY) -Each task JSON MUST include: -- **cli_execution.id**: Unique ID for CLI execution (format: `{session_id}-{task_id}`) -- **cli_execution**: Strategy object based on depends_on: - - No deps → `{ "strategy": "new" }` - - 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }` - - 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }` - - N deps → `{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }` - -**CLI Execution Strategy Rules**: -1. **new**: Task has no dependencies - starts fresh CLI conversation -2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation -3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context -4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation - -**Execution Command Patterns**: -- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]` -- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write` -- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write` -- merge_fork: `ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write` - -## QUALITY STANDARDS -Hard Constraints: - - Task count <= 18 (hard limit - request re-scope if exceeded) - - All requirements quantified (explicit counts and enumerated lists) - - Acceptance criteria measurable (include verification commands) - - Artifact references mapped from context package - - All documents follow agent-defined structure - -## SUCCESS CRITERIA -- All planning documents generated successfully: - - Task JSONs valid and saved to .task/ directory - - IMPL_PLAN.md created with complete structure - - TODO_LIST.md generated matching task JSONs -- Return completion status with document count and task breakdown summary - -## PLANNING NOTES RECORD (REQUIRED) -After completing, update planning-notes.md: - -**File**: .workflow/active/{session_id}/planning-notes.md - -1. **Task Generation (Phase 4)**: Task count and key tasks -2. **N+1 Context**: Key decisions (with rationale) + deferred items - -\`\`\`markdown -## Task Generation (Phase 4) -### [Action-Planning Agent] YYYY-MM-DD -- **Tasks**: [count] ([IDs]) - -## N+1 Context -### Decisions -| Decision | Rationale | Revisit? | -|----------|-----------|----------| -| [choice] | [why] | [Yes/No] | - -### Deferred -- [ ] [item] - [reason] -\`\`\` -` -) -``` - -### Phase 2B: N Parallel Planning (Multi-Module) - -**Condition**: `modules.length >= 2` (multi-module detected) - -**Purpose**: Launch N action-planning-agents simultaneously, one per module, for parallel task JSON generation. - -**Note**: Phase 2B agents generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md are generated by Phase 3 Coordinator. - -**Parallel Agent Invocation**: -```javascript -// Launch N agents in parallel (one per module) -const planningTasks = modules.map(module => - Task( - subagent_type="action-planning-agent", - run_in_background=false, - description=`Generate ${module.name} module task JSONs`, - prompt=` -## TASK OBJECTIVE -Generate task JSON files for ${module.name} module within workflow session - -IMPORTANT: This is PLANNING ONLY - generate task JSONs, NOT implementing code. -IMPORTANT: Generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md by Phase 3 Coordinator. - -CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size) - -## PLANNING NOTES (PHASE 1-3 CONTEXT) -Load: .workflow/active/{session-id}/planning-notes.md - -This document contains consolidated constraints and user intent to guide module-scoped task generation. - -## MODULE SCOPE -- Module: ${module.name} (${module.type}) -- Focus Paths: ${module.paths.join(', ')} -- Task ID Prefix: IMPL-${module.prefix} -- Task Limit: ≤6 tasks (hard limit for this module) -- Other Modules: ${otherModules.join(', ')} (reference only, do NOT generate tasks for them) - -## SESSION PATHS -Input: - - Session Metadata: .workflow/active/{session-id}/workflow-session.json - - Planning Notes: .workflow/active/{session-id}/planning-notes.md - - Context Package: .workflow/active/{session-id}/.process/context-package.json - -Output: - - Task Dir: .workflow/active/{session-id}/.task/ - -## CONTEXT METADATA -Session ID: {session-id} -MCP Capabilities: {exa_code, exa_web, code_index} - -## FEATURE SPECIFICATIONS (conditional) -If context-package has brainstorm_artifacts.feature_index_path: - Feature Index: ${contextPackage.brainstorm_artifacts.feature_index_path} - Feature Spec Dir: ${contextPackage.brainstorm_artifacts.feature_index_path.replace('/feature-index.json', '/')} -Else if .workflow/active/{session-id}/.brainstorming/feature-specs/ exists: - Feature Index: .workflow/active/{session-id}/.brainstorming/feature-specs/feature-index.json - Feature Spec Dir: .workflow/active/{session-id}/.brainstorming/feature-specs/ - -Use feature-index.json to: -- Map features to module-scoped tasks (filter by ${module.paths.join(', ')}) -- Reference individual feature spec files (spec_path) for detailed requirements -- Identify cross-cutting concerns affecting this module -- Align task priorities with feature priorities - -If the directory does not exist, skip this section (backward compatible with non-brainstorm workflows). - -## USER CONFIGURATION (from Phase 0) -Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli -Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto -Supplementary Materials: ${userConfig.supplementaryMaterials} - -## EXECUTION METHOD MAPPING -Based on userConfig.executionMethod, set task-level meta.execution_config: - -"agent" → - meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false } - Agent executes implementation steps directly - -"cli" → - meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true } - Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt() - -"hybrid" → - Per-task decision: Analyze task complexity, set method to "agent" OR "cli" per task - - Simple tasks (≤3 files, straightforward logic) → method: "agent" - - Complex tasks (>3 files, complex logic, refactoring) → method: "cli" - CLI tool: userConfig.preferredCliTool, enable_resume: true - -IMPORTANT: Do NOT add command field to implementation steps. Execution routing is controlled by task-level meta.execution_config.method only. - -## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED -Context sorting is ALREADY COMPLETED in context-gather Phase 2/3. DO NOT re-sort. -Filter by module scope (${module.paths.join(', ')}): -- **user_intent**: Use for task alignment within module -- **priority_tiers.critical**: Filter for files in ${module.paths.join(', ')} → PRIMARY focus -- **priority_tiers.high**: Filter for files in ${module.paths.join(', ')} → SECONDARY focus -- **dependency_order**: Use module-relevant entries for task sequencing - -## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY -If prioritized_context is incomplete for this module, fall back to exploration_results: -- Load exploration_results from context-package.json -- Filter for ${module.name} module: Use aggregated_insights.critical_files matching ${module.paths.join(', ')} -- Apply module-relevant constraints from aggregated_insights.constraints -- Reference aggregated_insights.all_patterns applicable to ${module.name} -- Use aggregated_insights.all_integration_points for precise modification locations within module scope -- Use conflict_indicators for risk-aware task sequencing - -## CONFLICT RESOLUTION CONTEXT (if exists) -- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path -- If exists, load .process/conflict-resolution.json: - - Apply planning_constraints relevant to ${module.name} as task constraints - - Reference resolved_conflicts affecting ${module.name} for implementation approach alignment - - Handle custom_conflicts with explicit task notes - -## CROSS-MODULE DEPENDENCIES -- For dependencies ON other modules: Use placeholder depends_on: ["CROSS::{module}::{pattern}"] -- Example: depends_on: ["CROSS::B::api-endpoint"] (this module depends on B's api-endpoint task) -- Phase 3 Coordinator resolves to actual task IDs -- For dependencies FROM other modules: Document in task context as "provides_for" annotation - -## EXPECTED DELIVERABLES -Task JSON Files (.task/IMPL-${module.prefix}*.json): - - Unified flat schema (task-schema.json) - - Task ID format: IMPL-${module.prefix}1, IMPL-${module.prefix}2, ... - - Quantified requirements with explicit counts - - Artifacts integration from context package (filtered for ${module.name}) - - **focus_paths generated directly from prioritized_context.priority_tiers filtered by ${module.paths.join(', ')}** - - NO re-sorting - use pre-computed tiers filtered for this module - - Critical files are PRIMARY focus, High files are SECONDARY - - Pre-analysis steps (use prioritized_context.dependency_order for module task sequencing) - - **CLI Execution IDs and strategies (MANDATORY)** - - Focus ONLY on ${module.name} module scope - -## CLI EXECUTION ID REQUIREMENTS (MANDATORY) -Each task JSON MUST include: -- **cli_execution.id**: Unique ID for CLI execution (format: `{session_id}-IMPL-${module.prefix}{seq}`) -- **cli_execution**: Strategy object based on depends_on: - - No deps → `{ "strategy": "new" }` - - 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }` - - 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }` - - N deps → `{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }` - - Cross-module dep → `{ "strategy": "cross_module_fork", "resume_from": "CROSS::{module}::{pattern}" }` - -**CLI Execution Strategy Rules**: -1. **new**: Task has no dependencies - starts fresh CLI conversation -2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation -3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context -4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation -5. **cross_module_fork**: Task depends on task from another module - Phase 3 resolves placeholder - -**Execution Command Patterns**: -- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]` -- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write` -- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write` -- merge_fork: `ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write` -- cross_module_fork: (Phase 3 resolves placeholder, then uses fork pattern) - -## QUALITY STANDARDS -Hard Constraints: - - Task count <= 9 for this module (hard limit - coordinate with Phase 3 if exceeded) - - All requirements quantified (explicit counts and enumerated lists) - - Acceptance criteria measurable (include verification commands) - - Artifact references mapped from context package (module-scoped filter) - - Focus paths use absolute paths or clear relative paths from project root - - Cross-module dependencies use CROSS:: placeholder format - -## SUCCESS CRITERIA -- Task JSONs saved to .task/ with IMPL-${module.prefix}* naming -- All task JSONs include cli_execution.id and cli_execution strategy -- Cross-module dependencies use CROSS:: placeholder format consistently -- Focus paths scoped to ${module.paths.join(', ')} only -- Return: task count, task IDs, dependency summary (internal + cross-module) - -## PLANNING NOTES RECORD (REQUIRED) -After completing, append to planning-notes.md: - -\`\`\`markdown -### [${module.name}] YYYY-MM-DD -- **Tasks**: [count] ([IDs]) -- **CROSS deps**: [placeholders used] -\`\`\` - ` - ) -); - -// Execute all in parallel -await Promise.all(planningTasks); -``` - -**Output Structure** (direct to .task/): -``` -.task/ -├── IMPL-A1.json # Module A (e.g., frontend) -├── IMPL-A2.json -├── IMPL-B1.json # Module B (e.g., backend) -├── IMPL-B2.json -└── IMPL-C1.json # Module C (e.g., shared) -``` - -**Task ID Naming**: -- Format: `IMPL-{prefix}{seq}.json` -- Prefix: A, B, C... (assigned by detection order) -- Sequence: 1, 2, 3... (per-module increment) - -### Phase 3: Integration (+1 Coordinator Agent, Multi-Module Only) - -**Condition**: Only executed when `modules.length >= 2` - -**Purpose**: Collect all module tasks, resolve cross-module dependencies, generate unified IMPL_PLAN.md and TODO_LIST.md documents. - -**Coordinator Agent Invocation**: -```javascript -// Wait for all Phase 2B agents to complete -const moduleResults = await Promise.all(planningTasks); - -// Launch +1 Coordinator Agent -Task( - subagent_type="action-planning-agent", - run_in_background=false, - description="Integrate module tasks and generate unified documents", - prompt=` -## TASK OBJECTIVE -Integrate all module task JSONs, resolve cross-module dependencies, and generate unified IMPL_PLAN.md and TODO_LIST.md - -IMPORTANT: This is INTEGRATION ONLY - consolidate existing task JSONs, NOT creating new tasks. - -## SESSION PATHS -Input: - - Session Metadata: .workflow/active/{session-id}/workflow-session.json - - Context Package: .workflow/active/{session-id}/.process/context-package.json - - Task JSONs: .workflow/active/{session-id}/.task/IMPL-*.json (from Phase 2B) -Output: - - Updated Task JSONs: .workflow/active/{session-id}/.task/IMPL-*.json (resolved dependencies) - - IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md - - TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md - -## CONTEXT METADATA -Session ID: {session-id} -Modules: ${modules.map(m => m.name + '(' + m.prefix + ')').join(', ')} -Module Count: ${modules.length} - -## INTEGRATION STEPS -1. Collect all .task/IMPL-*.json, group by module prefix -2. Resolve CROSS:: dependencies → actual task IDs, update task JSONs -3. Generate IMPL_PLAN.md (multi-module format per agent specification) -4. Generate TODO_LIST.md (hierarchical format per agent specification) - -## CROSS-MODULE DEPENDENCY RESOLUTION -- Pattern: CROSS::{module}::{pattern} → IMPL-{module}* matching title/context -- Example: CROSS::B::api-endpoint → IMPL-B1 (if B1 title contains "api-endpoint") -- Log unresolved as warnings - -## EXPECTED DELIVERABLES -1. Updated Task JSONs with resolved dependency IDs -2. IMPL_PLAN.md - multi-module format with cross-dependency section -3. TODO_LIST.md - hierarchical by module with cross-dependency section - -## SUCCESS CRITERIA -- No CROSS:: placeholders remaining in task JSONs -- IMPL_PLAN.md and TODO_LIST.md generated with multi-module structure -- Return: task count, per-module breakdown, resolved dependency count - -## PLANNING NOTES RECORD (REQUIRED) -After integration, update planning-notes.md: - -\`\`\`markdown -### [Coordinator] YYYY-MM-DD -- **Total**: [count] tasks -- **Resolved**: [CROSS:: resolutions] - -## N+1 Context -### Decisions -| Decision | Rationale | Revisit? | -|----------|-----------|----------| -| CROSS::X → IMPL-Y | [why this resolution] | [Yes/No] | - -### Deferred -- [ ] [unresolved CROSS or conflict] - [reason] -\`\`\` - ` -) -``` - -**Dependency Resolution Algorithm**: -```javascript -function resolveCrossModuleDependency(placeholder, allTasks) { - const [, targetModule, pattern] = placeholder.match(/CROSS::(\w+)::(.+)/); - const candidates = allTasks.filter(t => - t.id.startsWith(`IMPL-${targetModule}`) && - (t.title.toLowerCase().includes(pattern.toLowerCase()) || - t.description?.toLowerCase().includes(pattern.toLowerCase())) - ); - return candidates.length > 0 - ? candidates.sort((a, b) => a.id.localeCompare(b.id))[0].id - : placeholder; // Keep for manual resolution -} -``` \ No newline at end of file diff --git a/.claude/commands/workflow/tools/task-generate-tdd.md b/.claude/commands/workflow/tools/task-generate-tdd.md deleted file mode 100644 index 8b43b0c5..00000000 --- a/.claude/commands/workflow/tools/task-generate-tdd.md +++ /dev/null @@ -1,758 +0,0 @@ ---- -name: task-generate-tdd -description: Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation -argument-hint: "[-y|--yes] --session WFS-session-id" -examples: - - /workflow:tools:task-generate-tdd --session WFS-auth - - /workflow:tools:task-generate-tdd -y --session WFS-auth ---- - -## Auto Mode - -When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor). - -# Autonomous TDD Task Generation Command - -## Overview -Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Generates complete Red-Green-Refactor cycles contained within each task. - -## Core Philosophy -- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation -- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation) -- **Memory-First**: Reuse loaded documents from conversation memory -- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research -- **Semantic CLI Selection**: CLI tool usage determined from user's task description, not flags -- **Agent Simplicity**: Agent generates content with semantic CLI detection -- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`) -- **TDD-First**: Every feature starts with a failing test (Red phase) -- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle -- **Quantification-Enforced**: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations - -## Task Strategy & Philosophy - -### Optimized Task Structure (Current) -- **1 feature = 1 task** containing complete TDD cycle internally -- Each task executes Red-Green-Refactor phases sequentially -- Task count = Feature count (typically 5 features = 5 tasks) - -**Previous Approach** (Deprecated): -- 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M) -- 5 features = 15 tasks with complex dependency chains -- High context switching cost between phases - -### When to Use Subtasks -- Feature complexity >2500 lines or >6 files per TDD cycle -- Multiple independent sub-features needing parallel execution -- Strong technical dependency blocking (e.g., API before UI) -- Different tech stacks or domains within feature - -### Task Limits -- **Maximum 18 tasks** (hard limit for TDD workflows) -- **Feature-based**: Complete functional units with internal TDD cycles -- **Hierarchy**: Flat (≤5 simple features) | Two-level (6-10 for complex features with sub-features) -- **Re-scope**: If >18 tasks needed, break project into multiple TDD workflow sessions - -### TDD Cycle Mapping -- **Old approach**: 1 feature = 3 tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M) -- **Current approach**: 1 feature = 1 task (IMPL-N with internal Red-Green-Refactor phases) -- **Complex features**: 1 container (IMPL-N) + subtasks (IMPL-N.M) when necessary - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session - └─ Validation: session_id REQUIRED - -Phase 1: Discovery & Context Loading (Memory-First) - ├─ Load session context (if not in memory) - ├─ Load context package (if not in memory) - ├─ Load test context package (if not in memory) - ├─ Extract & load role analyses from context package - ├─ Load conflict resolution (if exists) - └─ Optional: MCP external research - -Phase 2: Agent Execution (Document Generation) - ├─ Pre-agent template selection (semantic CLI detection) - ├─ Invoke action-planning-agent - ├─ Generate TDD Task JSON Files (.task/IMPL-*.json) - │ └─ Each task: complete Red-Green-Refactor cycle internally - ├─ Create IMPL_PLAN.md (TDD variant) - └─ Generate TODO_LIST.md with TDD phase indicators -``` - -## Execution Lifecycle - -### Phase 0: User Configuration (Interactive) - -**Purpose**: Collect user preferences before TDD task generation to ensure generated tasks match execution expectations and provide necessary supplementary context. - -**User Questions**: -```javascript -AskUserQuestion({ - questions: [ - { - question: "Do you have supplementary materials or guidelines to include?", - header: "Materials", - multiSelect: false, - options: [ - { label: "No additional materials", description: "Use existing context only" }, - { label: "Provide file paths", description: "I'll specify paths to include" }, - { label: "Provide inline content", description: "I'll paste content directly" } - ] - }, - { - question: "Select execution method for generated TDD tasks:", - header: "Execution", - multiSelect: false, - options: [ - { label: "Agent (Recommended)", description: "Claude agent executes Red-Green-Refactor cycles directly" }, - { label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps (Red/Green phases)" }, - { label: "CLI Only", description: "All TDD cycles via CLI tools (codex/gemini/qwen)" } - ] - }, - { - question: "If using CLI, which tool do you prefer?", - header: "CLI Tool", - multiSelect: false, - options: [ - { label: "Codex (Recommended)", description: "Best for TDD Red-Green-Refactor cycles" }, - { label: "Gemini", description: "Best for analysis and large context" }, - { label: "Qwen", description: "Alternative analysis tool" }, - { label: "Auto", description: "Let agent decide per-task" } - ] - } - ] -}) -``` - -**Handle Materials Response**: -```javascript -if (userConfig.materials === "Provide file paths") { - // Follow-up question for file paths - const pathsResponse = AskUserQuestion({ - questions: [{ - question: "Enter file paths to include (comma-separated or one per line):", - header: "Paths", - multiSelect: false, - options: [ - { label: "Enter paths", description: "Provide paths in text input" } - ] - }] - }) - userConfig.supplementaryPaths = parseUserPaths(pathsResponse) -} -``` - -**Build userConfig**: -```javascript -const userConfig = { - supplementaryMaterials: { - type: "none|paths|inline", - content: [...], // Parsed paths or inline content - }, - executionMethod: "agent|hybrid|cli", - preferredCliTool: "codex|gemini|qwen|auto", - enableResume: true // Always enable resume for CLI executions -} -``` - -**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2. - ---- - -### Phase 1: Context Preparation & Discovery - -**Command Responsibility**: Command prepares session paths and metadata, provides to agent for autonomous context loading. - -**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory - -**📊 Progressive Loading Strategy**: Load context incrementally due to large analysis.md file sizes: -- **Core**: session metadata + context-package.json (always load) -- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all role analyses -- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context - -**🛤️ Path Clarity Requirement**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`) - -**Session Path Structure** (Provided by Command to Agent): -``` -.workflow/active/WFS-{session-id}/ -├── workflow-session.json # Session metadata -├── .process/ -│ ├── context-package.json # Context package with artifact catalog -│ ├── test-context-package.json # Test coverage analysis -│ └── conflict-resolution.json # Conflict resolution (if exists) -├── .task/ # Output: Task JSON files -│ ├── IMPL-1.json -│ ├── IMPL-2.json -│ └── ... -├── plan.json # Output: Structured plan overview (TDD variant) -├── IMPL_PLAN.md # Output: TDD implementation plan -└── TODO_LIST.md # Output: TODO list with TDD phases -``` - -**Command Preparation**: -1. **Assemble Session Paths** for agent prompt: - - `session_metadata_path`: `.workflow/active/{session-id}/workflow-session.json` - - `context_package_path`: `.workflow/active/{session-id}/.process/context-package.json` - - `test_context_package_path`: `.workflow/active/{session-id}/.process/test-context-package.json` - - Output directory paths - -2. **Provide Metadata** (simple values): - - `session_id`: WFS-{session-id} - - `workflow_type`: "tdd" - - `mcp_capabilities`: {exa_code, exa_web, code_index} - -3. **Pass userConfig** from Phase 0 - -**Agent Context Package** (Agent loads autonomously): -```javascript -{ - "session_id": "WFS-[session-id]", - "workflow_type": "tdd", - - // Core (ALWAYS load) - "session_metadata": { - // If in memory: use cached content - // Else: Load from workflow-session.json - }, - "context_package": { - // If in memory: use cached content - // Else: Load from context-package.json - }, - - // Selective (load based on progressive strategy) - "brainstorm_artifacts": { - // Loaded from context-package.json → brainstorm_artifacts section - "synthesis_output": {"path": "...", "exists": true}, // Load if exists (highest priority) - "guidance_specification": {"path": "...", "exists": true}, // Load if no synthesis - "role_analyses": [ // Load SELECTIVELY based on task relevance - { - "role": "system-architect", - "files": [{"path": "...", "type": "primary|supplementary"}] - } - ] - }, - - // On-Demand (load if exists) - "test_context_package": { - // Load from test-context-package.json - // Contains existing test patterns and coverage analysis - }, - "conflict_resolution": { - // Load from conflict-resolution.json if conflict_risk >= medium - // Check context-package.conflict_detection.resolution_file - }, - - // Capabilities - "mcp_capabilities": { - "exa_code": true, - "exa_web": true, - "code_index": true - }, - - // User configuration from Phase 0 - "user_config": { - // From Phase 0 AskUserQuestion - } -} -``` - -**Discovery Actions**: -1. **Load Session Context** (if not in memory) - ```javascript - if (!memory.has("workflow-session.json")) { - Read(.workflow/active/{session-id}/workflow-session.json) - } - ``` - -2. **Load Context Package** (if not in memory) - ```javascript - if (!memory.has("context-package.json")) { - Read(.workflow/active/{session-id}/.process/context-package.json) - } - ``` - -3. **Load Test Context Package** (if not in memory) - ```javascript - if (!memory.has("test-context-package.json")) { - Read(.workflow/active/{session-id}/.process/test-context-package.json) - } - ``` - -4. **Extract & Load Role Analyses** (from context-package.json) - ```javascript - // Extract role analysis paths from context package - const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses - .flatMap(role => role.files.map(f => f.path)); - - // Load each role analysis file - roleAnalysisPaths.forEach(path => Read(path)); - ``` - -5. **Load Conflict Resolution** (from conflict-resolution.json, if exists) - ```javascript - // Check for new conflict-resolution.json format - if (contextPackage.conflict_detection?.resolution_file) { - Read(contextPackage.conflict_detection.resolution_file) // .process/conflict-resolution.json - } - // Fallback: legacy brainstorm_artifacts path - else if (contextPackage.brainstorm_artifacts?.conflict_resolution?.exists) { - Read(contextPackage.brainstorm_artifacts.conflict_resolution.path) - } - ``` - -6. **Code Analysis with Native Tools** (optional - enhance understanding) - ```bash - # Find relevant test files and patterns - find . -name "*test*" -type f - rg "describe|it\(|test\(" -g "*.ts" - ``` - -7. **MCP External Research** (optional - gather TDD best practices) - ```javascript - // Get external TDD examples and patterns - mcp__exa__get_code_context_exa( - query="TypeScript TDD best practices Red-Green-Refactor", - tokensNum="dynamic" - ) - ``` - -### Phase 2: Agent Execution (TDD Document Generation) - -**Purpose**: Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - planning only, NOT code implementation. - -**Agent Invocation**: -```javascript -Task( - subagent_type="action-planning-agent", - run_in_background=false, - description="Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)", - prompt=` -## TASK OBJECTIVE -Generate TDD implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session - -IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code. - -CRITICAL: Follow the progressive loading strategy (load analysis.md files incrementally due to file size): -- **Core**: session metadata + context-package.json (always) -- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all -- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context - -## SESSION PATHS -Input: - - Session Metadata: .workflow/active/{session-id}/workflow-session.json - - Context Package: .workflow/active/{session-id}/.process/context-package.json - - Test Context: .workflow/active/{session-id}/.process/test-context-package.json - -Output: - - Task Dir: .workflow/active/{session-id}/.task/ - - IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md - - TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md - -## CONTEXT METADATA -Session ID: {session-id} -Workflow Type: TDD -MCP Capabilities: {exa_code, exa_web, code_index} - -## USER CONFIGURATION (from Phase 0) -Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli -Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto -Supplementary Materials: ${userConfig.supplementaryMaterials} - -## EXECUTION METHOD MAPPING -Based on userConfig.executionMethod, set task-level meta.execution_config: - -"agent" → - meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false } - Agent executes Red-Green-Refactor phases directly - -"cli" → - meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true } - Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt() - -"hybrid" → - Per-task decision: Analyze TDD cycle complexity, set method to "agent" OR "cli" per task - - Simple cycles (≤5 test cases, ≤3 files) → method: "agent" - - Complex cycles (>5 test cases, >3 files, integration tests) → method: "cli" - CLI tool: userConfig.preferredCliTool, enable_resume: true - -IMPORTANT: Do NOT add command field to implementation steps. Execution routing is controlled by task-level meta.execution_config.method only. - -## EXPLORATION CONTEXT (from context-package.exploration_results) -- Load exploration_results from context-package.json -- Use aggregated_insights.critical_files for focus_paths generation -- Apply aggregated_insights.constraints to acceptance criteria -- Reference aggregated_insights.all_patterns for implementation approach -- Use aggregated_insights.all_integration_points for precise modification locations -- Use conflict_indicators for risk-aware task sequencing - -## CONFLICT RESOLUTION CONTEXT (if exists) -- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path -- If exists, load .process/conflict-resolution.json: - - Apply planning_constraints as task constraints (for brainstorm-less workflows) - - Reference resolved_conflicts for implementation approach alignment - - Handle custom_conflicts with explicit task notes - -## TEST CONTEXT INTEGRATION -- Load test-context-package.json for existing test patterns and coverage analysis -- Extract test framework configuration (Jest/Pytest/etc.) -- Identify existing test conventions and patterns -- Map coverage gaps to TDD Red phase test targets - -## TDD DOCUMENT GENERATION TASK - -**Agent Configuration Reference**: All TDD task generation rules, quantification requirements, Red-Green-Refactor cycle structure, quality standards, and execution details are defined in action-planning-agent. - -### TDD-Specific Requirements Summary - -#### Task Structure Philosophy -- **1 feature = 1 task** containing complete TDD cycle internally -- Each task executes Red-Green-Refactor phases sequentially -- Task count = Feature count (typically 5 features = 5 tasks) -- Subtasks only when complexity >2500 lines or >6 files per cycle -- **Maximum 18 tasks** (hard limit for TDD workflows) - -#### TDD Cycle Mapping -- **Simple features**: IMPL-N with internal Red-Green-Refactor phases -- **Complex features**: IMPL-N (container) + IMPL-N.M (subtasks) -- Each cycle includes: test_count, test_cases array, implementation_scope, expected_coverage - -#### Required Outputs Summary - -##### 1. TDD Task JSON Files (.task/IMPL-*.json) -- **Location**: `.workflow/active/{session-id}/.task/` -- **Schema**: Unified flat schema (task-schema.json) with TDD-specific metadata - - `meta.tdd_workflow`: true (REQUIRED) - - `meta.max_iterations`: 3 (Green phase test-fix cycle limit) - - `cli_execution.id`: Unique CLI execution ID (format: `{session_id}-{task_id}`) - - `cli_execution`: Strategy object (new|resume|fork|merge_fork) - - `tdd_cycles`: Array with quantified test cases and coverage - - `focus_paths`: Absolute or clear relative paths (enhanced with exploration critical_files) - - `implementation`: Exactly 3 steps with `tdd_phase` field - 1. Red Phase (`tdd_phase: "red"`): Write failing tests - 2. Green Phase (`tdd_phase: "green"`): Implement to pass tests - 3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality - - `pre_analysis`: Include exploration integration_points analysis - - **meta.execution_config**: Set per userConfig.executionMethod (agent/cli/hybrid) -- **Details**: See action-planning-agent.md § TDD Task JSON Generation - -##### 2. IMPL_PLAN.md (TDD Variant) -- **Location**: `.workflow/active/{session-id}/IMPL_PLAN.md` -- **Template**: `~/.ccw/workflows/cli-templates/prompts/workflow/impl-plan-template.txt` -- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown -- **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles -- **Context Analysis**: Artifact references and exploration insights -- **Details**: See action-planning-agent.md § TDD Implementation Plan Creation - -##### 3. TODO_LIST.md -- **Location**: `.workflow/active/{session-id}/TODO_LIST.md` -- **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor) -- **Status**: ▸ (container), [ ] (pending), [x] (completed) -- **Links**: Task JSON references and summaries -- **Details**: See action-planning-agent.md § TODO List Generation - -### CLI EXECUTION ID REQUIREMENTS (MANDATORY) - -Each task JSON MUST include: -- **cli_execution.id**: Unique ID for CLI execution (format: `{session_id}-{task_id}`) -- **cli_execution**: Strategy object based on depends_on: - - No deps → `{ "strategy": "new" }` - - 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }` - - 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }` - - N deps → `{ "strategy": "merge_fork", "resume_from": ["id1", "id2", ...] }` - - **Type**: `resume_from: string | string[]` (string for resume/fork, array for merge_fork) - -**CLI Execution Strategy Rules**: -1. **new**: Task has no dependencies - starts fresh CLI conversation -2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation -3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context -4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation - -**Execution Command Patterns**: -- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]` -- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write` -- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write` -- merge_fork: `ccw cli -p "[prompt]" --resume [resume_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write` (resume_from is array) - -### Quantification Requirements (MANDATORY) - -**Core Rules**: -1. **Explicit Test Case Counts**: Red phase specifies exact number with enumerated list -2. **Quantified Coverage**: Acceptance includes measurable percentage (e.g., ">=85%") -3. **Detailed Implementation Scope**: Green phase enumerates files, functions, line counts -4. **Enumerated Refactoring Targets**: Refactor phase lists specific improvements with counts - -**TDD Phase Formats**: -- **Red Phase**: "Write N test cases: [test1, test2, ...]" -- **Green Phase**: "Implement N functions in file lines X-Y: [func1() X1-Y1, func2() X2-Y2, ...]" -- **Refactor Phase**: "Apply N refactorings: [improvement1 (details), improvement2 (details), ...]" -- **Acceptance**: "All N tests pass with >=X% coverage: verify by [test command]" - -**Validation Checklist**: -- [ ] Every Red phase specifies exact test case count with enumerated list -- [ ] Every Green phase enumerates files, functions, and estimated line counts -- [ ] Every Refactor phase lists specific improvements with counts -- [ ] Every acceptance criterion includes measurable coverage percentage -- [ ] tdd_cycles array contains test_count and test_cases for each cycle -- [ ] No vague language ("comprehensive", "complete", "thorough") -- [ ] cli_execution.id and cli_execution strategy assigned to each task - -### Agent Execution Summary - -**Key Steps** (Detailed instructions in action-planning-agent.md): -1. Load task JSON template from provided path -2. Extract and decompose features with TDD cycles -3. Generate TDD task JSON files enforcing quantification requirements -4. Create IMPL_PLAN.md using TDD template variant -5. Generate TODO_LIST.md with TDD phase indicators -6. Update session state with TDD metadata - -**Quality Gates** (Full checklist in action-planning-agent.md): -- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets) -- ✓ Task count ≤18 (hard limit) -- ✓ Each task has meta.tdd_workflow: true -- ✓ Each task has exactly 3 implementation steps with tdd_phase field ("red", "green", "refactor") -- ✓ Each task has cli_execution.id and cli_execution strategy -- ✓ Green phase includes test-fix cycle logic with max_iterations -- ✓ focus_paths are absolute or clear relative paths (from exploration critical_files) -- ✓ Artifact references mapped correctly from context package -- ✓ Exploration context integrated (critical_files, constraints, patterns, integration_points) -- ✓ Conflict resolution context applied (if conflict_risk >= medium) -- ✓ Test context integrated (existing test patterns and coverage analysis) -- ✓ Documents follow TDD template structure -- ✓ CLI tool selection based on userConfig.executionMethod - -## SUCCESS CRITERIA -- All planning documents generated successfully: - - Task JSONs valid and saved to .task/ directory with cli_execution.id - - IMPL_PLAN.md created with complete TDD structure - - TODO_LIST.md generated matching task JSONs -- CLI execution strategies assigned based on task dependencies -- Return completion status with document count and task breakdown summary - -## OUTPUT SUMMARY -Generate all three documents and report: -- TDD task JSON files created: N files (IMPL-*.json) with cli_execution.id assigned -- TDD cycles configured: N cycles with quantified test cases -- CLI execution strategies: new/resume/fork/merge_fork assigned per dependency graph -- Artifacts integrated: synthesis-spec/guidance-specification, relevant role analyses -- Exploration context: critical_files, constraints, patterns, integration_points -- Test context integrated: existing patterns and coverage -- Conflict resolution: applied (if conflict_risk >= medium) -- Session ready for TDD execution: /workflow:execute -` -) -``` - -### Agent Context Passing - -**Context Delegation Model**: Command provides paths and metadata, agent loads context autonomously using progressive loading strategy. - -**Command Provides** (in agent prompt): -```javascript -// Command assembles these simple values and paths for agent -const commandProvides = { - // Session paths - session_metadata_path: ".workflow/active/WFS-{id}/workflow-session.json", - context_package_path: ".workflow/active/WFS-{id}/.process/context-package.json", - test_context_package_path: ".workflow/active/WFS-{id}/.process/test-context-package.json", - output_task_dir: ".workflow/active/WFS-{id}/.task/", - output_impl_plan: ".workflow/active/WFS-{id}/IMPL_PLAN.md", - output_todo_list: ".workflow/active/WFS-{id}/TODO_LIST.md", - - // Simple metadata - session_id: "WFS-{id}", - workflow_type: "tdd", - mcp_capabilities: { exa_code: true, exa_web: true, code_index: true }, - - // User configuration from Phase 0 - user_config: { - supplementaryMaterials: { type: "...", content: [...] }, - executionMethod: "agent|hybrid|cli", - preferredCliTool: "codex|gemini|qwen|auto", - enableResume: true - } -} -``` - -**Agent Loads Autonomously** (progressive loading): -```javascript -// Agent executes progressive loading based on memory state -const agentLoads = { - // Core (ALWAYS load if not in memory) - session_metadata: loadIfNotInMemory(session_metadata_path), - context_package: loadIfNotInMemory(context_package_path), - - // Selective (based on progressive strategy) - // Priority: synthesis_output > guidance + relevant_role_analyses - brainstorm_content: loadSelectiveBrainstormArtifacts(context_package), - - // On-Demand (load if exists and relevant) - test_context: loadIfExists(test_context_package_path), - conflict_resolution: loadConflictResolution(context_package), - - // Optional (if MCP available) - exploration_results: extractExplorationResults(context_package), - external_research: executeMcpResearch() // If needed -} -``` - -**Progressive Loading Implementation** (agent responsibility): -1. **Check memory first** - skip if already loaded -2. **Load core files** - session metadata + context-package.json -3. **Smart selective loading** - synthesis_output OR (guidance + task-relevant role analyses) -4. **On-demand loading** - test context, conflict resolution (if conflict_risk >= medium) -5. **Extract references** - exploration results, artifact paths from context package - -## TDD Task Structure Reference - -This section provides quick reference for TDD task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above. - -**Quick Reference**: -- Each TDD task contains complete Red-Green-Refactor cycle -- Task ID format: `IMPL-N` (simple) or `IMPL-N.M` (complex subtasks) -- Required metadata: - - `meta.tdd_workflow: true` - - `meta.max_iterations: 3` - - `cli_execution.id: "{session_id}-{task_id}"` - - `cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }` -- `tdd_cycles` array with quantified test cases and coverage: - ```javascript - tdd_cycles: [ - { - test_count: 5, // Number of test cases to write - test_cases: ["case1", "case2"], // Enumerated test scenarios - implementation_scope: "...", // Files and functions to implement - expected_coverage: ">=85%" // Coverage target - } - ] - ``` -- `focus_paths` use absolute or clear relative paths -- `implementation`: Exactly 3 steps with `tdd_phase` field ("red", "green", "refactor") -- `pre_analysis`: includes exploration integration_points analysis -- **meta.execution_config**: Set per `userConfig.executionMethod` (agent/cli/hybrid) -- See Phase 2 agent prompt for full schema and requirements - -## Output Files Structure -``` -.workflow/active/{session-id}/ -├── plan.json # Structured plan overview (TDD variant) -├── IMPL_PLAN.md # Unified plan with TDD Implementation Tasks section -├── TODO_LIST.md # Progress tracking with internal TDD phase indicators -├── .task/ -│ ├── IMPL-1.json # Complete TDD task (Red-Green-Refactor internally) -│ ├── IMPL-2.json # Complete TDD task -│ ├── IMPL-3.json # Complex feature container (if needed) -│ ├── IMPL-3.1.json # Complex feature subtask (if needed) -│ ├── IMPL-3.2.json # Complex feature subtask (if needed) -│ └── ... -└── .process/ - ├── conflict-resolution.json # Conflict resolution results (if conflict_risk ≥ medium) - ├── test-context-package.json # Test coverage analysis - ├── context-package.json # Input from context-gather - ├── context_package_path # Path to smart context package - └── green-fix-iteration-*.md # Fix logs from Green phase test-fix cycles -``` - -**File Count**: -- **Old approach**: 5 features = 15 task JSON files (TEST/IMPL/REFACTOR × 5) -- **New approach**: 5 features = 5 task JSON files (IMPL-N × 5) -- **Complex feature**: 1 feature = 1 container + M subtasks (IMPL-N + IMPL-N.M) - -## Validation Rules - -### Task Completeness -- Every IMPL-N must contain complete TDD workflow in `implementation` -- Each task must have 3 steps with `tdd_phase`: "red", "green", "refactor" -- Every task must have `meta.tdd_workflow: true` - -### Dependency Enforcement -- Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed -- Complex feature subtasks: IMPL-N.M depends_on ["IMPL-N.(M-1)"] or parent dependencies -- No circular dependencies allowed - -### Task Limits -- Maximum 18 total tasks (simple + subtasks) - hard limit for TDD workflows -- Flat hierarchy (≤5 tasks) or two-level (6-18 tasks with containers) -- Re-scope requirements if >18 tasks needed - -### TDD Workflow Validation -- `meta.tdd_workflow` must be true -- `implementation` must have exactly 3 steps -- Each step must have `tdd_phase` field ("red", "green", or "refactor") -- Green phase step must include test-fix cycle logic -- `meta.max_iterations` must be present (default: 3) - -## Error Handling - -### Input Validation Errors -| Error | Cause | Resolution | -|-------|-------|------------| -| Session not found | Invalid session ID | Verify session exists | -| Context missing | Incomplete planning | Run context-gather first | - -### TDD Generation Errors -| Error | Cause | Resolution | -|-------|-------|------------| -| Task count exceeds 18 | Too many features or subtasks | Re-scope requirements or merge features into multiple TDD sessions | -| Missing test framework | No test config | Configure testing first | -| Invalid TDD workflow | Missing tdd_phase or incomplete flow_control | Fix TDD structure in ANALYSIS_RESULTS.md | -| Missing tdd_workflow flag | Task doesn't have meta.tdd_workflow: true | Add TDD workflow metadata | - -## Integration & Usage - -**Command Chain**: -- Called by: `/workflow:tdd-plan` (Phase 4) -- Invokes: `action-planning-agent` for autonomous task generation -- Followed by: `/workflow:execute`, `/workflow:tdd-verify` - -**Basic Usage**: -```bash -# Standard execution -/workflow:tools:task-generate-tdd --session WFS-auth - -# With semantic CLI request (include in task description) -# e.g., "Generate TDD tasks for auth module, use Codex for implementation" -``` - -**CLI Tool Selection**: Determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution. - -**Output**: -- TDD task JSON files in `.task/` directory (IMPL-N.json format) -- IMPL_PLAN.md with TDD Implementation Tasks section -- TODO_LIST.md with internal TDD phase indicators -- Session state updated with task count and TDD metadata -- MCP enhancements integrated (if available) - -## Test Coverage Analysis Integration - -The TDD workflow includes test coverage analysis (via `/workflow:tools:test-context-gather`) to: -- Detect existing test patterns and conventions -- Identify current test coverage gaps -- Discover test framework and configuration -- Enable integration with existing tests - -This makes TDD workflow context-aware instead of assuming greenfield scenarios. - -## Iterative Green Phase with Test-Fix Cycle - -IMPL (Green phase) tasks include automatic test-fix cycle: - -**Process Flow**: -1. **Initial Implementation**: Write minimal code to pass tests -2. **Test Execution**: Run test suite -3. **Success Path**: Tests pass → Complete task -4. **Failure Path**: Tests fail → Enter iterative fix cycle: - - **Gemini Diagnosis**: Analyze failures with bug-fix template - - **Fix Application**: Agent executes fixes directly - - **Retest**: Verify fix resolves failures - - **Repeat**: Up to max_iterations (default: 3) -5. **Safety Net**: Auto-revert all changes if max iterations reached - - - -## Configuration Options -- **meta.max_iterations**: Number of fix attempts in Green phase (default: 3) -- **meta.execution_config.method**: Execution routing (agent/cli) determined from userConfig.executionMethod - diff --git a/.claude/commands/workflow/tools/tdd-coverage-analysis.md b/.claude/commands/workflow/tools/tdd-coverage-analysis.md deleted file mode 100644 index 094153fa..00000000 --- a/.claude/commands/workflow/tools/tdd-coverage-analysis.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -name: tdd-coverage-analysis -description: Analyze test coverage and TDD cycle execution with Red-Green-Refactor compliance verification -argument-hint: "--session WFS-session-id" -allowed-tools: Read(*), Write(*), Bash(*) ---- - -# TDD Coverage Analysis Command - -## Overview -Analyze test coverage and verify Red-Green-Refactor cycle execution for TDD workflow validation. - -## Core Responsibilities -- Extract test files from TEST tasks -- Run test suite with coverage -- Parse coverage metrics -- Verify TDD cycle execution (Red -> Green -> Refactor) -- Generate coverage and cycle reports - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session - └─ Validation: session_id REQUIRED - -Phase 1: Extract Test Tasks - └─ Find TEST-*.json files and extract focus_paths - -Phase 2: Run Test Suite - └─ Decision (test framework): - ├─ Node.js → npm test --coverage --json - ├─ Python → pytest --cov --json-report - └─ Other → [test_command] --coverage --json - -Phase 3: Parse Coverage Data - ├─ Extract line coverage percentage - ├─ Extract branch coverage percentage - ├─ Extract function coverage percentage - └─ Identify uncovered lines/branches - -Phase 4: Verify TDD Cycle - └─ FOR each TDD chain (TEST-N.M → IMPL-N.M → REFACTOR-N.M): - ├─ Red Phase: Verify tests created and failed initially - ├─ Green Phase: Verify tests now pass - └─ Refactor Phase: Verify code quality improved - -Phase 5: Generate Analysis Report - └─ Create tdd-cycle-report.md with coverage metrics and cycle verification -``` - -## Execution Lifecycle - -### Phase 1: Extract Test Tasks -```bash -find .workflow/active/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \; -``` - -**Output**: List of test directories/files from all TEST tasks - -### Phase 2: Run Test Suite -```bash -# Node.js/JavaScript -npm test -- --coverage --json > .workflow/active/{session_id}/.process/test-results.json - -# Python -pytest --cov --json-report > .workflow/active/{session_id}/.process/test-results.json - -# Other frameworks (detect from project) -[test_command] --coverage --json-output .workflow/active/{session_id}/.process/test-results.json -``` - -**Output**: test-results.json with coverage data - -### Phase 3: Parse Coverage Data -```bash -jq '.coverage' .workflow/active/{session_id}/.process/test-results.json > .workflow/active/{session_id}/.process/coverage-report.json -``` - -**Extract**: -- Line coverage percentage -- Branch coverage percentage -- Function coverage percentage -- Uncovered lines/branches - -### Phase 4: Verify TDD Cycle - -For each TDD chain (TEST-N.M -> IMPL-N.M -> REFACTOR-N.M): - -**1. Red Phase Verification** -```bash -# Check TEST task summary -cat .workflow/active/{session_id}/.summaries/TEST-N.M-summary.md -``` - -Verify: -- Tests were created -- Tests failed initially -- Failure messages were clear - -**2. Green Phase Verification** -```bash -# Check IMPL task summary -cat .workflow/active/{session_id}/.summaries/IMPL-N.M-summary.md -``` - -Verify: -- Implementation was completed -- Tests now pass -- Implementation was minimal - -**3. Refactor Phase Verification** -```bash -# Check REFACTOR task summary -cat .workflow/active/{session_id}/.summaries/REFACTOR-N.M-summary.md -``` - -Verify: -- Refactoring was completed -- Tests still pass -- Code quality improved - -### Phase 5: Generate Analysis Report - -Create `.workflow/active/{session_id}/.process/tdd-cycle-report.md`: - -```markdown -# TDD Cycle Analysis - {Session ID} - -## Coverage Metrics -- **Line Coverage**: {percentage}% -- **Branch Coverage**: {percentage}% -- **Function Coverage**: {percentage}% - -## Coverage Details -### Covered -- {covered_lines} lines -- {covered_branches} branches -- {covered_functions} functions - -### Uncovered -- Lines: {uncovered_line_numbers} -- Branches: {uncovered_branch_locations} - -## TDD Cycle Verification - -### Feature 1: {Feature Name} -**Chain**: TEST-1.1 -> IMPL-1.1 -> REFACTOR-1.1 - -- [PASS] **Red Phase**: Tests created and failed initially -- [PASS] **Green Phase**: Implementation made tests pass -- [PASS] **Refactor Phase**: Refactoring maintained green tests - -### Feature 2: {Feature Name} -**Chain**: TEST-2.1 -> IMPL-2.1 -> REFACTOR-2.1 - -- [PASS] **Red Phase**: Tests created and failed initially -- [WARN] **Green Phase**: Tests pass but implementation seems over-engineered -- [PASS] **Refactor Phase**: Refactoring maintained green tests - -[Repeat for all features] - -## TDD Compliance Summary -- **Total Chains**: {N} -- **Complete Cycles**: {N} -- **Incomplete Cycles**: {0} -- **Compliance Score**: {score}/100 - -## Gaps Identified -- Feature 3: Missing initial test failure verification -- Feature 5: No refactoring step completed - -## Recommendations -- Complete missing refactoring steps -- Add edge case tests for Feature 2 -- Verify test failure messages are descriptive -``` - -## Output Files -``` -.workflow/active//{session-id}/ -└── .process/ - ├── test-results.json # Raw test execution results - ├── coverage-report.json # Parsed coverage data - └── tdd-cycle-report.md # TDD cycle analysis -``` - -## Test Framework Detection - -Auto-detect test framework from project: - -```bash -# Check for test frameworks -if [ -f "package.json" ] && grep -q "jest\|mocha\|vitest" package.json; then - TEST_CMD="npm test -- --coverage --json" -elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then - TEST_CMD="pytest --cov --json-report" -elif [ -f "Cargo.toml" ]; then - TEST_CMD="cargo test -- --test-threads=1 --nocapture" -elif [ -f "go.mod" ]; then - TEST_CMD="go test -coverprofile=coverage.out -json ./..." -else - TEST_CMD="echo 'No supported test framework found'" -fi -``` - -## TDD Cycle Verification Algorithm - -``` -For each feature N: - 1. Load TEST-N.M-summary.md - IF summary missing: - Mark: "Red phase incomplete" - SKIP to next feature - - CHECK: Contains "test" AND "fail" - IF NOT found: - Mark: "Red phase verification failed" - ELSE: - Mark: "Red phase [PASS]" - - 2. Load IMPL-N.M-summary.md - IF summary missing: - Mark: "Green phase incomplete" - SKIP to next feature - - CHECK: Contains "pass" OR "green" - IF NOT found: - Mark: "Green phase verification failed" - ELSE: - Mark: "Green phase [PASS]" - - 3. Load REFACTOR-N.M-summary.md - IF summary missing: - Mark: "Refactor phase incomplete" - CONTINUE (refactor is optional) - - CHECK: Contains "refactor" AND "pass" - IF NOT found: - Mark: "Refactor phase verification failed" - ELSE: - Mark: "Refactor phase [PASS]" - - 4. Calculate chain score: - - Red + Green + Refactor all [PASS] = 100% - - Red + Green [PASS], Refactor missing = 80% - - Red [PASS], Green missing = 40% - - All missing = 0% -``` - -## Coverage Metrics Calculation - -```bash -# Parse coverage from test-results.json -line_coverage=$(jq '.coverage.lineCoverage' test-results.json) -branch_coverage=$(jq '.coverage.branchCoverage' test-results.json) -function_coverage=$(jq '.coverage.functionCoverage' test-results.json) - -# Calculate overall score -overall_score=$(echo "($line_coverage + $branch_coverage + $function_coverage) / 3" | bc) -``` - -## Error Handling - -### Test Execution Errors -| Error | Cause | Resolution | -|-------|-------|------------| -| Test framework not found | No test config | Configure test framework first | -| Tests fail to run | Syntax errors | Fix code before analysis | -| Coverage not available | Missing coverage tool | Install coverage plugin | - -### Cycle Verification Errors -| Error | Cause | Resolution | -|-------|-------|------------| -| Summary missing | Task not executed | Execute tasks before analysis | -| Invalid summary format | Corrupted file | Re-run task to regenerate | -| No test evidence | Tests not committed | Ensure tests are committed | - -## Integration & Usage - -### Command Chain -- **Called By**: `/workflow:tdd-verify` (Phase 3) -- **Calls**: Test framework commands (npm test, pytest, etc.) -- **Followed By**: Compliance report generation - -### Basic Usage -```bash -/workflow:tools:tdd-coverage-analysis --session WFS-auth -``` - -### Expected Output -``` -TDD Coverage Analysis complete for session: WFS-auth - -## Coverage Results -Line Coverage: 87% -Branch Coverage: 82% -Function Coverage: 91% - -## TDD Cycle Verification -[PASS] Feature 1: Complete (Red -> Green -> Refactor) -[PASS] Feature 2: Complete (Red -> Green -> Refactor) -[WARN] Feature 3: Incomplete (Red -> Green, missing Refactor) - -Overall Compliance: 93/100 - -Detailed report: .workflow/active/WFS-auth/.process/tdd-cycle-report.md -``` - diff --git a/.claude/commands/workflow/tools/test-concept-enhanced.md b/.claude/commands/workflow/tools/test-concept-enhanced.md deleted file mode 100644 index 67dce103..00000000 --- a/.claude/commands/workflow/tools/test-concept-enhanced.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -name: test-concept-enhanced -description: Coordinate test analysis workflow using cli-execution-agent to generate test strategy via Gemini -argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json" -examples: - - /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/active/WFS-test-auth/.process/test-context-package.json ---- - -# Test Concept Enhanced Command - -## Overview -Workflow coordinator that delegates test analysis to cli-execution-agent. Agent executes Gemini to analyze test coverage gaps, implementation context, and generate comprehensive test generation strategies. - -## Core Philosophy -- **Coverage-Driven**: Focus on identified test gaps from context analysis -- **Pattern-Based**: Learn from existing tests and project conventions -- **Gemini-Powered**: Use Gemini for test requirement analysis and strategy design -- **Single-Round Analysis**: Comprehensive test analysis in one execution -- **No Code Generation**: Strategy and planning only, actual test generation happens in task execution - -## Core Responsibilities -- Coordinate test analysis workflow using cli-execution-agent -- Validate test-context-package.json prerequisites -- Execute Gemini analysis via agent for test strategy generation -- Validate agent outputs (gemini-test-analysis.md, TEST_ANALYSIS_RESULTS.md) - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session, --context - └─ Validation: Both REQUIRED - -Phase 1: Context Preparation (Command) - ├─ Load workflow-session.json - ├─ Verify test session type is "test-gen" - ├─ Validate test-context-package.json - └─ Determine strategy (Simple: 1-3 files | Medium: 4-6 | Complex: >6) - -Phase 2: Test Analysis Execution (Agent) - ├─ Execute Gemini analysis via cli-execution-agent - └─ Generate TEST_ANALYSIS_RESULTS.md - -Phase 3: Output Validation (Command) - ├─ Verify gemini-test-analysis.md exists - ├─ Validate TEST_ANALYSIS_RESULTS.md - └─ Confirm test requirements are actionable -``` - -## Execution Lifecycle - -### Phase 1: Context Preparation (Command Responsibility) - -**Command prepares session context and validates prerequisites.** - -1. **Session Validation** - - Load `.workflow/active/{test_session_id}/workflow-session.json` - - Verify test session type is "test-gen" - - Extract source session reference - -2. **Context Package Validation** - - Read `test-context-package.json` - - Validate required sections: metadata, source_context, test_coverage, test_framework - - Extract coverage gaps and framework details - -3. **Strategy Determination** - - **Simple** (1-3 files): Single Gemini analysis - - **Medium** (4-6 files): Comprehensive analysis - - **Complex** (>6 files): Modular analysis approach - -### Phase 2: Test Analysis Execution (Agent Responsibility) - -**Purpose**: Analyze test coverage gaps and generate comprehensive test strategy. - -**Agent Invocation**: -```javascript -Task( - subagent_type="cli-execution-agent", - run_in_background=false, - description="Analyze test coverage gaps and generate test strategy", - prompt=` -## TASK OBJECTIVE -Analyze test requirements and generate comprehensive test generation strategy using Gemini CLI - -## EXECUTION CONTEXT -Session: {test_session_id} -Source Session: {source_session_id} -Working Dir: .workflow/active/{test_session_id}/.process -Template: ~/.ccw/workflows/cli-templates/prompts/test/test-concept-analysis.txt - -## EXECUTION STEPS -1. Execute Gemini analysis: - ccw cli -p "..." --tool gemini --mode write --rule test-test-concept-analysis --cd .workflow/active/{test_session_id}/.process - -2. Generate TEST_ANALYSIS_RESULTS.md: - Synthesize gemini-test-analysis.md into standardized format for task generation - Include: coverage assessment, test framework, test requirements, generation strategy, implementation targets - -## EXPECTED OUTPUTS -1. gemini-test-analysis.md - Raw Gemini analysis -2. TEST_ANALYSIS_RESULTS.md - Standardized test requirements document - -## QUALITY VALIDATION -- Both output files exist and are complete -- All required sections present in TEST_ANALYSIS_RESULTS.md -- Test requirements are actionable and quantified -- Test scenarios cover happy path, errors, edge cases -- Dependencies and mocks clearly identified -` -) -``` - -**Output Files**: -- `.workflow/active/{test_session_id}/.process/gemini-test-analysis.md` -- `.workflow/active/{test_session_id}/.process/TEST_ANALYSIS_RESULTS.md` - -### Phase 3: Output Validation (Command Responsibility) - -**Command validates agent outputs.** - -- Verify `gemini-test-analysis.md` exists and is complete -- Validate `TEST_ANALYSIS_RESULTS.md` generated by agent -- Check required sections present -- Confirm test requirements are actionable - -## Error Handling - -### Validation Errors -| Error | Resolution | -|-------|------------| -| Missing context package | Run test-context-gather first | -| No coverage gaps | Skip test generation, proceed to execution | -| No test framework detected | Configure test framework | -| Invalid source session | Complete implementation first | - -### Execution Errors -| Error | Recovery | -|-------|----------| -| Gemini timeout | Reduce scope, analyze by module | -| Output incomplete | Retry with focused analysis | -| No output file | Check directory permissions | - -**Fallback Strategy**: Generate basic TEST_ANALYSIS_RESULTS.md from context package if Gemini fails - -## Integration & Usage - -### Command Chain -- **Called By**: `/workflow:test-gen` (Phase 4: Analysis) -- **Requires**: `test-context-package.json` from `/workflow:tools:test-context-gather` -- **Followed By**: `/workflow:tools:test-task-generate` - -### Performance -- Focused analysis: Only analyze files with missing tests -- Pattern reuse: Study existing tests for quick extraction -- Timeout: 20-minute limit for analysis - -### Success Criteria -- Valid TEST_ANALYSIS_RESULTS.md generated -- All missing tests documented with actionable requirements -- Test scenarios cover happy path, errors, edge cases, integration -- Dependencies and mocks clearly identified -- Test generation strategy is practical -- Output follows existing test conventions - diff --git a/.claude/commands/workflow/tools/test-context-gather.md b/.claude/commands/workflow/tools/test-context-gather.md deleted file mode 100644 index c28ce3c9..00000000 --- a/.claude/commands/workflow/tools/test-context-gather.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -name: test-context-gather -description: Collect test coverage context using test-context-search-agent and package into standardized test-context JSON -argument-hint: "--session WFS-test-session-id" -examples: - - /workflow:tools:test-context-gather --session WFS-test-auth - - /workflow:tools:test-context-gather --session WFS-test-payment -allowed-tools: Task(*), Read(*), Glob(*) ---- - -# Test Context Gather Command (/workflow:tools:test-context-gather) - -## Overview - -Orchestrator command that invokes `test-context-search-agent` to gather comprehensive test coverage context for test generation workflows. Generates standardized `test-context-package.json` with coverage analysis, framework detection, and source implementation context. - - - -## Core Philosophy - -- **Agent Delegation**: Delegate all test coverage analysis to `test-context-search-agent` for autonomous execution -- **Detection-First**: Check for existing test-context-package before executing -- **Coverage-First**: Analyze existing test coverage before planning new tests -- **Source Context Loading**: Import implementation summaries from source session -- **Standardized Output**: Generate `.workflow/active/{test_session_id}/.process/test-context-package.json` - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session - └─ Validation: test_session_id REQUIRED - -Step 1: Test-Context-Package Detection - └─ Decision (existing package): - ├─ Valid package exists → Return existing (skip execution) - └─ No valid package → Continue to Step 2 - -Step 2: Invoke Test-Context-Search Agent - ├─ Phase 1: Session Validation & Source Context Loading - │ ├─ Detection: Check for existing test-context-package - │ ├─ Test session validation - │ └─ Source context loading (summaries, changed files) - ├─ Phase 2: Test Coverage Analysis - │ ├─ Track 1: Existing test discovery - │ ├─ Track 2: Coverage gap analysis - │ └─ Track 3: Coverage statistics - └─ Phase 3: Framework Detection & Packaging - ├─ Framework identification - ├─ Convention analysis - └─ Generate test-context-package.json - -Step 3: Output Verification - └─ Verify test-context-package.json created -``` - -## Execution Flow - -### Step 1: Test-Context-Package Detection - -**Execute First** - Check if valid package already exists: - -```javascript -const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`; - -if (file_exists(testContextPath)) { - const existing = Read(testContextPath); - - // Validate package belongs to current test session - if (existing?.metadata?.test_session_id === test_session_id) { - console.log("✅ Valid test-context-package found for session:", test_session_id); - console.log("📊 Coverage Stats:", existing.test_coverage.coverage_stats); - console.log("🧪 Framework:", existing.test_framework.framework); - console.log("⚠️ Missing Tests:", existing.test_coverage.missing_tests.length); - return existing; // Skip execution, return existing - } else { - console.warn("⚠️ Invalid test_session_id in existing package, re-generating..."); - } -} -``` - -### Step 2: Invoke Test-Context-Search Agent - -**Only execute if Step 1 finds no valid package** - -```javascript -Task( - subagent_type="test-context-search-agent", - run_in_background=false, - description="Gather test coverage context", - prompt=` - -## Execution Mode -**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution - -## Session Information -- **Test Session ID**: ${test_session_id} -- **Output Path**: .workflow/${test_session_id}/.process/test-context-package.json - -## Mission -Execute complete test-context-search-agent workflow for test generation planning: - -### Phase 1: Session Validation & Source Context Loading -1. **Detection**: Check for existing test-context-package (early exit if valid) -2. **Test Session Validation**: Load test session metadata, extract source_session reference -3. **Source Context Loading**: Load source session implementation summaries, changed files, tech stack - -### Phase 2: Test Coverage Analysis -Execute coverage discovery: -- **Track 1**: Existing test discovery (find *.test.*, *.spec.* files) -- **Track 2**: Coverage gap analysis (match implementation files to test files) -- **Track 3**: Coverage statistics (calculate percentages, identify gaps by module) - -### Phase 3: Framework Detection & Packaging -1. Framework identification from package.json/requirements.txt -2. Convention analysis from existing test patterns -3. Generate and validate test-context-package.json - -## Output Requirements -Complete test-context-package.json with: -- **metadata**: test_session_id, source_session_id, task_type, complexity -- **source_context**: implementation_summaries, tech_stack, project_patterns -- **test_coverage**: existing_tests[], missing_tests[], coverage_stats -- **test_framework**: framework, version, test_pattern, conventions -- **assets**: implementation_summary[], existing_test[], source_code[] with priorities -- **focus_areas**: Test generation guidance based on coverage gaps - -## Quality Validation -Before completion verify: -- [ ] Valid JSON format with all required fields -- [ ] Source session context loaded successfully -- [ ] Test coverage gaps identified -- [ ] Test framework detected (or marked as 'unknown') -- [ ] Coverage percentage calculated correctly -- [ ] Missing tests catalogued with priority -- [ ] Execution time < 30 seconds (< 60s for large codebases) - -Execute autonomously following agent documentation. -Report completion with coverage statistics. -` -) -``` - -### Step 3: Output Verification - -After agent completes, verify output: - -```javascript -// Verify file was created -const outputPath = `.workflow/${test_session_id}/.process/test-context-package.json`; -if (!file_exists(outputPath)) { - throw new Error("❌ Agent failed to generate test-context-package.json"); -} - -// Load and display summary -const testContext = Read(outputPath); -console.log("✅ Test context package generated successfully"); -console.log("📊 Coverage:", testContext.test_coverage.coverage_stats.coverage_percentage + "%"); -console.log("⚠️ Tests to generate:", testContext.test_coverage.missing_tests.length); -``` - -## Parameter Reference - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `--session` | string | ✅ | Test workflow session ID (e.g., WFS-test-auth) | - -## Output Schema - -Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-package.json` schema. - -**Key Sections**: -- **metadata**: Test session info, source session reference, complexity -- **source_context**: Implementation summaries with changed files and tech stack -- **test_coverage**: Existing tests, missing tests with priorities, coverage statistics -- **test_framework**: Framework name, version, patterns, conventions -- **assets**: Categorized files with relevance (implementation_summary, existing_test, source_code) -- **focus_areas**: Test generation guidance based on analysis - -## Usage Examples - -### Basic Usage -```bash -/workflow:tools:test-context-gather --session WFS-test-auth -``` - -### Expected Output -``` -✅ Valid test-context-package found for session: WFS-test-auth -📊 Coverage Stats: { total: 3, with_tests: 2, without_tests: 1, percentage: 66.7 } -🧪 Framework: jest -⚠️ Missing Tests: 1 -``` - -## Success Criteria - -- ✅ Valid test-context-package.json generated in `.workflow/active/{test_session_id}/.process/` -- ✅ Source session context loaded successfully -- ✅ Test coverage gaps identified (>90% accuracy) -- ✅ Test framework detected and documented -- ✅ Execution completes within 30 seconds (60s for large codebases) -- ✅ All required schema fields present and valid -- ✅ Coverage statistics calculated correctly -- ✅ Agent reports completion with statistics - -## Error Handling - -| Error | Cause | Resolution | -|-------|-------|------------| -| Package validation failed | Invalid test_session_id in existing package | Re-run agent to regenerate | -| Source session not found | Invalid source_session reference | Verify test session metadata | -| No implementation summaries | Source session incomplete | Complete source session first | -| Agent execution timeout | Large codebase or slow analysis | Increase timeout, check file access | -| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance | -| No test framework detected | Missing test dependencies | Agent marks as 'unknown', manual specification needed | - -## Integration - -### Called By -- `/workflow:test-gen` (Phase 3: Context Gathering) - -### Calls -- `test-context-search-agent` - Autonomous test coverage analysis - -### Followed By -- `/workflow:tools:test-concept-enhanced` - Test generation analysis and planning - -## Notes - -- **Detection-first**: Always check for existing test-context-package before invoking agent - -- **No redundancy**: This command is a thin orchestrator, all logic in agent -- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc. -- **Coverage focus**: Primary goal is identifying implementation files without tests - diff --git a/.claude/commands/workflow/tools/test-task-generate.md b/.claude/commands/workflow/tools/test-task-generate.md deleted file mode 100644 index 4973b836..00000000 --- a/.claude/commands/workflow/tools/test-task-generate.md +++ /dev/null @@ -1,416 +0,0 @@ ---- -name: test-task-generate -description: Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) by invoking test-action-planning-agent -argument-hint: "--session WFS-test-session-id" -examples: - - /workflow:tools:test-task-generate --session WFS-test-auth ---- - -# Generate Test Planning Documents Command - -## Overview - -Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) by invoking **test-action-planning-agent**. - -This command produces **test planning artifacts only** - it does NOT execute tests or implement code. Actual test execution requires separate execution command (e.g., /workflow:test-cycle-execute). - -### Agent Specialization - -This command invokes `@test-action-planning-agent` - a specialized variant of action-planning-agent with: -- Progressive L0-L3 test layers (Static, Unit, Integration, E2E) -- AI code issue detection (L0.5) with severity levels -- Project type templates (React, Node API, CLI, Library, Monorepo) -- Test anti-pattern detection with quality gates -- Layer completeness thresholds and coverage targets - -**See**: `d:\Claude_dms3\.claude\agents\test-action-planning-agent.md` for complete test specifications. - ---- - -## Execution Process - -``` -Input Parsing: - └─ Parse flags: --session - -Phase 1: Context Preparation (Command) - ├─ Assemble test session paths - │ ├─ session_metadata_path - │ ├─ test_analysis_results_path (REQUIRED) - │ └─ test_context_package_path - ├─ Provide metadata (session_id, source_session_id) - └─ Create test-planning-notes.md (User Intent section) - -Phase 1.5: Gemini Test Enhancement (Command) - ├─ Invoke cli-execution-agent for Gemini analysis - ├─ Read TEST_ANALYSIS_RESULTS.md for context - ├─ Generate enriched test suggestions (API, integration, error scenarios) - └─ Record enriched suggestions to test-planning-notes.md (Gemini Enhancement section) - -Phase 2: Test Document Generation (Agent) - ├─ Load TEST_ANALYSIS_RESULTS.md (with enriched suggestions) - ├─ Load test-planning-notes.md (consolidated context) - ├─ Generate Test Task JSON Files (.task/IMPL-*.json) - │ ├─ IMPL-001: Test generation (L1-L3 layers, project-specific templates) - │ ├─ IMPL-001.3: Code validation gate (L0 + AI issue detection) - │ ├─ IMPL-001.5: Test quality gate (anti-patterns + coverage) - │ └─ IMPL-002: Test execution & fix cycle - ├─ Create IMPL_PLAN.md (test_session variant) - ├─ Generate TODO_LIST.md with test phase indicators - └─ Update test-planning-notes.md (Task Generation section) -``` - ---- - -## Phase 1: Context Preparation - -**Purpose**: Assemble test session paths, load test analysis context, and create test-planning-notes.md. - -**Execution Steps**: -1. Parse `--session` flag to get test session ID -2. Load `workflow-session.json` for session metadata -3. Verify `TEST_ANALYSIS_RESULTS.md` exists (from test-concept-enhanced) -4. Load `test-context-package.json` for coverage data -5. Create `test-planning-notes.md` with initial context - -**After Phase 1**: Initialize test-planning-notes.md - -```javascript -// Create test-planning-notes.md with N+1 context support -const testPlanningNotesPath = `.workflow/active/${testSessionId}/test-planning-notes.md` -const sessionMetadata = JSON.parse(Read(`.workflow/active/${testSessionId}/workflow-session.json`)) -const testAnalysis = Read(`.workflow/active/${testSessionId}/.process/TEST_ANALYSIS_RESULTS.md`) -const sourceSessionId = sessionMetadata.source_session_id || 'N/A' - -// Extract key info from TEST_ANALYSIS_RESULTS.md -const projectType = testAnalysis.match(/Project Type:\s*(.+)/)?.[1] || 'Unknown' -const testFramework = testAnalysis.match(/Test Framework:\s*(.+)/)?.[1] || 'Unknown' -const coverageTarget = testAnalysis.match(/Coverage Target:\s*(.+)/)?.[1] || '80%' - -Write(testPlanningNotesPath, `# Test Planning Notes - -**Session**: ${testSessionId} -**Source Session**: ${sourceSessionId} -**Created**: ${new Date().toISOString()} - -## Test Intent (Phase 1) - -- **PROJECT_TYPE**: ${projectType} -- **TEST_FRAMEWORK**: ${testFramework} -- **COVERAGE_TARGET**: ${coverageTarget} -- **SOURCE_SESSION**: ${sourceSessionId} - ---- - -## Context Findings (Phase 1) - -### Files with Coverage Gaps -(Extracted from TEST_ANALYSIS_RESULTS.md) - -### Test Framework & Conventions -- Framework: ${testFramework} -- Coverage Target: ${coverageTarget} - ---- - -## Gemini Enhancement (Phase 1.5) -(To be filled by Gemini analysis) - -### Enhanced Test Suggestions -- **L1 (Unit)**: (Pending) -- **L2.1 (Integration)**: (Pending) -- **L2.2 (API Contracts)**: (Pending) -- **L2.4 (External APIs)**: (Pending) -- **L2.5 (Failure Modes)**: (Pending) - -### Gemini Analysis Summary -(Pending enrichment) - ---- - -## Consolidated Test Requirements (Phase 2 Input) -1. [Context] ${testFramework} framework conventions -2. [Context] ${coverageTarget} coverage target - ---- - -## Task Generation (Phase 2) -(To be filled by test-action-planning-agent) - -## N+1 Context -### Decisions -| Decision | Rationale | Revisit? | -|----------|-----------|----------| - -### Deferred -- [ ] (For N+1) -`) - ---- - -## Phase 1.5: Gemini Test Enhancement - -**Purpose**: Enrich test specifications with comprehensive test suggestions and record to test-planning-notes.md. - -**Execution Steps**: -1. Load TEST_ANALYSIS_RESULTS.md from `.workflow/active/{test-session-id}/.process/` -2. Invoke `cli-execution-agent` with Gemini for test enhancement analysis -3. Use template: `~/.ccw/workflows/cli-templates/prompts/test-suggestions-enhancement.txt` -4. Gemini generates enriched test suggestions across L1-L3 layers → gemini-enriched-suggestions.md -5. Record enriched suggestions to test-planning-notes.md (Gemini Enhancement section) - -**Agent Invocation**: -```javascript -Task( - subagent_type="cli-execution-agent", - run_in_background=false, - description="Enhance test specifications with Gemini analysis", - prompt=` -## Task Objective -Analyze TEST_ANALYSIS_RESULTS.md and generate enriched test suggestions using Gemini CLI - -## Input Files -- Read: .workflow/active/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md -- Extract: Project type, test framework, coverage gaps, identified files - -## Gemini Analysis Execution -Execute Gemini with comprehensive test enhancement prompt: - ccw cli -p "[comprehensive test prompt]" --tool gemini --mode analysis --rule analysis-test-strategy-enhancement --cd .workflow/active/{test-session-id}/.process - -## Expected Output -Generate gemini-enriched-suggestions.md with structured test enhancements: - - L1 (Unit Tests): Edge cases, boundaries, error paths - - L2.1 (Integration): Module interactions, dependency injection - - L2.2 (API Contracts): Request/response, validation, error responses - - L2.4 (External APIs): Mock strategies, failure scenarios, timeouts - - L2.5 (Failure Modes): Exception handling, error propagation, recovery - -## Validation -- gemini-enriched-suggestions.md created and complete -- Suggestions are actionable and specific (not generic) -- All L1-L3 layers covered -` -) -``` - -**Output**: gemini-enriched-suggestions.md (complete Gemini analysis) - -**After Phase 1.5**: Update test-planning-notes.md with Gemini enhancement findings - -```javascript -// Read enriched suggestions from gemini-enriched-suggestions.md -const enrichedSuggestionsPath = `.workflow/active/${testSessionId}/.process/gemini-enriched-suggestions.md` -const enrichedSuggestions = Read(enrichedSuggestionsPath) - -// Update Phase 1.5 section in test-planning-notes.md with full enriched suggestions -Edit(testPlanningNotesPath, { - old: '## Gemini Enhancement (Phase 1.5)\n(To be filled by Gemini analysis)\n\n### Enhanced Test Suggestions\n- **L1 (Unit)**: (Pending)\n- **L2.1 (Integration)**: (Pending)\n- **L2.2 (API Contracts)**: (Pending)\n- **L2.4 (External APIs)**: (Pending)\n- **L2.5 (Failure Modes)**: (Pending)\n\n### Gemini Analysis Summary\n(Pending enrichment)', - new: `## Gemini Enhancement (Phase 1.5) - -**Analysis Timestamp**: ${new Date().toISOString()} -**Template**: test-suggestions-enhancement.txt -**Output File**: .process/gemini-enriched-suggestions.md - -### Enriched Test Suggestions (Complete Gemini Analysis) - -${enrichedSuggestions} - -### Gemini Analysis Summary -- **Status**: Enrichment complete -- **Layers Covered**: L1, L2.1, L2.2, L2.4, L2.5 -- **Focus Areas**: API contracts, integration patterns, error scenarios, edge cases -- **Output Stored**: Full analysis in gemini-enriched-suggestions.md` -}) - -// Append Gemini constraints to consolidated test requirements -const geminiConstraints = [ - '[Gemini] Implement all suggested L1 edge cases and boundary tests', - '[Gemini] Apply L2.1 module interaction patterns from analysis', - '[Gemini] Follow L2.2 API contract test matrix from analysis', - '[Gemini] Use L2.4 external API mock strategies from analysis', - '[Gemini] Cover L2.5 error scenarios from analysis' -] - -const currentNotes = Read(testPlanningNotesPath) -const constraintCount = (currentNotes.match(/^\d+\./gm) || []).length - -Edit(testPlanningNotesPath, { - old: '## Consolidated Test Requirements (Phase 2 Input)', - new: `## Consolidated Test Requirements (Phase 2 Input) -1. [Context] ${testFramework} framework conventions -2. [Context] ${coverageTarget} coverage target -${geminiConstraints.map((c, i) => `${i + 3}. ${c}`).join('\n')}` -}) -``` - ---- - -## Agent Invocation - -```javascript -Task( - subagent_type="test-action-planning-agent", - run_in_background=false, - description="Generate test planning documents", - prompt=` -## TASK OBJECTIVE -Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for test workflow session - -IMPORTANT: This is TEST PLANNING ONLY - you are generating planning documents, NOT executing tests. - -## SESSION PATHS -Input: - - Session Metadata: .workflow/active/{test-session-id}/workflow-session.json - - TEST_ANALYSIS_RESULTS: .workflow/active/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md (REQUIRED) - - Test Planning Notes: .workflow/active/{test-session-id}/test-planning-notes.md (REQUIRED - contains Gemini enhancement findings) - - Test Context Package: .workflow/active/{test-session-id}/.process/test-context-package.json - - Context Package: .workflow/active/{test-session-id}/.process/context-package.json - - Enriched Suggestions: .workflow/active/{test-session-id}/.process/gemini-enriched-suggestions.md (for reference) - - Source Session Summaries: .workflow/active/{source-session-id}/.summaries/IMPL-*.md (if exists) - -Output: - - Task Dir: .workflow/active/{test-session-id}/.task/ - - IMPL_PLAN: .workflow/active/{test-session-id}/IMPL_PLAN.md - - TODO_LIST: .workflow/active/{test-session-id}/TODO_LIST.md - -## CONTEXT METADATA -Session ID: {test-session-id} -Workflow Type: test_session -Source Session: {source-session-id} (if exists) -MCP Capabilities: {exa_code, exa_web, code_index} - -## CONSOLIDATED CONTEXT -**From test-planning-notes.md**: -- Test Intent: Project type, test framework, coverage target -- Context Findings: Coverage gaps, file analysis -- Gemini Enhancement: Complete enriched test suggestions (L1-L3 layers) - * Full analysis embedded in planning-notes.md - * API contracts, integration patterns, error scenarios -- Consolidated Requirements: Combined constraints from all phases - -## YOUR SPECIFICATIONS -You are @test-action-planning-agent. Your complete test specifications are defined in: - d:\Claude_dms3\.claude\agents\test-action-planning-agent.md - -This includes: - - Progressive Test Layers (L0-L3) with L0.1-L0.5, L1.1-L1.5, L2.1-L2.5, L3.1-L3.4 - - AI Code Issue Detection (L0.5) with 7 categories and severity levels - - Project Type Detection & Templates (6 project types) - - Test Anti-Pattern Detection (5 categories) - - Layer Completeness & Quality Metrics (thresholds and gate decisions) - - Task JSON structure requirements (minimum 4 tasks) - - Quality validation rules - -**Follow your specification exactly** when generating test task JSONs. - -## EXPECTED DELIVERABLES -1. Test Task JSON Files (.task/IMPL-*.json) - Minimum 4: - - IMPL-001.json: Test generation (L1-L3 layers per spec) - - IMPL-001.3-validation.json: Code validation gate (L0 + AI issues per spec) - - IMPL-001.5-review.json: Test quality gate (anti-patterns + coverage per spec) - - IMPL-002.json: Test execution & fix cycle - -2. IMPL_PLAN.md: Test implementation plan with quality gates - -3. TODO_LIST.md: Hierarchical task list with test phase indicators - -## SUCCESS CRITERIA -- All test planning documents generated successfully -- Task count: minimum 4 (expandable for complex projects) -- Test framework: {detected from project} -- Coverage targets: L0 zero errors, L1 80%+, L2 70%+ -- L0-L3 layers explicitly defined per spec -- AI issue detection configured per spec -- Quality gates with measurable thresholds -` -) -``` - ---- - -## Test-Specific Execution Modes - -### Test Generation (IMPL-001) -- **Agent Mode** (default): @code-developer generates tests within agent context -- **CLI Mode**: Use CLI tools when `command` field present in implementation_approach - -### Test Execution & Fix (IMPL-002+) -- **Agent Mode** (default): Gemini diagnosis → agent applies fixes -- **CLI Mode**: Gemini diagnosis → CLI applies fixes (when `command` field present) - -**CLI Tool Selection**: Determined semantically from user's task description (e.g., "use Codex for fixes") - ---- - -## Output - -### Directory Structure - -``` -.workflow/active/WFS-test-[session]/ -├── workflow-session.json # Session metadata -├── IMPL_PLAN.md # Test implementation plan -├── TODO_LIST.md # Task checklist -├── test-planning-notes.md # [NEW] Consolidated planning notes with full Gemini analysis -├── .task/ -│ ├── IMPL-001.json # Test generation (L1-L3) -│ ├── IMPL-001.3-validation.json # Code validation gate (L0 + AI) -│ ├── IMPL-001.5-review.json # Test quality gate -│ └── IMPL-002.json # Test execution & fix cycle -└── .process/ - ├── test-context-package.json # Test coverage and patterns - ├── gemini-enriched-suggestions.md # [NEW] Gemini-generated test enhancements - └── TEST_ANALYSIS_RESULTS.md # L0-L3 requirements (original from test-concept-enhanced) -``` - -### Task Summary - -| Task | Type | Agent | Purpose | -|------|------|-------|---------| -| IMPL-001 | test-gen | @code-developer | Generate L1-L3 tests with project templates | -| IMPL-001.3 | code-validation | @test-fix-agent | Validate L0 + detect AI issues (CRITICAL/ERROR/WARNING) | -| IMPL-001.5 | test-quality-review | @test-fix-agent | Check anti-patterns, layer completeness, coverage | -| IMPL-002 | test-fix | @test-fix-agent | Execute tests, diagnose failures, apply fixes | - ---- - -## Integration & Usage - -### Command Chain -- **Called By**: `/workflow:test-fix-gen` (Phase 4) -- **Invokes**: `@test-action-planning-agent` for test planning document generation -- **Followed By**: `/workflow:test-cycle-execute` or `/workflow:execute` (user-triggered) - -### Usage Examples -```bash -# Standard execution -/workflow:tools:test-task-generate --session WFS-test-auth - -# With semantic CLI request (include in task description when calling /workflow:test-fix-gen) -# e.g., "Generate tests, use Codex for implementation and fixes" -``` - -### Output Validation - -**Minimum Requirements**: -- 4 task JSON files created -- IMPL_PLAN.md exists with test-specific sections -- TODO_LIST.md exists with test phase hierarchy -- All tasks reference TEST_ANALYSIS_RESULTS.md specifications -- L0-L3 layers explicitly defined in IMPL-001 -- AI issue detection configured in IMPL-001.3 -- Quality gates with thresholds in IMPL-001.5 - ---- - -## Related Commands - -**Called By**: -- `/workflow:test-fix-gen` - Phase 4: Generate test planning documents - -**Prerequisite**: -- `/workflow:tools:test-concept-enhanced` - Must generate TEST_ANALYSIS_RESULTS.md first - -**Follow-Up**: -- `/workflow:test-cycle-execute` - Execute generated test tasks -- `/workflow:execute` - Alternative: Standard task execution diff --git a/ccw/frontend/src/components/cli-viewer/LayoutContainer.tsx b/ccw/frontend/src/components/cli-viewer/LayoutContainer.tsx index 83b0599d..83e16300 100644 --- a/ccw/frontend/src/components/cli-viewer/LayoutContainer.tsx +++ b/ccw/frontend/src/components/cli-viewer/LayoutContainer.tsx @@ -3,7 +3,7 @@ // ======================================== // Manages allotment-based split panes for CLI viewer -import { useCallback, useMemo } from 'react'; +import { useCallback, useMemo, useRef, useEffect } from 'react'; import { Allotment } from 'allotment'; import 'allotment/dist/style.css'; import { cn } from '@/lib/utils'; @@ -105,14 +105,46 @@ function LayoutGroupRenderer({ group, minSize, onSizeChange }: LayoutGroupRender export function LayoutContainer({ className }: LayoutContainerProps) { const layout = useViewerLayout(); const panes = useViewerPanes(); - const setLayout = useViewerStore((state) => state.setLayout); + // Use ref to track if we're currently updating to prevent infinite loops + const isUpdatingRef = useRef(false); + // Track previous sizes to avoid unnecessary updates + const prevSizesRef = useRef(layout.sizes); + + // Update prevSizesRef when layout.sizes changes from external sources + useEffect(() => { + if (!isUpdatingRef.current) { + prevSizesRef.current = layout.sizes; + } + }, [layout.sizes]); + + // Stable callback with no dependencies - prevents Allotment onChange infinite loop const handleSizeChange = useCallback( (sizes: number[]) => { - // Update the root layout with new sizes - setLayout({ ...layout, sizes }); + // Skip if sizes haven't actually changed (compare by value) + if ( + prevSizesRef.current && + sizes.length === prevSizesRef.current.length && + sizes.every((s, i) => Math.abs(s - prevSizesRef.current![i]) < 0.1) + ) { + return; + } + + // Use functional update to avoid dependency on layout + isUpdatingRef.current = true; + prevSizesRef.current = sizes; + + useViewerStore.getState().setLayout((prev) => ({ + ...prev, + sizes, + })); + + // Reset updating flag after a microtask + queueMicrotask(() => { + isUpdatingRef.current = false; + }); }, - [layout, setLayout] + [] // No dependencies - uses getState() and refs to prevent infinite loops ); // Render based on layout type diff --git a/ccw/frontend/src/components/terminal-dashboard/FloatingPanel.tsx b/ccw/frontend/src/components/terminal-dashboard/FloatingPanel.tsx index 066707cf..56b248a1 100644 --- a/ccw/frontend/src/components/terminal-dashboard/FloatingPanel.tsx +++ b/ccw/frontend/src/components/terminal-dashboard/FloatingPanel.tsx @@ -53,10 +53,10 @@ export function FloatingPanel({ {/* Backdrop */}
@@ -76,7 +76,7 @@ export function FloatingPanel({ )} style={{ top: '40px', // Below toolbar - height: 'calc(100vh - 56px - 40px)', // Subtract both app header and toolbar + height: 'calc(100vh - 40px)', // Full height below toolbar width: `${width}px`, }} > diff --git a/ccw/frontend/src/stores/viewerStore.ts b/ccw/frontend/src/stores/viewerStore.ts index 87ce86cd..d1b707a2 100644 --- a/ccw/frontend/src/stores/viewerStore.ts +++ b/ccw/frontend/src/stores/viewerStore.ts @@ -73,7 +73,7 @@ export interface ViewerState { nextTabIdCounter: number; // Actions - setLayout: (newLayout: AllotmentLayout) => void; + setLayout: (newLayout: AllotmentLayout | ((prev: AllotmentLayout) => AllotmentLayout)) => void; addPane: (parentPaneId?: PaneId, direction?: 'horizontal' | 'vertical') => PaneId; removePane: (paneId: PaneId) => void; addTab: (paneId: PaneId, executionId: CliExecutionId, title: string) => TabId; @@ -373,8 +373,14 @@ export const useViewerStore = create()( // ========== Layout Actions ========== - setLayout: (newLayout: AllotmentLayout) => { - set({ layout: newLayout }, false, 'viewer/setLayout'); + setLayout: (newLayout: AllotmentLayout | ((prev: AllotmentLayout) => AllotmentLayout)) => { + if (typeof newLayout === 'function') { + const currentLayout = get().layout; + const result = newLayout(currentLayout); + set({ layout: result }, false, 'viewer/setLayout'); + } else { + set({ layout: newLayout }, false, 'viewer/setLayout'); + } }, addPane: (parentPaneId?: PaneId, direction: 'horizontal' | 'vertical' = 'horizontal') => {