diff --git a/.claude/skills/_shared/COMMAND-TO-SKILL-CONVERSION.md b/.claude/skills/_shared/COMMAND-TO-SKILL-CONVERSION.md index caf5d70b..891d13cf 100644 --- a/.claude/skills/_shared/COMMAND-TO-SKILL-CONVERSION.md +++ b/.claude/skills/_shared/COMMAND-TO-SKILL-CONVERSION.md @@ -291,6 +291,27 @@ allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, ## Architecture Overview {ASCII 架构图} +## Key Design Principles +{设计原则列表} + +## Auto Mode +{自动模式说明} + +## Usage + +``` +Skill(skill="{skill-name}", args="") +Skill(skill="{skill-name}", args="[FLAGS] \"\"") + +# Flags +{flag 说明，每个 flag 一行} + +# Examples +Skill(skill="{skill-name}", args="\"Implement JWT authentication\"") # 说明 +Skill(skill="{skill-name}", args="--mode xxx \"Refactor payment module\"") # 说明 +Skill(skill="{skill-name}", args="-y \"Add user profile page\"") # 说明 +``` + ## Execution Flow {流程图 + Phase 引用表} @@ -313,6 +334,16 @@ allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, {错误处理策略} ``` +**Usage 格式要求**： + +- **必须使用代码块** 包裹 Usage 内容 +- 使用 `Skill()` 调用格式，不使用 `/skill-name` 命令行格式 +- 包含两种调用格式：基本调用 + 带 Flags 的完整调用 +- Flags 说明每行一个 flag，格式：`flag-name 说明` +- Examples 必须展示所有 flag 组合的典型调用场景 +- 字符串参数中的引号使用转义 `\"` +- Examples 行尾可添加 `# 说明` 注释 + ### 5.3 执行流程示例 ```markdown @@ -641,12 +672,34 @@ skills/workflow-plan/ | 原 plan.md 内容 | SKILL.md 对应位置 | |----------------|-------------------| | Frontmatter | Frontmatter (扩展) | +| argument-hint | Usage (转换为 Skill 调用格式) | | 执行流程描述 | Execution Flow (可视化) | | 子命令调用 | Phase Reference Table | | 数据传递 | Data Flow (显式定义) | +| (无) | Usage (新增 - Skill 调用格式) | | (无) | TodoWrite Pattern (新增) | | (无) | Error Handling (新增) | +**Usage 转换示例**： + +原命令 `argument-hint`: +```yaml +argument-hint: "[-y|--yes] \"text description\"|file.md" +``` + +转换为 SKILL.md Usage: +``` +Skill(skill="workflow-plan", args="") +Skill(skill="workflow-plan", args="[-y|--yes] \"\"") + +# Flags +-y, --yes Skip all confirmations (auto mode) + +# Examples +Skill(skill="workflow-plan", args="\"Implement authentication\"") # Interactive mode +Skill(skill="workflow-plan", args="-y \"Implement authentication\"") # Auto mode +``` + ### 9.3 Phase 文件与原子命令对比 | 原子命令内容 | Phase 文件对应 | @@ -685,3 +738,4 @@ wc -l skills/{skill-name}/SKILL.md skills/{skill-name}/phases/*.md | v1.0 | 2025-02-05 | 基于 workflow-plan 转换实践创建 | | v1.1 | 2025-02-05 | 强化内容一致性要求；添加第7章一致性验证；添加应移除的命令特有内容说明 | | v2.0 | 2026-02-05 | 命令调用引用统一转换为文件路径引用；移除 `/workflow:XX` 命令语法；引用转换规则重构 | +| v2.1 | 2026-02-05 | 添加 Usage 部分格式规范（Skill 调用格式）；更新 5.2 必需章节；添加 Usage 转换示例到 9.2 节 | diff --git a/.claude/skills/workflow-lite-plan/SKILL.md b/.claude/skills/workflow-lite-plan/SKILL.md new file mode 100644 index 00000000..0ee27ca6 --- /dev/null +++ b/.claude/skills/workflow-lite-plan/SKILL.md @@ -0,0 +1,217 @@ +--- +name: workflow-lite-plan +description: Unified lightweight planning skill with mode selection (Lite Plan, Multi-CLI Plan, Lite Fix). Supports exploration, diagnosis, multi-CLI collaboration, and shared execution via lite-execute. +allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep, Skill, mcp__ace-tool__search_context +--- + +# Planning Workflow + +Unified lightweight planning skill that consolidates multiple planning approaches into a single entry point with mode selection. Default mode: **Lite Plan**. All planning modes share a common execution phase (lite-execute). + +## Architecture Overview + +``` +┌──────────────────────────────────────────────────────────┐ +│ Planning Workflow Orchestrator (SKILL.md) │ +│ → Parse args → Mode selection → Load phase → Execute │ +└────────────┬─────────────────────────────────────────────┘ + │ Mode Selection (default: Lite Plan) + ┌────────┼────────┬──────────┐ + ↓ ↓ ↓ ↓ (shared) +┌────────┐ ┌────────┐ ┌────────┐ ┌────────────┐ +│Phase 1 │ │Phase 2 │ │Phase 3 │ │ Phase 4 │ +│ Lite │ │Multi- │ │ Lite │ │ Lite │ +│ Plan │ │CLI Plan│ │ Fix │ │ Execute │ +└────────┘ └────────┘ └────────┘ └────────────┘ + │ │ │ ↑ + └──────────┴──────────┴───────────┘ + (all hand off to Phase 4) +``` + +## Key Design Principles + +1. **Mode Selection First**: User chooses planning approach before any work begins +2. **Shared Execution**: All planning modes produce `executionContext` consumed by Phase 4 (lite-execute) +3. **Progressive Phase Loading**: Only load the selected planning phase + execution phase +4. **Auto-Continue**: Planning phase completes → automatically loads execution phase +5. **Default Lite Plan**: When no mode specified, use Lite Plan (most common) + +## Auto Mode + +When `--yes` or `-y`: Skip mode selection (use default or flag-specified mode), auto-approve plan, skip clarifications. + +## Usage + +``` +Skill(skill="workflow-lite-plan", args="") +Skill(skill="workflow-lite-plan", args="[FLAGS] \"\"") + +# Flags +--mode lite-plan|multi-cli|lite-fix Planning mode selection (default: lite-plan) +-y, --yes Skip all confirmations (auto mode) +-e, --explore Force exploration (lite-plan only) +--hotfix Fast hotfix mode (lite-fix only) + +# Examples +Skill(skill="workflow-lite-plan", args="\"Implement JWT authentication\"") # Default: lite-plan +Skill(skill="workflow-lite-plan", args="--mode multi-cli \"Refactor payment module\"") # Multi-CLI planning +Skill(skill="workflow-lite-plan", args="--mode lite-fix \"Login fails with 500 error\"") # Bug fix mode +Skill(skill="workflow-lite-plan", args="-y \"Add user profile page\"") # Auto mode +Skill(skill="workflow-lite-plan", args="--mode lite-fix --hotfix \"Production DB timeout\"") # Hotfix mode +``` + +## Execution Flow + +``` +Input Parsing: + ├─ Extract flags: --mode, --yes, --explore, --hotfix + └─ Extract task description (string or file path) + +Mode Selection: + └─ Decision: + ├─ --mode lite-plan (or no --mode flag) → Read phases/01-lite-plan.md + ├─ --mode multi-cli → Read phases/02-multi-cli-plan.md + ├─ --mode lite-fix → Read phases/03-lite-fix.md + └─ No flag + not --yes → AskUserQuestion (default: Lite Plan) + +Planning Phase (one of): + ├─ Phase 1: Lite Plan + │ └─ Ref: phases/01-lite-plan.md + │ └─ Output: executionContext (plan.json + explorations + selections) + │ + ├─ Phase 2: Multi-CLI Plan + │ └─ Ref: phases/02-multi-cli-plan.md + │ └─ Output: executionContext (plan.json + synthesis rounds + selections) + │ + └─ Phase 3: Lite Fix + └─ Ref: phases/03-lite-fix.md + └─ Output: executionContext (fix-plan.json + diagnoses + selections) + +Execution Phase (always): + └─ Phase 4: Lite Execute + └─ Ref: phases/04-lite-execute.md + └─ Input: executionContext from planning phase + └─ Output: Executed tasks + optional code review +``` + +**Phase Reference Documents** (read on-demand when phase executes): + +| Phase | Document | Purpose | +|-------|----------|---------| +| 1 | [phases/01-lite-plan.md](phases/01-lite-plan.md) | Lightweight planning with exploration, clarification, and plan generation | +| 2 | [phases/02-multi-cli-plan.md](phases/02-multi-cli-plan.md) | Multi-CLI collaborative planning with ACE context and cross-verification | +| 3 | [phases/03-lite-fix.md](phases/03-lite-fix.md) | Bug diagnosis and fix planning with severity-based workflow | +| 4 | [phases/04-lite-execute.md](phases/04-lite-execute.md) | Shared execution engine: task grouping, batch execution, code review | + +## Mode Selection Logic + +```javascript +// Flag parsing +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const modeFlag = extractFlag($ARGUMENTS, '--mode') // 'lite-plan' | 'multi-cli' | 'lite-fix' | null + +// Mode determination +let selectedMode + +if (modeFlag) { + // Explicit mode flag + selectedMode = modeFlag +} else if (autoYes) { + // Auto mode: default to lite-plan + selectedMode = 'lite-plan' +} else { + // Interactive: ask user + const selection = AskUserQuestion({ + questions: [{ + question: "Select planning approach:", + header: "Mode", + multiSelect: false, + options: [ + { label: "Lite Plan (Recommended)", description: "Lightweight planning with exploration and clarification" }, + { label: "Multi-CLI Plan", description: "Multi-model collaborative planning (Gemini + Codex + Claude)" }, + { label: "Lite Fix", description: "Bug diagnosis and fix planning with severity assessment" } + ] + }] + }) + selectedMode = parseSelection(selection) // Map to 'lite-plan' | 'multi-cli' | 'lite-fix' +} + +// Load phase document +const phaseDoc = { + 'lite-plan': 'phases/01-lite-plan.md', + 'multi-cli': 'phases/02-multi-cli-plan.md', + 'lite-fix': 'phases/03-lite-fix.md' +}[selectedMode] + +Read(phaseDoc) // Load selected planning phase +// Execute planning phase... +// After planning completes: +Read('phases/04-lite-execute.md') // Load execution phase +``` + +## Data Flow + +``` +Planning Phase (01/02/03) + │ + ├─ Produces: executionContext = { + │ planObject: plan.json or fix-plan.json, + │ explorationsContext / diagnosisContext / synthesis rounds, + │ clarificationContext, + │ executionMethod: "Agent" | "Codex" | "Auto", + │ codeReviewTool: "Skip" | "Gemini Review" | ..., + │ originalUserInput: string, + │ session: { id, folder, artifacts } + │ } + │ + ↓ +Execution Phase (04) + │ + ├─ Consumes: executionContext + ├─ Task grouping → Batch creation → Parallel/sequential execution + ├─ Optional code review + └─ Development index update +``` + +## TodoWrite Pattern + +**Initialization** (after mode selection): +```json +[ + {"content": "Mode: {selectedMode} - Planning", "status": "in_progress", "activeForm": "Planning ({selectedMode})"}, + {"content": "Execution (Phase 4)", "status": "pending", "activeForm": "Executing tasks"} +] +``` + +**After planning completes**: +```json +[ + {"content": "Mode: {selectedMode} - Planning", "status": "completed", "activeForm": "Planning ({selectedMode})"}, + {"content": "Execution (Phase 4)", "status": "in_progress", "activeForm": "Executing tasks"} +] +``` + +Phase-internal sub-tasks are managed by each phase document (attach/collapse pattern). + +## Core Rules + +1. **Planning phases NEVER execute code** - all execution delegated to Phase 4 +2. **Only ONE planning phase runs** per invocation (Phase 1, 2, or 3) +3. **Phase 4 ALWAYS runs** after planning completes +4. **executionContext is the contract** between planning and execution phases +5. **Progressive loading**: Read phase doc ONLY when about to execute +6. **No cross-phase loading**: Don't load Phase 2 if user selected Phase 1 + +## Error Handling + +| Error | Resolution | +|-------|------------| +| Unknown --mode value | Default to lite-plan with warning | +| Planning phase failure | Display error, offer retry or mode switch | +| executionContext missing | Error: planning phase did not produce context | +| Phase file not found | Error with file path for debugging | + +## Related Skills + +- Full planning workflow: [workflow-plan/SKILL.md](../workflow-plan/SKILL.md) +- Brainstorming: [workflow-brainstorm-auto-parallel/SKILL.md](../workflow-brainstorm-auto-parallel/SKILL.md) diff --git a/.claude/skills/workflow-lite-plan/phases/01-lite-plan.md b/.claude/skills/workflow-lite-plan/phases/01-lite-plan.md new file mode 100644 index 00000000..a284d1c4 --- /dev/null +++ b/.claude/skills/workflow-lite-plan/phases/01-lite-plan.md @@ -0,0 +1,691 @@ +# Phase 1: Lite Plan + +## Overview + +Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Focuses on planning phases (exploration, clarification, planning, confirmation) and delegates execution to Phase 4: Lite Execute (phases/04-lite-execute.md). + +**Core capabilities:** +- Intelligent task analysis with automatic exploration detection +- Dynamic code exploration (cli-explore-agent) when codebase understanding needed +- Interactive clarification after exploration to gather missing information +- Adaptive planning: Low complexity → Direct Claude; Medium/High → cli-lite-planning-agent +- Two-step confirmation: plan display → multi-dimensional input collection +- Execution execute with complete context handoff to lite-execute + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `-y`, `--yes` | Skip all confirmations (auto mode) | +| `-e`, `--explore` | Force code exploration phase (overrides auto-detection) | +| `` | Task description or path to .md file (required) | + +## Output Artifacts + +| Artifact | Description | +|----------|-------------| +| `exploration-{angle}.json` | Per-angle exploration results (1-4 files based on complexity) | +| `explorations-manifest.json` | Index of all exploration files | +| `planning-context.md` | Evidence paths + synthesized understanding | +| `plan.json` | Structured implementation plan (plan-json-schema.json) | + +**Output Directory**: `.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/` + +**Agent Usage**: +- Low complexity → Direct Claude planning (no agent) +- Medium/High complexity → `cli-lite-planning-agent` generates `plan.json` + +**Schema Reference**: `~/.claude/workflows/cli-templates/schemas/plan-json-schema.json` + +## Auto Mode Defaults + +When `--yes` or `-y` flag is used: +- **Clarification Questions**: Skipped (no clarification phase) +- **Plan Confirmation**: Auto-selected "Allow" +- **Execution Method**: Auto-selected "Auto" +- **Code Review**: Auto-selected "Skip" + +**Flag Parsing**: +```javascript +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const forceExplore = $ARGUMENTS.includes('--explore') || $ARGUMENTS.includes('-e') +``` + +## Execution Process + +``` +Phase 1: Task Analysis & Exploration + ├─ Parse input (description or .md file) + ├─ intelligent complexity assessment (Low/Medium/High) + ├─ Exploration decision (auto-detect or --explore flag) + ├─ Context protection: If file reading ≥50k chars → force cli-explore-agent + └─ Decision: + ├─ needsExploration=true → Launch parallel cli-explore-agents (1-4 based on complexity) + └─ needsExploration=false → Skip to Phase 2/3 + +Phase 2: Clarification (optional, multi-round) + ├─ Aggregate clarification_needs from all exploration angles + ├─ Deduplicate similar questions + └─ Decision: + ├─ Has clarifications → AskUserQuestion (max 4 questions per round, multiple rounds allowed) + └─ No clarifications → Skip to Phase 3 + +Phase 3: Planning (NO CODE EXECUTION - planning only) + └─ Decision (based on Phase 1 complexity): + ├─ Low → Load schema: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json → Direct Claude planning (following schema) → plan.json + └─ Medium/High → cli-lite-planning-agent → plan.json (agent internally executes quality check) + +Phase 4: Confirmation & Selection + ├─ Display plan summary (tasks, complexity, estimated time) + └─ AskUserQuestion: + ├─ Confirm: Allow / Modify / Cancel + ├─ Execution: Agent / Codex / Auto + └─ Review: Gemini / Agent / Skip + +Phase 5: Execute + ├─ Build executionContext (plan + explorations + clarifications + selections) + └─ → Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory +``` + +## Implementation + +### Phase 1: Intelligent Multi-Angle Exploration + +**Session Setup** (MANDATORY - follow exactly): +```javascript +// Helper: Get UTC+8 (China Standard Time) ISO string +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +const taskSlug = task_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) +const dateStr = getUtc8ISOString().substring(0, 10) // Format: 2025-11-29 + +const sessionId = `${taskSlug}-${dateStr}` // e.g., "implement-jwt-refresh-2025-11-29" +const sessionFolder = `.workflow/.lite-plan/${sessionId}` + +bash(`mkdir -p ${sessionFolder} && test -d ${sessionFolder} && echo "SUCCESS: ${sessionFolder}" || echo "FAILED: ${sessionFolder}"`) +``` + +**Exploration Decision Logic**: +```javascript +needsExploration = ( + flags.includes('--explore') || flags.includes('-e') || + task.mentions_specific_files || + task.requires_codebase_context || + task.needs_architecture_understanding || + task.modifies_existing_code +) + +if (!needsExploration) { + // Skip to Phase 2 (Clarification) or Phase 3 (Planning) + proceed_to_next_phase() +} +``` + +**⚠️ Context Protection**: File reading ≥50k chars → force `needsExploration=true` (delegate to cli-explore-agent) + +**Complexity Assessment** (Intelligent Analysis): +```javascript +// analyzes task complexity based on: +// - Scope: How many systems/modules are affected? +// - Depth: Surface change vs architectural impact? +// - Risk: Potential for breaking existing functionality? +// - Dependencies: How interconnected is the change? + +const complexity = analyzeTaskComplexity(task_description) +// Returns: 'Low' | 'Medium' | 'High' +// Low: Single file, isolated change, minimal risk +// Medium: Multiple files, some dependencies, moderate risk +// High: Cross-module, architectural, high risk + +// Angle assignment based on task type (orchestrator decides, not agent) +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'] +} + +function selectAngles(taskDescription, count) { + const text = taskDescription.toLowerCase() + let preset = 'feature' // default + + if (/refactor|architect|restructure|modular/.test(text)) preset = 'architecture' + else if (/security|auth|permission|access/.test(text)) preset = 'security' + else if (/performance|slow|optimi|cache/.test(text)) preset = 'performance' + else if (/fix|bug|error|issue|broken/.test(text)) preset = 'bugfix' + + return ANGLE_PRESETS[preset].slice(0, count) +} + +const selectedAngles = selectAngles(task_description, complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1)) + +// Planning strategy determination +const planningStrategy = complexity === 'Low' + ? 'Direct Claude Planning' + : 'cli-lite-planning-agent' + +console.log(` +## Exploration Plan + +Task Complexity: ${complexity} +Selected Angles: ${selectedAngles.join(', ')} +Planning Strategy: ${planningStrategy} + +Launching ${selectedAngles.length} parallel explorations... +`) +``` + +**Launch Parallel Explorations** - Orchestrator assigns angle to each agent: + +**⚠️ CRITICAL - NO BACKGROUND EXECUTION**: +- **MUST NOT use `run_in_background: true`** - exploration results are REQUIRED before planning + + +```javascript +// Launch agents with pre-assigned angles +const explorationTasks = selectedAngles.map((angle, index) => + Task( + subagent_type="cli-explore-agent", + run_in_background=false, // ⚠️ MANDATORY: Must wait for results + 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. + +## Output Location + +**Session Folder**: ${sessionFolder} +**Output File**: ${sessionFolder}/exploration-${angle}.json + +## Assigned Context +- **Exploration Angle**: ${angle} +- **Task Description**: ${task_description} +- **Exploration Index**: ${index + 1} of ${selectedAngles.length} + +## 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 ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference) +4. Read: .workflow/project-tech.json (technology stack and architecture context) +5. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) + +## 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 + +**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 + **IMPORTANT**: Use object format with relevance scores for synthesis: + \`[{path: "src/file.ts", relevance: 0.85, rationale: "Core ${angle} logic"}]\` + 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 + +## Execution +**Write**: \`${sessionFolder}/exploration-${angle}.json\` +**Return**: 2-3 sentence summary of ${angle} findings +` + ) +) + +// Execute all exploration tasks in parallel +``` + +**Auto-discover Generated Exploration Files**: +```javascript +// After explorations complete, auto-discover all exploration-*.json files +const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`) + .split('\n') + .filter(f => f.trim()) + +// Read metadata to build manifest +const explorationManifest = { + session_id: sessionId, + task_description: task_description, + timestamp: getUtc8ISOString(), + complexity: complexity, + exploration_count: explorationCount, + explorations: explorationFiles.map(file => { + const data = JSON.parse(Read(file)) + const filename = path.basename(file) + return { + angle: data._metadata.exploration_angle, + file: filename, + path: file, + index: data._metadata.exploration_index + } + }) +} + +Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2)) + +console.log(` +## Exploration Complete + +Generated exploration files in ${sessionFolder}: +${explorationManifest.explorations.map(e => `- exploration-${e.angle}.json (angle: ${e.angle})`).join('\n')} + +Manifest: explorations-manifest.json +Angles explored: ${explorationManifest.explorations.map(e => e.angle).join(', ')} +`) +``` + +**Output**: +- `${sessionFolder}/exploration-{angle1}.json` +- `${sessionFolder}/exploration-{angle2}.json` +- ... (1-4 files based on complexity) +- `${sessionFolder}/explorations-manifest.json` + +--- + +### Phase 2: Clarification (Optional, Multi-Round) + +**Skip if**: No exploration or `clarification_needs` is empty across all explorations + +**⚠️ CRITICAL**: AskUserQuestion tool limits max 4 questions per call. **MUST execute multiple rounds** to exhaust all clarification needs - do NOT stop at round 1. + +**Aggregate clarification needs from all exploration angles**: +```javascript +// Load manifest and all exploration files +const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`)) +const explorations = manifest.explorations.map(exp => ({ + angle: exp.angle, + data: JSON.parse(Read(exp.path)) +})) + +// Aggregate clarification needs from all explorations +const allClarifications = [] +explorations.forEach(exp => { + if (exp.data.clarification_needs?.length > 0) { + exp.data.clarification_needs.forEach(need => { + allClarifications.push({ + ...need, + source_angle: exp.angle + }) + }) + } +}) + +// Intelligent deduplication: analyze allClarifications by intent +// - Identify questions with similar intent across different angles +// - Merge similar questions: combine options, consolidate context +// - Produce dedupedClarifications with unique intents only +const dedupedClarifications = intelligentMerge(allClarifications) + +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +if (autoYes) { + // Auto mode: Skip clarification phase + console.log(`[--yes] Skipping ${dedupedClarifications.length} clarification questions`) + console.log(`Proceeding to planning with exploration results...`) + // Continue to Phase 3 +} else if (dedupedClarifications.length > 0) { + // Interactive mode: Multi-round clarification + const BATCH_SIZE = 4 + const totalRounds = Math.ceil(dedupedClarifications.length / BATCH_SIZE) + + for (let i = 0; i < dedupedClarifications.length; i += BATCH_SIZE) { + const batch = dedupedClarifications.slice(i, i + BATCH_SIZE) + const currentRound = Math.floor(i / BATCH_SIZE) + 1 + + console.log(`### Clarification Round ${currentRound}/${totalRounds}`) + + AskUserQuestion({ + questions: batch.map(need => ({ + question: `[${need.source_angle}] ${need.question}\n\nContext: ${need.context}`, + header: need.source_angle.substring(0, 12), + multiSelect: false, + options: need.options.map((opt, index) => ({ + label: need.recommended === index ? `${opt} ★` : opt, + description: need.recommended === index ? `Recommended` : `Use ${opt}` + })) + })) + }) + + // Store batch responses in clarificationContext before next round + } +} +``` + +**Output**: `clarificationContext` (in-memory) + +--- + +### Phase 3: Planning + +**Planning Strategy Selection** (based on Phase 1 complexity): + +**IMPORTANT**: Phase 3 is **planning only** - NO code execution. All execution happens in Phase 5 via lite-execute. + +**Executor Assignment** (Claude 智能分配，plan 生成后执行): + +```javascript +// 分配规则（优先级从高到低）： +// 1. 用户明确指定："用 gemini 分析..." → gemini, "codex 实现..." → codex +// 2. 默认 → agent + +const executorAssignments = {} // { taskId: { executor: 'gemini'|'codex'|'agent', reason: string } } +plan.tasks.forEach(task => { + // Claude 根据上述规则语义分析，为每个 task 分配 executor + executorAssignments[task.id] = { executor: '...', reason: '...' } +}) +``` + +**Low Complexity** - Direct planning by Claude: +```javascript +// Step 1: Read schema +const schema = Bash(`cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json`) + +// Step 2: ⚠️ MANDATORY - Read and review ALL exploration files +const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`)) +manifest.explorations.forEach(exp => { + const explorationData = Read(exp.path) + console.log(`\n### Exploration: ${exp.angle}\n${explorationData}`) +}) + +// Step 3: Generate plan following schema (Claude directly, no agent) +// ⚠️ Plan MUST incorporate insights from exploration files read in Step 2 +const plan = { + summary: "...", + approach: "...", + tasks: [...], // Each task: { id, title, scope, ..., depends_on, execution_group, complexity } + estimated_time: "...", + recommended_execution: "Agent", + complexity: "Low", + _metadata: { timestamp: getUtc8ISOString(), source: "direct-planning", planning_mode: "direct" } +} + +// Step 4: Write plan to session folder +Write(`${sessionFolder}/plan.json`, JSON.stringify(plan, null, 2)) + +// Step 5: MUST continue to Phase 4 (Confirmation) - DO NOT execute code here +``` + +**Medium/High Complexity** - Invoke cli-lite-planning-agent: + +```javascript +Task( + subagent_type="cli-lite-planning-agent", + run_in_background=false, + description="Generate detailed implementation plan", + prompt=` +Generate implementation plan and write plan.json. + +## Output Location + +**Session Folder**: ${sessionFolder} +**Output Files**: +- ${sessionFolder}/planning-context.md (evidence + understanding) +- ${sessionFolder}/plan.json (implementation plan) + +## Output Schema Reference +Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json (get schema reference before generating plan) + +## Project Context (MANDATORY - Read Both Files) +1. Read: .workflow/project-tech.json (technology stack, architecture, key components) +2. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) + +**CRITICAL**: All generated tasks MUST comply with constraints in project-guidelines.json + +## Task Description +${task_description} + +## Multi-Angle Exploration Context + +${manifest.explorations.map(exp => `### Exploration: ${exp.angle} (${exp.file}) +Path: ${exp.path} + +Read this file for detailed ${exp.angle} analysis.`).join('\n\n')} + +Total explorations: ${manifest.exploration_count} +Angles covered: ${manifest.explorations.map(e => e.angle).join(', ')} + +Manifest: ${sessionFolder}/explorations-manifest.json + +## User Clarifications +${JSON.stringify(clarificationContext) || "None"} + +## Complexity Level +${complexity} + +## Requirements +Generate plan.json following the schema obtained above. Key constraints: +- tasks: 2-7 structured tasks (**group by feature/module, NOT by file**) +- _metadata.exploration_angles: ${JSON.stringify(manifest.explorations.map(e => e.angle))} + +## Task Grouping Rules +1. **Group by feature**: All changes for one feature = one task (even if 3-5 files) +2. **Group by context**: Tasks with similar context or related functional changes can be grouped together +3. **Minimize agent count**: Simple, unrelated tasks can also be grouped to reduce agent execution overhead +4. **Avoid file-per-task**: Do NOT create separate tasks for each file +5. **Substantial tasks**: Each task should represent 15-60 minutes of work +6. **True dependencies only**: Only use depends_on when Task B cannot start without Task A's output +7. **Prefer parallel**: Most tasks should be independent (no depends_on) + +## Execution +1. Read schema file (cat command above) +2. Execute CLI planning using Gemini (Qwen fallback) +3. Read ALL exploration files for comprehensive context +4. Synthesize findings and generate plan following schema +5. **Write**: \`${sessionFolder}/planning-context.md\` (evidence paths + understanding) +6. **Write**: \`${sessionFolder}/plan.json\` +7. Return brief completion summary +` +) +``` + +**Output**: `${sessionFolder}/plan.json` + +--- + +### Phase 4: Task Confirmation & Execution Selection + +**Step 4.1: Display Plan** +```javascript +const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) + +console.log(` +## Implementation Plan + +**Summary**: ${plan.summary} +**Approach**: ${plan.approach} + +**Tasks** (${plan.tasks.length}): +${plan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.file})`).join('\n')} + +**Complexity**: ${plan.complexity} +**Estimated Time**: ${plan.estimated_time} +**Recommended**: ${plan.recommended_execution} +`) +``` + +**Step 4.2: Collect Confirmation** +```javascript +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +let userSelection + +if (autoYes) { + // Auto mode: Use defaults + console.log(`[--yes] Auto-confirming plan:`) + console.log(` - Confirmation: Allow`) + console.log(` - Execution: Auto`) + console.log(` - Review: Skip`) + + userSelection = { + confirmation: "Allow", + execution_method: "Auto", + code_review_tool: "Skip" + } +} else { + // Interactive mode: Ask user + // Note: Execution "Other" option allows specifying CLI tools from ~/.claude/cli-tools.json + userSelection = AskUserQuestion({ + questions: [ + { + question: `Confirm plan? (${plan.tasks.length} tasks, ${plan.complexity})`, + header: "Confirm", + multiSelect: false, + options: [ + { label: "Allow", description: "Proceed as-is" }, + { label: "Modify", description: "Adjust before execution" }, + { label: "Cancel", description: "Abort workflow" } + ] + }, + { + question: "Execution method:", + header: "Execution", + multiSelect: false, + options: [ + { label: "Agent", description: "@code-developer agent" }, + { label: "Codex", description: "codex CLI tool" }, + { label: "Auto", description: `Auto: ${plan.complexity === 'Low' ? 'Agent' : 'Codex'}` } + ] + }, + { + question: "Code review after execution?", + header: "Review", + multiSelect: false, + options: [ + { label: "Gemini Review", description: "Gemini CLI review" }, + { label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" }, + { label: "Agent Review", description: "@code-reviewer agent" }, + { label: "Skip", description: "No review" } + ] + } + ] + }) +} +``` + +--- + +### Phase 5: Execute to Execution + +**CRITICAL**: lite-plan NEVER executes code directly. ALL execution MUST go through lite-execute. + +**Step 5.1: Build executionContext** + +```javascript +// Load manifest and all exploration files +const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`)) +const explorations = {} + +manifest.explorations.forEach(exp => { + if (file_exists(exp.path)) { + explorations[exp.angle] = JSON.parse(Read(exp.path)) + } +}) + +const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) + +executionContext = { + planObject: plan, + explorationsContext: explorations, + explorationAngles: manifest.explorations.map(e => e.angle), + explorationManifest: manifest, + clarificationContext: clarificationContext || null, + executionMethod: userSelection.execution_method, // 全局默认，可被 executorAssignments 覆盖 + codeReviewTool: userSelection.code_review_tool, + originalUserInput: task_description, + + // 任务级 executor 分配（优先于全局 executionMethod） + executorAssignments: executorAssignments, // { taskId: { executor, reason } } + + session: { + id: sessionId, + folder: sessionFolder, + artifacts: { + explorations: manifest.explorations.map(exp => ({ + angle: exp.angle, + path: exp.path + })), + explorations_manifest: `${sessionFolder}/explorations-manifest.json`, + plan: `${sessionFolder}/plan.json` + } + } +} +``` + +**Step 5.2: Execute** + +```javascript +// → Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory +``` + +## Session Folder Structure + +``` +.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/ +├── exploration-{angle1}.json # Exploration angle 1 +├── exploration-{angle2}.json # Exploration angle 2 +├── exploration-{angle3}.json # Exploration angle 3 (if applicable) +├── exploration-{angle4}.json # Exploration angle 4 (if applicable) +├── explorations-manifest.json # Exploration index +└── plan.json # Implementation plan +``` + +**Example**: +``` +.workflow/.lite-plan/implement-jwt-refresh-2025-11-25-14-30-25/ +├── exploration-architecture.json +├── exploration-auth-patterns.json +├── exploration-security.json +├── explorations-manifest.json +└── plan.json +``` + +## Error Handling + +| Error | Resolution | +|-------|------------| +| Exploration agent failure | Skip exploration, continue with task description only | +| Planning agent failure | Fallback to direct planning by Claude | +| Clarification timeout | Use exploration findings as-is | +| Confirmation timeout | Save context, display resume instructions | +| Modify loop > 3 times | Suggest breaking task or using full planning workflow (workflow-plan/SKILL.md) | + +--- + +## Post-Phase Update + +After Phase 1 (Lite Plan) completes: +- **Output Created**: `executionContext` with plan.json, explorations, clarifications, user selections +- **Session Artifacts**: All files in `.workflow/.lite-plan/{session-id}/` +- **Next Action**: Auto-continue to [Phase 4: Lite Execute](04-lite-execute.md) with --in-memory +- **TodoWrite**: Mark "Lite Plan - Planning" as completed, start "Execution (Phase 4)" diff --git a/.claude/skills/workflow-lite-plan/phases/02-multi-cli-plan.md b/.claude/skills/workflow-lite-plan/phases/02-multi-cli-plan.md new file mode 100644 index 00000000..25ed57af --- /dev/null +++ b/.claude/skills/workflow-lite-plan/phases/02-multi-cli-plan.md @@ -0,0 +1,570 @@ +# Phase 2: Multi-CLI Plan + +## Auto Mode + +When `--yes` or `-y`: Auto-approve plan, use recommended solution and execution method (Agent, Skip review). + +## Overview + +Multi-CLI collaborative planning with ACE context gathering and iterative cross-verification. Uses cli-discuss-agent for Gemini+Codex+Claude analysis to converge on optimal execution plan. + +## Quick Start + +**Parameters**: +- `` (required): Task description +- `--max-rounds` (optional): Maximum discussion rounds (default: 3) +- `--tools` (optional): CLI tools for analysis (default: gemini,codex) +- `--mode` (optional): Execution mode: parallel or serial + +**Context Source**: ACE semantic search + Multi-CLI analysis +**Output Directory**: `.workflow/.multi-cli-plan/{session-id}/` +**Default Max Rounds**: 3 (convergence may complete earlier) +**CLI Tools**: @cli-discuss-agent (analysis), @cli-lite-planning-agent (plan generation) +**Execution**: Auto-hands off to Phase 4: Lite Execute (phases/04-lite-execute.md) after plan approval + +## What & Why + +### Core Concept + +Multi-CLI collaborative planning with **three-phase architecture**: ACE context gathering → Iterative multi-CLI discussion → Plan generation. Orchestrator delegates analysis to agents, only handles user decisions and session management. + +**Process**: +- **Phase 1**: ACE semantic search gathers codebase context +- **Phase 2**: cli-discuss-agent orchestrates Gemini/Codex/Claude for cross-verified analysis +- **Phase 3-5**: User decision → Plan generation → Execution handoff + +**vs Single-CLI Planning**: +- **Single**: One model perspective, potential blind spots +- **Multi-CLI**: Cross-verification catches inconsistencies, builds consensus on solutions + +### Value Proposition + +1. **Multi-Perspective Analysis**: Gemini + Codex + Claude analyze from different angles +2. **Cross-Verification**: Identify agreements/disagreements, build confidence +3. **User-Driven Decisions**: Every round ends with user decision point +4. **Iterative Convergence**: Progressive refinement until consensus reached + +### Orchestrator Boundary (CRITICAL) + +- **ONLY command** for multi-CLI collaborative planning +- Manages: Session state, user decisions, agent delegation, phase transitions +- Delegates: CLI execution to @cli-discuss-agent, plan generation to @cli-lite-planning-agent + +### Execution Flow + +``` +Phase 1: Context Gathering + └─ ACE semantic search, extract keywords, build context package + +Phase 2: Multi-CLI Discussion (Iterative, via @cli-discuss-agent) + ├─ Round N: Agent executes Gemini + Codex + Claude + ├─ Cross-verify findings, synthesize solutions + ├─ Write synthesis.json to rounds/{N}/ + └─ Loop until convergence or max rounds + +Phase 3: Present Options + └─ Display solutions with trade-offs from agent output + +Phase 4: User Decision + ├─ Select solution approach + ├─ Select execution method (Agent/Codex/Auto) + ├─ Select code review tool (Skip/Gemini/Codex/Agent) + └─ Route: + ├─ Approve → Phase 5 + ├─ Need More Analysis → Return to Phase 2 + └─ Cancel → Save session + +Phase 5: Plan Generation & Execution Handoff + ├─ Generate plan.json (via @cli-lite-planning-agent) + ├─ Build executionContext with user selections + └─ Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory +``` + +### Agent Roles + +| Agent | Responsibility | +|-------|---------------| +| **Orchestrator** | Session management, ACE context, user decisions, phase transitions, executionContext assembly | +| **@cli-discuss-agent** | Multi-CLI execution (Gemini/Codex/Claude), cross-verification, solution synthesis, synthesis.json output | +| **@cli-lite-planning-agent** | Task decomposition, plan.json generation following schema | + +## Core Responsibilities + +### Phase 1: Context Gathering + +**Session Initialization**: +```javascript +const sessionId = `MCP-${taskSlug}-${date}` +const sessionFolder = `.workflow/.multi-cli-plan/${sessionId}` +Bash(`mkdir -p ${sessionFolder}/rounds`) +``` + +**ACE Context Queries**: +```javascript +const aceQueries = [ + `Project architecture related to ${keywords}`, + `Existing implementations of ${keywords[0]}`, + `Code patterns for ${keywords} features`, + `Integration points for ${keywords[0]}` +] +// Execute via mcp__ace-tool__search_context +``` + +**Context Package** (passed to agent): +- `relevant_files[]` - Files identified by ACE +- `detected_patterns[]` - Code patterns found +- `architecture_insights` - Structure understanding + +### Phase 2: Agent Delegation + +**Core Principle**: Orchestrator only delegates and reads output - NO direct CLI execution. + +**⚠️ CRITICAL - CLI EXECUTION REQUIREMENT**: +- **MUST** execute CLI calls via `Bash` with `run_in_background: true` +- **MUST** wait for hook callback to receive complete results +- **MUST NOT** proceed with next phase until CLI execution fully completes +- Do NOT use `TaskOutput` polling during CLI execution - wait passively for results +- Minimize scope: Proceed only when 100% result available + +**Agent Invocation**: +```javascript +Task({ + subagent_type: "cli-discuss-agent", + run_in_background: false, + description: `Discussion round ${currentRound}`, + prompt: ` +## Input Context +- task_description: ${taskDescription} +- round_number: ${currentRound} +- session: { id: "${sessionId}", folder: "${sessionFolder}" } +- ace_context: ${JSON.stringify(contextPackageage)} +- previous_rounds: ${JSON.stringify(analysisResults)} +- user_feedback: ${userFeedback || 'None'} +- cli_config: { tools: ["gemini", "codex"], mode: "parallel", fallback_chain: ["gemini", "codex", "claude"] } + +## Execution Process +1. Parse input context (handle JSON strings) +2. Check if ACE supplementary search needed +3. Build CLI prompts with context +4. Execute CLIs (parallel or serial per cli_config.mode) +5. Parse CLI outputs, handle failures with fallback +6. Perform cross-verification between CLI results +7. Synthesize solutions, calculate scores +8. Calculate convergence, generate clarification questions +9. Write synthesis.json + +## Output +Write: ${sessionFolder}/rounds/${currentRound}/synthesis.json + +## Completion Checklist +- [ ] All configured CLI tools executed (or fallback triggered) +- [ ] Cross-verification completed with agreements/disagreements +- [ ] 2-3 solutions generated with file:line references +- [ ] Convergence score calculated (0.0-1.0) +- [ ] synthesis.json written with all Primary Fields +` +}) +``` + +**Read Agent Output**: +```javascript +const synthesis = JSON.parse(Read(`${sessionFolder}/rounds/${round}/synthesis.json`)) +// Access top-level fields: solutions, convergence, cross_verification, clarification_questions +``` + +**Convergence Decision**: +```javascript +if (synthesis.convergence.recommendation === 'converged') { + // Proceed to Phase 3 +} else if (synthesis.convergence.recommendation === 'user_input_needed') { + // Collect user feedback, return to Phase 2 +} else { + // Continue to next round if new_insights && round < maxRounds +} +``` + +### Phase 3: Present Options + +**Display from Agent Output** (no processing): +```javascript +console.log(` +## Solution Options + +${synthesis.solutions.map((s, i) => ` +**Option ${i+1}: ${s.name}** +Source: ${s.source_cli.join(' + ')} +Effort: ${s.effort} | Risk: ${s.risk} + +Pros: ${s.pros.join(', ')} +Cons: ${s.cons.join(', ')} + +Files: ${s.affected_files.slice(0,3).map(f => `${f.file}:${f.line}`).join(', ')} +`).join('\n')} + +## Cross-Verification +Agreements: ${synthesis.cross_verification.agreements.length} +Disagreements: ${synthesis.cross_verification.disagreements.length} +`) +``` + +### Phase 4: User Decision + +**Decision Options**: +```javascript +AskUserQuestion({ + questions: [ + { + question: "Which solution approach?", + header: "Solution", + multiSelect: false, + options: solutions.map((s, i) => ({ + label: `Option ${i+1}: ${s.name}`, + description: `${s.effort} effort, ${s.risk} risk` + })).concat([ + { label: "Need More Analysis", description: "Return to Phase 2" } + ]) + }, + { + question: "Execution method:", + header: "Execution", + multiSelect: false, + options: [ + { label: "Agent", description: "@code-developer agent" }, + { label: "Codex", description: "codex CLI tool" }, + { label: "Auto", description: "Auto-select based on complexity" } + ] + }, + { + question: "Code review after execution?", + header: "Review", + multiSelect: false, + options: [ + { label: "Skip", description: "No review" }, + { label: "Gemini Review", description: "Gemini CLI tool" }, + { label: "Codex Review", description: "codex review --uncommitted" }, + { label: "Agent Review", description: "Current agent review" } + ] + } + ] +}) +``` + +**Routing**: +- Approve + execution method → Phase 5 +- Need More Analysis → Phase 2 with feedback +- Cancel → Save session for resumption + +### Phase 5: Plan Generation & Execution Handoff + +**Step 1: Build Context-Package** (Orchestrator responsibility): +```javascript +// Extract key information from user decision and synthesis +const contextPackage = { + // Core solution details + solution: { + name: selectedSolution.name, + source_cli: selectedSolution.source_cli, + feasibility: selectedSolution.feasibility, + effort: selectedSolution.effort, + risk: selectedSolution.risk, + summary: selectedSolution.summary + }, + // Implementation plan (tasks, flow, milestones) + implementation_plan: selectedSolution.implementation_plan, + // Dependencies + dependencies: selectedSolution.dependencies || { internal: [], external: [] }, + // Technical concerns + technical_concerns: selectedSolution.technical_concerns || [], + // Consensus from cross-verification + consensus: { + agreements: synthesis.cross_verification.agreements, + resolved_conflicts: synthesis.cross_verification.resolution + }, + // User constraints (from Phase 4 feedback) + constraints: userConstraints || [], + // Task context + task_description: taskDescription, + session_id: sessionId +} + +// Write context-package for traceability +Write(`${sessionFolder}/context-package.json`, JSON.stringify(contextPackage, null, 2)) +``` + +**Context-Package Schema**: + +| Field | Type | Description | +|-------|------|-------------| +| `solution` | object | User-selected solution from synthesis | +| `solution.name` | string | Solution identifier | +| `solution.feasibility` | number | Viability score (0-1) | +| `solution.summary` | string | Brief analysis summary | +| `implementation_plan` | object | Task breakdown with flow and dependencies | +| `implementation_plan.approach` | string | High-level technical strategy | +| `implementation_plan.tasks[]` | array | Discrete tasks with id, name, depends_on, files | +| `implementation_plan.execution_flow` | string | Task sequence (e.g., "T1 → T2 → T3") | +| `implementation_plan.milestones` | string[] | Key checkpoints | +| `dependencies` | object | Module and package dependencies | +| `technical_concerns` | string[] | Risks and blockers | +| `consensus` | object | Cross-verified agreements from multi-CLI | +| `constraints` | string[] | User-specified constraints from Phase 4 | + +```json +{ + "solution": { + "name": "Strategy Pattern Refactoring", + "source_cli": ["gemini", "codex"], + "feasibility": 0.88, + "effort": "medium", + "risk": "low", + "summary": "Extract payment gateway interface, implement strategy pattern for multi-gateway support" + }, + "implementation_plan": { + "approach": "Define interface → Create concrete strategies → Implement factory → Migrate existing code", + "tasks": [ + {"id": "T1", "name": "Define PaymentGateway interface", "depends_on": [], "files": [{"file": "src/types/payment.ts", "line": 1, "action": "create"}], "key_point": "Include all existing Stripe methods"}, + {"id": "T2", "name": "Implement StripeGateway", "depends_on": ["T1"], "files": [{"file": "src/payment/stripe.ts", "line": 1, "action": "create"}], "key_point": "Wrap existing logic"}, + {"id": "T3", "name": "Create GatewayFactory", "depends_on": ["T1"], "files": [{"file": "src/payment/factory.ts", "line": 1, "action": "create"}], "key_point": null}, + {"id": "T4", "name": "Migrate processor to use factory", "depends_on": ["T2", "T3"], "files": [{"file": "src/payment/processor.ts", "line": 45, "action": "modify"}], "key_point": "Backward compatible"} + ], + "execution_flow": "T1 → (T2 | T3) → T4", + "milestones": ["Interface defined", "Gateway implementations complete", "Migration done"] + }, + "dependencies": { + "internal": ["@/lib/payment-gateway", "@/types/payment"], + "external": ["stripe@^14.0.0"] + }, + "technical_concerns": ["Existing tests must pass", "No breaking API changes"], + "consensus": { + "agreements": ["Use strategy pattern", "Keep existing API"], + "resolved_conflicts": "Factory over DI for simpler integration" + }, + "constraints": ["backward compatible", "no breaking changes to PaymentResult type"], + "task_description": "Refactor payment processing for multi-gateway support", + "session_id": "MCP-payment-refactor-2026-01-14" +} +``` + +**Step 2: Invoke Planning Agent**: +```javascript +Task({ + subagent_type: "cli-lite-planning-agent", + run_in_background: false, + description: "Generate implementation plan", + prompt: ` +## Schema Reference +Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json + +## Context-Package (from orchestrator) +${JSON.stringify(contextPackage, null, 2)} + +## Execution Process +1. Read plan-json-schema.json for output structure +2. Read project-tech.json and project-guidelines.json +3. Parse context-package fields: + - solution: name, feasibility, summary + - implementation_plan: tasks[], execution_flow, milestones + - dependencies: internal[], external[] + - technical_concerns: risks/blockers + - consensus: agreements, resolved_conflicts + - constraints: user requirements +4. Use implementation_plan.tasks[] as task foundation +5. Preserve task dependencies (depends_on) and execution_flow +6. Expand tasks with detailed acceptance criteria +7. Generate plan.json following schema exactly + +## Output +- ${sessionFolder}/plan.json + +## Completion Checklist +- [ ] plan.json preserves task dependencies from implementation_plan +- [ ] Task execution order follows execution_flow +- [ ] Key_points reflected in task descriptions +- [ ] User constraints applied to implementation +- [ ] Acceptance criteria are testable +- [ ] Schema fields match plan-json-schema.json exactly +` +}) +``` + +**Step 3: Build executionContext**: +```javascript +// After plan.json is generated by cli-lite-planning-agent +const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) + +// Build executionContext (same structure as lite-plan) +executionContext = { + planObject: plan, + explorationsContext: null, // Multi-CLI doesn't use exploration files + explorationAngles: [], // No exploration angles + explorationManifest: null, // No manifest + clarificationContext: null, // Store user feedback from Phase 2 if exists + executionMethod: userSelection.execution_method, // From Phase 4 + codeReviewTool: userSelection.code_review_tool, // From Phase 4 + originalUserInput: taskDescription, + + // Optional: Task-level executor assignments + executorAssignments: null, // Could be enhanced in future + + session: { + id: sessionId, + folder: sessionFolder, + artifacts: { + explorations: [], // No explorations in multi-CLI workflow + explorations_manifest: null, + plan: `${sessionFolder}/plan.json`, + synthesis_rounds: Array.from({length: currentRound}, (_, i) => + `${sessionFolder}/rounds/${i+1}/synthesis.json` + ), + context_package: `${sessionFolder}/context-package.json` + } + } +} +``` + +**Step 4: Hand off to Execution**: +```javascript +// Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) with in-memory context +// executionContext is passed in-memory to the execution phase +``` + +## Output File Structure + +``` +.workflow/.multi-cli-plan/{MCP-task-slug-YYYY-MM-DD}/ +├── session-state.json # Session tracking (orchestrator) +├── rounds/ +│ ├── 1/synthesis.json # Round 1 analysis (cli-discuss-agent) +│ ├── 2/synthesis.json # Round 2 analysis (cli-discuss-agent) +│ └── .../ +├── context-package.json # Extracted context for planning (orchestrator) +└── plan.json # Structured plan (cli-lite-planning-agent) +``` + +**File Producers**: + +| File | Producer | Content | +|------|----------|---------| +| `session-state.json` | Orchestrator | Session metadata, rounds, decisions | +| `rounds/*/synthesis.json` | cli-discuss-agent | Solutions, convergence, cross-verification | +| `context-package.json` | Orchestrator | Extracted solution, dependencies, consensus for planning | +| `plan.json` | cli-lite-planning-agent | Structured tasks for lite-execute | + +## synthesis.json Schema + +```json +{ + "round": 1, + "solutions": [{ + "name": "Solution Name", + "source_cli": ["gemini", "codex"], + "feasibility": 0.85, + "effort": "low|medium|high", + "risk": "low|medium|high", + "summary": "Brief analysis summary", + "implementation_plan": { + "approach": "High-level technical approach", + "tasks": [ + {"id": "T1", "name": "Task", "depends_on": [], "files": [], "key_point": "..."} + ], + "execution_flow": "T1 → T2 → T3", + "milestones": ["Checkpoint 1", "Checkpoint 2"] + }, + "dependencies": {"internal": [], "external": []}, + "technical_concerns": ["Risk 1", "Blocker 2"] + }], + "convergence": { + "score": 0.85, + "new_insights": false, + "recommendation": "converged|continue|user_input_needed" + }, + "cross_verification": { + "agreements": [], + "disagreements": [], + "resolution": "..." + }, + "clarification_questions": [] +} +``` + +**Key Planning Fields**: + +| Field | Purpose | +|-------|---------| +| `feasibility` | Viability score (0-1) | +| `implementation_plan.tasks[]` | Discrete tasks with dependencies | +| `implementation_plan.execution_flow` | Task sequence visualization | +| `implementation_plan.milestones` | Key checkpoints | +| `technical_concerns` | Risks and blockers | + +**Note**: Solutions ranked by internal scoring (array order = priority) + +## TodoWrite Structure + +**Initialization**: +```javascript +TodoWrite({ todos: [ + { content: "Phase 1: Context Gathering", status: "in_progress", activeForm: "Gathering context" }, + { content: "Phase 2: Multi-CLI Discussion", status: "pending", activeForm: "Running discussion" }, + { content: "Phase 3: Present Options", status: "pending", activeForm: "Presenting options" }, + { content: "Phase 4: User Decision", status: "pending", activeForm: "Awaiting decision" }, + { content: "Phase 5: Plan Generation", status: "pending", activeForm: "Generating plan" } +]}) +``` + +**During Discussion Rounds**: +```javascript +TodoWrite({ todos: [ + { content: "Phase 1: Context Gathering", status: "completed", activeForm: "Gathering context" }, + { content: "Phase 2: Multi-CLI Discussion", status: "in_progress", activeForm: "Running discussion" }, + { content: " → Round 1: Initial analysis", status: "completed", activeForm: "Analyzing" }, + { content: " → Round 2: Deep verification", status: "in_progress", activeForm: "Verifying" }, + { content: "Phase 3: Present Options", status: "pending", activeForm: "Presenting options" }, + // ... +]}) +``` + +## Error Handling + +| Error | Resolution | +|-------|------------| +| ACE search fails | Fall back to Glob/Grep for file discovery | +| Agent fails | Retry once, then present partial results | +| CLI timeout (in agent) | Agent uses fallback: gemini → codex → claude | +| No convergence | Present best options, flag uncertainty | +| synthesis.json parse error | Request agent retry | +| User cancels | Save session for later resumption | + +## Configuration + +| Flag | Default | Description | +|------|---------|-------------| +| `--max-rounds` | 3 | Maximum discussion rounds | +| `--tools` | gemini,codex | CLI tools for analysis | +| `--mode` | parallel | Execution mode: parallel or serial | +| `--auto-execute` | false | Auto-execute after approval | + +## Best Practices + +1. **Be Specific**: Detailed task descriptions improve ACE context quality +2. **Provide Feedback**: Use clarification rounds to refine requirements +3. **Trust Cross-Verification**: Multi-CLI consensus indicates high confidence +4. **Review Trade-offs**: Consider pros/cons before selecting solution +5. **Check synthesis.json**: Review agent output for detailed analysis +6. **Iterate When Needed**: Don't hesitate to request more analysis + +## Related Phases + +- Simpler single-round planning: [Phase 1: Lite Plan](01-lite-plan.md) +- Shared execution engine: [Phase 4: Lite Execute](04-lite-execute.md) +- Full planning workflow: [workflow-plan/SKILL.md](../../workflow-plan/SKILL.md) + +--- + +## Post-Phase Update + +After Phase 2 (Multi-CLI Plan) completes: +- **Output Created**: `executionContext` with plan.json, synthesis rounds, context-package, user selections +- **Session Artifacts**: All files in `.workflow/.multi-cli-plan/{session-id}/` +- **Next Action**: Auto-continue to [Phase 4: Lite Execute](04-lite-execute.md) with --in-memory +- **TodoWrite**: Mark "Multi-CLI Plan - Planning" as completed, start "Execution (Phase 4)" diff --git a/.claude/skills/workflow-lite-plan/phases/03-lite-fix.md b/.claude/skills/workflow-lite-plan/phases/03-lite-fix.md new file mode 100644 index 00000000..cb57885b --- /dev/null +++ b/.claude/skills/workflow-lite-plan/phases/03-lite-fix.md @@ -0,0 +1,799 @@ +# Phase 3: Lite Fix + +## Overview + +Intelligent lightweight bug fixing command with dynamic workflow adaptation based on severity assessment. Focuses on diagnosis phases (root cause analysis, impact assessment, fix planning, confirmation) and delegates execution to Phase 4: Lite Execute (phases/04-lite-execute.md). + +**Core capabilities:** +- Intelligent bug analysis with automatic severity detection +- Dynamic code diagnosis (cli-explore-agent) for root cause identification +- Interactive clarification after diagnosis to gather missing information +- Adaptive fix planning strategy (direct Claude vs cli-lite-planning-agent) based on complexity +- Two-step confirmation: fix-plan display -> multi-dimensional input collection +- Execution handoff with complete context to Phase 4: Lite Execute (phases/04-lite-execute.md) + +## Parameters + +- `-y, --yes`: Skip all confirmations (auto mode) +- `--hotfix, -h`: Production hotfix mode (minimal diagnosis, fast fix) +- `` (required): Bug description, error message, or path to .md file + +## Output Artifacts + +| Artifact | Description | +|----------|-------------| +| `diagnosis-{angle}.json` | Per-angle diagnosis results (1-4 files based on severity) | +| `diagnoses-manifest.json` | Index of all diagnosis files | +| `planning-context.md` | Evidence paths + synthesized understanding | +| `fix-plan.json` | Structured fix plan (fix-plan-json-schema.json) | + +**Output Directory**: `.workflow/.lite-fix/{bug-slug}-{YYYY-MM-DD}/` + +**Agent Usage**: +- Low/Medium severity → Direct Claude planning (no agent) +- High/Critical severity → `cli-lite-planning-agent` generates `fix-plan.json` + +**Schema Reference**: `~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json` + +## Auto Mode Defaults + +When `--yes` or `-y` flag is used: +- **Clarification Questions**: Skipped (no clarification phase) +- **Fix Plan Confirmation**: Auto-selected "Allow" +- **Execution Method**: Auto-selected "Auto" +- **Code Review**: Auto-selected "Skip" +- **Severity**: Uses auto-detected severity (no manual override) +- **Hotfix Mode**: Respects --hotfix flag if present, otherwise normal mode + +**Flag Parsing**: +```javascript +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const hotfixMode = $ARGUMENTS.includes('--hotfix') || $ARGUMENTS.includes('-h') +``` + +## Execution Process + +``` +Phase 1: Bug Analysis & Diagnosis + |- Parse input (description, error message, or .md file) + |- Intelligent severity pre-assessment (Low/Medium/High/Critical) + |- Diagnosis decision (auto-detect or --hotfix flag) + |- Context protection: If file reading >=50k chars -> force cli-explore-agent + +- Decision: + |- needsDiagnosis=true -> Launch parallel cli-explore-agents (1-4 based on severity) + +- needsDiagnosis=false (hotfix) -> Skip directly to Phase 3 (Fix Planning) + +Phase 2: Clarification (optional, multi-round) + |- Aggregate clarification_needs from all diagnosis angles + |- Deduplicate similar questions + +- Decision: + |- Has clarifications -> AskUserQuestion (max 4 questions per round, multiple rounds allowed) + +- No clarifications -> Skip to Phase 3 + +Phase 3: Fix Planning (NO CODE EXECUTION - planning only) + +- Decision (based on Phase 1 severity): + |- Low/Medium -> Load schema: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json -> Direct Claude planning (following schema) -> fix-plan.json -> MUST proceed to Phase 4 + +- High/Critical -> cli-lite-planning-agent -> fix-plan.json -> MUST proceed to Phase 4 + +Phase 4: Confirmation & Selection + |- Display fix-plan summary (tasks, severity, estimated time) + +- AskUserQuestion: + |- Confirm: Allow / Modify / Cancel + |- Execution: Agent / Codex / Auto + +- Review: Gemini / Agent / Skip + +Phase 5: Execute + |- Build executionContext (fix-plan + diagnoses + clarifications + selections) + +- Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory --mode bugfix +``` + +## Implementation + +### Phase 1: Intelligent Multi-Angle Diagnosis + +**Session Setup** (MANDATORY - follow exactly): +```javascript +// Helper: Get UTC+8 (China Standard Time) ISO string +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) +const dateStr = getUtc8ISOString().substring(0, 10) // Format: 2025-11-29 + +const sessionId = `${bugSlug}-${dateStr}` // e.g., "user-avatar-upload-fails-2025-11-29" +const sessionFolder = `.workflow/.lite-fix/${sessionId}` + +bash(`mkdir -p ${sessionFolder} && test -d ${sessionFolder} && echo "SUCCESS: ${sessionFolder}" || echo "FAILED: ${sessionFolder}"`) +``` + +**Diagnosis Decision Logic**: +```javascript +const hotfixMode = $ARGUMENTS.includes('--hotfix') || $ARGUMENTS.includes('-h') + +needsDiagnosis = ( + !hotfixMode && + ( + bug.lacks_specific_error_message || + bug.requires_codebase_context || + bug.needs_execution_tracing || + bug.root_cause_unclear + ) +) + +if (!needsDiagnosis) { + // Skip to Phase 2 (Clarification) or Phase 3 (Fix Planning) + proceed_to_next_phase() +} +``` + +**Context Protection**: File reading >=50k chars -> force `needsDiagnosis=true` (delegate to cli-explore-agent) + +**Severity Pre-Assessment** (Intelligent Analysis): +```javascript +// Analyzes bug severity based on: +// - Symptoms: Error messages, crash reports, user complaints +// - Scope: How many users/features are affected? +// - Urgency: Production down vs minor inconvenience +// - Impact: Data loss, security, business impact + +const severity = analyzeBugSeverity(bug_description) +// Returns: 'Low' | 'Medium' | 'High' | 'Critical' +// Low: Minor UI issue, localized, no data impact +// Medium: Multiple users affected, degraded functionality +// High: Significant functionality broken, many users affected +// Critical: Production down, data loss risk, security issue + +// Angle assignment based on bug type (orchestrator decides, not agent) +const DIAGNOSIS_ANGLE_PRESETS = { + runtime_error: ['error-handling', 'dataflow', 'state-management', 'edge-cases'], + performance: ['performance', 'bottlenecks', 'caching', 'data-access'], + security: ['security', 'auth-patterns', 'dataflow', 'validation'], + data_corruption: ['data-integrity', 'state-management', 'transactions', 'validation'], + ui_bug: ['state-management', 'event-handling', 'rendering', 'data-binding'], + integration: ['api-contracts', 'error-handling', 'timeouts', 'fallbacks'] +} + +function selectDiagnosisAngles(bugDescription, count) { + const text = bugDescription.toLowerCase() + let preset = 'runtime_error' // default + + if (/slow|timeout|performance|lag|hang/.test(text)) preset = 'performance' + else if (/security|auth|permission|access|token/.test(text)) preset = 'security' + else if (/corrupt|data|lost|missing|inconsistent/.test(text)) preset = 'data_corruption' + else if (/ui|display|render|style|click|button/.test(text)) preset = 'ui_bug' + else if (/api|integration|connect|request|response/.test(text)) preset = 'integration' + + return DIAGNOSIS_ANGLE_PRESETS[preset].slice(0, count) +} + +const selectedAngles = selectDiagnosisAngles(bug_description, severity === 'Critical' ? 4 : (severity === 'High' ? 3 : (severity === 'Medium' ? 2 : 1))) + +console.log(` +## Diagnosis Plan + +Bug Severity: ${severity} +Selected Angles: ${selectedAngles.join(', ')} + +Launching ${selectedAngles.length} parallel diagnoses... +`) +``` + +**Launch Parallel Diagnoses** - Orchestrator assigns angle to each agent: + +```javascript +// Launch agents with pre-assigned diagnosis angles +const diagnosisTasks = selectedAngles.map((angle, index) => + Task( + subagent_type="cli-explore-agent", + run_in_background=false, + description=`Diagnose: ${angle}`, + prompt=` +## Task Objective +Execute **${angle}** diagnosis for bug root cause analysis. Analyze codebase from this specific angle to discover root cause, affected paths, and fix hints. + +## Output Location + +**Session Folder**: ${sessionFolder} +**Output File**: ${sessionFolder}/diagnosis-${angle}.json + +## Assigned Context +- **Diagnosis Angle**: ${angle} +- **Bug Description**: ${bug_description} +- **Diagnosis Index**: ${index + 1} of ${selectedAngles.length} + +## 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 "{error_keyword_from_bug}" --type ts (locate relevant files) +3. Execute: cat ~/.claude/workflows/cli-templates/schemas/diagnosis-json-schema.json (get output schema reference) +4. Read: .workflow/project-tech.json (technology stack and architecture context) +5. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) + +## Diagnosis Strategy (${angle} focus) + +**Step 1: Error Tracing** (Bash) +- rg for error messages, stack traces, log patterns +- git log --since='2 weeks ago' for recent changes +- Trace execution path in affected modules + +**Step 2: Root Cause Analysis** (Gemini CLI) +- What code paths lead to this ${angle} issue? +- What edge cases are not handled from ${angle} perspective? +- What recent changes might have introduced this bug? + +**Step 3: Write Output** +- Consolidate ${angle} findings into JSON +- Identify ${angle}-specific clarification needs +- Provide fix hints based on ${angle} analysis + +## Expected Output + +**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly + +**Required Fields** (all ${angle} focused): +- symptom: Bug symptoms and error messages +- root_cause: Root cause hypothesis from ${angle} perspective + **IMPORTANT**: Use structured format: + \`{file: "src/module/file.ts", line_range: "45-60", issue: "Description", confidence: 0.85}\` +- affected_files: Files involved from ${angle} perspective + **IMPORTANT**: Use object format with relevance scores: + \`[{path: "src/file.ts", relevance: 0.85, rationale: "Contains ${angle} logic"}]\` +- reproduction_steps: Steps to reproduce the bug +- fix_hints: Suggested fix approaches from ${angle} viewpoint +- dependencies: Dependencies relevant to ${angle} diagnosis +- constraints: ${angle}-specific limitations affecting fix +- clarification_needs: ${angle}-related ambiguities (options array + recommended index) +- _metadata.diagnosis_angle: "${angle}" +- _metadata.diagnosis_index: ${index + 1} + +## Success Criteria +- [ ] Schema obtained via cat diagnosis-json-schema.json +- [ ] get_modules_by_depth.sh executed +- [ ] Root cause identified with confidence score +- [ ] At least 3 affected files identified with ${angle} rationale +- [ ] Fix hints are actionable (specific code changes, not generic advice) +- [ ] Reproduction steps are verifiable +- [ ] JSON output follows schema exactly +- [ ] clarification_needs includes options + recommended + +## Execution +**Write**: \`${sessionFolder}/diagnosis-${angle}.json\` +**Return**: 2-3 sentence summary of ${angle} diagnosis findings +` + ) +) + +// Execute all diagnosis tasks in parallel +``` + +**Auto-discover Generated Diagnosis Files**: +```javascript +// After diagnoses complete, auto-discover all diagnosis-*.json files +const diagnosisFiles = bash(`find ${sessionFolder} -name "diagnosis-*.json" -type f`) + .split('\n') + .filter(f => f.trim()) + +// Read metadata to build manifest +const diagnosisManifest = { + session_id: sessionId, + bug_description: bug_description, + timestamp: getUtc8ISOString(), + severity: severity, + diagnosis_count: diagnosisFiles.length, + diagnoses: diagnosisFiles.map(file => { + const data = JSON.parse(Read(file)) + const filename = path.basename(file) + return { + angle: data._metadata.diagnosis_angle, + file: filename, + path: file, + index: data._metadata.diagnosis_index + } + }) +} + +Write(`${sessionFolder}/diagnoses-manifest.json`, JSON.stringify(diagnosisManifest, null, 2)) + +console.log(` +## Diagnosis Complete + +Generated diagnosis files in ${sessionFolder}: +${diagnosisManifest.diagnoses.map(d => `- diagnosis-${d.angle}.json (angle: ${d.angle})`).join('\n')} + +Manifest: diagnoses-manifest.json +Angles diagnosed: ${diagnosisManifest.diagnoses.map(d => d.angle).join(', ')} +`) +``` + +**Output**: +- `${sessionFolder}/diagnosis-{angle1}.json` +- `${sessionFolder}/diagnosis-{angle2}.json` +- ... (1-4 files based on severity) +- `${sessionFolder}/diagnoses-manifest.json` + +--- + +### Phase 2: Clarification (Optional, Multi-Round) + +**Skip if**: No diagnosis or `clarification_needs` is empty across all diagnoses + +**⚠️ CRITICAL**: AskUserQuestion tool limits max 4 questions per call. **MUST execute multiple rounds** to exhaust all clarification needs - do NOT stop at round 1. + +**Aggregate clarification needs from all diagnosis angles**: +```javascript +// Load manifest and all diagnosis files +const manifest = JSON.parse(Read(`${sessionFolder}/diagnoses-manifest.json`)) +const diagnoses = manifest.diagnoses.map(diag => ({ + angle: diag.angle, + data: JSON.parse(Read(diag.path)) +})) + +// Aggregate clarification needs from all diagnoses +const allClarifications = [] +diagnoses.forEach(diag => { + if (diag.data.clarification_needs?.length > 0) { + diag.data.clarification_needs.forEach(need => { + allClarifications.push({ + ...need, + source_angle: diag.angle + }) + }) + } +}) + +// Deduplicate by question similarity +function deduplicateClarifications(clarifications) { + const unique = [] + clarifications.forEach(c => { + const isDuplicate = unique.some(u => + u.question.toLowerCase() === c.question.toLowerCase() + ) + if (!isDuplicate) unique.push(c) + }) + return unique +} + +const uniqueClarifications = deduplicateClarifications(allClarifications) + +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +if (autoYes) { + // Auto mode: Skip clarification phase + console.log(`[--yes] Skipping ${uniqueClarifications.length} clarification questions`) + console.log(`Proceeding to fix planning with diagnosis results...`) + // Continue to Phase 3 +} else if (uniqueClarifications.length > 0) { + // Interactive mode: Multi-round clarification + // ⚠️ MUST execute ALL rounds until uniqueClarifications exhausted + const BATCH_SIZE = 4 + const totalRounds = Math.ceil(uniqueClarifications.length / BATCH_SIZE) + + for (let i = 0; i < uniqueClarifications.length; i += BATCH_SIZE) { + const batch = uniqueClarifications.slice(i, i + BATCH_SIZE) + const currentRound = Math.floor(i / BATCH_SIZE) + 1 + + console.log(`### Clarification Round ${currentRound}/${totalRounds}`) + + AskUserQuestion({ + questions: batch.map(need => ({ + question: `[${need.source_angle}] ${need.question}\n\nContext: ${need.context}`, + header: need.source_angle, + multiSelect: false, + options: need.options.map((opt, index) => { + const isRecommended = need.recommended === index + return { + label: isRecommended ? `${opt} ★` : opt, + description: isRecommended ? `Use ${opt} approach (Recommended)` : `Use ${opt} approach` + } + }) + })) + }) + + // Store batch responses in clarificationContext before next round + } +} +``` + +**Output**: `clarificationContext` (in-memory) + +--- + +### Phase 3: Fix Planning + +**Planning Strategy Selection** (based on Phase 1 severity): + +**IMPORTANT**: Phase 3 is **planning only** - NO code execution. All execution happens in Phase 5 via lite-execute. + +**Low/Medium Severity** - Direct planning by Claude: +```javascript +// Step 1: Read schema +const schema = Bash(`cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json`) + +// Step 2: Generate fix-plan following schema (Claude directly, no agent) +// For Medium complexity: include rationale + verification (optional, but recommended) +const fixPlan = { + summary: "...", + root_cause: "...", + strategy: "immediate_patch|comprehensive_fix|refactor", + tasks: [...], // Each task: { id, title, scope, ..., depends_on, complexity } + estimated_time: "...", + recommended_execution: "Agent", + severity: severity, + risk_level: "...", + + // Medium complexity fields (optional for direct planning, auto-filled for Low) + ...(severity === "Medium" ? { + design_decisions: [ + { + decision: "Use immediate_patch strategy for minimal risk", + rationale: "Keeps changes localized and quick to review", + tradeoff: "Defers comprehensive refactoring" + } + ], + tasks_with_rationale: { + // Each task gets rationale if Medium + task_rationale_example: { + rationale: { + chosen_approach: "Direct fix approach", + alternatives_considered: ["Workaround", "Refactor"], + decision_factors: ["Minimal impact", "Quick turnaround"], + tradeoffs: "Doesn't address underlying issue" + }, + verification: { + unit_tests: ["test_bug_fix_basic"], + integration_tests: [], + manual_checks: ["Reproduce issue", "Verify fix"], + success_metrics: ["Issue resolved", "No regressions"] + } + } + } + } : {}), + + _metadata: { + timestamp: getUtc8ISOString(), + source: "direct-planning", + planning_mode: "direct", + complexity: severity === "Medium" ? "Medium" : "Low" + } +} + +// Step 3: Merge task rationale into tasks array +if (severity === "Medium") { + fixPlan.tasks = fixPlan.tasks.map(task => ({ + ...task, + rationale: fixPlan.tasks_with_rationale[task.id]?.rationale || { + chosen_approach: "Standard fix", + alternatives_considered: [], + decision_factors: ["Correctness", "Simplicity"], + tradeoffs: "None" + }, + verification: fixPlan.tasks_with_rationale[task.id]?.verification || { + unit_tests: [`test_${task.id}_basic`], + integration_tests: [], + manual_checks: ["Verify fix works"], + success_metrics: ["Test pass"] + } + })) + delete fixPlan.tasks_with_rationale // Clean up temp field +} + +// Step 4: Write fix-plan to session folder +Write(`${sessionFolder}/fix-plan.json`, JSON.stringify(fixPlan, null, 2)) + +// Step 5: MUST continue to Phase 4 (Confirmation) - DO NOT execute code here +``` + +**High/Critical Severity** - Invoke cli-lite-planning-agent: + +```javascript +Task( + subagent_type="cli-lite-planning-agent", + run_in_background=false, + description="Generate detailed fix plan", + prompt=` +Generate fix plan and write fix-plan.json. + +## Output Location + +**Session Folder**: ${sessionFolder} +**Output Files**: +- ${sessionFolder}/planning-context.md (evidence + understanding) +- ${sessionFolder}/fix-plan.json (fix plan) + +## Output Schema Reference +Execute: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json (get schema reference before generating plan) + +## Project Context (MANDATORY - Read Both Files) +1. Read: .workflow/project-tech.json (technology stack, architecture, key components) +2. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) + +**CRITICAL**: All fix tasks MUST comply with constraints in project-guidelines.json + +## Bug Description +${bug_description} + +## Multi-Angle Diagnosis Context + +${manifest.diagnoses.map(diag => `### Diagnosis: ${diag.angle} (${diag.file}) +Path: ${diag.path} + +Read this file for detailed ${diag.angle} analysis.`).join('\n\n')} + +Total diagnoses: ${manifest.diagnosis_count} +Angles covered: ${manifest.diagnoses.map(d => d.angle).join(', ')} + +Manifest: ${sessionFolder}/diagnoses-manifest.json + +## User Clarifications +${JSON.stringify(clarificationContext) || "None"} + +## Severity Level +${severity} + +## Requirements +Generate fix-plan.json with: +- summary: 2-3 sentence overview of the fix +- root_cause: Consolidated root cause from all diagnoses +- strategy: "immediate_patch" | "comprehensive_fix" | "refactor" +- tasks: 1-5 structured fix tasks (**IMPORTANT: group by fix area, NOT by file**) + - **Task Granularity Principle**: Each task = one complete fix unit + - title: action verb + target (e.g., "Fix token validation edge case") + - scope: module path (src/auth/) or feature name + - action: "Fix" | "Update" | "Refactor" | "Add" | "Delete" + - description + - modification_points: ALL files to modify for this fix (group related changes) + - implementation (2-5 steps covering all modification_points) + - acceptance: Quantified acceptance criteria + - depends_on: task IDs this task depends on (use sparingly) + + **High/Critical complexity fields per task** (REQUIRED): + - rationale: + - chosen_approach: Why this fix approach (not alternatives) + - alternatives_considered: Other approaches evaluated + - decision_factors: Key factors influencing choice + - tradeoffs: Known tradeoffs of this approach + - verification: + - unit_tests: Test names to add/verify + - integration_tests: Integration test names + - manual_checks: Manual verification steps + - success_metrics: Quantified success criteria + - risks: + - description: Risk description + - probability: Low|Medium|High + - impact: Low|Medium|High + - mitigation: How to mitigate + - fallback: Fallback if fix fails + - code_skeleton (optional): Key interfaces/functions to implement + - interfaces: [{name, definition, purpose}] + - key_functions: [{signature, purpose, returns}] + +**Top-level High/Critical fields** (REQUIRED): +- data_flow: How data flows through affected code + - diagram: "A → B → C" style flow + - stages: [{stage, input, output, component}] +- design_decisions: Global fix decisions + - [{decision, rationale, tradeoff}] + +- estimated_time, recommended_execution, severity, risk_level +- _metadata: + - timestamp, source, planning_mode + - complexity: "High" | "Critical" + - diagnosis_angles: ${JSON.stringify(manifest.diagnoses.map(d => d.angle))} + +## Task Grouping Rules +1. **Group by fix area**: All changes for one fix = one task (even if 2-3 files) +2. **Avoid file-per-task**: Do NOT create separate tasks for each file +3. **Substantial tasks**: Each task should represent 10-45 minutes of work +4. **True dependencies only**: Only use depends_on when Task B cannot start without Task A's output +5. **Prefer parallel**: Most tasks should be independent (no depends_on) + +## Execution +1. Read ALL diagnosis files for comprehensive context +2. Execute CLI planning using Gemini (Qwen fallback) with --rule planning-fix-strategy template +3. Synthesize findings from multiple diagnosis angles +4. Generate fix-plan with: + - For High/Critical: REQUIRED new fields (rationale, verification, risks, code_skeleton, data_flow, design_decisions) + - Each task MUST have rationale (why this fix), verification (how to verify success), and risks (potential issues) +5. Parse output and structure fix-plan +6. **Write**: \`${sessionFolder}/planning-context.md\` (evidence paths + understanding) +7. **Write**: \`${sessionFolder}/fix-plan.json\` +8. Return brief completion summary + +## Output Format for CLI +Include these sections in your fix-plan output: +- Summary, Root Cause, Strategy (existing) +- Data Flow: Diagram showing affected code paths +- Design Decisions: Key architectural choices in the fix +- Tasks: Each with rationale (Medium/High), verification (Medium/High), risks (High), code_skeleton (High) +` +) +``` + +**Output**: `${sessionFolder}/fix-plan.json` + +--- + +### Phase 4: Task Confirmation & Execution Selection + +**Step 4.1: Display Fix Plan** +```javascript +const fixPlan = JSON.parse(Read(`${sessionFolder}/fix-plan.json`)) + +console.log(` +## Fix Plan + +**Summary**: ${fixPlan.summary} +**Root Cause**: ${fixPlan.root_cause} +**Strategy**: ${fixPlan.strategy} + +**Tasks** (${fixPlan.tasks.length}): +${fixPlan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.scope})`).join('\n')} + +**Severity**: ${fixPlan.severity} +**Risk Level**: ${fixPlan.risk_level} +**Estimated Time**: ${fixPlan.estimated_time} +**Recommended**: ${fixPlan.recommended_execution} +`) +``` + +**Step 4.2: Collect Confirmation** +```javascript +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +let userSelection + +if (autoYes) { + // Auto mode: Use defaults + console.log(`[--yes] Auto-confirming fix plan:`) + console.log(` - Confirmation: Allow`) + console.log(` - Execution: Auto`) + console.log(` - Review: Skip`) + + userSelection = { + confirmation: "Allow", + execution_method: "Auto", + code_review_tool: "Skip" + } +} else { + // Interactive mode: Ask user + userSelection = AskUserQuestion({ + questions: [ + { + question: `Confirm fix plan? (${fixPlan.tasks.length} tasks, ${fixPlan.severity} severity)`, + header: "Confirm", + multiSelect: false, + options: [ + { label: "Allow", description: "Proceed as-is" }, + { label: "Modify", description: "Adjust before execution" }, + { label: "Cancel", description: "Abort workflow" } + ] + }, + { + question: "Execution method:", + header: "Execution", + multiSelect: false, + options: [ + { label: "Agent", description: "@code-developer agent" }, + { label: "Codex", description: "codex CLI tool" }, + { label: "Auto", description: `Auto: ${fixPlan.severity === 'Low' ? 'Agent' : 'Codex'}` } + ] + }, + { + question: "Code review after fix?", + header: "Review", + multiSelect: false, + options: [ + { label: "Gemini Review", description: "Gemini CLI" }, + { label: "Agent Review", description: "@code-reviewer" }, + { label: "Skip", description: "No review" } + ] + } + ] + }) +} +``` + +--- + +### Phase 5: Execute to Execution + +**CRITICAL**: lite-fix NEVER executes code directly. ALL execution MUST go through lite-execute. + +**Step 5.1: Build executionContext** + +```javascript +// Load manifest and all diagnosis files +const manifest = JSON.parse(Read(`${sessionFolder}/diagnoses-manifest.json`)) +const diagnoses = {} + +manifest.diagnoses.forEach(diag => { + if (file_exists(diag.path)) { + diagnoses[diag.angle] = JSON.parse(Read(diag.path)) + } +}) + +const fixPlan = JSON.parse(Read(`${sessionFolder}/fix-plan.json`)) + +executionContext = { + mode: "bugfix", + severity: fixPlan.severity, + planObject: { + ...fixPlan, + // Ensure complexity is set based on severity for new field consumption + complexity: fixPlan.complexity || (fixPlan.severity === 'Critical' ? 'High' : (fixPlan.severity === 'High' ? 'High' : 'Medium')) + }, + diagnosisContext: diagnoses, + diagnosisAngles: manifest.diagnoses.map(d => d.angle), + diagnosisManifest: manifest, + clarificationContext: clarificationContext || null, + executionMethod: userSelection.execution_method, + codeReviewTool: userSelection.code_review_tool, + originalUserInput: bug_description, + session: { + id: sessionId, + folder: sessionFolder, + artifacts: { + diagnoses: manifest.diagnoses.map(diag => ({ + angle: diag.angle, + path: diag.path + })), + diagnoses_manifest: `${sessionFolder}/diagnoses-manifest.json`, + fix_plan: `${sessionFolder}/fix-plan.json` + } + } +} +``` + +**Step 5.2: Execute** + +```javascript +// Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory --mode bugfix +// executionContext is passed in-memory to the execution phase +``` + +## Session Folder Structure + +``` +.workflow/.lite-fix/{bug-slug}-{YYYY-MM-DD}/ +├── diagnosis-{angle1}.json # Diagnosis angle 1 +├── diagnosis-{angle2}.json # Diagnosis angle 2 +├── diagnosis-{angle3}.json # Diagnosis angle 3 (if applicable) +├── diagnosis-{angle4}.json # Diagnosis angle 4 (if applicable) +├── diagnoses-manifest.json # Diagnosis index +├── planning-context.md # Evidence + understanding +└── fix-plan.json # Fix plan +``` + +**Example**: +``` +.workflow/.lite-fix/user-avatar-upload-fails-413-2025-11-25/ +├── diagnosis-error-handling.json +├── diagnosis-dataflow.json +├── diagnosis-validation.json +├── diagnoses-manifest.json +├── planning-context.md +└── fix-plan.json +``` + +## Error Handling + +| Error | Resolution | +|-------|------------| +| Diagnosis agent failure | Skip diagnosis, continue with bug description only | +| Planning agent failure | Fallback to direct planning by Claude | +| Clarification timeout | Use diagnosis findings as-is | +| Confirmation timeout | Save context, display resume instructions | +| Modify loop > 3 times | Suggest breaking task or using full planning workflow (workflow-plan/SKILL.md) | +| Root cause unclear | Extend diagnosis time or use broader angles | +| Too complex for lite-fix | Escalate to full planning workflow (workflow-plan/SKILL.md) | + +--- + +## Post-Phase Update + +After Phase 3 (Lite Fix) completes: +- **Output Created**: `executionContext` with fix-plan.json, diagnoses, clarifications, user selections +- **Session Artifacts**: All files in `.workflow/.lite-fix/{session-id}/` +- **Next Action**: Auto-continue to [Phase 4: Lite Execute](04-lite-execute.md) with --in-memory --mode bugfix +- **TodoWrite**: Mark "Lite Fix - Planning" as completed, start "Execution (Phase 4)" diff --git a/.claude/skills/workflow-lite-plan/phases/04-lite-execute.md b/.claude/skills/workflow-lite-plan/phases/04-lite-execute.md new file mode 100644 index 00000000..97d91948 --- /dev/null +++ b/.claude/skills/workflow-lite-plan/phases/04-lite-execute.md @@ -0,0 +1,738 @@ +# Phase 4: Lite Execute + +## Overview + +Flexible task execution phase supporting three input modes: in-memory plan (from planning phases), direct prompt description, or file content. Handles execution orchestration, progress tracking, and optional code review. + +**Core capabilities:** +- Multi-mode input (in-memory plan, prompt description, or file path) +- Execution orchestration (Agent or Codex) with full context +- Live progress tracking via TodoWrite at execution call level +- Optional code review with selected tool (Gemini, Agent, or custom) +- Context continuity across multiple executions +- Intelligent format detection (Enhanced Task JSON vs plain text) + +## Parameters + +- `--in-memory`: Use plan from memory (called by planning phases) +- ``: Task description string, or path to file (required) + +## Input Modes + +### Mode 1: In-Memory Plan + +**Trigger**: Called by planning phase after confirmation with `--in-memory` flag + +**Input Source**: `executionContext` global variable set by planning phase + +**Content**: Complete execution context (see Data Structures section) + +**Behavior**: +- Skip execution method selection (already set by planning phase) +- Directly proceed to execution with full context +- All planning artifacts available (exploration, clarifications, plan) + +### Mode 2: Prompt Description + +**Trigger**: User calls with task description string + +**Input**: Simple task description (e.g., "Add unit tests for auth module") + +**Behavior**: +- Store prompt as `originalUserInput` +- Create simple execution plan from prompt +- AskUserQuestion: Select execution method (Agent/Codex/Auto) +- AskUserQuestion: Select code review tool (Skip/Gemini/Agent/Other) +- Proceed to execution with `originalUserInput` included + +**User Interaction**: +```javascript +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +let userSelection + +if (autoYes) { + // Auto mode: Use defaults + console.log(`[--yes] Auto-confirming execution:`) + console.log(` - Execution method: Auto`) + console.log(` - Code review: Skip`) + + userSelection = { + execution_method: "Auto", + code_review_tool: "Skip" + } +} else { + // Interactive mode: Ask user + userSelection = AskUserQuestion({ + questions: [ + { + question: "Select execution method:", + header: "Execution", + multiSelect: false, + options: [ + { label: "Agent", description: "@code-developer agent" }, + { label: "Codex", description: "codex CLI tool" }, + { label: "Auto", description: "Auto-select based on complexity" } + ] + }, + { + question: "Enable code review after execution?", + header: "Code Review", + multiSelect: false, + options: [ + { label: "Skip", description: "No review" }, + { label: "Gemini Review", description: "Gemini CLI tool" }, + { label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" }, + { label: "Agent Review", description: "Current agent review" } + ] + } + ] + }) +} +``` + +### Mode 3: File Content + +**Trigger**: User calls with file path + +**Input**: Path to file containing task description or plan.json + +**Step 1: Read and Detect Format** + +```javascript +fileContent = Read(filePath) + +// Attempt JSON parsing +try { + jsonData = JSON.parse(fileContent) + + // Check if plan.json from lite-plan session + if (jsonData.summary && jsonData.approach && jsonData.tasks) { + planObject = jsonData + originalUserInput = jsonData.summary + isPlanJson = true + } else { + // Valid JSON but not plan.json - treat as plain text + originalUserInput = fileContent + isPlanJson = false + } +} catch { + // Not valid JSON - treat as plain text prompt + originalUserInput = fileContent + isPlanJson = false +} +``` + +**Step 2: Create Execution Plan** + +If `isPlanJson === true`: +- Use `planObject` directly +- User selects execution method and code review + +If `isPlanJson === false`: +- Treat file content as prompt (same behavior as Mode 2) +- Create simple execution plan from content + +**Step 3: User Interaction** + +- AskUserQuestion: Select execution method (Agent/Codex/Auto) +- AskUserQuestion: Select code review tool +- Proceed to execution with full context + +## Execution Process + +``` +Input Parsing: + └─ Decision (mode detection): + ├─ --in-memory flag → Mode 1: Load executionContext → Skip user selection + ├─ Ends with .md/.json/.txt → Mode 3: Read file → Detect format + │ ├─ Valid plan.json → Use planObject → User selects method + review + │ └─ Not plan.json → Treat as prompt → User selects method + review + └─ Other → Mode 2: Prompt description → User selects method + review + +Execution: + ├─ Step 1: Initialize result tracking (previousExecutionResults = []) + ├─ Step 2: Task grouping & batch creation + │ ├─ Extract explicit depends_on (no file/keyword inference) + │ ├─ Group: independent tasks → single parallel batch (maximize utilization) + │ ├─ Group: dependent tasks → sequential phases (respect dependencies) + │ └─ Create TodoWrite list for batches + ├─ Step 3: Launch execution + │ ├─ Phase 1: All independent tasks (single batch, concurrent) + │ └─ Phase 2+: Dependent tasks by dependency order + ├─ Step 4: Track progress (TodoWrite updates per batch) + └─ Step 5: Code review (if codeReviewTool ≠ "Skip") + +Output: + └─ Execution complete with results in previousExecutionResults[] +``` + +## Detailed Execution Steps + +### Step 1: Initialize Execution Tracking + +**Operations**: +- Initialize result tracking for multi-execution scenarios +- Set up `previousExecutionResults` array for context continuity +- **In-Memory Mode**: Echo execution strategy from planning phase for transparency + +```javascript +// Initialize result tracking +previousExecutionResults = [] + +// In-Memory Mode: Echo execution strategy (transparency before execution) +if (executionContext) { + console.log(` +Execution Strategy (from planning phase): + Method: ${executionContext.executionMethod} + Review: ${executionContext.codeReviewTool} + Tasks: ${executionContext.planObject.tasks.length} + Complexity: ${executionContext.planObject.complexity} +${executionContext.executorAssignments ? ` Assignments: ${JSON.stringify(executionContext.executorAssignments)}` : ''} + `) +} +``` + +### Step 2: Task Grouping & Batch Creation + +**Dependency Analysis & Grouping Algorithm**: +```javascript +// Use explicit depends_on from plan.json (no inference from file/keywords) +function extractDependencies(tasks) { + const taskIdToIndex = {} + tasks.forEach((t, i) => { taskIdToIndex[t.id] = i }) + + return tasks.map((task, i) => { + // Only use explicit depends_on from plan.json + const deps = (task.depends_on || []) + .map(depId => taskIdToIndex[depId]) + .filter(idx => idx !== undefined && idx < i) + return { ...task, taskIndex: i, dependencies: deps } + }) +} + +// Group into batches: maximize parallel execution +function createExecutionCalls(tasks, executionMethod) { + const tasksWithDeps = extractDependencies(tasks) + const processed = new Set() + const calls = [] + + // Phase 1: All independent tasks → single parallel batch (maximize utilization) + const independentTasks = tasksWithDeps.filter(t => t.dependencies.length === 0) + if (independentTasks.length > 0) { + independentTasks.forEach(t => processed.add(t.taskIndex)) + calls.push({ + method: executionMethod, + executionType: "parallel", + groupId: "P1", + taskSummary: independentTasks.map(t => t.title).join(' | '), + tasks: independentTasks + }) + } + + // Phase 2: Dependent tasks → sequential batches (respect dependencies) + let sequentialIndex = 1 + let remaining = tasksWithDeps.filter(t => !processed.has(t.taskIndex)) + + while (remaining.length > 0) { + // Find tasks whose dependencies are all satisfied + const ready = remaining.filter(t => + t.dependencies.every(d => processed.has(d)) + ) + + if (ready.length === 0) { + console.warn('Circular dependency detected, forcing remaining tasks') + ready.push(...remaining) + } + + // Group ready tasks (can run in parallel within this phase) + ready.forEach(t => processed.add(t.taskIndex)) + calls.push({ + method: executionMethod, + executionType: ready.length > 1 ? "parallel" : "sequential", + groupId: ready.length > 1 ? `P${calls.length + 1}` : `S${sequentialIndex++}`, + taskSummary: ready.map(t => t.title).join(ready.length > 1 ? ' | ' : ' → '), + tasks: ready + }) + + remaining = remaining.filter(t => !processed.has(t.taskIndex)) + } + + return calls +} + +executionCalls = createExecutionCalls(planObject.tasks, executionMethod).map(c => ({ ...c, id: `[${c.groupId}]` })) + +TodoWrite({ + todos: executionCalls.map(c => ({ + content: `${c.executionType === "parallel" ? "⚡" : "→"} ${c.id} (${c.tasks.length} tasks)`, + status: "pending", + activeForm: `Executing ${c.id}` + })) +}) +``` + +### Step 3: Launch Execution + +**Executor Resolution** (任务级 executor 优先于全局设置): +```javascript +// 获取任务的 executor（优先使用 executorAssignments，fallback 到全局 executionMethod） +function getTaskExecutor(task) { + const assignments = executionContext?.executorAssignments || {} + if (assignments[task.id]) { + return assignments[task.id].executor // 'gemini' | 'codex' | 'agent' + } + // Fallback: 全局 executionMethod 映射 + const method = executionContext?.executionMethod || 'Auto' + if (method === 'Agent') return 'agent' + if (method === 'Codex') return 'codex' + // Auto: 根据复杂度 + return planObject.complexity === 'Low' ? 'agent' : 'codex' +} + +// 按 executor 分组任务 +function groupTasksByExecutor(tasks) { + const groups = { gemini: [], codex: [], agent: [] } + tasks.forEach(task => { + const executor = getTaskExecutor(task) + groups[executor].push(task) + }) + return groups +} +``` + +**Execution Flow**: Parallel batches concurrently → Sequential batches in order +```javascript +const parallel = executionCalls.filter(c => c.executionType === "parallel") +const sequential = executionCalls.filter(c => c.executionType === "sequential") + +// Phase 1: Launch all parallel batches (single message with multiple tool calls) +if (parallel.length > 0) { + TodoWrite({ todos: executionCalls.map(c => ({ status: c.executionType === "parallel" ? "in_progress" : "pending" })) }) + parallelResults = await Promise.all(parallel.map(c => executeBatch(c))) + previousExecutionResults.push(...parallelResults) + TodoWrite({ todos: executionCalls.map(c => ({ status: parallel.includes(c) ? "completed" : "pending" })) }) +} + +// Phase 2: Execute sequential batches one by one +for (const call of sequential) { + TodoWrite({ todos: executionCalls.map(c => ({ status: c === call ? "in_progress" : "..." })) }) + result = await executeBatch(call) + previousExecutionResults.push(result) + TodoWrite({ todos: executionCalls.map(c => ({ status: "completed" or "pending" })) }) +} +``` + +### Unified Task Prompt Builder + +**Task Formatting Principle**: Each task is a self-contained checklist. The executor only needs to know what THIS task requires. Same template for Agent and CLI. + +```javascript +function buildExecutionPrompt(batch) { + // Task template (6 parts: Modification Points → Why → How → Reference → Risks → Done) + const formatTask = (t) => ` +## ${t.title} + +**Scope**: \`${t.scope}\` | **Action**: ${t.action} + +### Modification Points +${t.modification_points.map(p => `- **${p.file}** → \`${p.target}\`: ${p.change}`).join('\n')} + +${t.rationale ? ` +### Why this approach (Medium/High) +${t.rationale.chosen_approach} +${t.rationale.decision_factors?.length > 0 ? `\nKey factors: ${t.rationale.decision_factors.join(', ')}` : ''} +${t.rationale.tradeoffs ? `\nTradeoffs: ${t.rationale.tradeoffs}` : ''} +` : ''} + +### How to do it +${t.description} + +${t.implementation.map(step => `- ${step}`).join('\n')} + +${t.code_skeleton ? ` +### Code skeleton (High) +${t.code_skeleton.interfaces?.length > 0 ? `**Interfaces**: ${t.code_skeleton.interfaces.map(i => `\`${i.name}\` - ${i.purpose}`).join(', ')}` : ''} +${t.code_skeleton.key_functions?.length > 0 ? `\n**Functions**: ${t.code_skeleton.key_functions.map(f => `\`${f.signature}\` - ${f.purpose}`).join(', ')}` : ''} +${t.code_skeleton.classes?.length > 0 ? `\n**Classes**: ${t.code_skeleton.classes.map(c => `\`${c.name}\` - ${c.purpose}`).join(', ')}` : ''} +` : ''} + +### Reference +- Pattern: ${t.reference?.pattern || 'N/A'} +- Files: ${t.reference?.files?.join(', ') || 'N/A'} +${t.reference?.examples ? `- Notes: ${t.reference.examples}` : ''} + +${t.risks?.length > 0 ? ` +### Risk mitigations (High) +${t.risks.map(r => `- ${r.description} → **${r.mitigation}**`).join('\n')} +` : ''} + +### Done when +${t.acceptance.map(c => `- [ ] ${c}`).join('\n')} +${t.verification?.success_metrics?.length > 0 ? `\n**Success metrics**: ${t.verification.success_metrics.join(', ')}` : ''}` + + // Build prompt + const sections = [] + + if (originalUserInput) sections.push(`## Goal\n${originalUserInput}`) + + sections.push(`## Tasks\n${batch.tasks.map(formatTask).join('\n\n---\n')}`) + + // Context (reference only) + const context = [] + if (previousExecutionResults.length > 0) { + context.push(`### Previous Work\n${previousExecutionResults.map(r => `- ${r.tasksSummary}: ${r.status}`).join('\n')}`) + } + if (clarificationContext) { + context.push(`### Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `- ${q}: ${a}`).join('\n')}`) + } + if (executionContext?.planObject?.data_flow?.diagram) { + context.push(`### Data Flow\n${executionContext.planObject.data_flow.diagram}`) + } + if (executionContext?.session?.artifacts?.plan) { + context.push(`### Artifacts\nPlan: ${executionContext.session.artifacts.plan}`) + } + // Project guidelines (user-defined constraints) + context.push(`### Project Guidelines\n@.workflow/project-guidelines.json`) + if (context.length > 0) sections.push(`## Context\n${context.join('\n\n')}`) + + sections.push(`Complete each task according to its "Done when" checklist.`) + + return sections.join('\n\n') +} +``` + +**Option A: Agent Execution** + +When to use: +- `getTaskExecutor(task) === "agent"` +- or `executionMethod = "Agent"` (global fallback) +- or `executionMethod = "Auto" AND complexity = "Low"` (global fallback) + +```javascript +Task( + subagent_type="code-developer", + run_in_background=false, + description=batch.taskSummary, + prompt=buildExecutionPrompt(batch) +) +``` + +**Result Collection**: After completion, collect result following `executionResult` structure (see Data Structures section) + +**Option B: CLI Execution (Codex)** + +When to use: +- `getTaskExecutor(task) === "codex"` +- or `executionMethod = "Codex"` (global fallback) +- or `executionMethod = "Auto" AND complexity = "Medium/High"` (global fallback) + +```bash +ccw cli -p "${buildExecutionPrompt(batch)}" --tool codex --mode write +``` + +**Execution with fixed IDs** (predictable ID pattern): +```javascript +// Launch CLI in background, wait for task hook callback +// Generate fixed execution ID: ${sessionId}-${groupId} +const sessionId = executionContext?.session?.id || 'standalone' +const fixedExecutionId = `${sessionId}-${batch.groupId}` // e.g., "implement-auth-2025-12-13-P1" + +// Check if resuming from previous failed execution +const previousCliId = batch.resumeFromCliId || null + +// Build command with fixed ID (and optional resume for continuation) +const cli_command = previousCliId + ? `ccw cli -p "${buildExecutionPrompt(batch)}" --tool codex --mode write --id ${fixedExecutionId} --resume ${previousCliId}` + : `ccw cli -p "${buildExecutionPrompt(batch)}" --tool codex --mode write --id ${fixedExecutionId}` + +// Execute in background, stop output and wait for task hook callback +Bash( + command=cli_command, + run_in_background=true +) +// STOP HERE - CLI executes in background, task hook will notify on completion +``` + +**Resume on Failure** (with fixed ID): +```javascript +// If execution failed or timed out, offer resume option +if (bash_result.status === 'failed' || bash_result.status === 'timeout') { + console.log(` +Execution incomplete. Resume available: + Fixed ID: ${fixedExecutionId} + Lookup: ccw cli detail ${fixedExecutionId} + Resume: ccw cli -p "Continue tasks" --resume ${fixedExecutionId} --tool codex --mode write --id ${fixedExecutionId}-retry +`) + + // Store for potential retry in same session + batch.resumeFromCliId = fixedExecutionId +} +``` + +**Result Collection**: After completion, analyze output and collect result following `executionResult` structure (include `cliExecutionId` for resume capability) + +**Option C: CLI Execution (Gemini)** + +When to use: `getTaskExecutor(task) === "gemini"` (analysis tasks) + +```bash +# Use unified buildExecutionPrompt, switch tool and mode +ccw cli -p "${buildExecutionPrompt(batch)}" --tool gemini --mode analysis --id ${sessionId}-${batch.groupId} +``` + +### Step 4: Progress Tracking + +Progress tracked at batch level (not individual task level). Icons: ⚡ (parallel, concurrent), → (sequential, one-by-one) + +### Step 5: Code Review (Optional) + +**Skip Condition**: Only run if `codeReviewTool ≠ "Skip"` + +**Review Focus**: Verify implementation against plan acceptance criteria and verification requirements +- Read plan.json for task acceptance criteria and verification checklist +- Check each acceptance criterion is fulfilled +- Verify success metrics from verification field (Medium/High complexity) +- Run unit/integration tests specified in verification field +- Validate code quality and identify issues +- Ensure alignment with planned approach and risk mitigations + +**Operations**: +- Agent Review: Current agent performs direct review +- Gemini Review: Execute gemini CLI with review prompt +- Codex Review: Two options - (A) with prompt for complex reviews, (B) `--uncommitted` flag only for quick reviews +- Custom tool: Execute specified CLI tool (qwen, etc.) + +**Unified Review Template** (All tools use same standard): + +**Review Criteria**: +- **Acceptance Criteria**: Verify each criterion from plan.tasks[].acceptance +- **Verification Checklist** (Medium/High): Check unit_tests, integration_tests, success_metrics from plan.tasks[].verification +- **Code Quality**: Analyze quality, identify issues, suggest improvements +- **Plan Alignment**: Validate implementation matches planned approach and risk mitigations + +**Shared Prompt Template** (used by all CLI tools): +``` +PURPOSE: Code review for implemented changes against plan acceptance criteria and verification requirements +TASK: • Verify plan acceptance criteria fulfillment • Check verification requirements (unit tests, success metrics) • Analyze code quality • Identify issues • Suggest improvements • Validate plan adherence and risk mitigations +MODE: analysis +CONTEXT: @**/* @{plan.json} [@{exploration.json}] | Memory: Review lite-execute changes against plan requirements including verification checklist +EXPECTED: Quality assessment with: + - Acceptance criteria verification (all tasks) + - Verification checklist validation (Medium/High: unit_tests, integration_tests, success_metrics) + - Issue identification + - Recommendations + Explicitly check each acceptance criterion and verification item from plan.json tasks. +CONSTRAINTS: Focus on plan acceptance criteria, verification requirements, and plan adherence | analysis=READ-ONLY +``` + +**Tool-Specific Execution** (Apply shared prompt template above): + +```bash +# Method 1: Agent Review (current agent) +# - Read plan.json: ${executionContext.session.artifacts.plan} +# - Apply unified review criteria (see Shared Prompt Template) +# - Report findings directly + +# Method 2: Gemini Review (recommended) +ccw cli -p "[Shared Prompt Template with artifacts]" --tool gemini --mode analysis +# CONTEXT includes: @**/* @${plan.json} [@${exploration.json}] + +# Method 3: Qwen Review (alternative) +ccw cli -p "[Shared Prompt Template with artifacts]" --tool qwen --mode analysis +# Same prompt as Gemini, different execution engine + +# Method 4: Codex Review (git-aware) - Two mutually exclusive options: + +# Option A: With custom prompt (reviews uncommitted by default) +ccw cli -p "[Shared Prompt Template with artifacts]" --tool codex --mode review +# Use for complex reviews with specific focus areas + +# Option B: Target flag only (no prompt allowed) +ccw cli --tool codex --mode review --uncommitted +# Quick review of uncommitted changes without custom instructions + +# IMPORTANT: -p prompt and target flags (--uncommitted/--base/--commit) are MUTUALLY EXCLUSIVE +``` + +**Multi-Round Review with Fixed IDs**: +```javascript +// Generate fixed review ID +const reviewId = `${sessionId}-review` + +// First review pass with fixed ID +const reviewResult = Bash(`ccw cli -p "[Review prompt]" --tool gemini --mode analysis --id ${reviewId}`) + +// If issues found, continue review dialog with fixed ID chain +if (hasUnresolvedIssues(reviewResult)) { + // Resume with follow-up questions + Bash(`ccw cli -p "Clarify the security concerns you mentioned" --resume ${reviewId} --tool gemini --mode analysis --id ${reviewId}-followup`) +} +``` + +**Implementation Note**: Replace `[Shared Prompt Template with artifacts]` placeholder with actual template content, substituting: +- `@{plan.json}` → `@${executionContext.session.artifacts.plan}` +- `[@{exploration.json}]` → exploration files from artifacts (if exists) + +### Step 6: Update Development Index + +**Trigger**: After all executions complete (regardless of code review) + +**Skip Condition**: Skip if `.workflow/project-tech.json` does not exist + +**Operations**: +```javascript +const projectJsonPath = '.workflow/project-tech.json' +if (!fileExists(projectJsonPath)) return // Silent skip + +const projectJson = JSON.parse(Read(projectJsonPath)) + +// Initialize if needed +if (!projectJson.development_index) { + projectJson.development_index = { feature: [], enhancement: [], bugfix: [], refactor: [], docs: [] } +} + +// Detect category from keywords +function detectCategory(text) { + text = text.toLowerCase() + if (/\b(fix|bug|error|issue|crash)\b/.test(text)) return 'bugfix' + if (/\b(refactor|cleanup|reorganize)\b/.test(text)) return 'refactor' + if (/\b(doc|readme|comment)\b/.test(text)) return 'docs' + if (/\b(add|new|create|implement)\b/.test(text)) return 'feature' + return 'enhancement' +} + +// Detect sub_feature from task file paths +function detectSubFeature(tasks) { + const dirs = tasks.map(t => t.file?.split('/').slice(-2, -1)[0]).filter(Boolean) + const counts = dirs.reduce((a, d) => { a[d] = (a[d] || 0) + 1; return a }, {}) + return Object.entries(counts).sort((a, b) => b[1] - a[1])[0]?.[0] || 'general' +} + +const category = detectCategory(`${planObject.summary} ${planObject.approach}`) +const entry = { + title: planObject.summary.slice(0, 60), + sub_feature: detectSubFeature(planObject.tasks), + date: new Date().toISOString().split('T')[0], + description: planObject.approach.slice(0, 100), + status: previousExecutionResults.every(r => r.status === 'completed') ? 'completed' : 'partial', + session_id: executionContext?.session?.id || null +} + +projectJson.development_index[category].push(entry) +projectJson.statistics.last_updated = new Date().toISOString() +Write(projectJsonPath, JSON.stringify(projectJson, null, 2)) + +console.log(`Development index: [${category}] ${entry.title}`) +``` + +## Best Practices + +**Input Modes**: In-memory (planning phase), prompt (standalone), file (JSON/text) +**Task Grouping**: Based on explicit depends_on only; independent tasks run in single parallel batch +**Execution**: All independent tasks launch concurrently via single Claude message with multiple tool calls + +## Error Handling + +| Error | Cause | Resolution | +|-------|-------|------------| +| Missing executionContext | --in-memory without context | Error: "No execution context found. Only available when called by planning phase." | +| File not found | File path doesn't exist | Error: "File not found: {path}. Check file path." | +| Empty file | File exists but no content | Error: "File is empty: {path}. Provide task description." | +| Invalid Enhanced Task JSON | JSON missing required fields | Warning: "Missing required fields. Treating as plain text." | +| Malformed JSON | JSON parsing fails | Treat as plain text (expected for non-JSON files) | +| Execution failure | Agent/Codex crashes | Display error, use fixed ID `${sessionId}-${groupId}` for resume: `ccw cli -p "Continue" --resume --id -retry` | +| Execution timeout | CLI exceeded timeout | Use fixed ID for resume with extended timeout | +| Codex unavailable | Codex not installed | Show installation instructions, offer Agent execution | +| Fixed ID not found | Custom ID lookup failed | Check `ccw cli history`, verify date directories | + +## Data Structures + +### executionContext (Input - Mode 1) + +Passed from planning phase via global variable: + +```javascript +{ + planObject: { + summary: string, + approach: string, + tasks: [...], + estimated_time: string, + recommended_execution: string, + complexity: string + }, + explorationsContext: {...} | null, // Multi-angle explorations + explorationAngles: string[], // List of exploration angles + explorationManifest: {...} | null, // Exploration manifest + clarificationContext: {...} | null, + executionMethod: "Agent" | "Codex" | "Auto", // Global default + codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string, + originalUserInput: string, + + // Task-level executor assignments (priority over executionMethod) + executorAssignments: { + [taskId]: { executor: "gemini" | "codex" | "agent", reason: string } + }, + + // Session artifacts location (saved by planning phase) + session: { + id: string, // Session identifier: {taskSlug}-{shortTimestamp} + folder: string, // Session folder path: .workflow/.lite-plan/{session-id} + artifacts: { + explorations: [{angle, path}], // exploration-{angle}.json paths + explorations_manifest: string, // explorations-manifest.json path + plan: string // plan.json path (always present) + } + } +} +``` + +**Artifact Usage**: +- Artifact files contain detailed planning context +- Pass artifact paths to CLI tools and agents for enhanced context +- See execution options above for usage examples + +### executionResult (Output) + +Collected after each execution call completes: + +```javascript +{ + executionId: string, // e.g., "[Agent-1]", "[Codex-1]" + status: "completed" | "partial" | "failed", + tasksSummary: string, // Brief description of tasks handled + completionSummary: string, // What was completed + keyOutputs: string, // Files created/modified, key changes + notes: string, // Important context for next execution + fixedCliId: string | null // Fixed CLI execution ID (e.g., "implement-auth-2025-12-13-P1") +} +``` + +Appended to `previousExecutionResults` array for context continuity in multi-execution scenarios. + +## Post-Completion Expansion + +After completion, ask user whether to expand as issue (test/enhance/refactor/doc). Selected items create new issues accordingly. + +**Fixed ID Pattern**: `${sessionId}-${groupId}` enables predictable lookup without auto-generated timestamps. + +**Resume Usage**: If `status` is "partial" or "failed", use `fixedCliId` to resume: +```bash +# Lookup previous execution +ccw cli detail ${fixedCliId} + +# Resume with new fixed ID for retry +ccw cli -p "Continue from where we left off" --resume ${fixedCliId} --tool codex --mode write --id ${fixedCliId}-retry +``` + +--- + +## Post-Phase Update + +After Phase 4 (Lite Execute) completes: +- **Output Created**: Executed tasks, optional code review results, updated development index +- **Execution Results**: `previousExecutionResults[]` with status per batch +- **Next Action**: Workflow complete. Optionally expand to issue (test/enhance/refactor/doc) +- **TodoWrite**: Mark all execution batches as completed diff --git a/.claude/skills/workflow-plan/SKILL.md b/.claude/skills/workflow-plan/SKILL.md index 9176007c..f8575a1d 100644 --- a/.claude/skills/workflow-plan/SKILL.md +++ b/.claude/skills/workflow-plan/SKILL.md @@ -41,6 +41,25 @@ allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, When `--yes` or `-y`: Auto-continue all phases (skip confirmations), use recommended conflict resolutions. +## Usage + +``` +Skill(skill="workflow-plan", args="") +Skill(skill="workflow-plan", args="[-y|--yes] \"\"") + +# Flags +-y, --yes Skip all confirmations (auto mode) + +# Arguments + Task description text, structured GOAL/SCOPE/CONTEXT, or path to .md file + +# Examples +Skill(skill="workflow-plan", args="\"Build authentication system\"") # Simple task +Skill(skill="workflow-plan", args="\"Add JWT auth with email/password and refresh\"") # Detailed task +Skill(skill="workflow-plan", args="-y \"Implement user profile page\"") # Auto mode +Skill(skill="workflow-plan", args="\"requirements.md\"") # From file +``` + ## Execution Flow ``` diff --git a/.claude/skills/workflow-tdd-plan/SKILL.md b/.claude/skills/workflow-tdd-plan/SKILL.md new file mode 100644 index 00000000..082caa9e --- /dev/null +++ b/.claude/skills/workflow-tdd-plan/SKILL.md @@ -0,0 +1,747 @@ +--- +name: workflow-tdd-plan +description: TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, cycle tracking, and post-execution compliance verification. Triggers on "workflow:tdd-plan", "workflow:tdd-verify". +allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep, Skill +--- + +# Workflow TDD Plan + +6-phase TDD planning workflow that orchestrates session discovery, context gathering, test coverage analysis, conflict resolution, and TDD task generation to produce implementation plans with Red-Green-Refactor cycles. Includes post-execution TDD compliance verification. + +## Architecture Overview + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Workflow TDD Plan Orchestrator (SKILL.md) │ +│ → Pure coordinator: Execute phases, parse outputs, pass context │ +└───────────────┬──────────────────────────────────────────────────┘ + │ + ┌────────────┼────────────┬────────────┬────────────┐ + ↓ ↓ ↓ ↓ ↓ +┌────────┐ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Phase 1│ │ Phase 2│ │ Phase 3 │ │ Phase 4 │ │ Phase 5 │ +│Session │ │Context │ │Test Covg │ │Conflict │ │TDD Task │ +│Discover│ │Gather │ │Analysis │ │Resolve │ │Generate │ +│ (ext) │ │ (ext) │ │ (local) │ │(ext,cond)│ │ (local) │ +└────────┘ └────────┘ └──────────┘ └──────────┘ └──────────┘ + ↓ ↓ ↓ ↓ ↓ + sessionId contextPath testContext resolved IMPL_PLAN.md + conflict_risk artifacts task JSONs + +Phase 6: TDD Structure Validation (inline in SKILL.md) + +Post-execution verification: +┌──────────────┐ ┌───────────────────┐ +│ TDD Verify │────→│ Coverage Analysis │ +│ (local) │ │ (local) │ +└──────────────┘ └───────────────────┘ +phases/03-tdd- phases/04-tdd- +verify.md coverage-analysis.md +``` + +## Key Design Principles + +1. **Pure Orchestrator**: Execute phases in sequence, parse outputs, pass context between them +2. **Auto-Continue**: All phases run autonomously without user intervention between phases +3. **Task Attachment Model**: Sub-tasks are attached/collapsed dynamically in TodoWrite +4. **Progressive Phase Loading**: Phase docs are read on-demand, not all at once +5. **Conditional Execution**: Phase 4 only executes when conflict_risk >= medium +6. **TDD-First**: Every feature starts with a failing test (Red phase) + +**CLI Tool Selection**: CLI tool usage is determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution. + +**Task Attachment Model**: +- Skill execute **expands workflow** by attaching sub-tasks to current TodoWrite +- When executing a sub-command, its internal tasks are attached to the orchestrator's TodoWrite +- Orchestrator **executes these attached tasks** sequentially +- After completion, attached tasks are **collapsed** back to high-level phase summary +- This is **task expansion**, not external delegation + +**Auto-Continue Mechanism**: +- TodoList tracks current phase status and dynamically manages task attachment/collapse +- When each phase finishes executing, automatically execute next pending phase +- All phases run autonomously without user interaction +- **CONTINUOUS EXECUTION** - Do not stop until all phases complete + +## Auto Mode + +When `--yes` or `-y`: Auto-continue all phases (skip confirmations), use recommended conflict resolutions, skip TDD clarifications. + +## Usage + +``` +Skill(skill="workflow-tdd-plan", args="") +Skill(skill="workflow-tdd-plan", args="[-y|--yes] \"\"") + +# Flags +-y, --yes Skip all confirmations (auto mode) + +# Arguments + Task description text, TDD-structured format, or path to .md file + +# Examples +Skill(skill="workflow-tdd-plan", args="\"Build user authentication with tests\"") # Simple TDD task +Skill(skill="workflow-tdd-plan", args="\"Add JWT auth with email/password and token refresh\"") # Detailed task +Skill(skill="workflow-tdd-plan", args="-y \"Implement payment processing\"") # Auto mode +Skill(skill="workflow-tdd-plan", args="\"tdd-requirements.md\"") # From file +``` + +## TDD Compliance Requirements + +### The Iron Law + +``` +NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST +``` + +**Enforcement Method**: +- Phase 5: `implementation_approach` includes test-first steps (Red → Green → Refactor) +- Green phase: Includes test-fix-cycle configuration (max 3 iterations) +- Auto-revert: Triggered when max iterations reached without passing tests + +**Verification**: Phase 6 validates Red-Green-Refactor structure in all generated tasks + +### TDD Compliance Checkpoint + +| Checkpoint | Validation Phase | Evidence Required | +|------------|------------------|-------------------| +| Test-first structure | Phase 5 | `implementation_approach` has 3 steps | +| Red phase exists | Phase 6 | Step 1: `tdd_phase: "red"` | +| Green phase with test-fix | Phase 6 | Step 2: `tdd_phase: "green"` + test-fix-cycle | +| Refactor phase exists | Phase 6 | Step 3: `tdd_phase: "refactor"` | + +### Core TDD Principles + +**Red Flags - STOP and Reassess**: +- Code written before test +- Test passes immediately (no Red phase witnessed) +- Cannot explain why test should fail +- "Just this once" rationalization +- "Tests after achieve same goals" thinking + +**Why Order Matters**: +- Tests written after code pass immediately → proves nothing +- Test-first forces edge case discovery before implementation +- Tests-after verify what was built, not what's required + +## Core Rules + +1. **Start Immediately**: First action is TodoWrite initialization, second action is execute Phase 1 +2. **No Preliminary Analysis**: Do not read files before Phase 1 +3. **Parse Every Output**: Extract required data for next phase +4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically +5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern +6. **TDD Context**: All descriptions include "TDD:" prefix +7. **Task Attachment Model**: Skill execute **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion +8. **CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase + +## Execution Flow + +``` +Input Parsing: + └─ Convert user input to TDD-structured format (TDD:/GOAL/SCOPE/CONTEXT/TEST_FOCUS) + +Phase 1: Session Discovery + └─ Ref: workflow-plan/phases/01-session-discovery.md (external) + └─ Output: sessionId (WFS-xxx) + +Phase 2: Context Gathering + └─ Ref: workflow-plan/phases/02-context-gathering.md (external) + ├─ Tasks attached: Analyze structure → Identify integration → Generate package + └─ Output: contextPath + conflict_risk + +Phase 3: Test Coverage Analysis ← ATTACHED (3 tasks) + └─ Ref: phases/01-test-context-gather.md + ├─ Phase 3.1: Detect test framework + ├─ Phase 3.2: Analyze existing test coverage + └─ Phase 3.3: Identify coverage gaps + └─ Output: test-context-package.json ← COLLAPSED + +Phase 4: Conflict Resolution (conditional) + └─ Decision (conflict_risk check): + ├─ conflict_risk ≥ medium → Ref: workflow-plan/phases/03-conflict-resolution.md (external) + │ ├─ Tasks attached: Detect conflicts → Present to user → Apply strategies + │ └─ Output: Modified brainstorm artifacts ← COLLAPSED + └─ conflict_risk < medium → Skip to Phase 5 + +Phase 5: TDD Task Generation ← ATTACHED (3 tasks) + └─ Ref: phases/02-task-generate-tdd.md + ├─ Phase 5.1: Discovery - analyze TDD requirements + ├─ Phase 5.2: Planning - design Red-Green-Refactor cycles + └─ Phase 5.3: Output - generate IMPL tasks with internal TDD phases + └─ Output: IMPL-*.json, IMPL_PLAN.md ← COLLAPSED + +Phase 6: TDD Structure Validation (inline) + └─ Internal validation + summary returned + └─ Recommend: plan-verify (external) + +Return: + └─ Summary with recommended next steps +``` + +### Phase Reference Documents + +**Local phases** (read on-demand when phase executes): + +| Phase | Document | Purpose | +|-------|----------|---------| +| Phase 3 | [phases/01-test-context-gather.md](phases/01-test-context-gather.md) | Test coverage context gathering via test-context-search-agent | +| Phase 5 | [phases/02-task-generate-tdd.md](phases/02-task-generate-tdd.md) | TDD task JSON generation via action-planning-agent | + +**External phases** (from workflow-plan skill): + +| Phase | Document | Purpose | +|-------|----------|---------| +| Phase 1 | workflow-plan/phases/01-session-discovery.md | Session creation/discovery | +| Phase 2 | workflow-plan/phases/02-context-gathering.md | Project context collection | +| Phase 4 | workflow-plan/phases/03-conflict-resolution.md | Conflict detection and resolution (conditional) | + +**Post-execution verification**: + +| Phase | Document | Purpose | +|-------|----------|---------| +| TDD Verify | [phases/03-tdd-verify.md](phases/03-tdd-verify.md) | TDD compliance verification with quality gate | +| Coverage Analysis | [phases/04-tdd-coverage-analysis.md](phases/04-tdd-coverage-analysis.md) | Test coverage and cycle analysis (called by TDD Verify) | + +## 6-Phase Execution + +### Phase 1: Session Discovery + +**Step 1.1: Execute** - Session discovery and initialization + +Read and execute: `workflow-plan/phases/01-session-discovery.md` with `--type tdd --auto "TDD: [structured-description]"` + +**TDD Structured Format**: +``` +TDD: [Feature Name] +GOAL: [Objective] +SCOPE: [Included/excluded] +CONTEXT: [Background] +TEST_FOCUS: [Test scenarios] +``` + +**Parse**: Extract sessionId + +**TodoWrite**: Mark phase 1 completed, phase 2 in_progress + +**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2 + +--- + +### Phase 2: Context Gathering + +**Step 2.1: Execute** - Context gathering and analysis + +Read and execute: `workflow-plan/phases/02-context-gathering.md` with `--session [sessionId] "TDD: [structured-description]"` + +**Use Same Structured Description**: Pass the same structured format from Phase 1 + +**Input**: `sessionId` from Phase 1 + +**Parse Output**: +- Extract: context-package.json path (store as `contextPath`) +- Typical pattern: `.workflow/active/[sessionId]/.process/context-package.json` + +**Validation**: +- Context package path extracted +- File exists and is valid JSON + +**TodoWrite**: Mark phase 2 completed, phase 3 in_progress + +**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3 + +--- + +### Phase 3: Test Coverage Analysis + +**Step 3.1: Execute** - Test coverage analysis and framework detection + +Read and execute: `phases/01-test-context-gather.md` with `--session [sessionId]` + +**Purpose**: Analyze existing codebase for: +- Existing test patterns and conventions +- Current test coverage +- Related components and integration points +- Test framework detection + +**Parse**: Extract testContextPath (`.workflow/active/[sessionId]/.process/test-context-package.json`) + +**TodoWrite Update (Phase 3 - tasks attached)**: +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Phase 3: Test Coverage Analysis", "status": "in_progress", "activeForm": "Executing test coverage analysis"}, + {"content": " → Detect test framework and conventions", "status": "in_progress", "activeForm": "Detecting test framework"}, + {"content": " → Analyze existing test coverage", "status": "pending", "activeForm": "Analyzing test coverage"}, + {"content": " → Identify coverage gaps", "status": "pending", "activeForm": "Identifying coverage gaps"}, + {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"}, + {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"} +] +``` + +**Note**: Skill execute **attaches** test-context-gather's 3 tasks. Orchestrator **executes** these tasks. + +**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially + +**TodoWrite Update (Phase 3 completed - tasks collapsed)**: +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"}, + {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"}, + {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"} +] +``` + +**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4/5 + +--- + +### Phase 4: Conflict Resolution (Optional) + +**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high" + +**Step 4.1: Execute** - Conflict detection and resolution + +Read and execute: `workflow-plan/phases/03-conflict-resolution.md` with `--session [sessionId] --context [contextPath]` + +**Input**: +- sessionId from Phase 1 +- contextPath from Phase 2 +- conflict_risk from context-package.json + +**Parse Output**: +- Extract: Execution status (success/skipped/failed) +- Verify: conflict-resolution.json file path (if executed) + +**Skip Behavior**: +- If conflict_risk is "none" or "low", skip directly to Phase 5 +- Display: "No significant conflicts detected, proceeding to TDD task generation" + +**TodoWrite Update (Phase 4 - tasks attached, if conflict_risk >= medium)**: +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"}, + {"content": "Phase 4: Conflict Resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"}, + {"content": " → Detect conflicts with CLI analysis", "status": "in_progress", "activeForm": "Detecting conflicts"}, + {"content": " → Log and analyze detected conflicts", "status": "pending", "activeForm": "Analyzing conflicts"}, + {"content": " → Apply resolution strategies", "status": "pending", "activeForm": "Applying resolution strategies"}, + {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"}, + {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"} +] +``` + +**TodoWrite Update (Phase 4 completed - tasks collapsed)**: +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"}, + {"content": "Phase 4: Conflict Resolution", "status": "completed", "activeForm": "Executing conflict resolution"}, + {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"}, + {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"} +] +``` + +**After Phase 4**: Return to user showing conflict resolution results, then auto-continue to Phase 5 + +**Memory State Check**: +- Evaluate current context window usage and memory state +- If memory usage is high (>110K tokens or approaching context limits): + + **Step 4.5: Execute** - Memory compaction (external skill: compact) + + - This optimizes memory before proceeding to Phase 5 +- Memory compaction is particularly important after analysis phase which may generate extensive documentation + +--- + +### Phase 5: TDD Task Generation + +**Step 5.1: Execute** - TDD task generation via action-planning-agent with Phase 0 user configuration + +Read and execute: `phases/02-task-generate-tdd.md` with `--session [sessionId]` + +**Note**: Phase 0 now includes: +- Supplementary materials collection (file paths or inline content) +- Execution method preference (Agent/Hybrid/CLI) +- CLI tool preference (Codex/Gemini/Qwen/Auto) +- These preferences are passed to agent for task generation + +**Parse**: Extract feature count, task count, CLI execution IDs assigned + +**Validate**: +- IMPL_PLAN.md exists (unified plan with TDD Implementation Tasks section) +- IMPL-*.json files exist (one per feature, or container + subtasks for complex features) +- TODO_LIST.md exists with internal TDD phase indicators +- Each IMPL task includes: + - `meta.tdd_workflow: true` + - `meta.cli_execution_id: {session_id}-{task_id}` + - `meta.cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }` + - `flow_control.implementation_approach` with exactly 3 steps (red/green/refactor) + - Green phase includes test-fix-cycle configuration + - `context.focus_paths`: absolute or clear relative paths + - `flow_control.pre_analysis`: includes exploration integration_points analysis +- IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter +- Task count <=18 (compliance with hard limit) + +**Red Flag Detection** (Non-Blocking Warnings): +- Task count >18: `Warning: Task count exceeds hard limit - request re-scope` +- Missing cli_execution_id: `Warning: Task lacks CLI execution ID for resume support` +- Missing test-fix-cycle: `Warning: Green phase lacks auto-revert configuration` +- Generic task names: `Warning: Vague task names suggest unclear TDD cycles` +- Missing focus_paths: `Warning: Task lacks clear file scope for implementation` + +**Action**: Log warnings to `.workflow/active/[sessionId]/.process/tdd-warnings.log` (non-blocking) + +**TodoWrite Update (Phase 5 - tasks attached)**: +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"}, + {"content": "Phase 5: TDD Task Generation", "status": "in_progress", "activeForm": "Executing TDD task generation"}, + {"content": " → Discovery - analyze TDD requirements", "status": "in_progress", "activeForm": "Analyzing TDD requirements"}, + {"content": " → Planning - design Red-Green-Refactor cycles", "status": "pending", "activeForm": "Designing TDD cycles"}, + {"content": " → Output - generate IMPL tasks with internal TDD phases", "status": "pending", "activeForm": "Generating TDD tasks"}, + {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"} +] +``` + +**TodoWrite Update (Phase 5 completed - tasks collapsed)**: +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"}, + {"content": "Phase 5: TDD Task Generation", "status": "completed", "activeForm": "Executing TDD task generation"}, + {"content": "Phase 6: TDD Structure Validation", "status": "in_progress", "activeForm": "Validating TDD structure"} +] +``` + +### Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED) + +**Internal validation first, then recommend external verification** + +**Internal Validation**: +1. Each task contains complete TDD workflow (Red-Green-Refactor internally) +2. Task structure validation: + - `meta.tdd_workflow: true` in all IMPL tasks + - `meta.cli_execution_id` present (format: {session_id}-{task_id}) + - `meta.cli_execution` strategy assigned (new/resume/fork/merge_fork) + - `flow_control.implementation_approach` has exactly 3 steps + - Each step has correct `tdd_phase`: "red", "green", "refactor" + - `context.focus_paths` are absolute or clear relative paths + - `flow_control.pre_analysis` includes exploration integration analysis +3. Dependency validation: + - Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed + - Complex features: IMPL-N.M depends_on ["IMPL-N.(M-1)"] for subtasks + - CLI execution strategies correctly assigned based on dependency graph +4. Agent assignment: All IMPL tasks use @code-developer +5. Test-fix cycle: Green phase step includes test-fix-cycle logic with max_iterations +6. Task count: Total tasks <=18 (simple + subtasks hard limit) +7. User configuration: + - Execution method choice reflected in task structure + - CLI tool preference documented in implementation guidance (if CLI selected) + +**Red Flag Checklist** (from TDD best practices): +- [ ] No tasks skip Red phase (`tdd_phase: "red"` exists in step 1) +- [ ] Test files referenced in Red phase (explicit paths, not placeholders) +- [ ] Green phase has test-fix-cycle with `max_iterations` configured +- [ ] Refactor phase has clear completion criteria + +**Non-Compliance Warning Format**: +``` +Warning TDD Red Flag: [issue description] + Task: [IMPL-N] + Recommendation: [action to fix] +``` + +**Evidence Gathering** (Before Completion Claims): + +```bash +# Verify session artifacts exist +ls -la .workflow/active/[sessionId]/{IMPL_PLAN.md,TODO_LIST.md} +ls -la .workflow/active/[sessionId]/.task/IMPL-*.json + +# Count generated artifacts +echo "IMPL tasks: $(ls .workflow/active/[sessionId]/.task/IMPL-*.json 2>/dev/null | wc -l)" + +# Sample task structure verification (first task) +jq '{id, tdd: .meta.tdd_workflow, cli_id: .meta.cli_execution_id, phases: [.flow_control.implementation_approach[].tdd_phase]}' \ + "$(ls .workflow/active/[sessionId]/.task/IMPL-*.json | head -1)" +``` + +**Evidence Required Before Summary**: +| Evidence Type | Verification Method | Pass Criteria | +|---------------|---------------------|---------------| +| File existence | `ls -la` artifacts | All files present | +| Task count | Count IMPL-*.json | Count matches claims (<=18) | +| TDD structure | jq sample extraction | Shows red/green/refactor + cli_execution_id | +| CLI execution IDs | jq extraction | All tasks have cli_execution_id assigned | +| Warning log | Check tdd-warnings.log | Logged (may be empty) | + +**Return Summary**: +``` +TDD Planning complete for session: [sessionId] + +Features analyzed: [N] +Total tasks: [M] (1 task per simple feature + subtasks for complex features) + +Task breakdown: +- Simple features: [K] tasks (IMPL-1 to IMPL-K) +- Complex features: [L] features with [P] subtasks +- Total task count: [M] (within 18-task hard limit) + +Structure: +- IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor) +- IMPL-2: {Feature 2 Name} (Internal: Red → Green → Refactor) +- IMPL-3: {Complex Feature} (Container) + - IMPL-3.1: {Sub-feature A} (Internal: Red → Green → Refactor) + - IMPL-3.2: {Sub-feature B} (Internal: Red → Green → Refactor) +[...] + +Plans generated: +- Unified Implementation Plan: .workflow/active/[sessionId]/IMPL_PLAN.md + (includes TDD Implementation Tasks section with workflow_type: "tdd") +- Task List: .workflow/active/[sessionId]/TODO_LIST.md + (with internal TDD phase indicators and CLI execution strategies) +- Task JSONs: .workflow/active/[sessionId]/.task/IMPL-*.json + (with cli_execution_id and execution strategies for resume support) + +TDD Configuration: +- Each task contains complete Red-Green-Refactor cycle +- Green phase includes test-fix cycle (max 3 iterations) +- Auto-revert on max iterations reached +- CLI execution strategies: new/resume/fork/merge_fork based on dependency graph + +User Configuration Applied: +- Execution Method: [agent|hybrid|cli] +- CLI Tool Preference: [codex|gemini|qwen|auto] +- Supplementary Materials: [included|none] +- Task generation follows cli-tools-usage.md guidelines + +ACTION REQUIRED: Before execution, ensure you understand WHY each Red phase test is expected to fail. + This is crucial for valid TDD - if you don't know why the test fails, you can't verify it tests the right thing. + +Recommended Next Steps: +1. plan-verify (external) --session [sessionId] # Verify TDD plan quality and dependencies +2. workflow:execute (external) --session [sessionId] # Start TDD execution with CLI strategies +3. phases/03-tdd-verify.md [sessionId] # Post-execution TDD compliance check + +Quality Gate: Consider running plan-verify to validate TDD task structure, dependencies, and CLI execution strategies +``` + +## Input Processing + +Convert user input to TDD-structured format: + +**Simple text** → Add TDD context +**Detailed text** → Extract components with TEST_FOCUS +**File/Issue** → Read and structure with TDD + +## Data Flow + +``` +User Input (task description) + ↓ +[Convert to TDD Structured Format] + ↓ TDD Structured Description: + ↓ TDD: [Feature Name] + ↓ GOAL: [objective] + ↓ SCOPE: [boundaries] + ↓ CONTEXT: [background] + ↓ TEST_FOCUS: [test scenarios] + ↓ +Phase 1: session:start --type tdd --auto "TDD: structured-description" + ↓ Output: sessionId + ↓ +Phase 2: context-gather --session sessionId "TDD: structured-description" + ↓ Output: contextPath + conflict_risk + ↓ +Phase 3: test-context-gather --session sessionId + ↓ Output: testContextPath (test-context-package.json) + ↓ +Phase 4: conflict-resolution [AUTO-TRIGGERED if conflict_risk >= medium] + ↓ Output: Modified brainstorm artifacts + ↓ Skip if conflict_risk is none/low → proceed directly to Phase 5 + ↓ +Phase 5: task-generate-tdd --session sessionId + ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md + ↓ +Phase 6: Internal validation + summary + ↓ +Return summary to user +``` + +## TodoWrite Pattern + +**Core Concept**: Dynamic task attachment and collapse for TDD workflow with test coverage analysis and Red-Green-Refactor cycle generation. + +### Key Principles + +1. **Task Attachment** (when Skill executed): + - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite + - First attached task marked as `in_progress`, others as `pending` + - Orchestrator **executes** these attached tasks sequentially + +2. **Task Collapse** (after sub-tasks complete): + - Remove detailed sub-tasks from TodoWrite + - **Collapse** to high-level phase summary + - Maintains clean orchestrator-level view + +3. **Continuous Execution**: + - After collapse, automatically proceed to next pending phase + - No user intervention required between phases + - TodoWrite dynamically reflects current execution state + +**Lifecycle Summary**: Initial pending tasks → Phase executed (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins (conditional Phase 4 if conflict_risk >= medium) → Repeat until all phases complete. + +### TDD-Specific Features + +- **Phase 3**: Test coverage analysis detects existing patterns and gaps +- **Phase 5**: Generated IMPL tasks contain internal Red-Green-Refactor cycles +- **Conditional Phase 4**: Conflict resolution only if conflict_risk >= medium + +**Note**: See individual Phase descriptions (Phase 3, 4, 5) for detailed TodoWrite Update examples with full JSON structures. + +## Execution Flow Diagram + +``` +TDD Workflow Orchestrator +│ +├─ Phase 1: Session Discovery +│ └─ workflow-plan/phases/01-session-discovery.md --auto +│ └─ Returns: sessionId +│ +├─ Phase 2: Context Gathering +│ └─ workflow-plan/phases/02-context-gathering.md +│ └─ Returns: context-package.json path +│ +├─ Phase 3: Test Coverage Analysis ← ATTACHED (3 tasks) +│ └─ phases/01-test-context-gather.md +│ ├─ Phase 3.1: Detect test framework +│ ├─ Phase 3.2: Analyze existing test coverage +│ └─ Phase 3.3: Identify coverage gaps +│ └─ Returns: test-context-package.json ← COLLAPSED +│ +├─ Phase 4: Conflict Resolution (conditional) +│ IF conflict_risk >= medium: +│ └─ workflow-plan/phases/03-conflict-resolution.md ← ATTACHED (3 tasks) +│ ├─ Phase 4.1: Detect conflicts with CLI +│ ├─ Phase 4.2: Log and analyze detected conflicts +│ └─ Phase 4.3: Apply resolution strategies +│ └─ Returns: conflict-resolution.json ← COLLAPSED +│ ELSE: +│ └─ Skip to Phase 5 +│ +├─ Phase 5: TDD Task Generation ← ATTACHED (3 tasks) +│ └─ phases/02-task-generate-tdd.md +│ ├─ Phase 5.1: Discovery - analyze TDD requirements +│ ├─ Phase 5.2: Planning - design Red-Green-Refactor cycles +│ └─ Phase 5.3: Output - generate IMPL tasks with internal TDD phases +│ └─ Returns: IMPL-*.json, IMPL_PLAN.md ← COLLAPSED +│ (Each IMPL task contains internal Red-Green-Refactor cycle) +│ +└─ Phase 6: TDD Structure Validation + └─ Internal validation + summary returned + └─ Recommend: plan-verify (external) + +Key Points: +• ← ATTACHED: Sub-tasks attached to orchestrator TodoWrite +• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary +• TDD-specific: Each generated IMPL task contains complete Red-Green-Refactor cycle +``` + +## Error Handling + +- **Parsing failure**: Retry once, then report +- **Validation failure**: Report missing/invalid data +- **Command failure**: Keep phase in_progress, report error +- **TDD validation failure**: Report incomplete chains or wrong dependencies + +### TDD Warning Patterns + +| Pattern | Warning Message | Recommended Action | +|---------|----------------|-------------------| +| Task count >10 | High task count detected | Consider splitting into multiple sessions | +| Missing test-fix-cycle | Green phase lacks auto-revert | Add `max_iterations: 3` to task config | +| Red phase missing test path | Test file path not specified | Add explicit test file paths | +| Generic task names | Vague names like "Add feature" | Use specific behavior descriptions | +| No refactor criteria | Refactor phase lacks completion criteria | Define clear refactor scope | + +### Non-Blocking Warning Policy + +**All warnings are advisory** - they do not halt execution: +1. Warnings logged to `.process/tdd-warnings.log` +2. Summary displayed in Phase 6 output +3. User decides whether to address before execution + +### Error Handling Quick Reference + +| Error Type | Detection | Recovery Action | +|------------|-----------|-----------------| +| Parsing failure | Empty/malformed output | Retry once, then report | +| Missing context-package | File read error | Re-run context-gather (workflow-plan/phases/02-context-gathering.md) | +| Invalid task JSON | jq parse error | Report malformed file path | +| Task count exceeds 18 | Count validation >=19 | Request re-scope, split into multiple sessions | +| Missing cli_execution_id | All tasks lack ID | Regenerate tasks with phase 0 user config | +| Test-context missing | File not found | Re-run phases/01-test-context-gather.md | +| Phase timeout | No response | Retry phase, check CLI connectivity | +| CLI tool not available | Tool not in cli-tools.json | Fall back to alternative preferred tool | + +## Post-Execution: TDD Verification + +After TDD tasks have been executed (via workflow:execute), run TDD compliance verification: + +Read and execute: `phases/03-tdd-verify.md` with `--session [sessionId]` + +This generates a comprehensive TDD_COMPLIANCE_REPORT.md with quality gate recommendation. + +## Related Skills + +**Prerequisite**: +- None - TDD planning is self-contained (can optionally run brainstorm before) + +**Called by This Skill** (6 phases): +- workflow-plan/phases/01-session-discovery.md - Phase 1: Create or discover TDD workflow session +- workflow-plan/phases/02-context-gathering.md - Phase 2: Gather project context and analyze codebase +- phases/01-test-context-gather.md - Phase 3: Analyze existing test patterns and coverage +- workflow-plan/phases/03-conflict-resolution.md - Phase 4: Detect and resolve conflicts (conditional) +- compact (external skill) - Phase 4.5: Memory optimization (if context approaching limits) +- phases/02-task-generate-tdd.md - Phase 5: Generate TDD tasks + +**Follow-up**: +- plan-verify (external) - Recommended: Verify TDD plan quality and structure before execution +- workflow:status (external) - Review TDD task breakdown +- workflow:execute (external) - Begin TDD implementation +- phases/03-tdd-verify.md - Post-execution: Verify TDD compliance and generate quality report + +## Next Steps Decision Table + +| Situation | Recommended Action | Purpose | +|-----------|-------------------|---------| +| First time planning | Run plan-verify (external) | Validate task structure before execution | +| Warnings in tdd-warnings.log | Review log, refine tasks | Address Red Flags before proceeding | +| High task count warning | Consider new session | Split into focused sub-sessions | +| Ready to implement | Run workflow:execute (external) | Begin TDD Red-Green-Refactor cycles | +| After implementation | Run phases/03-tdd-verify.md | Generate TDD compliance report | +| Need to review tasks | Run workflow:status (external) | Inspect current task breakdown | + +### TDD Workflow State Transitions + +``` +workflow-tdd-plan (this skill) + ↓ +[Planning Complete] ──→ plan-verify (external, recommended) + ↓ +[Verified/Ready] ─────→ workflow:execute (external) + ↓ +[Implementation] ─────→ phases/03-tdd-verify.md (post-execution) + ↓ +[Quality Report] ─────→ Done or iterate +``` diff --git a/.claude/skills/workflow-tdd-plan/phases/01-test-context-gather.md b/.claude/skills/workflow-tdd-plan/phases/01-test-context-gather.md new file mode 100644 index 00000000..d07a49b8 --- /dev/null +++ b/.claude/skills/workflow-tdd-plan/phases/01-test-context-gather.md @@ -0,0 +1,213 @@ +# Phase 1: 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 | Yes | 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 + +## 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 +- SKILL.md (Phase 3: Test Coverage Analysis) + +### Calls +- `test-context-search-agent` - Autonomous test coverage analysis + +## 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 + +--- + +## Post-Phase Update + +After Phase 1 (Test Context Gather) completes: +- **Output Created**: `test-context-package.json` in `.workflow/active/{session}/.process/` +- **Data Available**: Test coverage stats, framework info, missing tests list +- **Next Action**: Continue to Phase 4 (Conflict Resolution, if conflict_risk >= medium) or Phase 5 (TDD Task Generation) +- **TodoWrite**: Collapse Phase 3 sub-tasks to "Phase 3: Test Coverage Analysis: completed" diff --git a/.claude/skills/workflow-tdd-plan/phases/02-task-generate-tdd.md b/.claude/skills/workflow-tdd-plan/phases/02-task-generate-tdd.md new file mode 100644 index 00000000..459ff754 --- /dev/null +++ b/.claude/skills/workflow-tdd-plan/phases/02-task-generate-tdd.md @@ -0,0 +1,746 @@ +## Auto Mode + +When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor). + +# Phase 2: TDD Task Generation + +## 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 +│ └── ... +├── 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_approach 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**: 6-field structure with TDD-specific metadata + - \`id, title, status, context_package_path, meta, context, flow_control\` + - \`meta.tdd_workflow\`: true (REQUIRED) + - \`meta.max_iterations\`: 3 (Green phase test-fix cycle limit) + - \`meta.cli_execution_id\`: Unique CLI execution ID (format: \`{session_id}-{task_id}\`) + - \`meta.cli_execution\`: Strategy object (new|resume|fork|merge_fork) + - \`context.tdd_cycles\`: Array with quantified test cases and coverage + - \`context.focus_paths\`: Absolute or clear relative paths (enhanced with exploration critical_files) + - \`flow_control.implementation_approach\`: 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 + - \`flow_control.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**: \`~/.claude/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: +- **meta.cli_execution_id**: Unique ID for CLI execution (format: \`{session_id}-{task_id}\`) +- **meta.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): +- 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 meta.cli_execution_id and meta.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 +- Quantification requirements enforced (explicit counts, measurable acceptance, exact targets) + +## 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 +` +) +``` + +### 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` + - `meta.cli_execution_id: "{session_id}-{task_id}"` + - `meta.cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }` +- Context: `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 + } + ] + ``` +- Context: `focus_paths` use absolute or clear relative paths +- Flow control: Exactly 3 steps with `tdd_phase` field ("red", "green", "refactor") +- Flow control: `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}/ +├── 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 x 5) +- **New approach**: 5 features = 5 task JSON files (IMPL-N x 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 `flow_control.implementation_approach` +- 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 +- `flow_control.implementation_approach` 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 + +**Called By**: SKILL.md (Phase 5: TDD Task Generation) +**Invokes**: `action-planning-agent` for autonomous task generation +**Followed By**: Phase 6 (TDD Structure Validation in SKILL.md), then workflow:execute (external) + +**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 phases/01-test-context-gather.md) 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 + +--- + +## Post-Phase Update + +After Phase 2 (TDD Task Generation) completes: +- **Output Created**: IMPL_PLAN.md, TODO_LIST.md, IMPL-*.json task files in `.task/` directory +- **TDD Structure**: Each task contains complete Red-Green-Refactor cycle internally +- **CLI Execution IDs**: All tasks assigned unique cli_execution_id for resume support +- **Next Action**: Phase 6 (TDD Structure Validation) in SKILL.md +- **TodoWrite**: Collapse Phase 5 sub-tasks to "Phase 5: TDD Task Generation: completed" diff --git a/.claude/skills/workflow-tdd-plan/phases/03-tdd-verify.md b/.claude/skills/workflow-tdd-plan/phases/03-tdd-verify.md new file mode 100644 index 00000000..e27c9a93 --- /dev/null +++ b/.claude/skills/workflow-tdd-plan/phases/03-tdd-verify.md @@ -0,0 +1,575 @@ +# Phase 3: TDD Verify + +## Goal + +Verify TDD workflow execution quality by validating Red-Green-Refactor cycle compliance, test coverage completeness, and task chain structure integrity. This phase orchestrates multiple analysis steps and generates a comprehensive compliance report with quality gate recommendation. + +**Output**: A structured Markdown report saved to `.workflow/active/WFS-{session}/TDD_COMPLIANCE_REPORT.md` containing: +- Executive summary with compliance score and quality gate recommendation +- Task chain validation (TEST → IMPL → REFACTOR structure) +- Test coverage metrics (line, branch, function) +- Red-Green-Refactor cycle verification +- Best practices adherence assessment +- Actionable improvement recommendations + +## Operating Constraints + +**ORCHESTRATOR MODE**: +- This phase coordinates coverage analysis (`phases/04-tdd-coverage-analysis.md`) and internal validation +- MAY write output files: TDD_COMPLIANCE_REPORT.md (primary report), .process/*.json (intermediate artifacts) +- MUST NOT modify source task files or implementation code +- MUST NOT create or delete tasks in the workflow + +**Quality Gate Authority**: The compliance report provides a binding recommendation (BLOCK_MERGE / REQUIRE_FIXES / PROCEED_WITH_CAVEATS / APPROVED) based on objective compliance criteria. + +## Core Responsibilities +- Verify TDD task chain structure (TEST → IMPL → REFACTOR) +- Analyze test coverage metrics +- Validate TDD cycle execution quality +- Generate compliance report with quality gate recommendation + +## Execution Process + +``` +Input Parsing: + └─ Decision (session argument): + ├─ --session provided → Use provided session + └─ No session → Auto-detect active session + +Phase 1: Session Discovery & Validation + ├─ Detect or validate session directory + ├─ Check required artifacts exist (.task/*.json, .summaries/*) + └─ ERROR if invalid or incomplete + +Phase 2: Task Chain Structure Validation + ├─ Load all task JSONs from .task/ + ├─ Validate TDD structure: TEST-N.M → IMPL-N.M → REFACTOR-N.M + ├─ Verify dependencies (depends_on) + ├─ Validate meta fields (tdd_phase, agent) + └─ Extract chain validation data + +Phase 3: Coverage & Cycle Analysis + ├─ Read and execute: phases/04-tdd-coverage-analysis.md + ├─ Parse: test-results.json, coverage-report.json, tdd-cycle-report.md + └─ Extract coverage metrics and TDD cycle verification + +Phase 4: Compliance Report Generation + ├─ Aggregate findings from Phases 1-3 + ├─ Calculate compliance score (0-100) + ├─ Determine quality gate recommendation + ├─ Generate TDD_COMPLIANCE_REPORT.md + └─ Display summary to user +``` + +## 4-Phase Execution + +### Phase 1: Session Discovery & Validation + +**Step 1.1: Detect Session** +```bash +IF --session parameter provided: + session_id = provided session +ELSE: + # Auto-detect active session + active_sessions = bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null) + IF active_sessions is empty: + ERROR: "No active workflow session found. Use --session " + EXIT + ELSE IF active_sessions has multiple entries: + # Use most recently modified session + session_id = bash(ls -td .workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename) + ELSE: + session_id = basename(active_sessions[0]) + +# Derive paths +session_dir = .workflow/active/WFS-{session_id} +task_dir = session_dir/.task +summaries_dir = session_dir/.summaries +process_dir = session_dir/.process +``` + +**Step 1.2: Validate Required Artifacts** +```bash +# Check task files exist +task_files = Glob(task_dir/*.json) +IF task_files.count == 0: + ERROR: "No task JSON files found. Run TDD planning (SKILL.md) first" + EXIT + +# Check summaries exist (optional but recommended for full analysis) +summaries_exist = EXISTS(summaries_dir) +IF NOT summaries_exist: + WARNING: "No .summaries/ directory found. Some analysis may be limited." +``` + +**Output**: session_id, session_dir, task_files list + +--- + +### Phase 2: Task Chain Structure Validation + +**Step 2.1: Load and Parse Task JSONs** +```bash +# Single-pass JSON extraction using jq +validation_data = bash(""" +# Load all tasks and extract structured data +cd '{session_dir}/.task' + +# Extract all task IDs +task_ids=$(jq -r '.id' *.json 2>/dev/null | sort) + +# Extract dependencies for IMPL tasks +impl_deps=$(jq -r 'select(.id | startswith("IMPL")) | .id + ":" + (.context.depends_on[]? // "none")' *.json 2>/dev/null) + +# Extract dependencies for REFACTOR tasks +refactor_deps=$(jq -r 'select(.id | startswith("REFACTOR")) | .id + ":" + (.context.depends_on[]? // "none")' *.json 2>/dev/null) + +# Extract meta fields +meta_tdd=$(jq -r '.id + ":" + (.meta.tdd_phase // "missing")' *.json 2>/dev/null) +meta_agent=$(jq -r '.id + ":" + (.meta.agent // "missing")' *.json 2>/dev/null) + +# Output as JSON +jq -n --arg ids "$task_ids" \ + --arg impl "$impl_deps" \ + --arg refactor "$refactor_deps" \ + --arg tdd "$meta_tdd" \ + --arg agent "$meta_agent" \ + '{ids: $ids, impl_deps: $impl, refactor_deps: $refactor, tdd: $tdd, agent: $agent}' +""") +``` + +**Step 2.2: Validate TDD Chain Structure** +``` +Parse validation_data JSON and validate: + +For each feature N (extracted from task IDs): + 1. TEST-N.M exists? + 2. IMPL-N.M exists? + 3. REFACTOR-N.M exists? (optional but recommended) + 4. IMPL-N.M.context.depends_on contains TEST-N.M? + 5. REFACTOR-N.M.context.depends_on contains IMPL-N.M? + 6. TEST-N.M.meta.tdd_phase == "red"? + 7. TEST-N.M.meta.agent == "@code-review-test-agent"? + 8. IMPL-N.M.meta.tdd_phase == "green"? + 9. IMPL-N.M.meta.agent == "@code-developer"? + 10. REFACTOR-N.M.meta.tdd_phase == "refactor"? + +Calculate: +- chain_completeness_score = (complete_chains / total_chains) * 100 +- dependency_accuracy = (correct_deps / total_deps) * 100 +- meta_field_accuracy = (correct_meta / total_meta) * 100 +``` + +**Output**: chain_validation_report (JSON structure with validation results) + +--- + +### Phase 3: Coverage & Cycle Analysis + +**Step 3.1: Call Coverage Analysis Phase** + +Read and execute the coverage analysis phase: +- **Phase file**: `phases/04-tdd-coverage-analysis.md` +- **Args**: `--session {session_id}` + +**Step 3.2: Parse Output Files** +```bash +# Check required outputs exist +IF NOT EXISTS(process_dir/test-results.json): + WARNING: "test-results.json not found. Coverage analysis incomplete." + coverage_data = null +ELSE: + coverage_data = Read(process_dir/test-results.json) + +IF NOT EXISTS(process_dir/coverage-report.json): + WARNING: "coverage-report.json not found. Coverage metrics incomplete." + metrics = null +ELSE: + metrics = Read(process_dir/coverage-report.json) + +IF NOT EXISTS(process_dir/tdd-cycle-report.md): + WARNING: "tdd-cycle-report.md not found. Cycle validation incomplete." + cycle_data = null +ELSE: + cycle_data = Read(process_dir/tdd-cycle-report.md) +``` + +**Step 3.3: Extract Coverage Metrics** +``` +If coverage_data exists: + - line_coverage_percent + - branch_coverage_percent + - function_coverage_percent + - uncovered_files (list) + - uncovered_lines (map: file -> line ranges) + +If cycle_data exists: + - red_phase_compliance (tests failed initially?) + - green_phase_compliance (tests pass after impl?) + - refactor_phase_compliance (tests stay green during refactor?) + - minimal_implementation_score (was impl minimal?) +``` + +**Output**: coverage_analysis, cycle_analysis + +--- + +### Phase 4: Compliance Report Generation + +**Step 4.1: Calculate Compliance Score** +``` +Base Score: 100 points + +Deductions: +Chain Structure: + - Missing TEST task: -30 points per feature + - Missing IMPL task: -30 points per feature + - Missing REFACTOR task: -10 points per feature + - Wrong dependency: -15 points per error + - Wrong agent: -5 points per error + - Wrong tdd_phase: -5 points per error + +TDD Cycle Compliance: + - Test didn't fail initially: -10 points per feature + - Tests didn't pass after IMPL: -20 points per feature + - Tests broke during REFACTOR: -15 points per feature + - Over-engineered IMPL: -10 points per feature + +Coverage Quality: + - Line coverage < 80%: -5 points + - Branch coverage < 70%: -5 points + - Function coverage < 80%: -5 points + - Critical paths uncovered: -10 points + +Final Score: Max(0, Base Score - Total Deductions) +``` + +**Step 4.2: Determine Quality Gate** +``` +IF score >= 90 AND no_critical_violations: + recommendation = "APPROVED" +ELSE IF score >= 70 AND critical_violations == 0: + recommendation = "PROCEED_WITH_CAVEATS" +ELSE IF score >= 50: + recommendation = "REQUIRE_FIXES" +ELSE: + recommendation = "BLOCK_MERGE" +``` + +**Step 4.3: Generate Report** +```bash +report_content = Generate markdown report (see structure below) +report_path = "{session_dir}/TDD_COMPLIANCE_REPORT.md" +Write(report_path, report_content) +``` + +**Step 4.4: Display Summary to User** +```bash +echo "=== TDD Verification Complete ===" +echo "Session: {session_id}" +echo "Report: {report_path}" +echo "" +echo "Quality Gate: {recommendation}" +echo "Compliance Score: {score}/100" +echo "" +echo "Chain Validation: {chain_completeness_score}%" +echo "Line Coverage: {line_coverage}%" +echo "Branch Coverage: {branch_coverage}%" +echo "" +echo "Next: Review full report for detailed findings" +``` + +## TodoWrite Pattern (Optional) + +**Note**: As an orchestrator phase, TodoWrite tracking is optional and primarily useful for long-running verification processes. For most cases, the 4-phase execution is fast enough that progress tracking adds noise without value. + +```javascript +// Only use TodoWrite for complex multi-session verification +// Skip for single-session verification +``` + +## Validation Logic + +### Chain Validation Algorithm +``` +1. Load all task JSONs from .workflow/active/{sessionId}/.task/ +2. Extract task IDs and group by feature number +3. For each feature: + - Check TEST-N.M exists + - Check IMPL-N.M exists + - Check REFACTOR-N.M exists (optional but recommended) + - Verify IMPL-N.M depends_on TEST-N.M + - Verify REFACTOR-N.M depends_on IMPL-N.M + - Verify meta.tdd_phase values + - Verify meta.agent assignments +4. Calculate chain completeness score +5. Report incomplete or invalid chains +``` + +### Quality Gate Criteria + +| Recommendation | Score Range | Critical Violations | Action | +|----------------|-------------|---------------------|--------| +| **APPROVED** | ≥90 | 0 | Safe to merge | +| **PROCEED_WITH_CAVEATS** | ≥70 | 0 | Can proceed, address minor issues | +| **REQUIRE_FIXES** | ≥50 | Any | Must fix before merge | +| **BLOCK_MERGE** | <50 | Any | Block merge until resolved | + +**Critical Violations**: +- Missing TEST or IMPL task for any feature +- Tests didn't fail initially (Red phase violation) +- Tests didn't pass after IMPL (Green phase violation) +- Tests broke during REFACTOR (Refactor phase violation) + +## Output Files +``` +.workflow/active/WFS-{session-id}/ +├── TDD_COMPLIANCE_REPORT.md # Comprehensive compliance report +└── .process/ + ├── test-results.json # From phases/04-tdd-coverage-analysis.md + ├── coverage-report.json # From phases/04-tdd-coverage-analysis.md + └── tdd-cycle-report.md # From phases/04-tdd-coverage-analysis.md +``` + +## Error Handling + +### Session Discovery Errors +| Error | Cause | Resolution | +|-------|-------|------------| +| No active session | No WFS-* directories | Provide --session explicitly | +| Multiple active sessions | Multiple WFS-* directories | Provide --session explicitly | +| Session not found | Invalid session-id | Check available sessions | + +### Validation Errors +| Error | Cause | Resolution | +|-------|-------|------------| +| Task files missing | Incomplete planning | Run TDD planning (SKILL.md) first | +| Invalid JSON | Corrupted task files | Regenerate tasks | +| Missing summaries | Tasks not executed | Execute tasks before verify | + +### Analysis Errors +| Error | Cause | Resolution | +|-------|-------|------------| +| Coverage tool missing | No test framework | Configure testing first | +| Tests fail to run | Code errors | Fix errors before verify | +| Coverage analysis fails | phases/04-tdd-coverage-analysis.md error | Check analysis output | + +## Integration + +### Phase Chain +- **Called After**: Task execution completes (all TDD tasks done) +- **Calls**: `phases/04-tdd-coverage-analysis.md` +- **Related Skills**: SKILL.md (orchestrator), `workflow-plan/` (session management) + +### When to Use +- After completing all TDD tasks in a workflow +- Before merging TDD workflow branch +- For TDD process quality assessment +- To identify missing TDD steps + +## TDD Compliance Report Structure + +```markdown +# TDD Compliance Report - {Session ID} + +**Generated**: {timestamp} +**Session**: WFS-{sessionId} +**Workflow Type**: TDD + +--- + +## Executive Summary + +### Quality Gate Decision + +| Metric | Value | Status | +|--------|-------|--------| +| Compliance Score | {score}/100 | {status_emoji} | +| Chain Completeness | {percentage}% | {status} | +| Line Coverage | {percentage}% | {status} | +| Branch Coverage | {percentage}% | {status} | +| Function Coverage | {percentage}% | {status} | + +### Recommendation + +**{RECOMMENDATION}** + +**Decision Rationale**: +{brief explanation based on score and violations} + +**Quality Gate Criteria**: +- **APPROVED**: Score ≥90, no critical violations +- **PROCEED_WITH_CAVEATS**: Score ≥70, no critical violations +- **REQUIRE_FIXES**: Score ≥50 or critical violations exist +- **BLOCK_MERGE**: Score <50 + +--- + +## Chain Analysis + +### Feature 1: {Feature Name} +**Status**: Complete +**Chain**: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 + +| Phase | Task | Status | Details | +|-------|------|--------|---------| +| Red | TEST-1.1 | Pass | Test created and failed with clear message | +| Green | IMPL-1.1 | Pass | Minimal implementation made test pass | +| Refactor | REFACTOR-1.1 | Pass | Code improved, tests remained green | + +### Feature 2: {Feature Name} +**Status**: Incomplete +**Chain**: TEST-2.1 → IMPL-2.1 (Missing REFACTOR-2.1) + +| Phase | Task | Status | Details | +|-------|------|--------|---------| +| Red | TEST-2.1 | Pass | Test created and failed | +| Green | IMPL-2.1 | Warning | Implementation seems over-engineered | +| Refactor | REFACTOR-2.1 | Missing | Task not completed | + +**Issues**: +- REFACTOR-2.1 task not completed (-10 points) +- IMPL-2.1 implementation exceeded minimal scope (-10 points) + +### Chain Validation Summary + +| Metric | Value | +|--------|-------| +| Total Features | {count} | +| Complete Chains | {count} ({percent}%) | +| Incomplete Chains | {count} | +| Missing TEST | {count} | +| Missing IMPL | {count} | +| Missing REFACTOR | {count} | +| Dependency Errors | {count} | +| Meta Field Errors | {count} | + +--- + +## Test Coverage Analysis + +### Coverage Metrics + +| Metric | Coverage | Target | Status | +|--------|----------|--------|--------| +| Line Coverage | {percentage}% | ≥80% | {status} | +| Branch Coverage | {percentage}% | ≥70% | {status} | +| Function Coverage | {percentage}% | ≥80% | {status} | + +### Coverage Gaps + +| File | Lines | Issue | Priority | +|------|-------|-------|----------| +| src/auth/service.ts | 45-52 | Uncovered error handling | HIGH | +| src/utils/parser.ts | 78-85 | Uncovered edge case | MEDIUM | + +--- + +## TDD Cycle Validation + +### Red Phase (Write Failing Test) +- {N}/{total} features had failing tests initially ({percent}%) +- Compliant features: {list} +- Non-compliant features: {list} + +**Violations**: +- Feature 3: No evidence of initial test failure (-10 points) + +### Green Phase (Make Test Pass) +- {N}/{total} implementations made tests pass ({percent}%) +- Compliant features: {list} +- Non-compliant features: {list} + +**Violations**: +- Feature 2: Implementation over-engineered (-10 points) + +### Refactor Phase (Improve Quality) +- {N}/{total} features completed refactoring ({percent}%) +- Compliant features: {list} +- Non-compliant features: {list} + +**Violations**: +- Feature 2, 4: Refactoring step skipped (-20 points total) + +--- + +## Best Practices Assessment + +### Strengths +- Clear test descriptions +- Good test coverage +- Consistent naming conventions +- Well-structured code + +### Areas for Improvement +- Some implementations over-engineered in Green phase +- Missing refactoring steps +- Test failure messages could be more descriptive + +--- + +## Detailed Findings by Severity + +### Critical Issues ({count}) +{List of critical issues with impact and remediation} + +### High Priority Issues ({count}) +{List of high priority issues with impact and remediation} + +### Medium Priority Issues ({count}) +{List of medium priority issues with impact and remediation} + +### Low Priority Issues ({count}) +{List of low priority issues with impact and remediation} + +--- + +## Recommendations + +### Required Fixes (Before Merge) +1. Complete missing REFACTOR tasks (Features 2, 4) +2. Verify initial test failures for Feature 3 +3. Fix tests that broke during refactoring + +### Recommended Improvements +1. Simplify over-engineered implementations +2. Add edge case tests for Features 1, 3 +3. Improve test failure message clarity +4. Increase branch coverage to >85% + +### Optional Enhancements +1. Add more descriptive test names +2. Consider parameterized tests for similar scenarios +3. Document TDD process learnings + +--- + +## Metrics Summary + +| Metric | Value | +|--------|-------| +| Total Features | {count} | +| Complete Chains | {count} ({percent}%) | +| Compliance Score | {score}/100 | +| Critical Issues | {count} | +| High Issues | {count} | +| Medium Issues | {count} | +| Low Issues | {count} | +| Line Coverage | {percent}% | +| Branch Coverage | {percent}% | +| Function Coverage | {percent}% | + +--- + +**Report End** +``` + +--- + +## Post-Phase Update + +After TDD Verify completes: +- **Output Created**: `TDD_COMPLIANCE_REPORT.md` in session directory +- **Data Produced**: Compliance score, quality gate recommendation, chain validation, coverage metrics +- **Next Action**: Based on quality gate - APPROVED (merge), REQUIRE_FIXES (iterate), BLOCK_MERGE (rework) +- **TodoWrite**: Mark "TDD Verify: completed" with quality gate result diff --git a/.claude/skills/workflow-tdd-plan/phases/04-tdd-coverage-analysis.md b/.claude/skills/workflow-tdd-plan/phases/04-tdd-coverage-analysis.md new file mode 100644 index 00000000..bc1a28da --- /dev/null +++ b/.claude/skills/workflow-tdd-plan/phases/04-tdd-coverage-analysis.md @@ -0,0 +1,287 @@ +# Phase 4: TDD Coverage Analysis + +## 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 + +### Phase Chain +- **Called By**: `phases/03-tdd-verify.md` (Coverage & Cycle Analysis step) +- **Calls**: Test framework commands (npm test, pytest, etc.) +- **Followed By**: Compliance report generation in `phases/03-tdd-verify.md` + +--- + +## Post-Phase Update + +After TDD Coverage Analysis completes: +- **Output Created**: `test-results.json`, `coverage-report.json`, `tdd-cycle-report.md` in `.process/` +- **Data Produced**: Coverage metrics (line/branch/function), TDD cycle verification results per feature +- **Next Action**: Return data to `phases/03-tdd-verify.md` for compliance report aggregation +- **TodoWrite**: Mark "Coverage & Cycle Analysis: completed" diff --git a/.codex/skills/workflow-lite-plan/SKILL.md b/.codex/skills/workflow-lite-plan/SKILL.md new file mode 100644 index 00000000..2d2f98af --- /dev/null +++ b/.codex/skills/workflow-lite-plan/SKILL.md @@ -0,0 +1,283 @@ +--- +name: workflow-lite-plan +description: Unified lightweight planning skill with mode selection (Lite Plan, Multi-CLI Plan, Lite Fix). Supports exploration, diagnosis, multi-CLI collaboration, and shared execution via lite-execute. +allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context +--- + +# Planning Workflow + +Unified lightweight planning skill that consolidates multiple planning approaches into a single entry point with mode selection. Default mode: **Lite Plan**. All planning modes share a common execution phase (lite-execute). + +## Architecture Overview + +``` +┌──────────────────────────────────────────────────────────┐ +│ Planning Workflow Orchestrator (SKILL.md) │ +│ → Parse args → Mode selection → Load phase → Execute │ +└────────────┬─────────────────────────────────────────────┘ + │ Mode Selection (default: Lite Plan) + ┌────────┼────────┬──────────┐ + ↓ ↓ ↓ ↓ (shared) +┌────────┐ ┌────────┐ ┌────────┐ ┌────────────┐ +│Phase 1 │ │Phase 2 │ │Phase 3 │ │ Phase 4 │ +│ Lite │ │Multi- │ │ Lite │ │ Lite │ +│ Plan │ │CLI Plan│ │ Fix │ │ Execute │ +└────────┘ └────────┘ └────────┘ └────────────┘ + │ │ │ ↑ + └──────────┴──────────┴───────────┘ + (all hand off to Phase 4) +``` + +## Key Design Principles + +1. **Mode Selection First**: User chooses planning approach before any work begins +2. **Shared Execution**: All planning modes produce `executionContext` consumed by Phase 4 (lite-execute) +3. **Progressive Phase Loading**: Only load the selected planning phase + execution phase +4. **Auto-Continue**: Planning phase completes → automatically loads execution phase +5. **Default Lite Plan**: When no mode specified, use Lite Plan (most common) + +## Auto Mode + +When `--yes` or `-y`: Skip mode selection (use default or flag-specified mode), auto-approve plan, skip clarifications. + +## Usage + +``` +Skill(skill="workflow-lite-plan", args="") +Skill(skill="workflow-lite-plan", args="[FLAGS] \"\"") + +# Flags +--mode lite-plan|multi-cli|lite-fix Planning mode selection (default: lite-plan) +-y, --yes Skip all confirmations (auto mode) +-e, --explore Force exploration (lite-plan only) +--hotfix Fast hotfix mode (lite-fix only) + +# Examples +Skill(skill="workflow-lite-plan", args="\"Implement JWT authentication\"") # Default: lite-plan +Skill(skill="workflow-lite-plan", args="--mode multi-cli \"Refactor payment module\"") # Multi-CLI planning +Skill(skill="workflow-lite-plan", args="--mode lite-fix \"Login fails with 500 error\"") # Bug fix mode +Skill(skill="workflow-lite-plan", args="-y \"Add user profile page\"") # Auto mode +Skill(skill="workflow-lite-plan", args="--mode lite-fix --hotfix \"Production DB timeout\"") # Hotfix mode +``` + +## Subagent API Reference + +### spawn_agent + +Create a new subagent with task assignment. + +```javascript +const agentId = spawn_agent({ + message: ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json + +## TASK CONTEXT +${taskContext} + +## DELIVERABLES +${deliverables} +` +}) +``` + +### wait + +Get results from subagent (only way to retrieve results). + +```javascript +const result = wait({ + ids: [agentId], + timeout_ms: 600000 // 10 minutes +}) + +if (result.timed_out) { + // Handle timeout - can continue waiting or send_input to prompt completion +} +``` + +### send_input + +Continue interaction with active subagent (for clarification or follow-up). + +```javascript +send_input({ + id: agentId, + message: ` +## CLARIFICATION ANSWERS +${answers} + +## NEXT STEP +Continue with plan generation. +` +}) +``` + +### close_agent + +Clean up subagent resources (irreversible). + +```javascript +close_agent({ id: agentId }) +``` + +## Execution Flow + +``` +Input Parsing: + ├─ Extract flags: --mode, --yes, --explore, --hotfix + └─ Extract task description (string or file path) + +Mode Selection: + └─ Decision: + ├─ --mode lite-plan (or no --mode flag) → Read phases/01-lite-plan.md + ├─ --mode multi-cli → Read phases/02-multi-cli-plan.md + ├─ --mode lite-fix → Read phases/03-lite-fix.md + └─ No flag + not --yes → AskUserQuestion (default: Lite Plan) + +Planning Phase (one of): + ├─ Phase 1: Lite Plan + │ └─ Ref: phases/01-lite-plan.md + │ └─ Output: executionContext (plan.json + explorations + selections) + │ + ├─ Phase 2: Multi-CLI Plan + │ └─ Ref: phases/02-multi-cli-plan.md + │ └─ Output: executionContext (plan.json + synthesis rounds + selections) + │ + └─ Phase 3: Lite Fix + └─ Ref: phases/03-lite-fix.md + └─ Output: executionContext (fix-plan.json + diagnoses + selections) + +Execution Phase (always): + └─ Phase 4: Lite Execute + └─ Ref: phases/04-lite-execute.md + └─ Input: executionContext from planning phase + └─ Output: Executed tasks + optional code review +``` + +**Phase Reference Documents** (read on-demand when phase executes): + +| Phase | Document | Purpose | +|-------|----------|---------| +| 1 | [phases/01-lite-plan.md](phases/01-lite-plan.md) | Lightweight planning with exploration, clarification, and plan generation | +| 2 | [phases/02-multi-cli-plan.md](phases/02-multi-cli-plan.md) | Multi-CLI collaborative planning with ACE context and cross-verification | +| 3 | [phases/03-lite-fix.md](phases/03-lite-fix.md) | Bug diagnosis and fix planning with severity-based workflow | +| 4 | [phases/04-lite-execute.md](phases/04-lite-execute.md) | Shared execution engine: task grouping, batch execution, code review | + +## Mode Selection Logic + +```javascript +// Flag parsing +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const modeFlag = extractFlag($ARGUMENTS, '--mode') // 'lite-plan' | 'multi-cli' | 'lite-fix' | null + +// Mode determination +let selectedMode + +if (modeFlag) { + // Explicit mode flag + selectedMode = modeFlag +} else if (autoYes) { + // Auto mode: default to lite-plan + selectedMode = 'lite-plan' +} else { + // Interactive: ask user + const selection = AskUserQuestion({ + questions: [{ + question: "Select planning approach:", + header: "Mode", + multiSelect: false, + options: [ + { label: "Lite Plan (Recommended)", description: "Lightweight planning with exploration and clarification" }, + { label: "Multi-CLI Plan", description: "Multi-model collaborative planning (Gemini + Codex + Claude)" }, + { label: "Lite Fix", description: "Bug diagnosis and fix planning with severity assessment" } + ] + }] + }) + selectedMode = parseSelection(selection) // Map to 'lite-plan' | 'multi-cli' | 'lite-fix' +} + +// Load phase document +const phaseDoc = { + 'lite-plan': 'phases/01-lite-plan.md', + 'multi-cli': 'phases/02-multi-cli-plan.md', + 'lite-fix': 'phases/03-lite-fix.md' +}[selectedMode] + +Read(phaseDoc) // Load selected planning phase +// Execute planning phase... +// After planning completes: +Read('phases/04-lite-execute.md') // Load execution phase +``` + +## Data Flow + +``` +Planning Phase (01/02/03) + │ + ├─ Produces: executionContext = { + │ planObject: plan.json or fix-plan.json, + │ explorationsContext / diagnosisContext / synthesis rounds, + │ clarificationContext, + │ executionMethod: "Agent" | "Codex" | "Auto", + │ codeReviewTool: "Skip" | "Gemini Review" | ..., + │ originalUserInput: string, + │ session: { id, folder, artifacts } + │ } + │ + ↓ +Execution Phase (04) + │ + ├─ Consumes: executionContext + ├─ Task grouping → Batch creation → Parallel/sequential execution + ├─ Optional code review + └─ Development index update +``` + +## TodoWrite Pattern + +**Initialization** (after mode selection): +```json +[ + {"content": "Mode: {selectedMode} - Planning", "status": "in_progress", "activeForm": "Planning ({selectedMode})"}, + {"content": "Execution (Phase 4)", "status": "pending", "activeForm": "Executing tasks"} +] +``` + +**After planning completes**: +```json +[ + {"content": "Mode: {selectedMode} - Planning", "status": "completed", "activeForm": "Planning ({selectedMode})"}, + {"content": "Execution (Phase 4)", "status": "in_progress", "activeForm": "Executing tasks"} +] +``` + +Phase-internal sub-tasks are managed by each phase document (attach/collapse pattern). + +## Core Rules + +1. **Planning phases NEVER execute code** - all execution delegated to Phase 4 +2. **Only ONE planning phase runs** per invocation (Phase 1, 2, or 3) +3. **Phase 4 ALWAYS runs** after planning completes +4. **executionContext is the contract** between planning and execution phases +5. **Progressive loading**: Read phase doc ONLY when about to execute +6. **No cross-phase loading**: Don't load Phase 2 if user selected Phase 1 +7. **Explicit Lifecycle**: Always close_agent after wait completes to free resources + +## Error Handling + +| Error | Resolution | +|-------|------------| +| Unknown --mode value | Default to lite-plan with warning | +| Planning phase failure | Display error, offer retry or mode switch | +| executionContext missing | Error: planning phase did not produce context | +| Phase file not found | Error with file path for debugging | + +## Related Skills + +- Full planning workflow: [workflow-plan/SKILL.md](../workflow-plan/SKILL.md) +- Brainstorming: [workflow-brainstorm-auto-parallel/SKILL.md](../workflow-brainstorm-auto-parallel/SKILL.md) diff --git a/.codex/skills/workflow-lite-plan/phases/01-lite-plan.md b/.codex/skills/workflow-lite-plan/phases/01-lite-plan.md new file mode 100644 index 00000000..10f338fc --- /dev/null +++ b/.codex/skills/workflow-lite-plan/phases/01-lite-plan.md @@ -0,0 +1,738 @@ +# Phase 1: Lite Plan + +## Overview + +Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Focuses on planning phases (exploration, clarification, planning, confirmation) and delegates execution to Phase 4: Lite Execute (phases/04-lite-execute.md). + +**Core capabilities:** +- Intelligent task analysis with automatic exploration detection +- Dynamic code exploration (cli-explore-agent) when codebase understanding needed +- Interactive clarification after exploration to gather missing information +- Adaptive planning: Low complexity → Direct Claude; Medium/High → cli-lite-planning-agent +- Two-step confirmation: plan display → multi-dimensional input collection +- Execution execute with complete context handoff to lite-execute + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `-y`, `--yes` | Skip all confirmations (auto mode) | +| `-e`, `--explore` | Force code exploration phase (overrides auto-detection) | +| `` | Task description or path to .md file (required) | + +## Output Artifacts + +| Artifact | Description | +|----------|-------------| +| `exploration-{angle}.json` | Per-angle exploration results (1-4 files based on complexity) | +| `explorations-manifest.json` | Index of all exploration files | +| `planning-context.md` | Evidence paths + synthesized understanding | +| `plan.json` | Structured implementation plan (plan-json-schema.json) | + +**Output Directory**: `.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/` + +**Agent Usage**: +- Low complexity → Direct Claude planning (no agent) +- Medium/High complexity → `cli-lite-planning-agent` generates `plan.json` + +**Schema Reference**: `~/.claude/workflows/cli-templates/schemas/plan-json-schema.json` + +## Auto Mode Defaults + +When `--yes` or `-y` flag is used: +- **Clarification Questions**: Skipped (no clarification phase) +- **Plan Confirmation**: Auto-selected "Allow" +- **Execution Method**: Auto-selected "Auto" +- **Code Review**: Auto-selected "Skip" + +**Flag Parsing**: +```javascript +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const forceExplore = $ARGUMENTS.includes('--explore') || $ARGUMENTS.includes('-e') +``` + +## Execution Process + +``` +Phase 1: Task Analysis & Exploration + ├─ Parse input (description or .md file) + ├─ intelligent complexity assessment (Low/Medium/High) + ├─ Exploration decision (auto-detect or --explore flag) + ├─ Context protection: If file reading ≥50k chars → force cli-explore-agent + └─ Decision: + ├─ needsExploration=true → Launch parallel cli-explore-agents (1-4 based on complexity) + └─ needsExploration=false → Skip to Phase 2/3 + +Phase 2: Clarification (optional, multi-round) + ├─ Aggregate clarification_needs from all exploration angles + ├─ Deduplicate similar questions + └─ Decision: + ├─ Has clarifications → AskUserQuestion (max 4 questions per round, multiple rounds allowed) + └─ No clarifications → Skip to Phase 3 + +Phase 3: Planning (NO CODE EXECUTION - planning only) + └─ Decision (based on Phase 1 complexity): + ├─ Low → Load schema: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json → Direct Claude planning (following schema) → plan.json + └─ Medium/High → cli-lite-planning-agent → plan.json (agent internally executes quality check) + +Phase 4: Confirmation & Selection + ├─ Display plan summary (tasks, complexity, estimated time) + └─ AskUserQuestion: + ├─ Confirm: Allow / Modify / Cancel + ├─ Execution: Agent / Codex / Auto + └─ Review: Gemini / Agent / Skip + +Phase 5: Execute + ├─ Build executionContext (plan + explorations + clarifications + selections) + └─ → Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory +``` + +## Implementation + +### Phase 1: Intelligent Multi-Angle Exploration + +**Session Setup** (MANDATORY - follow exactly): +```javascript +// Helper: Get UTC+8 (China Standard Time) ISO string +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +const taskSlug = task_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) +const dateStr = getUtc8ISOString().substring(0, 10) // Format: 2025-11-29 + +const sessionId = `${taskSlug}-${dateStr}` // e.g., "implement-jwt-refresh-2025-11-29" +const sessionFolder = `.workflow/.lite-plan/${sessionId}` + +bash(`mkdir -p ${sessionFolder} && test -d ${sessionFolder} && echo "SUCCESS: ${sessionFolder}" || echo "FAILED: ${sessionFolder}"`) +``` + +**Exploration Decision Logic**: +```javascript +needsExploration = ( + flags.includes('--explore') || flags.includes('-e') || + task.mentions_specific_files || + task.requires_codebase_context || + task.needs_architecture_understanding || + task.modifies_existing_code +) + +if (!needsExploration) { + // Skip to Phase 2 (Clarification) or Phase 3 (Planning) + proceed_to_next_phase() +} +``` + +**⚠️ Context Protection**: File reading ≥50k chars → force `needsExploration=true` (delegate to cli-explore-agent) + +**Complexity Assessment** (Intelligent Analysis): +```javascript +// analyzes task complexity based on: +// - Scope: How many systems/modules are affected? +// - Depth: Surface change vs architectural impact? +// - Risk: Potential for breaking existing functionality? +// - Dependencies: How interconnected is the change? + +const complexity = analyzeTaskComplexity(task_description) +// Returns: 'Low' | 'Medium' | 'High' +// Low: Single file, isolated change, minimal risk +// Medium: Multiple files, some dependencies, moderate risk +// High: Cross-module, architectural, high risk + +// Angle assignment based on task type (orchestrator decides, not agent) +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'] +} + +function selectAngles(taskDescription, count) { + const text = taskDescription.toLowerCase() + let preset = 'feature' // default + + if (/refactor|architect|restructure|modular/.test(text)) preset = 'architecture' + else if (/security|auth|permission|access/.test(text)) preset = 'security' + else if (/performance|slow|optimi|cache/.test(text)) preset = 'performance' + else if (/fix|bug|error|issue|broken/.test(text)) preset = 'bugfix' + + return ANGLE_PRESETS[preset].slice(0, count) +} + +const selectedAngles = selectAngles(task_description, complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1)) + +// Planning strategy determination +const planningStrategy = complexity === 'Low' + ? 'Direct Claude Planning' + : 'cli-lite-planning-agent' + +console.log(` +## Exploration Plan + +Task Complexity: ${complexity} +Selected Angles: ${selectedAngles.join(', ')} +Planning Strategy: ${planningStrategy} + +Launching ${selectedAngles.length} parallel explorations... +`) +``` + +**Launch Parallel Explorations** - Orchestrator assigns angle to each agent: + +**⚠️ CRITICAL - SYNCHRONOUS EXECUTION**: +- **Exploration results are REQUIRED before planning** +- Use `spawn_agent` + `wait` pattern to ensure results are collected + + +```javascript +// Step 1: Create exploration agents in parallel +const explorationAgents = [] + +selectedAngles.forEach((angle, index) => { + const agentId = spawn_agent({ + message: ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json + +--- + +## Task Objective +Execute **${angle}** exploration for task planning context. Analyze codebase from this specific angle to discover relevant structure, patterns, and constraints. + +## Output Location + +**Session Folder**: ${sessionFolder} +**Output File**: ${sessionFolder}/exploration-${angle}.json + +## Assigned Context +- **Exploration Angle**: ${angle} +- **Task Description**: ${task_description} +- **Exploration Index**: ${index + 1} of ${selectedAngles.length} + +## MANDATORY 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 ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference) +4. Read: .workflow/project-tech.json (technology stack and architecture context) +5. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) + +## 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 + +**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 + **IMPORTANT**: Use object format with relevance scores for synthesis: + \`[{path: "src/file.ts", relevance: 0.85, rationale: "Core ${angle} logic"}]\` + 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 + +## Execution +**Write**: \`${sessionFolder}/exploration-${angle}.json\` +**Return**: 2-3 sentence summary of ${angle} findings +` + }) + + explorationAgents.push({ agentId, angle, index }) +}) + +// Step 2: Batch wait for all exploration agents +const explorationResults = wait({ + ids: explorationAgents.map(a => a.agentId), + timeout_ms: 600000 // 10 minutes +}) + +// Step 3: Check for timeout +if (explorationResults.timed_out) { + console.log('部分探索超时，继续使用已完成结果') +} + +// Step 4: Collect completed results +const completedExplorations = {} +explorationAgents.forEach(({ agentId, angle }) => { + if (explorationResults.status[agentId].completed) { + completedExplorations[angle] = explorationResults.status[agentId].completed + } +}) + +// Step 5: Close all exploration agents +explorationAgents.forEach(({ agentId }) => close_agent({ id: agentId })) +``` + +**Auto-discover Generated Exploration Files**: +```javascript +// After explorations complete, auto-discover all exploration-*.json files +const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`) + .split('\n') + .filter(f => f.trim()) + +// Read metadata to build manifest +const explorationManifest = { + session_id: sessionId, + task_description: task_description, + timestamp: getUtc8ISOString(), + complexity: complexity, + exploration_count: explorationCount, + explorations: explorationFiles.map(file => { + const data = JSON.parse(Read(file)) + const filename = path.basename(file) + return { + angle: data._metadata.exploration_angle, + file: filename, + path: file, + index: data._metadata.exploration_index + } + }) +} + +Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2)) + +console.log(` +## Exploration Complete + +Generated exploration files in ${sessionFolder}: +${explorationManifest.explorations.map(e => `- exploration-${e.angle}.json (angle: ${e.angle})`).join('\n')} + +Manifest: explorations-manifest.json +Angles explored: ${explorationManifest.explorations.map(e => e.angle).join(', ')} +`) +``` + +**Output**: +- `${sessionFolder}/exploration-{angle1}.json` +- `${sessionFolder}/exploration-{angle2}.json` +- ... (1-4 files based on complexity) +- `${sessionFolder}/explorations-manifest.json` + +--- + +### Phase 2: Clarification (Optional, Multi-Round) + +**Skip if**: No exploration or `clarification_needs` is empty across all explorations + +**⚠️ CRITICAL**: AskUserQuestion tool limits max 4 questions per call. **MUST execute multiple rounds** to exhaust all clarification needs - do NOT stop at round 1. + +**Aggregate clarification needs from all exploration angles**: +```javascript +// Load manifest and all exploration files +const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`)) +const explorations = manifest.explorations.map(exp => ({ + angle: exp.angle, + data: JSON.parse(Read(exp.path)) +})) + +// Aggregate clarification needs from all explorations +const allClarifications = [] +explorations.forEach(exp => { + if (exp.data.clarification_needs?.length > 0) { + exp.data.clarification_needs.forEach(need => { + allClarifications.push({ + ...need, + source_angle: exp.angle + }) + }) + } +}) + +// Intelligent deduplication: analyze allClarifications by intent +// - Identify questions with similar intent across different angles +// - Merge similar questions: combine options, consolidate context +// - Produce dedupedClarifications with unique intents only +const dedupedClarifications = intelligentMerge(allClarifications) + +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +if (autoYes) { + // Auto mode: Skip clarification phase + console.log(`[--yes] Skipping ${dedupedClarifications.length} clarification questions`) + console.log(`Proceeding to planning with exploration results...`) + // Continue to Phase 3 +} else if (dedupedClarifications.length > 0) { + // Interactive mode: Multi-round clarification + const BATCH_SIZE = 4 + const totalRounds = Math.ceil(dedupedClarifications.length / BATCH_SIZE) + + for (let i = 0; i < dedupedClarifications.length; i += BATCH_SIZE) { + const batch = dedupedClarifications.slice(i, i + BATCH_SIZE) + const currentRound = Math.floor(i / BATCH_SIZE) + 1 + + console.log(`### Clarification Round ${currentRound}/${totalRounds}`) + + AskUserQuestion({ + questions: batch.map(need => ({ + question: `[${need.source_angle}] ${need.question}\n\nContext: ${need.context}`, + header: need.source_angle.substring(0, 12), + multiSelect: false, + options: need.options.map((opt, index) => ({ + label: need.recommended === index ? `${opt} ★` : opt, + description: need.recommended === index ? `Recommended` : `Use ${opt}` + })) + })) + }) + + // Store batch responses in clarificationContext before next round + } +} +``` + +**Output**: `clarificationContext` (in-memory) + +--- + +### Phase 3: Planning + +**Planning Strategy Selection** (based on Phase 1 complexity): + +**IMPORTANT**: Phase 3 is **planning only** - NO code execution. All execution happens in Phase 5 via lite-execute. + +**Executor Assignment** (Claude 智能分配，plan 生成后执行): + +```javascript +// 分配规则（优先级从高到低）： +// 1. 用户明确指定："用 gemini 分析..." → gemini, "codex 实现..." → codex +// 2. 默认 → agent + +const executorAssignments = {} // { taskId: { executor: 'gemini'|'codex'|'agent', reason: string } } +plan.tasks.forEach(task => { + // Claude 根据上述规则语义分析，为每个 task 分配 executor + executorAssignments[task.id] = { executor: '...', reason: '...' } +}) +``` + +**Low Complexity** - Direct planning by Claude: +```javascript +// Step 1: Read schema +const schema = Bash(`cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json`) + +// Step 2: ⚠️ MANDATORY - Read and review ALL exploration files +const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`)) +manifest.explorations.forEach(exp => { + const explorationData = Read(exp.path) + console.log(`\n### Exploration: ${exp.angle}\n${explorationData}`) +}) + +// Step 3: Generate plan following schema (Claude directly, no agent) +// ⚠️ Plan MUST incorporate insights from exploration files read in Step 2 +const plan = { + summary: "...", + approach: "...", + tasks: [...], // Each task: { id, title, scope, ..., depends_on, execution_group, complexity } + estimated_time: "...", + recommended_execution: "Agent", + complexity: "Low", + _metadata: { timestamp: getUtc8ISOString(), source: "direct-planning", planning_mode: "direct" } +} + +// Step 4: Write plan to session folder +Write(`${sessionFolder}/plan.json`, JSON.stringify(plan, null, 2)) + +// Step 5: MUST continue to Phase 4 (Confirmation) - DO NOT execute code here +``` + +**Medium/High Complexity** - Invoke cli-lite-planning-agent: + +```javascript +// Step 1: Create planning agent +const planningAgentId = spawn_agent({ + message: ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/cli-lite-planning-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json + +--- + +Generate implementation plan and write plan.json. + +## Output Location + +**Session Folder**: ${sessionFolder} +**Output Files**: +- ${sessionFolder}/planning-context.md (evidence + understanding) +- ${sessionFolder}/plan.json (implementation plan) + +## Output Schema Reference +Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json (get schema reference before generating plan) + +## Project Context (MANDATORY - Read Both Files) +1. Read: .workflow/project-tech.json (technology stack, architecture, key components) +2. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) + +**CRITICAL**: All generated tasks MUST comply with constraints in project-guidelines.json + +## Task Description +${task_description} + +## Multi-Angle Exploration Context + +${manifest.explorations.map(exp => `### Exploration: ${exp.angle} (${exp.file}) +Path: ${exp.path} + +Read this file for detailed ${exp.angle} analysis.`).join('\n\n')} + +Total explorations: ${manifest.exploration_count} +Angles covered: ${manifest.explorations.map(e => e.angle).join(', ')} + +Manifest: ${sessionFolder}/explorations-manifest.json + +## User Clarifications +${JSON.stringify(clarificationContext) || "None"} + +## Complexity Level +${complexity} + +## Requirements +Generate plan.json following the schema obtained above. Key constraints: +- tasks: 2-7 structured tasks (**group by feature/module, NOT by file**) +- _metadata.exploration_angles: ${JSON.stringify(manifest.explorations.map(e => e.angle))} + +## Task Grouping Rules +1. **Group by feature**: All changes for one feature = one task (even if 3-5 files) +2. **Group by context**: Tasks with similar context or related functional changes can be grouped together +3. **Minimize agent count**: Simple, unrelated tasks can also be grouped to reduce agent execution overhead +4. **Avoid file-per-task**: Do NOT create separate tasks for each file +5. **Substantial tasks**: Each task should represent 15-60 minutes of work +6. **True dependencies only**: Only use depends_on when Task B cannot start without Task A's output +7. **Prefer parallel**: Most tasks should be independent (no depends_on) + +## Execution +1. Read schema file (cat command above) +2. Execute CLI planning using Gemini (Qwen fallback) +3. Read ALL exploration files for comprehensive context +4. Synthesize findings and generate plan following schema +5. **Write**: \`${sessionFolder}/planning-context.md\` (evidence paths + understanding) +6. **Write**: \`${sessionFolder}/plan.json\` +7. Return brief completion summary +` +}) + +// Step 2: Wait for planning completion +const planResult = wait({ + ids: [planningAgentId], + timeout_ms: 900000 // 15 minutes +}) + +// Step 3: Close planning agent +close_agent({ id: planningAgentId }) +``` + +**Output**: `${sessionFolder}/plan.json` + +--- + +### Phase 4: Task Confirmation & Execution Selection + +**Step 4.1: Display Plan** +```javascript +const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) + +console.log(` +## Implementation Plan + +**Summary**: ${plan.summary} +**Approach**: ${plan.approach} + +**Tasks** (${plan.tasks.length}): +${plan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.file})`).join('\n')} + +**Complexity**: ${plan.complexity} +**Estimated Time**: ${plan.estimated_time} +**Recommended**: ${plan.recommended_execution} +`) +``` + +**Step 4.2: Collect Confirmation** +```javascript +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +let userSelection + +if (autoYes) { + // Auto mode: Use defaults + console.log(`[--yes] Auto-confirming plan:`) + console.log(` - Confirmation: Allow`) + console.log(` - Execution: Auto`) + console.log(` - Review: Skip`) + + userSelection = { + confirmation: "Allow", + execution_method: "Auto", + code_review_tool: "Skip" + } +} else { + // Interactive mode: Ask user + // Note: Execution "Other" option allows specifying CLI tools from ~/.claude/cli-tools.json + userSelection = AskUserQuestion({ + questions: [ + { + question: `Confirm plan? (${plan.tasks.length} tasks, ${plan.complexity})`, + header: "Confirm", + multiSelect: false, + options: [ + { label: "Allow", description: "Proceed as-is" }, + { label: "Modify", description: "Adjust before execution" }, + { label: "Cancel", description: "Abort workflow" } + ] + }, + { + question: "Execution method:", + header: "Execution", + multiSelect: false, + options: [ + { label: "Agent", description: "@code-developer agent" }, + { label: "Codex", description: "codex CLI tool" }, + { label: "Auto", description: `Auto: ${plan.complexity === 'Low' ? 'Agent' : 'Codex'}` } + ] + }, + { + question: "Code review after execution?", + header: "Review", + multiSelect: false, + options: [ + { label: "Gemini Review", description: "Gemini CLI review" }, + { label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" }, + { label: "Agent Review", description: "@code-reviewer agent" }, + { label: "Skip", description: "No review" } + ] + } + ] + }) +} +``` + +--- + +### Phase 5: Execute to Execution + +**CRITICAL**: lite-plan NEVER executes code directly. ALL execution MUST go through lite-execute. + +**Step 5.1: Build executionContext** + +```javascript +// Load manifest and all exploration files +const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`)) +const explorations = {} + +manifest.explorations.forEach(exp => { + if (file_exists(exp.path)) { + explorations[exp.angle] = JSON.parse(Read(exp.path)) + } +}) + +const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) + +executionContext = { + planObject: plan, + explorationsContext: explorations, + explorationAngles: manifest.explorations.map(e => e.angle), + explorationManifest: manifest, + clarificationContext: clarificationContext || null, + executionMethod: userSelection.execution_method, // 全局默认，可被 executorAssignments 覆盖 + codeReviewTool: userSelection.code_review_tool, + originalUserInput: task_description, + + // 任务级 executor 分配（优先于全局 executionMethod） + executorAssignments: executorAssignments, // { taskId: { executor, reason } } + + session: { + id: sessionId, + folder: sessionFolder, + artifacts: { + explorations: manifest.explorations.map(exp => ({ + angle: exp.angle, + path: exp.path + })), + explorations_manifest: `${sessionFolder}/explorations-manifest.json`, + plan: `${sessionFolder}/plan.json` + } + } +} +``` + +**Step 5.2: Execute** + +```javascript +// → Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory +``` + +## Session Folder Structure + +``` +.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/ +├── exploration-{angle1}.json # Exploration angle 1 +├── exploration-{angle2}.json # Exploration angle 2 +├── exploration-{angle3}.json # Exploration angle 3 (if applicable) +├── exploration-{angle4}.json # Exploration angle 4 (if applicable) +├── explorations-manifest.json # Exploration index +└── plan.json # Implementation plan +``` + +**Example**: +``` +.workflow/.lite-plan/implement-jwt-refresh-2025-11-25-14-30-25/ +├── exploration-architecture.json +├── exploration-auth-patterns.json +├── exploration-security.json +├── explorations-manifest.json +└── plan.json +``` + +## Error Handling + +| Error | Resolution | +|-------|------------| +| Exploration agent failure | Skip exploration, continue with task description only | +| Planning agent failure | Fallback to direct planning by Claude | +| Clarification timeout | Use exploration findings as-is | +| Confirmation timeout | Save context, display resume instructions | +| Modify loop > 3 times | Suggest breaking task or using full planning workflow (workflow-plan/SKILL.md) | + +--- + +## Post-Phase Update + +After Phase 1 (Lite Plan) completes: +- **Output Created**: `executionContext` with plan.json, explorations, clarifications, user selections +- **Session Artifacts**: All files in `.workflow/.lite-plan/{session-id}/` +- **Next Action**: Auto-continue to [Phase 4: Lite Execute](04-lite-execute.md) with --in-memory +- **TodoWrite**: Mark "Lite Plan - Planning" as completed, start "Execution (Phase 4)" diff --git a/.codex/skills/workflow-lite-plan/phases/02-multi-cli-plan.md b/.codex/skills/workflow-lite-plan/phases/02-multi-cli-plan.md new file mode 100644 index 00000000..3e9ecf0c --- /dev/null +++ b/.codex/skills/workflow-lite-plan/phases/02-multi-cli-plan.md @@ -0,0 +1,548 @@ +# Phase 2: Multi-CLI Plan + +## Auto Mode + +When `--yes` or `-y`: Auto-approve plan, use recommended solution and execution method (Agent, Skip review). + +## Overview + +Multi-CLI collaborative planning with ACE context gathering and iterative cross-verification. Uses cli-discuss-agent for Gemini+Codex+Claude analysis to converge on optimal execution plan. + +## Quick Start + +**Parameters**: +- `` (required): Task description +- `--max-rounds` (optional): Maximum discussion rounds (default: 3) +- `--tools` (optional): CLI tools for analysis (default: gemini,codex) +- `--mode` (optional): Execution mode: parallel or serial + +**Context Source**: ACE semantic search + Multi-CLI analysis +**Output Directory**: `.workflow/.multi-cli-plan/{session-id}/` +**Default Max Rounds**: 3 (convergence may complete earlier) +**CLI Tools**: @cli-discuss-agent (analysis), @cli-lite-planning-agent (plan generation) +**Execution**: Auto-hands off to Phase 4: Lite Execute (phases/04-lite-execute.md) after plan approval + +## What & Why + +### Core Concept + +Multi-CLI collaborative planning with **three-phase architecture**: ACE context gathering → Iterative multi-CLI discussion → Plan generation. Orchestrator delegates analysis to agents, only handles user decisions and session management. + +**Process**: +- **Phase 1**: ACE semantic search gathers codebase context +- **Phase 2**: cli-discuss-agent orchestrates Gemini/Codex/Claude for cross-verified analysis +- **Phase 3-5**: User decision → Plan generation → Execution handoff + +**vs Single-CLI Planning**: +- **Single**: One model perspective, potential blind spots +- **Multi-CLI**: Cross-verification catches inconsistencies, builds consensus on solutions + +### Value Proposition + +1. **Multi-Perspective Analysis**: Gemini + Codex + Claude analyze from different angles +2. **Cross-Verification**: Identify agreements/disagreements, build confidence +3. **User-Driven Decisions**: Every round ends with user decision point +4. **Iterative Convergence**: Progressive refinement until consensus reached + +### Orchestrator Boundary (CRITICAL) + +- **ONLY command** for multi-CLI collaborative planning +- Manages: Session state, user decisions, agent delegation, phase transitions +- Delegates: CLI execution to @cli-discuss-agent, plan generation to @cli-lite-planning-agent + +### Execution Flow + +``` +Phase 1: Context Gathering + └─ ACE semantic search, extract keywords, build context package + +Phase 2: Multi-CLI Discussion (Iterative, via @cli-discuss-agent) + ├─ Round N: Agent executes Gemini + Codex + Claude + ├─ Cross-verify findings, synthesize solutions + ├─ Write synthesis.json to rounds/{N}/ + └─ Loop until convergence or max rounds + +Phase 3: Present Options + └─ Display solutions with trade-offs from agent output + +Phase 4: User Decision + ├─ Select solution approach + ├─ Select execution method (Agent/Codex/Auto) + ├─ Select code review tool (Skip/Gemini/Codex/Agent) + └─ Route: + ├─ Approve → Phase 5 + ├─ Need More Analysis → Return to Phase 2 + └─ Cancel → Save session + +Phase 5: Plan Generation & Execution Handoff + ├─ Generate plan.json (via @cli-lite-planning-agent) + ├─ Build executionContext with user selections + └─ Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory +``` + +### Agent Roles + +| Agent | Responsibility | +|-------|---------------| +| **Orchestrator** | Session management, ACE context, user decisions, phase transitions, executionContext assembly | +| **@cli-discuss-agent** | Multi-CLI execution (Gemini/Codex/Claude), cross-verification, solution synthesis, synthesis.json output | +| **@cli-lite-planning-agent** | Task decomposition, plan.json generation following schema | + +## Core Responsibilities + +### Phase 1: Context Gathering + +**Session Initialization**: +```javascript +const sessionId = `MCP-${taskSlug}-${date}` +const sessionFolder = `.workflow/.multi-cli-plan/${sessionId}` +Bash(`mkdir -p ${sessionFolder}/rounds`) +``` + +**ACE Context Queries**: +```javascript +const aceQueries = [ + `Project architecture related to ${keywords}`, + `Existing implementations of ${keywords[0]}`, + `Code patterns for ${keywords} features`, + `Integration points for ${keywords[0]}` +] +// Execute via mcp__ace-tool__search_context +``` + +**Context Package** (passed to agent): +- `relevant_files[]` - Files identified by ACE +- `detected_patterns[]` - Code patterns found +- `architecture_insights` - Structure understanding + +### Phase 2: Agent Delegation + +**Core Principle**: Orchestrator only delegates and reads output - NO direct CLI execution. + +**⚠️ CRITICAL - CLI EXECUTION REQUIREMENT**: +- **MUST** execute CLI calls via `Bash` with `run_in_background: true` +- **MUST** wait for hook callback to receive complete results +- **MUST NOT** proceed with next phase until CLI execution fully completes +- Do NOT use `TaskOutput` polling during CLI execution - wait passively for results +- Minimize scope: Proceed only when 100% result available + +**Agent Invocation** (Codex subagent pattern): +```javascript +// Step 1: Create discussion agent +const discussAgentId = spawn_agent({ + message: ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/cli-discuss-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json + +--- + +## Input Context +- task_description: ${taskDescription} +- round_number: ${currentRound} +- session: { id: "${sessionId}", folder: "${sessionFolder}" } +- ace_context: ${JSON.stringify(contextPackage)} +- previous_rounds: ${JSON.stringify(analysisResults)} +- user_feedback: ${userFeedback || 'None'} +- cli_config: { tools: ["gemini", "codex"], mode: "parallel", fallback_chain: ["gemini", "codex", "claude"] } + +## Execution Process +1. Parse input context (handle JSON strings) +2. Check if ACE supplementary search needed +3. Build CLI prompts with context +4. Execute CLIs (parallel or serial per cli_config.mode) +5. Parse CLI outputs, handle failures with fallback +6. Perform cross-verification between CLI results +7. Synthesize solutions, calculate scores +8. Calculate convergence, generate clarification questions +9. Write synthesis.json + +## Output +Write: ${sessionFolder}/rounds/${currentRound}/synthesis.json + +## Completion Checklist +- [ ] All configured CLI tools executed (or fallback triggered) +- [ ] Cross-verification completed with agreements/disagreements +- [ ] 2-3 solutions generated with file:line references +- [ ] Convergence score calculated (0.0-1.0) +- [ ] synthesis.json written with all Primary Fields +` +}) + +// Step 2: Wait for discussion completion +const discussResult = wait({ + ids: [discussAgentId], + timeout_ms: 600000 // 10 minutes +}) + +// Step 3: Close discussion agent +close_agent({ id: discussAgentId }) +``` + +**Read Agent Output**: +```javascript +const synthesis = JSON.parse(Read(`${sessionFolder}/rounds/${round}/synthesis.json`)) +// Access top-level fields: solutions, convergence, cross_verification, clarification_questions +``` + +**Convergence Decision**: +```javascript +if (synthesis.convergence.recommendation === 'converged') { + // Proceed to Phase 3 +} else if (synthesis.convergence.recommendation === 'user_input_needed') { + // Collect user feedback, return to Phase 2 +} else { + // Continue to next round if new_insights && round < maxRounds +} +``` + +### Phase 3: Present Options + +**Display from Agent Output** (no processing): +```javascript +console.log(` +## Solution Options + +${synthesis.solutions.map((s, i) => ` +**Option ${i+1}: ${s.name}** +Source: ${s.source_cli.join(' + ')} +Effort: ${s.effort} | Risk: ${s.risk} + +Pros: ${s.pros.join(', ')} +Cons: ${s.cons.join(', ')} + +Files: ${s.affected_files.slice(0,3).map(f => `${f.file}:${f.line}`).join(', ')} +`).join('\n')} + +## Cross-Verification +Agreements: ${synthesis.cross_verification.agreements.length} +Disagreements: ${synthesis.cross_verification.disagreements.length} +`) +``` + +### Phase 4: User Decision + +**Decision Options**: +```javascript +AskUserQuestion({ + questions: [ + { + question: "Which solution approach?", + header: "Solution", + multiSelect: false, + options: solutions.map((s, i) => ({ + label: `Option ${i+1}: ${s.name}`, + description: `${s.effort} effort, ${s.risk} risk` + })).concat([ + { label: "Need More Analysis", description: "Return to Phase 2" } + ]) + }, + { + question: "Execution method:", + header: "Execution", + multiSelect: false, + options: [ + { label: "Agent", description: "@code-developer agent" }, + { label: "Codex", description: "codex CLI tool" }, + { label: "Auto", description: "Auto-select based on complexity" } + ] + }, + { + question: "Code review after execution?", + header: "Review", + multiSelect: false, + options: [ + { label: "Skip", description: "No review" }, + { label: "Gemini Review", description: "Gemini CLI tool" }, + { label: "Codex Review", description: "codex review --uncommitted" }, + { label: "Agent Review", description: "Current agent review" } + ] + } + ] +}) +``` + +**Routing**: +- Approve + execution method → Phase 5 +- Need More Analysis → Phase 2 with feedback +- Cancel → Save session for resumption + +### Phase 5: Plan Generation & Execution Handoff + +**Step 1: Build Context-Package** (Orchestrator responsibility): +```javascript +// Extract key information from user decision and synthesis +const contextPackage = { + // Core solution details + solution: { + name: selectedSolution.name, + source_cli: selectedSolution.source_cli, + feasibility: selectedSolution.feasibility, + effort: selectedSolution.effort, + risk: selectedSolution.risk, + summary: selectedSolution.summary + }, + // Implementation plan (tasks, flow, milestones) + implementation_plan: selectedSolution.implementation_plan, + // Dependencies + dependencies: selectedSolution.dependencies || { internal: [], external: [] }, + // Technical concerns + technical_concerns: selectedSolution.technical_concerns || [], + // Consensus from cross-verification + consensus: { + agreements: synthesis.cross_verification.agreements, + resolved_conflicts: synthesis.cross_verification.resolution + }, + // User constraints (from Phase 4 feedback) + constraints: userConstraints || [], + // Task context + task_description: taskDescription, + session_id: sessionId +} + +// Write context-package for traceability +Write(`${sessionFolder}/context-package.json`, JSON.stringify(contextPackage, null, 2)) +``` + +**Step 2: Invoke Planning Agent** (Codex subagent pattern): +```javascript +// Step 1: Create planning agent +const planningAgentId = spawn_agent({ + message: ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/cli-lite-planning-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json + +--- + +## Schema Reference +Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json + +## Context-Package (from orchestrator) +${JSON.stringify(contextPackage, null, 2)} + +## Execution Process +1. Read plan-json-schema.json for output structure +2. Read project-tech.json and project-guidelines.json +3. Parse context-package fields: + - solution: name, feasibility, summary + - implementation_plan: tasks[], execution_flow, milestones + - dependencies: internal[], external[] + - technical_concerns: risks/blockers + - consensus: agreements, resolved_conflicts + - constraints: user requirements +4. Use implementation_plan.tasks[] as task foundation +5. Preserve task dependencies (depends_on) and execution_flow +6. Expand tasks with detailed acceptance criteria +7. Generate plan.json following schema exactly + +## Output +- ${sessionFolder}/plan.json + +## Completion Checklist +- [ ] plan.json preserves task dependencies from implementation_plan +- [ ] Task execution order follows execution_flow +- [ ] Key_points reflected in task descriptions +- [ ] User constraints applied to implementation +- [ ] Acceptance criteria are testable +- [ ] Schema fields match plan-json-schema.json exactly +` +}) + +// Step 2: Wait for planning completion +const planResult = wait({ + ids: [planningAgentId], + timeout_ms: 900000 // 15 minutes +}) + +// Step 3: Close planning agent +close_agent({ id: planningAgentId }) +``` + +**Step 3: Build executionContext**: +```javascript +// After plan.json is generated by cli-lite-planning-agent +const plan = JSON.parse(Read(`${sessionFolder}/plan.json`)) + +// Build executionContext (same structure as lite-plan) +executionContext = { + planObject: plan, + explorationsContext: null, // Multi-CLI doesn't use exploration files + explorationAngles: [], // No exploration angles + explorationManifest: null, // No manifest + clarificationContext: null, // Store user feedback from Phase 2 if exists + executionMethod: userSelection.execution_method, // From Phase 4 + codeReviewTool: userSelection.code_review_tool, // From Phase 4 + originalUserInput: taskDescription, + + // Optional: Task-level executor assignments + executorAssignments: null, // Could be enhanced in future + + session: { + id: sessionId, + folder: sessionFolder, + artifacts: { + explorations: [], // No explorations in multi-CLI workflow + explorations_manifest: null, + plan: `${sessionFolder}/plan.json`, + synthesis_rounds: Array.from({length: currentRound}, (_, i) => + `${sessionFolder}/rounds/${i+1}/synthesis.json` + ), + context_package: `${sessionFolder}/context-package.json` + } + } +} +``` + +**Step 4: Hand off to Execution**: +```javascript +// Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) with in-memory context +// executionContext is passed in-memory to the execution phase +``` + +## Output File Structure + +``` +.workflow/.multi-cli-plan/{MCP-task-slug-YYYY-MM-DD}/ +├── session-state.json # Session tracking (orchestrator) +├── rounds/ +│ ├── 1/synthesis.json # Round 1 analysis (cli-discuss-agent) +│ ├── 2/synthesis.json # Round 2 analysis (cli-discuss-agent) +│ └── .../ +├── context-package.json # Extracted context for planning (orchestrator) +└── plan.json # Structured plan (cli-lite-planning-agent) +``` + +**File Producers**: + +| File | Producer | Content | +|------|----------|---------| +| `session-state.json` | Orchestrator | Session metadata, rounds, decisions | +| `rounds/*/synthesis.json` | cli-discuss-agent | Solutions, convergence, cross-verification | +| `context-package.json` | Orchestrator | Extracted solution, dependencies, consensus for planning | +| `plan.json` | cli-lite-planning-agent | Structured tasks for lite-execute | + +## synthesis.json Schema + +```json +{ + "round": 1, + "solutions": [{ + "name": "Solution Name", + "source_cli": ["gemini", "codex"], + "feasibility": 0.85, + "effort": "low|medium|high", + "risk": "low|medium|high", + "summary": "Brief analysis summary", + "implementation_plan": { + "approach": "High-level technical approach", + "tasks": [ + {"id": "T1", "name": "Task", "depends_on": [], "files": [], "key_point": "..."} + ], + "execution_flow": "T1 → T2 → T3", + "milestones": ["Checkpoint 1", "Checkpoint 2"] + }, + "dependencies": {"internal": [], "external": []}, + "technical_concerns": ["Risk 1", "Blocker 2"] + }], + "convergence": { + "score": 0.85, + "new_insights": false, + "recommendation": "converged|continue|user_input_needed" + }, + "cross_verification": { + "agreements": [], + "disagreements": [], + "resolution": "..." + }, + "clarification_questions": [] +} +``` + +**Key Planning Fields**: + +| Field | Purpose | +|-------|---------| +| `feasibility` | Viability score (0-1) | +| `implementation_plan.tasks[]` | Discrete tasks with dependencies | +| `implementation_plan.execution_flow` | Task sequence visualization | +| `implementation_plan.milestones` | Key checkpoints | +| `technical_concerns` | Risks and blockers | + +**Note**: Solutions ranked by internal scoring (array order = priority) + +## TodoWrite Structure + +**Initialization**: +```javascript +TodoWrite({ todos: [ + { content: "Phase 1: Context Gathering", status: "in_progress", activeForm: "Gathering context" }, + { content: "Phase 2: Multi-CLI Discussion", status: "pending", activeForm: "Running discussion" }, + { content: "Phase 3: Present Options", status: "pending", activeForm: "Presenting options" }, + { content: "Phase 4: User Decision", status: "pending", activeForm: "Awaiting decision" }, + { content: "Phase 5: Plan Generation", status: "pending", activeForm: "Generating plan" } +]}) +``` + +**During Discussion Rounds**: +```javascript +TodoWrite({ todos: [ + { content: "Phase 1: Context Gathering", status: "completed", activeForm: "Gathering context" }, + { content: "Phase 2: Multi-CLI Discussion", status: "in_progress", activeForm: "Running discussion" }, + { content: " → Round 1: Initial analysis", status: "completed", activeForm: "Analyzing" }, + { content: " → Round 2: Deep verification", status: "in_progress", activeForm: "Verifying" }, + { content: "Phase 3: Present Options", status: "pending", activeForm: "Presenting options" }, + // ... +]}) +``` + +## Error Handling + +| Error | Resolution | +|-------|------------| +| ACE search fails | Fall back to Glob/Grep for file discovery | +| Agent fails | Retry once, then present partial results | +| CLI timeout (in agent) | Agent uses fallback: gemini → codex → claude | +| No convergence | Present best options, flag uncertainty | +| synthesis.json parse error | Request agent retry | +| User cancels | Save session for later resumption | + +## Configuration + +| Flag | Default | Description | +|------|---------|-------------| +| `--max-rounds` | 3 | Maximum discussion rounds | +| `--tools` | gemini,codex | CLI tools for analysis | +| `--mode` | parallel | Execution mode: parallel or serial | +| `--auto-execute` | false | Auto-execute after approval | + +## Best Practices + +1. **Be Specific**: Detailed task descriptions improve ACE context quality +2. **Provide Feedback**: Use clarification rounds to refine requirements +3. **Trust Cross-Verification**: Multi-CLI consensus indicates high confidence +4. **Review Trade-offs**: Consider pros/cons before selecting solution +5. **Check synthesis.json**: Review agent output for detailed analysis +6. **Iterate When Needed**: Don't hesitate to request more analysis + +## Related Phases + +- Simpler single-round planning: [Phase 1: Lite Plan](01-lite-plan.md) +- Shared execution engine: [Phase 4: Lite Execute](04-lite-execute.md) +- Full planning workflow: [workflow-plan/SKILL.md](../../workflow-plan/SKILL.md) + +--- + +## Post-Phase Update + +After Phase 2 (Multi-CLI Plan) completes: +- **Output Created**: `executionContext` with plan.json, synthesis rounds, context-package, user selections +- **Session Artifacts**: All files in `.workflow/.multi-cli-plan/{session-id}/` +- **Next Action**: Auto-continue to [Phase 4: Lite Execute](04-lite-execute.md) with --in-memory +- **TodoWrite**: Mark "Multi-CLI Plan - Planning" as completed, start "Execution (Phase 4)" diff --git a/.codex/skills/workflow-lite-plan/phases/03-lite-fix.md b/.codex/skills/workflow-lite-plan/phases/03-lite-fix.md new file mode 100644 index 00000000..cb57885b --- /dev/null +++ b/.codex/skills/workflow-lite-plan/phases/03-lite-fix.md @@ -0,0 +1,799 @@ +# Phase 3: Lite Fix + +## Overview + +Intelligent lightweight bug fixing command with dynamic workflow adaptation based on severity assessment. Focuses on diagnosis phases (root cause analysis, impact assessment, fix planning, confirmation) and delegates execution to Phase 4: Lite Execute (phases/04-lite-execute.md). + +**Core capabilities:** +- Intelligent bug analysis with automatic severity detection +- Dynamic code diagnosis (cli-explore-agent) for root cause identification +- Interactive clarification after diagnosis to gather missing information +- Adaptive fix planning strategy (direct Claude vs cli-lite-planning-agent) based on complexity +- Two-step confirmation: fix-plan display -> multi-dimensional input collection +- Execution handoff with complete context to Phase 4: Lite Execute (phases/04-lite-execute.md) + +## Parameters + +- `-y, --yes`: Skip all confirmations (auto mode) +- `--hotfix, -h`: Production hotfix mode (minimal diagnosis, fast fix) +- `` (required): Bug description, error message, or path to .md file + +## Output Artifacts + +| Artifact | Description | +|----------|-------------| +| `diagnosis-{angle}.json` | Per-angle diagnosis results (1-4 files based on severity) | +| `diagnoses-manifest.json` | Index of all diagnosis files | +| `planning-context.md` | Evidence paths + synthesized understanding | +| `fix-plan.json` | Structured fix plan (fix-plan-json-schema.json) | + +**Output Directory**: `.workflow/.lite-fix/{bug-slug}-{YYYY-MM-DD}/` + +**Agent Usage**: +- Low/Medium severity → Direct Claude planning (no agent) +- High/Critical severity → `cli-lite-planning-agent` generates `fix-plan.json` + +**Schema Reference**: `~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json` + +## Auto Mode Defaults + +When `--yes` or `-y` flag is used: +- **Clarification Questions**: Skipped (no clarification phase) +- **Fix Plan Confirmation**: Auto-selected "Allow" +- **Execution Method**: Auto-selected "Auto" +- **Code Review**: Auto-selected "Skip" +- **Severity**: Uses auto-detected severity (no manual override) +- **Hotfix Mode**: Respects --hotfix flag if present, otherwise normal mode + +**Flag Parsing**: +```javascript +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const hotfixMode = $ARGUMENTS.includes('--hotfix') || $ARGUMENTS.includes('-h') +``` + +## Execution Process + +``` +Phase 1: Bug Analysis & Diagnosis + |- Parse input (description, error message, or .md file) + |- Intelligent severity pre-assessment (Low/Medium/High/Critical) + |- Diagnosis decision (auto-detect or --hotfix flag) + |- Context protection: If file reading >=50k chars -> force cli-explore-agent + +- Decision: + |- needsDiagnosis=true -> Launch parallel cli-explore-agents (1-4 based on severity) + +- needsDiagnosis=false (hotfix) -> Skip directly to Phase 3 (Fix Planning) + +Phase 2: Clarification (optional, multi-round) + |- Aggregate clarification_needs from all diagnosis angles + |- Deduplicate similar questions + +- Decision: + |- Has clarifications -> AskUserQuestion (max 4 questions per round, multiple rounds allowed) + +- No clarifications -> Skip to Phase 3 + +Phase 3: Fix Planning (NO CODE EXECUTION - planning only) + +- Decision (based on Phase 1 severity): + |- Low/Medium -> Load schema: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json -> Direct Claude planning (following schema) -> fix-plan.json -> MUST proceed to Phase 4 + +- High/Critical -> cli-lite-planning-agent -> fix-plan.json -> MUST proceed to Phase 4 + +Phase 4: Confirmation & Selection + |- Display fix-plan summary (tasks, severity, estimated time) + +- AskUserQuestion: + |- Confirm: Allow / Modify / Cancel + |- Execution: Agent / Codex / Auto + +- Review: Gemini / Agent / Skip + +Phase 5: Execute + |- Build executionContext (fix-plan + diagnoses + clarifications + selections) + +- Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory --mode bugfix +``` + +## Implementation + +### Phase 1: Intelligent Multi-Angle Diagnosis + +**Session Setup** (MANDATORY - follow exactly): +```javascript +// Helper: Get UTC+8 (China Standard Time) ISO string +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40) +const dateStr = getUtc8ISOString().substring(0, 10) // Format: 2025-11-29 + +const sessionId = `${bugSlug}-${dateStr}` // e.g., "user-avatar-upload-fails-2025-11-29" +const sessionFolder = `.workflow/.lite-fix/${sessionId}` + +bash(`mkdir -p ${sessionFolder} && test -d ${sessionFolder} && echo "SUCCESS: ${sessionFolder}" || echo "FAILED: ${sessionFolder}"`) +``` + +**Diagnosis Decision Logic**: +```javascript +const hotfixMode = $ARGUMENTS.includes('--hotfix') || $ARGUMENTS.includes('-h') + +needsDiagnosis = ( + !hotfixMode && + ( + bug.lacks_specific_error_message || + bug.requires_codebase_context || + bug.needs_execution_tracing || + bug.root_cause_unclear + ) +) + +if (!needsDiagnosis) { + // Skip to Phase 2 (Clarification) or Phase 3 (Fix Planning) + proceed_to_next_phase() +} +``` + +**Context Protection**: File reading >=50k chars -> force `needsDiagnosis=true` (delegate to cli-explore-agent) + +**Severity Pre-Assessment** (Intelligent Analysis): +```javascript +// Analyzes bug severity based on: +// - Symptoms: Error messages, crash reports, user complaints +// - Scope: How many users/features are affected? +// - Urgency: Production down vs minor inconvenience +// - Impact: Data loss, security, business impact + +const severity = analyzeBugSeverity(bug_description) +// Returns: 'Low' | 'Medium' | 'High' | 'Critical' +// Low: Minor UI issue, localized, no data impact +// Medium: Multiple users affected, degraded functionality +// High: Significant functionality broken, many users affected +// Critical: Production down, data loss risk, security issue + +// Angle assignment based on bug type (orchestrator decides, not agent) +const DIAGNOSIS_ANGLE_PRESETS = { + runtime_error: ['error-handling', 'dataflow', 'state-management', 'edge-cases'], + performance: ['performance', 'bottlenecks', 'caching', 'data-access'], + security: ['security', 'auth-patterns', 'dataflow', 'validation'], + data_corruption: ['data-integrity', 'state-management', 'transactions', 'validation'], + ui_bug: ['state-management', 'event-handling', 'rendering', 'data-binding'], + integration: ['api-contracts', 'error-handling', 'timeouts', 'fallbacks'] +} + +function selectDiagnosisAngles(bugDescription, count) { + const text = bugDescription.toLowerCase() + let preset = 'runtime_error' // default + + if (/slow|timeout|performance|lag|hang/.test(text)) preset = 'performance' + else if (/security|auth|permission|access|token/.test(text)) preset = 'security' + else if (/corrupt|data|lost|missing|inconsistent/.test(text)) preset = 'data_corruption' + else if (/ui|display|render|style|click|button/.test(text)) preset = 'ui_bug' + else if (/api|integration|connect|request|response/.test(text)) preset = 'integration' + + return DIAGNOSIS_ANGLE_PRESETS[preset].slice(0, count) +} + +const selectedAngles = selectDiagnosisAngles(bug_description, severity === 'Critical' ? 4 : (severity === 'High' ? 3 : (severity === 'Medium' ? 2 : 1))) + +console.log(` +## Diagnosis Plan + +Bug Severity: ${severity} +Selected Angles: ${selectedAngles.join(', ')} + +Launching ${selectedAngles.length} parallel diagnoses... +`) +``` + +**Launch Parallel Diagnoses** - Orchestrator assigns angle to each agent: + +```javascript +// Launch agents with pre-assigned diagnosis angles +const diagnosisTasks = selectedAngles.map((angle, index) => + Task( + subagent_type="cli-explore-agent", + run_in_background=false, + description=`Diagnose: ${angle}`, + prompt=` +## Task Objective +Execute **${angle}** diagnosis for bug root cause analysis. Analyze codebase from this specific angle to discover root cause, affected paths, and fix hints. + +## Output Location + +**Session Folder**: ${sessionFolder} +**Output File**: ${sessionFolder}/diagnosis-${angle}.json + +## Assigned Context +- **Diagnosis Angle**: ${angle} +- **Bug Description**: ${bug_description} +- **Diagnosis Index**: ${index + 1} of ${selectedAngles.length} + +## 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 "{error_keyword_from_bug}" --type ts (locate relevant files) +3. Execute: cat ~/.claude/workflows/cli-templates/schemas/diagnosis-json-schema.json (get output schema reference) +4. Read: .workflow/project-tech.json (technology stack and architecture context) +5. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) + +## Diagnosis Strategy (${angle} focus) + +**Step 1: Error Tracing** (Bash) +- rg for error messages, stack traces, log patterns +- git log --since='2 weeks ago' for recent changes +- Trace execution path in affected modules + +**Step 2: Root Cause Analysis** (Gemini CLI) +- What code paths lead to this ${angle} issue? +- What edge cases are not handled from ${angle} perspective? +- What recent changes might have introduced this bug? + +**Step 3: Write Output** +- Consolidate ${angle} findings into JSON +- Identify ${angle}-specific clarification needs +- Provide fix hints based on ${angle} analysis + +## Expected Output + +**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly + +**Required Fields** (all ${angle} focused): +- symptom: Bug symptoms and error messages +- root_cause: Root cause hypothesis from ${angle} perspective + **IMPORTANT**: Use structured format: + \`{file: "src/module/file.ts", line_range: "45-60", issue: "Description", confidence: 0.85}\` +- affected_files: Files involved from ${angle} perspective + **IMPORTANT**: Use object format with relevance scores: + \`[{path: "src/file.ts", relevance: 0.85, rationale: "Contains ${angle} logic"}]\` +- reproduction_steps: Steps to reproduce the bug +- fix_hints: Suggested fix approaches from ${angle} viewpoint +- dependencies: Dependencies relevant to ${angle} diagnosis +- constraints: ${angle}-specific limitations affecting fix +- clarification_needs: ${angle}-related ambiguities (options array + recommended index) +- _metadata.diagnosis_angle: "${angle}" +- _metadata.diagnosis_index: ${index + 1} + +## Success Criteria +- [ ] Schema obtained via cat diagnosis-json-schema.json +- [ ] get_modules_by_depth.sh executed +- [ ] Root cause identified with confidence score +- [ ] At least 3 affected files identified with ${angle} rationale +- [ ] Fix hints are actionable (specific code changes, not generic advice) +- [ ] Reproduction steps are verifiable +- [ ] JSON output follows schema exactly +- [ ] clarification_needs includes options + recommended + +## Execution +**Write**: \`${sessionFolder}/diagnosis-${angle}.json\` +**Return**: 2-3 sentence summary of ${angle} diagnosis findings +` + ) +) + +// Execute all diagnosis tasks in parallel +``` + +**Auto-discover Generated Diagnosis Files**: +```javascript +// After diagnoses complete, auto-discover all diagnosis-*.json files +const diagnosisFiles = bash(`find ${sessionFolder} -name "diagnosis-*.json" -type f`) + .split('\n') + .filter(f => f.trim()) + +// Read metadata to build manifest +const diagnosisManifest = { + session_id: sessionId, + bug_description: bug_description, + timestamp: getUtc8ISOString(), + severity: severity, + diagnosis_count: diagnosisFiles.length, + diagnoses: diagnosisFiles.map(file => { + const data = JSON.parse(Read(file)) + const filename = path.basename(file) + return { + angle: data._metadata.diagnosis_angle, + file: filename, + path: file, + index: data._metadata.diagnosis_index + } + }) +} + +Write(`${sessionFolder}/diagnoses-manifest.json`, JSON.stringify(diagnosisManifest, null, 2)) + +console.log(` +## Diagnosis Complete + +Generated diagnosis files in ${sessionFolder}: +${diagnosisManifest.diagnoses.map(d => `- diagnosis-${d.angle}.json (angle: ${d.angle})`).join('\n')} + +Manifest: diagnoses-manifest.json +Angles diagnosed: ${diagnosisManifest.diagnoses.map(d => d.angle).join(', ')} +`) +``` + +**Output**: +- `${sessionFolder}/diagnosis-{angle1}.json` +- `${sessionFolder}/diagnosis-{angle2}.json` +- ... (1-4 files based on severity) +- `${sessionFolder}/diagnoses-manifest.json` + +--- + +### Phase 2: Clarification (Optional, Multi-Round) + +**Skip if**: No diagnosis or `clarification_needs` is empty across all diagnoses + +**⚠️ CRITICAL**: AskUserQuestion tool limits max 4 questions per call. **MUST execute multiple rounds** to exhaust all clarification needs - do NOT stop at round 1. + +**Aggregate clarification needs from all diagnosis angles**: +```javascript +// Load manifest and all diagnosis files +const manifest = JSON.parse(Read(`${sessionFolder}/diagnoses-manifest.json`)) +const diagnoses = manifest.diagnoses.map(diag => ({ + angle: diag.angle, + data: JSON.parse(Read(diag.path)) +})) + +// Aggregate clarification needs from all diagnoses +const allClarifications = [] +diagnoses.forEach(diag => { + if (diag.data.clarification_needs?.length > 0) { + diag.data.clarification_needs.forEach(need => { + allClarifications.push({ + ...need, + source_angle: diag.angle + }) + }) + } +}) + +// Deduplicate by question similarity +function deduplicateClarifications(clarifications) { + const unique = [] + clarifications.forEach(c => { + const isDuplicate = unique.some(u => + u.question.toLowerCase() === c.question.toLowerCase() + ) + if (!isDuplicate) unique.push(c) + }) + return unique +} + +const uniqueClarifications = deduplicateClarifications(allClarifications) + +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +if (autoYes) { + // Auto mode: Skip clarification phase + console.log(`[--yes] Skipping ${uniqueClarifications.length} clarification questions`) + console.log(`Proceeding to fix planning with diagnosis results...`) + // Continue to Phase 3 +} else if (uniqueClarifications.length > 0) { + // Interactive mode: Multi-round clarification + // ⚠️ MUST execute ALL rounds until uniqueClarifications exhausted + const BATCH_SIZE = 4 + const totalRounds = Math.ceil(uniqueClarifications.length / BATCH_SIZE) + + for (let i = 0; i < uniqueClarifications.length; i += BATCH_SIZE) { + const batch = uniqueClarifications.slice(i, i + BATCH_SIZE) + const currentRound = Math.floor(i / BATCH_SIZE) + 1 + + console.log(`### Clarification Round ${currentRound}/${totalRounds}`) + + AskUserQuestion({ + questions: batch.map(need => ({ + question: `[${need.source_angle}] ${need.question}\n\nContext: ${need.context}`, + header: need.source_angle, + multiSelect: false, + options: need.options.map((opt, index) => { + const isRecommended = need.recommended === index + return { + label: isRecommended ? `${opt} ★` : opt, + description: isRecommended ? `Use ${opt} approach (Recommended)` : `Use ${opt} approach` + } + }) + })) + }) + + // Store batch responses in clarificationContext before next round + } +} +``` + +**Output**: `clarificationContext` (in-memory) + +--- + +### Phase 3: Fix Planning + +**Planning Strategy Selection** (based on Phase 1 severity): + +**IMPORTANT**: Phase 3 is **planning only** - NO code execution. All execution happens in Phase 5 via lite-execute. + +**Low/Medium Severity** - Direct planning by Claude: +```javascript +// Step 1: Read schema +const schema = Bash(`cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json`) + +// Step 2: Generate fix-plan following schema (Claude directly, no agent) +// For Medium complexity: include rationale + verification (optional, but recommended) +const fixPlan = { + summary: "...", + root_cause: "...", + strategy: "immediate_patch|comprehensive_fix|refactor", + tasks: [...], // Each task: { id, title, scope, ..., depends_on, complexity } + estimated_time: "...", + recommended_execution: "Agent", + severity: severity, + risk_level: "...", + + // Medium complexity fields (optional for direct planning, auto-filled for Low) + ...(severity === "Medium" ? { + design_decisions: [ + { + decision: "Use immediate_patch strategy for minimal risk", + rationale: "Keeps changes localized and quick to review", + tradeoff: "Defers comprehensive refactoring" + } + ], + tasks_with_rationale: { + // Each task gets rationale if Medium + task_rationale_example: { + rationale: { + chosen_approach: "Direct fix approach", + alternatives_considered: ["Workaround", "Refactor"], + decision_factors: ["Minimal impact", "Quick turnaround"], + tradeoffs: "Doesn't address underlying issue" + }, + verification: { + unit_tests: ["test_bug_fix_basic"], + integration_tests: [], + manual_checks: ["Reproduce issue", "Verify fix"], + success_metrics: ["Issue resolved", "No regressions"] + } + } + } + } : {}), + + _metadata: { + timestamp: getUtc8ISOString(), + source: "direct-planning", + planning_mode: "direct", + complexity: severity === "Medium" ? "Medium" : "Low" + } +} + +// Step 3: Merge task rationale into tasks array +if (severity === "Medium") { + fixPlan.tasks = fixPlan.tasks.map(task => ({ + ...task, + rationale: fixPlan.tasks_with_rationale[task.id]?.rationale || { + chosen_approach: "Standard fix", + alternatives_considered: [], + decision_factors: ["Correctness", "Simplicity"], + tradeoffs: "None" + }, + verification: fixPlan.tasks_with_rationale[task.id]?.verification || { + unit_tests: [`test_${task.id}_basic`], + integration_tests: [], + manual_checks: ["Verify fix works"], + success_metrics: ["Test pass"] + } + })) + delete fixPlan.tasks_with_rationale // Clean up temp field +} + +// Step 4: Write fix-plan to session folder +Write(`${sessionFolder}/fix-plan.json`, JSON.stringify(fixPlan, null, 2)) + +// Step 5: MUST continue to Phase 4 (Confirmation) - DO NOT execute code here +``` + +**High/Critical Severity** - Invoke cli-lite-planning-agent: + +```javascript +Task( + subagent_type="cli-lite-planning-agent", + run_in_background=false, + description="Generate detailed fix plan", + prompt=` +Generate fix plan and write fix-plan.json. + +## Output Location + +**Session Folder**: ${sessionFolder} +**Output Files**: +- ${sessionFolder}/planning-context.md (evidence + understanding) +- ${sessionFolder}/fix-plan.json (fix plan) + +## Output Schema Reference +Execute: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json (get schema reference before generating plan) + +## Project Context (MANDATORY - Read Both Files) +1. Read: .workflow/project-tech.json (technology stack, architecture, key components) +2. Read: .workflow/project-guidelines.json (user-defined constraints and conventions) + +**CRITICAL**: All fix tasks MUST comply with constraints in project-guidelines.json + +## Bug Description +${bug_description} + +## Multi-Angle Diagnosis Context + +${manifest.diagnoses.map(diag => `### Diagnosis: ${diag.angle} (${diag.file}) +Path: ${diag.path} + +Read this file for detailed ${diag.angle} analysis.`).join('\n\n')} + +Total diagnoses: ${manifest.diagnosis_count} +Angles covered: ${manifest.diagnoses.map(d => d.angle).join(', ')} + +Manifest: ${sessionFolder}/diagnoses-manifest.json + +## User Clarifications +${JSON.stringify(clarificationContext) || "None"} + +## Severity Level +${severity} + +## Requirements +Generate fix-plan.json with: +- summary: 2-3 sentence overview of the fix +- root_cause: Consolidated root cause from all diagnoses +- strategy: "immediate_patch" | "comprehensive_fix" | "refactor" +- tasks: 1-5 structured fix tasks (**IMPORTANT: group by fix area, NOT by file**) + - **Task Granularity Principle**: Each task = one complete fix unit + - title: action verb + target (e.g., "Fix token validation edge case") + - scope: module path (src/auth/) or feature name + - action: "Fix" | "Update" | "Refactor" | "Add" | "Delete" + - description + - modification_points: ALL files to modify for this fix (group related changes) + - implementation (2-5 steps covering all modification_points) + - acceptance: Quantified acceptance criteria + - depends_on: task IDs this task depends on (use sparingly) + + **High/Critical complexity fields per task** (REQUIRED): + - rationale: + - chosen_approach: Why this fix approach (not alternatives) + - alternatives_considered: Other approaches evaluated + - decision_factors: Key factors influencing choice + - tradeoffs: Known tradeoffs of this approach + - verification: + - unit_tests: Test names to add/verify + - integration_tests: Integration test names + - manual_checks: Manual verification steps + - success_metrics: Quantified success criteria + - risks: + - description: Risk description + - probability: Low|Medium|High + - impact: Low|Medium|High + - mitigation: How to mitigate + - fallback: Fallback if fix fails + - code_skeleton (optional): Key interfaces/functions to implement + - interfaces: [{name, definition, purpose}] + - key_functions: [{signature, purpose, returns}] + +**Top-level High/Critical fields** (REQUIRED): +- data_flow: How data flows through affected code + - diagram: "A → B → C" style flow + - stages: [{stage, input, output, component}] +- design_decisions: Global fix decisions + - [{decision, rationale, tradeoff}] + +- estimated_time, recommended_execution, severity, risk_level +- _metadata: + - timestamp, source, planning_mode + - complexity: "High" | "Critical" + - diagnosis_angles: ${JSON.stringify(manifest.diagnoses.map(d => d.angle))} + +## Task Grouping Rules +1. **Group by fix area**: All changes for one fix = one task (even if 2-3 files) +2. **Avoid file-per-task**: Do NOT create separate tasks for each file +3. **Substantial tasks**: Each task should represent 10-45 minutes of work +4. **True dependencies only**: Only use depends_on when Task B cannot start without Task A's output +5. **Prefer parallel**: Most tasks should be independent (no depends_on) + +## Execution +1. Read ALL diagnosis files for comprehensive context +2. Execute CLI planning using Gemini (Qwen fallback) with --rule planning-fix-strategy template +3. Synthesize findings from multiple diagnosis angles +4. Generate fix-plan with: + - For High/Critical: REQUIRED new fields (rationale, verification, risks, code_skeleton, data_flow, design_decisions) + - Each task MUST have rationale (why this fix), verification (how to verify success), and risks (potential issues) +5. Parse output and structure fix-plan +6. **Write**: \`${sessionFolder}/planning-context.md\` (evidence paths + understanding) +7. **Write**: \`${sessionFolder}/fix-plan.json\` +8. Return brief completion summary + +## Output Format for CLI +Include these sections in your fix-plan output: +- Summary, Root Cause, Strategy (existing) +- Data Flow: Diagram showing affected code paths +- Design Decisions: Key architectural choices in the fix +- Tasks: Each with rationale (Medium/High), verification (Medium/High), risks (High), code_skeleton (High) +` +) +``` + +**Output**: `${sessionFolder}/fix-plan.json` + +--- + +### Phase 4: Task Confirmation & Execution Selection + +**Step 4.1: Display Fix Plan** +```javascript +const fixPlan = JSON.parse(Read(`${sessionFolder}/fix-plan.json`)) + +console.log(` +## Fix Plan + +**Summary**: ${fixPlan.summary} +**Root Cause**: ${fixPlan.root_cause} +**Strategy**: ${fixPlan.strategy} + +**Tasks** (${fixPlan.tasks.length}): +${fixPlan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.scope})`).join('\n')} + +**Severity**: ${fixPlan.severity} +**Risk Level**: ${fixPlan.risk_level} +**Estimated Time**: ${fixPlan.estimated_time} +**Recommended**: ${fixPlan.recommended_execution} +`) +``` + +**Step 4.2: Collect Confirmation** +```javascript +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +let userSelection + +if (autoYes) { + // Auto mode: Use defaults + console.log(`[--yes] Auto-confirming fix plan:`) + console.log(` - Confirmation: Allow`) + console.log(` - Execution: Auto`) + console.log(` - Review: Skip`) + + userSelection = { + confirmation: "Allow", + execution_method: "Auto", + code_review_tool: "Skip" + } +} else { + // Interactive mode: Ask user + userSelection = AskUserQuestion({ + questions: [ + { + question: `Confirm fix plan? (${fixPlan.tasks.length} tasks, ${fixPlan.severity} severity)`, + header: "Confirm", + multiSelect: false, + options: [ + { label: "Allow", description: "Proceed as-is" }, + { label: "Modify", description: "Adjust before execution" }, + { label: "Cancel", description: "Abort workflow" } + ] + }, + { + question: "Execution method:", + header: "Execution", + multiSelect: false, + options: [ + { label: "Agent", description: "@code-developer agent" }, + { label: "Codex", description: "codex CLI tool" }, + { label: "Auto", description: `Auto: ${fixPlan.severity === 'Low' ? 'Agent' : 'Codex'}` } + ] + }, + { + question: "Code review after fix?", + header: "Review", + multiSelect: false, + options: [ + { label: "Gemini Review", description: "Gemini CLI" }, + { label: "Agent Review", description: "@code-reviewer" }, + { label: "Skip", description: "No review" } + ] + } + ] + }) +} +``` + +--- + +### Phase 5: Execute to Execution + +**CRITICAL**: lite-fix NEVER executes code directly. ALL execution MUST go through lite-execute. + +**Step 5.1: Build executionContext** + +```javascript +// Load manifest and all diagnosis files +const manifest = JSON.parse(Read(`${sessionFolder}/diagnoses-manifest.json`)) +const diagnoses = {} + +manifest.diagnoses.forEach(diag => { + if (file_exists(diag.path)) { + diagnoses[diag.angle] = JSON.parse(Read(diag.path)) + } +}) + +const fixPlan = JSON.parse(Read(`${sessionFolder}/fix-plan.json`)) + +executionContext = { + mode: "bugfix", + severity: fixPlan.severity, + planObject: { + ...fixPlan, + // Ensure complexity is set based on severity for new field consumption + complexity: fixPlan.complexity || (fixPlan.severity === 'Critical' ? 'High' : (fixPlan.severity === 'High' ? 'High' : 'Medium')) + }, + diagnosisContext: diagnoses, + diagnosisAngles: manifest.diagnoses.map(d => d.angle), + diagnosisManifest: manifest, + clarificationContext: clarificationContext || null, + executionMethod: userSelection.execution_method, + codeReviewTool: userSelection.code_review_tool, + originalUserInput: bug_description, + session: { + id: sessionId, + folder: sessionFolder, + artifacts: { + diagnoses: manifest.diagnoses.map(diag => ({ + angle: diag.angle, + path: diag.path + })), + diagnoses_manifest: `${sessionFolder}/diagnoses-manifest.json`, + fix_plan: `${sessionFolder}/fix-plan.json` + } + } +} +``` + +**Step 5.2: Execute** + +```javascript +// Hand off to Phase 4: Lite Execute (phases/04-lite-execute.md) --in-memory --mode bugfix +// executionContext is passed in-memory to the execution phase +``` + +## Session Folder Structure + +``` +.workflow/.lite-fix/{bug-slug}-{YYYY-MM-DD}/ +├── diagnosis-{angle1}.json # Diagnosis angle 1 +├── diagnosis-{angle2}.json # Diagnosis angle 2 +├── diagnosis-{angle3}.json # Diagnosis angle 3 (if applicable) +├── diagnosis-{angle4}.json # Diagnosis angle 4 (if applicable) +├── diagnoses-manifest.json # Diagnosis index +├── planning-context.md # Evidence + understanding +└── fix-plan.json # Fix plan +``` + +**Example**: +``` +.workflow/.lite-fix/user-avatar-upload-fails-413-2025-11-25/ +├── diagnosis-error-handling.json +├── diagnosis-dataflow.json +├── diagnosis-validation.json +├── diagnoses-manifest.json +├── planning-context.md +└── fix-plan.json +``` + +## Error Handling + +| Error | Resolution | +|-------|------------| +| Diagnosis agent failure | Skip diagnosis, continue with bug description only | +| Planning agent failure | Fallback to direct planning by Claude | +| Clarification timeout | Use diagnosis findings as-is | +| Confirmation timeout | Save context, display resume instructions | +| Modify loop > 3 times | Suggest breaking task or using full planning workflow (workflow-plan/SKILL.md) | +| Root cause unclear | Extend diagnosis time or use broader angles | +| Too complex for lite-fix | Escalate to full planning workflow (workflow-plan/SKILL.md) | + +--- + +## Post-Phase Update + +After Phase 3 (Lite Fix) completes: +- **Output Created**: `executionContext` with fix-plan.json, diagnoses, clarifications, user selections +- **Session Artifacts**: All files in `.workflow/.lite-fix/{session-id}/` +- **Next Action**: Auto-continue to [Phase 4: Lite Execute](04-lite-execute.md) with --in-memory --mode bugfix +- **TodoWrite**: Mark "Lite Fix - Planning" as completed, start "Execution (Phase 4)" diff --git a/.codex/skills/workflow-lite-plan/phases/04-lite-execute.md b/.codex/skills/workflow-lite-plan/phases/04-lite-execute.md new file mode 100644 index 00000000..97d91948 --- /dev/null +++ b/.codex/skills/workflow-lite-plan/phases/04-lite-execute.md @@ -0,0 +1,738 @@ +# Phase 4: Lite Execute + +## Overview + +Flexible task execution phase supporting three input modes: in-memory plan (from planning phases), direct prompt description, or file content. Handles execution orchestration, progress tracking, and optional code review. + +**Core capabilities:** +- Multi-mode input (in-memory plan, prompt description, or file path) +- Execution orchestration (Agent or Codex) with full context +- Live progress tracking via TodoWrite at execution call level +- Optional code review with selected tool (Gemini, Agent, or custom) +- Context continuity across multiple executions +- Intelligent format detection (Enhanced Task JSON vs plain text) + +## Parameters + +- `--in-memory`: Use plan from memory (called by planning phases) +- ``: Task description string, or path to file (required) + +## Input Modes + +### Mode 1: In-Memory Plan + +**Trigger**: Called by planning phase after confirmation with `--in-memory` flag + +**Input Source**: `executionContext` global variable set by planning phase + +**Content**: Complete execution context (see Data Structures section) + +**Behavior**: +- Skip execution method selection (already set by planning phase) +- Directly proceed to execution with full context +- All planning artifacts available (exploration, clarifications, plan) + +### Mode 2: Prompt Description + +**Trigger**: User calls with task description string + +**Input**: Simple task description (e.g., "Add unit tests for auth module") + +**Behavior**: +- Store prompt as `originalUserInput` +- Create simple execution plan from prompt +- AskUserQuestion: Select execution method (Agent/Codex/Auto) +- AskUserQuestion: Select code review tool (Skip/Gemini/Agent/Other) +- Proceed to execution with `originalUserInput` included + +**User Interaction**: +```javascript +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +let userSelection + +if (autoYes) { + // Auto mode: Use defaults + console.log(`[--yes] Auto-confirming execution:`) + console.log(` - Execution method: Auto`) + console.log(` - Code review: Skip`) + + userSelection = { + execution_method: "Auto", + code_review_tool: "Skip" + } +} else { + // Interactive mode: Ask user + userSelection = AskUserQuestion({ + questions: [ + { + question: "Select execution method:", + header: "Execution", + multiSelect: false, + options: [ + { label: "Agent", description: "@code-developer agent" }, + { label: "Codex", description: "codex CLI tool" }, + { label: "Auto", description: "Auto-select based on complexity" } + ] + }, + { + question: "Enable code review after execution?", + header: "Code Review", + multiSelect: false, + options: [ + { label: "Skip", description: "No review" }, + { label: "Gemini Review", description: "Gemini CLI tool" }, + { label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" }, + { label: "Agent Review", description: "Current agent review" } + ] + } + ] + }) +} +``` + +### Mode 3: File Content + +**Trigger**: User calls with file path + +**Input**: Path to file containing task description or plan.json + +**Step 1: Read and Detect Format** + +```javascript +fileContent = Read(filePath) + +// Attempt JSON parsing +try { + jsonData = JSON.parse(fileContent) + + // Check if plan.json from lite-plan session + if (jsonData.summary && jsonData.approach && jsonData.tasks) { + planObject = jsonData + originalUserInput = jsonData.summary + isPlanJson = true + } else { + // Valid JSON but not plan.json - treat as plain text + originalUserInput = fileContent + isPlanJson = false + } +} catch { + // Not valid JSON - treat as plain text prompt + originalUserInput = fileContent + isPlanJson = false +} +``` + +**Step 2: Create Execution Plan** + +If `isPlanJson === true`: +- Use `planObject` directly +- User selects execution method and code review + +If `isPlanJson === false`: +- Treat file content as prompt (same behavior as Mode 2) +- Create simple execution plan from content + +**Step 3: User Interaction** + +- AskUserQuestion: Select execution method (Agent/Codex/Auto) +- AskUserQuestion: Select code review tool +- Proceed to execution with full context + +## Execution Process + +``` +Input Parsing: + └─ Decision (mode detection): + ├─ --in-memory flag → Mode 1: Load executionContext → Skip user selection + ├─ Ends with .md/.json/.txt → Mode 3: Read file → Detect format + │ ├─ Valid plan.json → Use planObject → User selects method + review + │ └─ Not plan.json → Treat as prompt → User selects method + review + └─ Other → Mode 2: Prompt description → User selects method + review + +Execution: + ├─ Step 1: Initialize result tracking (previousExecutionResults = []) + ├─ Step 2: Task grouping & batch creation + │ ├─ Extract explicit depends_on (no file/keyword inference) + │ ├─ Group: independent tasks → single parallel batch (maximize utilization) + │ ├─ Group: dependent tasks → sequential phases (respect dependencies) + │ └─ Create TodoWrite list for batches + ├─ Step 3: Launch execution + │ ├─ Phase 1: All independent tasks (single batch, concurrent) + │ └─ Phase 2+: Dependent tasks by dependency order + ├─ Step 4: Track progress (TodoWrite updates per batch) + └─ Step 5: Code review (if codeReviewTool ≠ "Skip") + +Output: + └─ Execution complete with results in previousExecutionResults[] +``` + +## Detailed Execution Steps + +### Step 1: Initialize Execution Tracking + +**Operations**: +- Initialize result tracking for multi-execution scenarios +- Set up `previousExecutionResults` array for context continuity +- **In-Memory Mode**: Echo execution strategy from planning phase for transparency + +```javascript +// Initialize result tracking +previousExecutionResults = [] + +// In-Memory Mode: Echo execution strategy (transparency before execution) +if (executionContext) { + console.log(` +Execution Strategy (from planning phase): + Method: ${executionContext.executionMethod} + Review: ${executionContext.codeReviewTool} + Tasks: ${executionContext.planObject.tasks.length} + Complexity: ${executionContext.planObject.complexity} +${executionContext.executorAssignments ? ` Assignments: ${JSON.stringify(executionContext.executorAssignments)}` : ''} + `) +} +``` + +### Step 2: Task Grouping & Batch Creation + +**Dependency Analysis & Grouping Algorithm**: +```javascript +// Use explicit depends_on from plan.json (no inference from file/keywords) +function extractDependencies(tasks) { + const taskIdToIndex = {} + tasks.forEach((t, i) => { taskIdToIndex[t.id] = i }) + + return tasks.map((task, i) => { + // Only use explicit depends_on from plan.json + const deps = (task.depends_on || []) + .map(depId => taskIdToIndex[depId]) + .filter(idx => idx !== undefined && idx < i) + return { ...task, taskIndex: i, dependencies: deps } + }) +} + +// Group into batches: maximize parallel execution +function createExecutionCalls(tasks, executionMethod) { + const tasksWithDeps = extractDependencies(tasks) + const processed = new Set() + const calls = [] + + // Phase 1: All independent tasks → single parallel batch (maximize utilization) + const independentTasks = tasksWithDeps.filter(t => t.dependencies.length === 0) + if (independentTasks.length > 0) { + independentTasks.forEach(t => processed.add(t.taskIndex)) + calls.push({ + method: executionMethod, + executionType: "parallel", + groupId: "P1", + taskSummary: independentTasks.map(t => t.title).join(' | '), + tasks: independentTasks + }) + } + + // Phase 2: Dependent tasks → sequential batches (respect dependencies) + let sequentialIndex = 1 + let remaining = tasksWithDeps.filter(t => !processed.has(t.taskIndex)) + + while (remaining.length > 0) { + // Find tasks whose dependencies are all satisfied + const ready = remaining.filter(t => + t.dependencies.every(d => processed.has(d)) + ) + + if (ready.length === 0) { + console.warn('Circular dependency detected, forcing remaining tasks') + ready.push(...remaining) + } + + // Group ready tasks (can run in parallel within this phase) + ready.forEach(t => processed.add(t.taskIndex)) + calls.push({ + method: executionMethod, + executionType: ready.length > 1 ? "parallel" : "sequential", + groupId: ready.length > 1 ? `P${calls.length + 1}` : `S${sequentialIndex++}`, + taskSummary: ready.map(t => t.title).join(ready.length > 1 ? ' | ' : ' → '), + tasks: ready + }) + + remaining = remaining.filter(t => !processed.has(t.taskIndex)) + } + + return calls +} + +executionCalls = createExecutionCalls(planObject.tasks, executionMethod).map(c => ({ ...c, id: `[${c.groupId}]` })) + +TodoWrite({ + todos: executionCalls.map(c => ({ + content: `${c.executionType === "parallel" ? "⚡" : "→"} ${c.id} (${c.tasks.length} tasks)`, + status: "pending", + activeForm: `Executing ${c.id}` + })) +}) +``` + +### Step 3: Launch Execution + +**Executor Resolution** (任务级 executor 优先于全局设置): +```javascript +// 获取任务的 executor（优先使用 executorAssignments，fallback 到全局 executionMethod） +function getTaskExecutor(task) { + const assignments = executionContext?.executorAssignments || {} + if (assignments[task.id]) { + return assignments[task.id].executor // 'gemini' | 'codex' | 'agent' + } + // Fallback: 全局 executionMethod 映射 + const method = executionContext?.executionMethod || 'Auto' + if (method === 'Agent') return 'agent' + if (method === 'Codex') return 'codex' + // Auto: 根据复杂度 + return planObject.complexity === 'Low' ? 'agent' : 'codex' +} + +// 按 executor 分组任务 +function groupTasksByExecutor(tasks) { + const groups = { gemini: [], codex: [], agent: [] } + tasks.forEach(task => { + const executor = getTaskExecutor(task) + groups[executor].push(task) + }) + return groups +} +``` + +**Execution Flow**: Parallel batches concurrently → Sequential batches in order +```javascript +const parallel = executionCalls.filter(c => c.executionType === "parallel") +const sequential = executionCalls.filter(c => c.executionType === "sequential") + +// Phase 1: Launch all parallel batches (single message with multiple tool calls) +if (parallel.length > 0) { + TodoWrite({ todos: executionCalls.map(c => ({ status: c.executionType === "parallel" ? "in_progress" : "pending" })) }) + parallelResults = await Promise.all(parallel.map(c => executeBatch(c))) + previousExecutionResults.push(...parallelResults) + TodoWrite({ todos: executionCalls.map(c => ({ status: parallel.includes(c) ? "completed" : "pending" })) }) +} + +// Phase 2: Execute sequential batches one by one +for (const call of sequential) { + TodoWrite({ todos: executionCalls.map(c => ({ status: c === call ? "in_progress" : "..." })) }) + result = await executeBatch(call) + previousExecutionResults.push(result) + TodoWrite({ todos: executionCalls.map(c => ({ status: "completed" or "pending" })) }) +} +``` + +### Unified Task Prompt Builder + +**Task Formatting Principle**: Each task is a self-contained checklist. The executor only needs to know what THIS task requires. Same template for Agent and CLI. + +```javascript +function buildExecutionPrompt(batch) { + // Task template (6 parts: Modification Points → Why → How → Reference → Risks → Done) + const formatTask = (t) => ` +## ${t.title} + +**Scope**: \`${t.scope}\` | **Action**: ${t.action} + +### Modification Points +${t.modification_points.map(p => `- **${p.file}** → \`${p.target}\`: ${p.change}`).join('\n')} + +${t.rationale ? ` +### Why this approach (Medium/High) +${t.rationale.chosen_approach} +${t.rationale.decision_factors?.length > 0 ? `\nKey factors: ${t.rationale.decision_factors.join(', ')}` : ''} +${t.rationale.tradeoffs ? `\nTradeoffs: ${t.rationale.tradeoffs}` : ''} +` : ''} + +### How to do it +${t.description} + +${t.implementation.map(step => `- ${step}`).join('\n')} + +${t.code_skeleton ? ` +### Code skeleton (High) +${t.code_skeleton.interfaces?.length > 0 ? `**Interfaces**: ${t.code_skeleton.interfaces.map(i => `\`${i.name}\` - ${i.purpose}`).join(', ')}` : ''} +${t.code_skeleton.key_functions?.length > 0 ? `\n**Functions**: ${t.code_skeleton.key_functions.map(f => `\`${f.signature}\` - ${f.purpose}`).join(', ')}` : ''} +${t.code_skeleton.classes?.length > 0 ? `\n**Classes**: ${t.code_skeleton.classes.map(c => `\`${c.name}\` - ${c.purpose}`).join(', ')}` : ''} +` : ''} + +### Reference +- Pattern: ${t.reference?.pattern || 'N/A'} +- Files: ${t.reference?.files?.join(', ') || 'N/A'} +${t.reference?.examples ? `- Notes: ${t.reference.examples}` : ''} + +${t.risks?.length > 0 ? ` +### Risk mitigations (High) +${t.risks.map(r => `- ${r.description} → **${r.mitigation}**`).join('\n')} +` : ''} + +### Done when +${t.acceptance.map(c => `- [ ] ${c}`).join('\n')} +${t.verification?.success_metrics?.length > 0 ? `\n**Success metrics**: ${t.verification.success_metrics.join(', ')}` : ''}` + + // Build prompt + const sections = [] + + if (originalUserInput) sections.push(`## Goal\n${originalUserInput}`) + + sections.push(`## Tasks\n${batch.tasks.map(formatTask).join('\n\n---\n')}`) + + // Context (reference only) + const context = [] + if (previousExecutionResults.length > 0) { + context.push(`### Previous Work\n${previousExecutionResults.map(r => `- ${r.tasksSummary}: ${r.status}`).join('\n')}`) + } + if (clarificationContext) { + context.push(`### Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `- ${q}: ${a}`).join('\n')}`) + } + if (executionContext?.planObject?.data_flow?.diagram) { + context.push(`### Data Flow\n${executionContext.planObject.data_flow.diagram}`) + } + if (executionContext?.session?.artifacts?.plan) { + context.push(`### Artifacts\nPlan: ${executionContext.session.artifacts.plan}`) + } + // Project guidelines (user-defined constraints) + context.push(`### Project Guidelines\n@.workflow/project-guidelines.json`) + if (context.length > 0) sections.push(`## Context\n${context.join('\n\n')}`) + + sections.push(`Complete each task according to its "Done when" checklist.`) + + return sections.join('\n\n') +} +``` + +**Option A: Agent Execution** + +When to use: +- `getTaskExecutor(task) === "agent"` +- or `executionMethod = "Agent"` (global fallback) +- or `executionMethod = "Auto" AND complexity = "Low"` (global fallback) + +```javascript +Task( + subagent_type="code-developer", + run_in_background=false, + description=batch.taskSummary, + prompt=buildExecutionPrompt(batch) +) +``` + +**Result Collection**: After completion, collect result following `executionResult` structure (see Data Structures section) + +**Option B: CLI Execution (Codex)** + +When to use: +- `getTaskExecutor(task) === "codex"` +- or `executionMethod = "Codex"` (global fallback) +- or `executionMethod = "Auto" AND complexity = "Medium/High"` (global fallback) + +```bash +ccw cli -p "${buildExecutionPrompt(batch)}" --tool codex --mode write +``` + +**Execution with fixed IDs** (predictable ID pattern): +```javascript +// Launch CLI in background, wait for task hook callback +// Generate fixed execution ID: ${sessionId}-${groupId} +const sessionId = executionContext?.session?.id || 'standalone' +const fixedExecutionId = `${sessionId}-${batch.groupId}` // e.g., "implement-auth-2025-12-13-P1" + +// Check if resuming from previous failed execution +const previousCliId = batch.resumeFromCliId || null + +// Build command with fixed ID (and optional resume for continuation) +const cli_command = previousCliId + ? `ccw cli -p "${buildExecutionPrompt(batch)}" --tool codex --mode write --id ${fixedExecutionId} --resume ${previousCliId}` + : `ccw cli -p "${buildExecutionPrompt(batch)}" --tool codex --mode write --id ${fixedExecutionId}` + +// Execute in background, stop output and wait for task hook callback +Bash( + command=cli_command, + run_in_background=true +) +// STOP HERE - CLI executes in background, task hook will notify on completion +``` + +**Resume on Failure** (with fixed ID): +```javascript +// If execution failed or timed out, offer resume option +if (bash_result.status === 'failed' || bash_result.status === 'timeout') { + console.log(` +Execution incomplete. Resume available: + Fixed ID: ${fixedExecutionId} + Lookup: ccw cli detail ${fixedExecutionId} + Resume: ccw cli -p "Continue tasks" --resume ${fixedExecutionId} --tool codex --mode write --id ${fixedExecutionId}-retry +`) + + // Store for potential retry in same session + batch.resumeFromCliId = fixedExecutionId +} +``` + +**Result Collection**: After completion, analyze output and collect result following `executionResult` structure (include `cliExecutionId` for resume capability) + +**Option C: CLI Execution (Gemini)** + +When to use: `getTaskExecutor(task) === "gemini"` (analysis tasks) + +```bash +# Use unified buildExecutionPrompt, switch tool and mode +ccw cli -p "${buildExecutionPrompt(batch)}" --tool gemini --mode analysis --id ${sessionId}-${batch.groupId} +``` + +### Step 4: Progress Tracking + +Progress tracked at batch level (not individual task level). Icons: ⚡ (parallel, concurrent), → (sequential, one-by-one) + +### Step 5: Code Review (Optional) + +**Skip Condition**: Only run if `codeReviewTool ≠ "Skip"` + +**Review Focus**: Verify implementation against plan acceptance criteria and verification requirements +- Read plan.json for task acceptance criteria and verification checklist +- Check each acceptance criterion is fulfilled +- Verify success metrics from verification field (Medium/High complexity) +- Run unit/integration tests specified in verification field +- Validate code quality and identify issues +- Ensure alignment with planned approach and risk mitigations + +**Operations**: +- Agent Review: Current agent performs direct review +- Gemini Review: Execute gemini CLI with review prompt +- Codex Review: Two options - (A) with prompt for complex reviews, (B) `--uncommitted` flag only for quick reviews +- Custom tool: Execute specified CLI tool (qwen, etc.) + +**Unified Review Template** (All tools use same standard): + +**Review Criteria**: +- **Acceptance Criteria**: Verify each criterion from plan.tasks[].acceptance +- **Verification Checklist** (Medium/High): Check unit_tests, integration_tests, success_metrics from plan.tasks[].verification +- **Code Quality**: Analyze quality, identify issues, suggest improvements +- **Plan Alignment**: Validate implementation matches planned approach and risk mitigations + +**Shared Prompt Template** (used by all CLI tools): +``` +PURPOSE: Code review for implemented changes against plan acceptance criteria and verification requirements +TASK: • Verify plan acceptance criteria fulfillment • Check verification requirements (unit tests, success metrics) • Analyze code quality • Identify issues • Suggest improvements • Validate plan adherence and risk mitigations +MODE: analysis +CONTEXT: @**/* @{plan.json} [@{exploration.json}] | Memory: Review lite-execute changes against plan requirements including verification checklist +EXPECTED: Quality assessment with: + - Acceptance criteria verification (all tasks) + - Verification checklist validation (Medium/High: unit_tests, integration_tests, success_metrics) + - Issue identification + - Recommendations + Explicitly check each acceptance criterion and verification item from plan.json tasks. +CONSTRAINTS: Focus on plan acceptance criteria, verification requirements, and plan adherence | analysis=READ-ONLY +``` + +**Tool-Specific Execution** (Apply shared prompt template above): + +```bash +# Method 1: Agent Review (current agent) +# - Read plan.json: ${executionContext.session.artifacts.plan} +# - Apply unified review criteria (see Shared Prompt Template) +# - Report findings directly + +# Method 2: Gemini Review (recommended) +ccw cli -p "[Shared Prompt Template with artifacts]" --tool gemini --mode analysis +# CONTEXT includes: @**/* @${plan.json} [@${exploration.json}] + +# Method 3: Qwen Review (alternative) +ccw cli -p "[Shared Prompt Template with artifacts]" --tool qwen --mode analysis +# Same prompt as Gemini, different execution engine + +# Method 4: Codex Review (git-aware) - Two mutually exclusive options: + +# Option A: With custom prompt (reviews uncommitted by default) +ccw cli -p "[Shared Prompt Template with artifacts]" --tool codex --mode review +# Use for complex reviews with specific focus areas + +# Option B: Target flag only (no prompt allowed) +ccw cli --tool codex --mode review --uncommitted +# Quick review of uncommitted changes without custom instructions + +# IMPORTANT: -p prompt and target flags (--uncommitted/--base/--commit) are MUTUALLY EXCLUSIVE +``` + +**Multi-Round Review with Fixed IDs**: +```javascript +// Generate fixed review ID +const reviewId = `${sessionId}-review` + +// First review pass with fixed ID +const reviewResult = Bash(`ccw cli -p "[Review prompt]" --tool gemini --mode analysis --id ${reviewId}`) + +// If issues found, continue review dialog with fixed ID chain +if (hasUnresolvedIssues(reviewResult)) { + // Resume with follow-up questions + Bash(`ccw cli -p "Clarify the security concerns you mentioned" --resume ${reviewId} --tool gemini --mode analysis --id ${reviewId}-followup`) +} +``` + +**Implementation Note**: Replace `[Shared Prompt Template with artifacts]` placeholder with actual template content, substituting: +- `@{plan.json}` → `@${executionContext.session.artifacts.plan}` +- `[@{exploration.json}]` → exploration files from artifacts (if exists) + +### Step 6: Update Development Index + +**Trigger**: After all executions complete (regardless of code review) + +**Skip Condition**: Skip if `.workflow/project-tech.json` does not exist + +**Operations**: +```javascript +const projectJsonPath = '.workflow/project-tech.json' +if (!fileExists(projectJsonPath)) return // Silent skip + +const projectJson = JSON.parse(Read(projectJsonPath)) + +// Initialize if needed +if (!projectJson.development_index) { + projectJson.development_index = { feature: [], enhancement: [], bugfix: [], refactor: [], docs: [] } +} + +// Detect category from keywords +function detectCategory(text) { + text = text.toLowerCase() + if (/\b(fix|bug|error|issue|crash)\b/.test(text)) return 'bugfix' + if (/\b(refactor|cleanup|reorganize)\b/.test(text)) return 'refactor' + if (/\b(doc|readme|comment)\b/.test(text)) return 'docs' + if (/\b(add|new|create|implement)\b/.test(text)) return 'feature' + return 'enhancement' +} + +// Detect sub_feature from task file paths +function detectSubFeature(tasks) { + const dirs = tasks.map(t => t.file?.split('/').slice(-2, -1)[0]).filter(Boolean) + const counts = dirs.reduce((a, d) => { a[d] = (a[d] || 0) + 1; return a }, {}) + return Object.entries(counts).sort((a, b) => b[1] - a[1])[0]?.[0] || 'general' +} + +const category = detectCategory(`${planObject.summary} ${planObject.approach}`) +const entry = { + title: planObject.summary.slice(0, 60), + sub_feature: detectSubFeature(planObject.tasks), + date: new Date().toISOString().split('T')[0], + description: planObject.approach.slice(0, 100), + status: previousExecutionResults.every(r => r.status === 'completed') ? 'completed' : 'partial', + session_id: executionContext?.session?.id || null +} + +projectJson.development_index[category].push(entry) +projectJson.statistics.last_updated = new Date().toISOString() +Write(projectJsonPath, JSON.stringify(projectJson, null, 2)) + +console.log(`Development index: [${category}] ${entry.title}`) +``` + +## Best Practices + +**Input Modes**: In-memory (planning phase), prompt (standalone), file (JSON/text) +**Task Grouping**: Based on explicit depends_on only; independent tasks run in single parallel batch +**Execution**: All independent tasks launch concurrently via single Claude message with multiple tool calls + +## Error Handling + +| Error | Cause | Resolution | +|-------|-------|------------| +| Missing executionContext | --in-memory without context | Error: "No execution context found. Only available when called by planning phase." | +| File not found | File path doesn't exist | Error: "File not found: {path}. Check file path." | +| Empty file | File exists but no content | Error: "File is empty: {path}. Provide task description." | +| Invalid Enhanced Task JSON | JSON missing required fields | Warning: "Missing required fields. Treating as plain text." | +| Malformed JSON | JSON parsing fails | Treat as plain text (expected for non-JSON files) | +| Execution failure | Agent/Codex crashes | Display error, use fixed ID `${sessionId}-${groupId}` for resume: `ccw cli -p "Continue" --resume --id -retry` | +| Execution timeout | CLI exceeded timeout | Use fixed ID for resume with extended timeout | +| Codex unavailable | Codex not installed | Show installation instructions, offer Agent execution | +| Fixed ID not found | Custom ID lookup failed | Check `ccw cli history`, verify date directories | + +## Data Structures + +### executionContext (Input - Mode 1) + +Passed from planning phase via global variable: + +```javascript +{ + planObject: { + summary: string, + approach: string, + tasks: [...], + estimated_time: string, + recommended_execution: string, + complexity: string + }, + explorationsContext: {...} | null, // Multi-angle explorations + explorationAngles: string[], // List of exploration angles + explorationManifest: {...} | null, // Exploration manifest + clarificationContext: {...} | null, + executionMethod: "Agent" | "Codex" | "Auto", // Global default + codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string, + originalUserInput: string, + + // Task-level executor assignments (priority over executionMethod) + executorAssignments: { + [taskId]: { executor: "gemini" | "codex" | "agent", reason: string } + }, + + // Session artifacts location (saved by planning phase) + session: { + id: string, // Session identifier: {taskSlug}-{shortTimestamp} + folder: string, // Session folder path: .workflow/.lite-plan/{session-id} + artifacts: { + explorations: [{angle, path}], // exploration-{angle}.json paths + explorations_manifest: string, // explorations-manifest.json path + plan: string // plan.json path (always present) + } + } +} +``` + +**Artifact Usage**: +- Artifact files contain detailed planning context +- Pass artifact paths to CLI tools and agents for enhanced context +- See execution options above for usage examples + +### executionResult (Output) + +Collected after each execution call completes: + +```javascript +{ + executionId: string, // e.g., "[Agent-1]", "[Codex-1]" + status: "completed" | "partial" | "failed", + tasksSummary: string, // Brief description of tasks handled + completionSummary: string, // What was completed + keyOutputs: string, // Files created/modified, key changes + notes: string, // Important context for next execution + fixedCliId: string | null // Fixed CLI execution ID (e.g., "implement-auth-2025-12-13-P1") +} +``` + +Appended to `previousExecutionResults` array for context continuity in multi-execution scenarios. + +## Post-Completion Expansion + +After completion, ask user whether to expand as issue (test/enhance/refactor/doc). Selected items create new issues accordingly. + +**Fixed ID Pattern**: `${sessionId}-${groupId}` enables predictable lookup without auto-generated timestamps. + +**Resume Usage**: If `status` is "partial" or "failed", use `fixedCliId` to resume: +```bash +# Lookup previous execution +ccw cli detail ${fixedCliId} + +# Resume with new fixed ID for retry +ccw cli -p "Continue from where we left off" --resume ${fixedCliId} --tool codex --mode write --id ${fixedCliId}-retry +``` + +--- + +## Post-Phase Update + +After Phase 4 (Lite Execute) completes: +- **Output Created**: Executed tasks, optional code review results, updated development index +- **Execution Results**: `previousExecutionResults[]` with status per batch +- **Next Action**: Workflow complete. Optionally expand to issue (test/enhance/refactor/doc) +- **TodoWrite**: Mark all execution batches as completed diff --git a/ccw/docs-site/.docusaurus/docusaurus-plugin-debug/default/p/docs-zh-docusaurus-debug-content-ba9.json b/ccw/docs-site/.docusaurus/docusaurus-plugin-debug/default/p/docs-zh-docusaurus-debug-content-ba9.json new file mode 100644 index 00000000..82696ebb --- /dev/null +++ b/ccw/docs-site/.docusaurus/docusaurus-plugin-debug/default/p/docs-zh-docusaurus-debug-content-ba9.json @@ -0,0 +1 @@ +{"allContent":{"docusaurus-plugin-content-docs":{"default":{"loadedVersions":[{"versionName":"current","label":"当前","banner":null,"badge":false,"noIndex":false,"className":"docs-version-current","path":"/docs/zh/","tagsPath":"/docs/zh/tags","editUrl":"https://github.com/ccw/docs/tree/main/docs","editUrlLocalized":"https://github.com/ccw/docs/tree/main/i18n/zh/docusaurus-plugin-content-docs/current","isLast":true,"routePriority":-1,"sidebarFilePath":"D:\\Claude_dms3\\ccw\\docs-site\\sidebars.ts","contentPath":"D:\\Claude_dms3\\ccw\\docs-site\\docs","contentPathLocalized":"D:\\Claude_dms3\\ccw\\docs-site\\i18n\\zh\\docusaurus-plugin-content-docs\\current","docs":[{"id":"commands/cli/cli-init","title":"/cli:cli-init","description":"Initialize CLI configuration for workspace with automatic technology detection","source":"@site/docs/commands/cli/cli-init.mdx","sourceDirName":"commands/cli","slug":"/commands/cli/cli-init","permalink":"/docs/zh/commands/cli/cli-init","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/cli/cli-init.mdx","tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"title":"/cli:cli-init","sidebar_label":"/cli:cli-init","sidebar_position":1,"description":"Initialize CLI configuration for workspace with automatic technology detection"},"sidebar":"docs","previous":{"title":"issue:convert-to-plan","permalink":"/docs/zh/commands/issue/issue-convert-to-plan"},"next":{"title":"/cli:codex-review","permalink":"/docs/zh/commands/cli/codex-review"}},{"id":"commands/cli/codex-review","title":"/cli:codex-review","description":"Interactive code review using Codex CLI with configurable review targets","source":"@site/docs/commands/cli/codex-review.mdx","sourceDirName":"commands/cli","slug":"/commands/cli/codex-review","permalink":"/docs/zh/commands/cli/codex-review","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/cli/codex-review.mdx","tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"title":"/cli:codex-review","sidebar_label":"/cli:codex-review","sidebar_position":2,"description":"Interactive code review using Codex CLI with configurable review targets"},"sidebar":"docs","previous":{"title":"/cli:cli-init","permalink":"/docs/zh/commands/cli/cli-init"},"next":{"title":"/memory:update-full","permalink":"/docs/zh/commands/memory/memory-update-full"}},{"id":"commands/general/ccw","title":"/ccw","description":"Main CCW workflow coordinator for intelligent command orchestration","source":"@site/docs/commands/general/ccw.mdx","sourceDirName":"commands/general","slug":"/commands/general/ccw","permalink":"/docs/zh/commands/general/ccw","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/general/ccw.mdx","tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"title":"/ccw","sidebar_label":"/ccw","sidebar_position":1,"description":"Main CCW workflow coordinator for intelligent command orchestration"},"sidebar":"docs","previous":{"title":"概览","permalink":"/docs/zh/overview"},"next":{"title":"/ccw-plan","permalink":"/docs/zh/commands/general/ccw-plan"}},{"id":"commands/general/ccw-coordinator","title":"/ccw-coordinator","description":"Generic command orchestration tool for CCW workflows","source":"@site/docs/commands/general/ccw-coordinator.mdx","sourceDirName":"commands/general","slug":"/commands/general/ccw-coordinator","permalink":"/docs/zh/commands/general/ccw-coordinator","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/general/ccw-coordinator.mdx","tags":[],"version":"current","sidebarPosition":4,"frontMatter":{"title":"/ccw-coordinator","sidebar_label":"/ccw-coordinator","sidebar_position":4,"description":"Generic command orchestration tool for CCW workflows"},"sidebar":"docs","previous":{"title":"/ccw-test","permalink":"/docs/zh/commands/general/ccw-test"},"next":{"title":"/ccw-debug","permalink":"/docs/zh/commands/general/ccw-debug"}},{"id":"commands/general/ccw-debug","title":"/ccw-debug","description":"Debug coordinator for intelligent debugging workflows","source":"@site/docs/commands/general/ccw-debug.mdx","sourceDirName":"commands/general","slug":"/commands/general/ccw-debug","permalink":"/docs/zh/commands/general/ccw-debug","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/general/ccw-debug.mdx","tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"/ccw-debug","sidebar_label":"/ccw-debug","sidebar_position":5,"description":"Debug coordinator for intelligent debugging workflows"},"sidebar":"docs","previous":{"title":"/ccw-coordinator","permalink":"/docs/zh/commands/general/ccw-coordinator"},"next":{"title":"/flow-create","permalink":"/docs/zh/commands/general/flow-create"}},{"id":"commands/general/ccw-plan","title":"/ccw-plan","description":"Planning coordinator for intelligent workflow selection","source":"@site/docs/commands/general/ccw-plan.mdx","sourceDirName":"commands/general","slug":"/commands/general/ccw-plan","permalink":"/docs/zh/commands/general/ccw-plan","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/general/ccw-plan.mdx","tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"title":"/ccw-plan","sidebar_label":"/ccw-plan","sidebar_position":2,"description":"Planning coordinator for intelligent workflow selection"},"sidebar":"docs","previous":{"title":"/ccw","permalink":"/docs/zh/commands/general/ccw"},"next":{"title":"/ccw-test","permalink":"/docs/zh/commands/general/ccw-test"}},{"id":"commands/general/ccw-test","title":"/ccw-test","description":"Test workflow coordinator for testing strategies","source":"@site/docs/commands/general/ccw-test.mdx","sourceDirName":"commands/general","slug":"/commands/general/ccw-test","permalink":"/docs/zh/commands/general/ccw-test","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/general/ccw-test.mdx","tags":[],"version":"current","sidebarPosition":3,"frontMatter":{"title":"/ccw-test","sidebar_label":"/ccw-test","sidebar_position":3,"description":"Test workflow coordinator for testing strategies"},"sidebar":"docs","previous":{"title":"/ccw-plan","permalink":"/docs/zh/commands/general/ccw-plan"},"next":{"title":"/ccw-coordinator","permalink":"/docs/zh/commands/general/ccw-coordinator"}},{"id":"commands/general/codex-coordinator","title":"/codex-coordinator","description":"Command orchestration tool for Codex workflows","source":"@site/docs/commands/general/codex-coordinator.mdx","sourceDirName":"commands/general","slug":"/commands/general/codex-coordinator","permalink":"/docs/zh/commands/general/codex-coordinator","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/general/codex-coordinator.mdx","tags":[],"version":"current","sidebarPosition":7,"frontMatter":{"title":"/codex-coordinator","sidebar_label":"/codex-coordinator","sidebar_position":7,"description":"Command orchestration tool for Codex workflows"},"sidebar":"docs","previous":{"title":"/flow-create","permalink":"/docs/zh/commands/general/flow-create"},"next":{"title":"issue:new","permalink":"/docs/zh/commands/issue/issue-new"}},{"id":"commands/general/flow-create","title":"/flow-create","description":"Generate workflow templates for flow-coordinator","source":"@site/docs/commands/general/flow-create.mdx","sourceDirName":"commands/general","slug":"/commands/general/flow-create","permalink":"/docs/zh/commands/general/flow-create","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/general/flow-create.mdx","tags":[],"version":"current","sidebarPosition":6,"frontMatter":{"title":"/flow-create","sidebar_label":"/flow-create","sidebar_position":6,"description":"Generate workflow templates for flow-coordinator"},"sidebar":"docs","previous":{"title":"/ccw-debug","permalink":"/docs/zh/commands/general/ccw-debug"},"next":{"title":"/codex-coordinator","permalink":"/docs/zh/commands/general/codex-coordinator"}},{"id":"commands/issue/issue-convert-to-plan","title":"issue:convert-to-plan","description":"Convert planning artifacts to issue solutions","source":"@site/docs/commands/issue/issue-convert-to-plan.md","sourceDirName":"commands/issue","slug":"/commands/issue/issue-convert-to-plan","permalink":"/docs/zh/commands/issue/issue-convert-to-plan","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/issue/issue-convert-to-plan.md","tags":[],"version":"current","sidebarPosition":7,"frontMatter":{"title":"issue:convert-to-plan","sidebar_label":"issue:convert-to-plan","sidebar_position":7,"description":"Convert planning artifacts to issue solutions"},"sidebar":"docs","previous":{"title":"issue:from-brainstorm","permalink":"/docs/zh/commands/issue/issue-from-brainstorm"},"next":{"title":"/cli:cli-init","permalink":"/docs/zh/commands/cli/cli-init"}},{"id":"commands/issue/issue-discover","title":"issue:discover","description":"Discover potential issues from multiple code analysis perspectives","source":"@site/docs/commands/issue/issue-discover.md","sourceDirName":"commands/issue","slug":"/commands/issue/issue-discover","permalink":"/docs/zh/commands/issue/issue-discover","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/issue/issue-discover.md","tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"title":"issue:discover","sidebar_label":"issue:discover","sidebar_position":2,"description":"Discover potential issues from multiple code analysis perspectives"},"sidebar":"docs","previous":{"title":"issue:new","permalink":"/docs/zh/commands/issue/issue-new"},"next":{"title":"issue:plan","permalink":"/docs/zh/commands/issue/issue-plan"}},{"id":"commands/issue/issue-execute","title":"issue:execute","description":"Execute issue queue with DAG-based parallel orchestration","source":"@site/docs/commands/issue/issue-execute.md","sourceDirName":"commands/issue","slug":"/commands/issue/issue-execute","permalink":"/docs/zh/commands/issue/issue-execute","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/issue/issue-execute.md","tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"issue:execute","sidebar_label":"issue:execute","sidebar_position":5,"description":"Execute issue queue with DAG-based parallel orchestration"},"sidebar":"docs","previous":{"title":"issue:queue","permalink":"/docs/zh/commands/issue/issue-queue"},"next":{"title":"issue:from-brainstorm","permalink":"/docs/zh/commands/issue/issue-from-brainstorm"}},{"id":"commands/issue/issue-from-brainstorm","title":"issue:from-brainstorm","description":"Convert brainstorm session ideas into issues with solutions","source":"@site/docs/commands/issue/issue-from-brainstorm.md","sourceDirName":"commands/issue","slug":"/commands/issue/issue-from-brainstorm","permalink":"/docs/zh/commands/issue/issue-from-brainstorm","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/issue/issue-from-brainstorm.md","tags":[],"version":"current","sidebarPosition":6,"frontMatter":{"title":"issue:from-brainstorm","sidebar_label":"issue:from-brainstorm","sidebar_position":6,"description":"Convert brainstorm session ideas into issues with solutions"},"sidebar":"docs","previous":{"title":"issue:execute","permalink":"/docs/zh/commands/issue/issue-execute"},"next":{"title":"issue:convert-to-plan","permalink":"/docs/zh/commands/issue/issue-convert-to-plan"}},{"id":"commands/issue/issue-new","title":"issue:new","description":"Create new issue with automatic categorization","source":"@site/docs/commands/issue/issue-new.md","sourceDirName":"commands/issue","slug":"/commands/issue/issue-new","permalink":"/docs/zh/commands/issue/issue-new","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/issue/issue-new.md","tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"title":"issue:new","sidebar_label":"issue:new","sidebar_position":1,"description":"Create new issue with automatic categorization"},"sidebar":"docs","previous":{"title":"/codex-coordinator","permalink":"/docs/zh/commands/general/codex-coordinator"},"next":{"title":"issue:discover","permalink":"/docs/zh/commands/issue/issue-discover"}},{"id":"commands/issue/issue-plan","title":"issue:plan","description":"Plan issue solutions with exploration and task breakdown","source":"@site/docs/commands/issue/issue-plan.md","sourceDirName":"commands/issue","slug":"/commands/issue/issue-plan","permalink":"/docs/zh/commands/issue/issue-plan","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/issue/issue-plan.md","tags":[],"version":"current","sidebarPosition":3,"frontMatter":{"title":"issue:plan","sidebar_label":"issue:plan","sidebar_position":3,"description":"Plan issue solutions with exploration and task breakdown"},"sidebar":"docs","previous":{"title":"issue:discover","permalink":"/docs/zh/commands/issue/issue-discover"},"next":{"title":"issue:queue","permalink":"/docs/zh/commands/issue/issue-queue"}},{"id":"commands/issue/issue-queue","title":"issue:queue","description":"Form execution queue from bound solutions with conflict resolution","source":"@site/docs/commands/issue/issue-queue.md","sourceDirName":"commands/issue","slug":"/commands/issue/issue-queue","permalink":"/docs/zh/commands/issue/issue-queue","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/issue/issue-queue.md","tags":[],"version":"current","sidebarPosition":4,"frontMatter":{"title":"issue:queue","sidebar_label":"issue:queue","sidebar_position":4,"description":"Form execution queue from bound solutions with conflict resolution"},"sidebar":"docs","previous":{"title":"issue:plan","permalink":"/docs/zh/commands/issue/issue-plan"},"next":{"title":"issue:execute","permalink":"/docs/zh/commands/issue/issue-execute"}},{"id":"commands/memory/memory-compact","title":"/memory:compact","description":"Compact session memory into structured text for recovery","source":"@site/docs/commands/memory/memory-compact.mdx","sourceDirName":"commands/memory","slug":"/commands/memory/memory-compact","permalink":"/docs/zh/commands/memory/memory-compact","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/memory/memory-compact.mdx","tags":[],"version":"current","sidebarPosition":6,"frontMatter":{"title":"/memory:compact","sidebar_label":"/memory:compact","sidebar_position":6,"description":"Compact session memory into structured text for recovery"},"sidebar":"docs","previous":{"title":"/memory:docs-related-cli","permalink":"/docs/zh/commands/memory/memory-docs-related-cli"},"next":{"title":"Introduction","permalink":"/docs/zh/workflows/introduction"}},{"id":"commands/memory/memory-docs-full-cli","title":"/memory:docs-full-cli","description":"Generate full CLI documentation for all project modules","source":"@site/docs/commands/memory/memory-docs-full-cli.mdx","sourceDirName":"commands/memory","slug":"/commands/memory/memory-docs-full-cli","permalink":"/docs/zh/commands/memory/memory-docs-full-cli","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/memory/memory-docs-full-cli.mdx","tags":[],"version":"current","sidebarPosition":4,"frontMatter":{"title":"/memory:docs-full-cli","sidebar_label":"/memory:docs-full-cli","sidebar_position":4,"description":"Generate full CLI documentation for all project modules"},"sidebar":"docs","previous":{"title":"/memory:load","permalink":"/docs/zh/commands/memory/memory-load"},"next":{"title":"/memory:docs-related-cli","permalink":"/docs/zh/commands/memory/memory-docs-related-cli"}},{"id":"commands/memory/memory-docs-related-cli","title":"/memory:docs-related-cli","description":"Generate CLI documentation for git-changed modules","source":"@site/docs/commands/memory/memory-docs-related-cli.mdx","sourceDirName":"commands/memory","slug":"/commands/memory/memory-docs-related-cli","permalink":"/docs/zh/commands/memory/memory-docs-related-cli","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/memory/memory-docs-related-cli.mdx","tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"/memory:docs-related-cli","sidebar_label":"/memory:docs-related-cli","sidebar_position":5,"description":"Generate CLI documentation for git-changed modules"},"sidebar":"docs","previous":{"title":"/memory:docs-full-cli","permalink":"/docs/zh/commands/memory/memory-docs-full-cli"},"next":{"title":"/memory:compact","permalink":"/docs/zh/commands/memory/memory-compact"}},{"id":"commands/memory/memory-load","title":"/memory:load","description":"Load project context and core content into memory","source":"@site/docs/commands/memory/memory-load.mdx","sourceDirName":"commands/memory","slug":"/commands/memory/memory-load","permalink":"/docs/zh/commands/memory/memory-load","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/memory/memory-load.mdx","tags":[],"version":"current","sidebarPosition":3,"frontMatter":{"title":"/memory:load","sidebar_label":"/memory:load","sidebar_position":3,"description":"Load project context and core content into memory"},"sidebar":"docs","previous":{"title":"/memory:update-related","permalink":"/docs/zh/commands/memory/memory-update-related"},"next":{"title":"/memory:docs-full-cli","permalink":"/docs/zh/commands/memory/memory-docs-full-cli"}},{"id":"commands/memory/memory-update-full","title":"/memory:update-full","description":"Update CLAUDE.md for all project modules using batched agent execution","source":"@site/docs/commands/memory/memory-update-full.mdx","sourceDirName":"commands/memory","slug":"/commands/memory/memory-update-full","permalink":"/docs/zh/commands/memory/memory-update-full","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/memory/memory-update-full.mdx","tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"title":"/memory:update-full","sidebar_label":"/memory:update-full","sidebar_position":1,"description":"Update CLAUDE.md for all project modules using batched agent execution"},"sidebar":"docs","previous":{"title":"/cli:codex-review","permalink":"/docs/zh/commands/cli/codex-review"},"next":{"title":"/memory:update-related","permalink":"/docs/zh/commands/memory/memory-update-related"}},{"id":"commands/memory/memory-update-related","title":"/memory:update-related","description":"Update CLAUDE.md for git-changed modules using batched execution","source":"@site/docs/commands/memory/memory-update-related.mdx","sourceDirName":"commands/memory","slug":"/commands/memory/memory-update-related","permalink":"/docs/zh/commands/memory/memory-update-related","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/commands/memory/memory-update-related.mdx","tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"title":"/memory:update-related","sidebar_label":"/memory:update-related","sidebar_position":2,"description":"Update CLAUDE.md for git-changed modules using batched execution"},"sidebar":"docs","previous":{"title":"/memory:update-full","permalink":"/docs/zh/commands/memory/memory-update-full"},"next":{"title":"/memory:load","permalink":"/docs/zh/commands/memory/memory-load"}},{"id":"faq","title":"Frequently Asked Questions","description":"Common questions about CCW, workflows, commands, and troubleshooting.","source":"@site/docs/faq.mdx","sourceDirName":".","slug":"/faq","permalink":"/docs/zh/faq","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/faq.mdx","tags":[],"version":"current","sidebarPosition":99,"frontMatter":{"title":"Frequently Asked Questions","sidebar_label":"FAQ","sidebar_position":99},"sidebar":"docs","previous":{"title":"Level 5: Intelligent","permalink":"/docs/zh/workflows/level-5-intelligent"}},{"id":"index","title":"CCW 帮助文档","description":"工作流","source":"@site/i18n/zh/docusaurus-plugin-content-docs/current/index.mdx","sourceDirName":".","slug":"/","permalink":"/docs/zh/","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/index.mdx","tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"title":"CCW 帮助文档","sidebar_label":"首页","sidebar_position":1},"sidebar":"docs","next":{"title":"概览","permalink":"/docs/zh/overview"}},{"id":"overview","title":"欢迎使用 CCW","description":"CCW 是一个专业的工作流自动化平台，结合了 AI 驱动的智能与结构化开发工作流。凭借 40+ 命令和 15 个集成工作流，CCW 彻底改变了您构建、测试和交付软件的方式。","source":"@site/i18n/zh/docusaurus-plugin-content-docs/current/overview.mdx","sourceDirName":".","slug":"/overview","permalink":"/docs/zh/overview","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/overview.mdx","tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"title":"欢迎使用 CCW","sidebar_label":"概览","sidebar_position":1},"sidebar":"docs","previous":{"title":"首页","permalink":"/docs/zh/"},"next":{"title":"/ccw","permalink":"/docs/zh/commands/general/ccw"}},{"id":"workflows/faq","title":"工作流常见问题","description":"工作流使用中的常见问题和解答","source":"@site/i18n/zh/docusaurus-plugin-content-docs/current/workflows/faq.mdx","sourceDirName":"workflows","slug":"/workflows/faq","permalink":"/docs/zh/workflows/faq","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/workflows/faq.mdx","tags":[],"version":"current","sidebarPosition":7,"frontMatter":{"title":"工作流常见问题","description":"工作流使用中的常见问题和解答","sidebar_position":7}},{"id":"workflows/introduction","title":"工作流介绍","description":"CCW 工作流全面概述 - 从急速执行到智能编排","source":"@site/i18n/zh/docusaurus-plugin-content-docs/current/workflows/introduction.mdx","sourceDirName":"workflows","slug":"/workflows/introduction","permalink":"/docs/zh/workflows/introduction","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/workflows/introduction.mdx","tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"title":"工作流介绍","description":"CCW 工作流全面概述 - 从急速执行到智能编排","sidebar_position":1},"sidebar":"docs","previous":{"title":"/memory:compact","permalink":"/docs/zh/commands/memory/memory-compact"},"next":{"title":"Level 1: Ultra Lightweight","permalink":"/docs/zh/workflows/level-1-ultra-lightweight"}},{"id":"workflows/level-1-ultra-lightweight","title":"层级 1: 超轻量工作流","description":"急速执行工作流 - 零开销直接执行","source":"@site/i18n/zh/docusaurus-plugin-content-docs/current/workflows/level-1-ultra-lightweight.mdx","sourceDirName":"workflows","slug":"/workflows/level-1-ultra-lightweight","permalink":"/docs/zh/workflows/level-1-ultra-lightweight","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/workflows/level-1-ultra-lightweight.mdx","tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"title":"层级 1: 超轻量工作流","description":"急速执行工作流 - 零开销直接执行","sidebar_position":2},"sidebar":"docs","previous":{"title":"Introduction","permalink":"/docs/zh/workflows/introduction"},"next":{"title":"Level 2: Rapid","permalink":"/docs/zh/workflows/level-2-rapid"}},{"id":"workflows/level-2-rapid","title":"层级 2: 快速工作流","description":"轻量规划和漏洞诊断工作流 - 适用于单模块功能","source":"@site/i18n/zh/docusaurus-plugin-content-docs/current/workflows/level-2-rapid.mdx","sourceDirName":"workflows","slug":"/workflows/level-2-rapid","permalink":"/docs/zh/workflows/level-2-rapid","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/workflows/level-2-rapid.mdx","tags":[],"version":"current","sidebarPosition":3,"frontMatter":{"title":"层级 2: 快速工作流","description":"轻量规划和漏洞诊断工作流 - 适用于单模块功能","sidebar_position":3},"sidebar":"docs","previous":{"title":"Level 1: Ultra Lightweight","permalink":"/docs/zh/workflows/level-1-ultra-lightweight"},"next":{"title":"Level 3: Standard","permalink":"/docs/zh/workflows/level-3-standard"}},{"id":"workflows/level-3-standard","title":"层级 3: 标准工作流","description":"标准规划工作流 - 完整规划和 TDD 开发","source":"@site/i18n/zh/docusaurus-plugin-content-docs/current/workflows/level-3-standard.mdx","sourceDirName":"workflows","slug":"/workflows/level-3-standard","permalink":"/docs/zh/workflows/level-3-standard","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/workflows/level-3-standard.mdx","tags":[],"version":"current","sidebarPosition":4,"frontMatter":{"title":"层级 3: 标准工作流","description":"标准规划工作流 - 完整规划和 TDD 开发","sidebar_position":4},"sidebar":"docs","previous":{"title":"Level 2: Rapid","permalink":"/docs/zh/workflows/level-2-rapid"},"next":{"title":"Level 4: Brainstorm","permalink":"/docs/zh/workflows/level-4-brainstorm"}},{"id":"workflows/level-4-brainstorm","title":"层级 4: 头脑风暴工作流","description":"多角色头脑风暴工作流 - 协作探索和创意生成","source":"@site/i18n/zh/docusaurus-plugin-content-docs/current/workflows/level-4-brainstorm.mdx","sourceDirName":"workflows","slug":"/workflows/level-4-brainstorm","permalink":"/docs/zh/workflows/level-4-brainstorm","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/workflows/level-4-brainstorm.mdx","tags":[],"version":"current","sidebarPosition":5,"frontMatter":{"title":"层级 4: 头脑风暴工作流","description":"多角色头脑风暴工作流 - 协作探索和创意生成","sidebar_position":5},"sidebar":"docs","previous":{"title":"Level 3: Standard","permalink":"/docs/zh/workflows/level-3-standard"},"next":{"title":"Level 5: Intelligent","permalink":"/docs/zh/workflows/level-5-intelligent"}},{"id":"workflows/level-5-intelligent","title":"层级 5: 智能工作流","description":"智能编排工作流 - 自动分析和推荐","source":"@site/i18n/zh/docusaurus-plugin-content-docs/current/workflows/level-5-intelligent.mdx","sourceDirName":"workflows","slug":"/workflows/level-5-intelligent","permalink":"/docs/zh/workflows/level-5-intelligent","draft":false,"unlisted":false,"editUrl":"https://github.com/ccw/docs/tree/main/docs/workflows/level-5-intelligent.mdx","tags":[],"version":"current","sidebarPosition":6,"frontMatter":{"title":"层级 5: 智能工作流","description":"智能编排工作流 - 自动分析和推荐","sidebar_position":6},"sidebar":"docs","previous":{"title":"Level 4: Brainstorm","permalink":"/docs/zh/workflows/level-4-brainstorm"},"next":{"title":"FAQ","permalink":"/docs/zh/faq"}}],"drafts":[],"sidebars":{"docs":[{"type":"doc","id":"index","label":"Home","translatable":true},{"type":"doc","id":"overview","label":"概览","translatable":true},{"type":"category","label":"命令","collapsible":true,"collapsed":false,"items":[{"type":"category","label":"通用命令","collapsible":true,"collapsed":false,"items":[{"type":"doc","id":"commands/general/ccw","label":"ccw","translatable":true},{"type":"doc","id":"commands/general/ccw-plan","label":"ccw-plan","translatable":true},{"type":"doc","id":"commands/general/ccw-test","label":"ccw-test","translatable":true},{"type":"doc","id":"commands/general/ccw-coordinator","label":"ccw-coordinator","translatable":true},{"type":"doc","id":"commands/general/ccw-debug","label":"ccw-debug","translatable":true},{"type":"doc","id":"commands/general/flow-create","label":"flow-create","translatable":true},{"type":"doc","id":"commands/general/codex-coordinator","label":"codex-coordinator","translatable":true}]},{"type":"category","label":"Issue 命令","collapsible":true,"collapsed":false,"items":[{"type":"doc","id":"commands/issue/issue-new","label":"issue-new","translatable":true},{"type":"doc","id":"commands/issue/issue-discover","label":"issue-discover","translatable":true},{"type":"doc","id":"commands/issue/issue-plan","label":"issue-plan","translatable":true},{"type":"doc","id":"commands/issue/issue-queue","label":"issue-queue","translatable":true},{"type":"doc","id":"commands/issue/issue-execute","label":"issue-execute","translatable":true},{"type":"doc","id":"commands/issue/issue-from-brainstorm","label":"issue-from-brainstorm","translatable":true},{"type":"doc","id":"commands/issue/issue-convert-to-plan","label":"issue-convert-to-plan","translatable":true}]},{"type":"category","label":"CLI 命令","collapsible":true,"collapsed":false,"items":[{"type":"doc","id":"commands/cli/cli-init","label":"cli-init","translatable":true},{"type":"doc","id":"commands/cli/codex-review","label":"codex-review","translatable":true}]},{"type":"category","label":"Memory 命令","collapsible":true,"collapsed":false,"items":[{"type":"doc","id":"commands/memory/memory-update-full","label":"memory-update-full","translatable":true},{"type":"doc","id":"commands/memory/memory-update-related","label":"memory-update-related","translatable":true},{"type":"doc","id":"commands/memory/memory-load","label":"memory-load","translatable":true},{"type":"doc","id":"commands/memory/memory-docs-full-cli","label":"memory-docs-full-cli","translatable":true},{"type":"doc","id":"commands/memory/memory-docs-related-cli","label":"memory-docs-related-cli","translatable":true},{"type":"doc","id":"commands/memory/memory-compact","label":"memory-compact","translatable":true}]}]},{"type":"category","label":"工作流","collapsible":true,"collapsed":false,"items":[{"type":"doc","id":"workflows/introduction","label":"介绍","translatable":true},{"type":"doc","id":"workflows/level-1-ultra-lightweight","label":"级别 1：超轻量","translatable":true},{"type":"doc","id":"workflows/level-2-rapid","label":"级别 2：快速","translatable":true},{"type":"doc","id":"workflows/level-3-standard","label":"级别 3：标准","translatable":true},{"type":"doc","id":"workflows/level-4-brainstorm","label":"级别 4：头脑风暴","translatable":true},{"type":"doc","id":"workflows/level-5-intelligent","label":"级别 5：智能","translatable":true}]},{"type":"doc","id":"faq","label":"常见问题","translatable":true}]}}]}},"docusaurus-plugin-content-pages":{"default":null},"docusaurus-plugin-debug":{},"docusaurus-plugin-svgr":{},"docusaurus-theme-classic":{},"docusaurus-bootstrap-plugin":{},"docusaurus-mdx-fallback-plugin":{}}} \ No newline at end of file diff --git a/ccw/docs-site/package.json b/ccw/docs-site/package.json index 2c4e6d13..f76a159f 100644 --- a/ccw/docs-site/package.json +++ b/ccw/docs-site/package.json @@ -6,11 +6,14 @@ "scripts": { "docusaurus": "docusaurus", "start": "docusaurus start", + "start:en": "docusaurus start --locale en", + "start:zh": "docusaurus start --locale zh", "build": "docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", "serve": "docusaurus serve", + "serve:build": "docusaurus serve --build", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids" }, diff --git a/ccw/src/commands/serve.ts b/ccw/src/commands/serve.ts index fb0821cb..1418916c 100644 --- a/ccw/src/commands/serve.ts +++ b/ccw/src/commands/serve.ts @@ -62,7 +62,7 @@ export async function serveCommand(options: ServeOptions): Promise { } catch (error) { console.log(chalk.yellow(`\n Warning: Failed to start docs site: ${error}`)); console.log(chalk.gray(` The /docs endpoint will not be available.`)); - console.log(chalk.gray(` You can start it manually: cd docs-site && npm start\n`)); + console.log(chalk.gray(` You can start it manually: cd ccw/docs-site && npm run serve -- --build --port 3001 --no-open\n`)); } } diff --git a/ccw/src/utils/docs-frontend.ts b/ccw/src/utils/docs-frontend.ts index c9fd0c10..a4c2477f 100644 --- a/ccw/src/utils/docs-frontend.ts +++ b/ccw/src/utils/docs-frontend.ts @@ -13,6 +13,13 @@ let docsPort: number | null = null; // Default Docusaurus port const DEFAULT_DOCS_PORT = 3001; +type DocsStartMode = 'serve' | 'start'; + +function normalizeDocsStartMode(mode: string | undefined): DocsStartMode { + const normalized = (mode ?? '').trim().toLowerCase(); + return normalized === 'start' ? 'start' : 'serve'; +} + /** * Start Docusaurus documentation development server * @param port - Port to run Docusaurus server on (default: 3001) @@ -55,15 +62,35 @@ export async function startDocsSite(port: number = DEFAULT_DOCS_PORT): Promise { if (docsProcess) { console.log(chalk.yellow(' Stopping docs site...')); - // Try graceful shutdown first - docsProcess.kill('SIGTERM'); + const pid = docsProcess.pid; + + // On Windows with shell: true, killing the shell process can orphan children. + // Prefer taskkill to terminate the entire process tree. + if (process.platform === 'win32' && pid) { + try { + const { exec } = await import('child_process'); + await new Promise((resolve) => { + exec(`taskkill /T /PID ${pid}`, () => resolve()); + }); + } catch { + // Fall back to SIGTERM below + } + } else { + // Try graceful shutdown first + docsProcess.kill('SIGTERM'); + } // Wait up to 5 seconds for graceful shutdown await new Promise((resolve) => { @@ -184,13 +253,12 @@ export async function stopDocsSite(): Promise { }); // Force kill if still running - if (docsProcess && !docsProcess.killed) { + if (docsProcess && docsProcess.exitCode === null) { // On Windows with shell: true, we need to kill the entire process group if (process.platform === 'win32') { try { // Use taskkill to forcefully terminate the process tree const { exec } = await import('child_process'); - const pid = docsProcess.pid; if (pid) { await new Promise((resolve) => { exec(`taskkill /F /T /PID ${pid}`, (err) => { diff --git a/ccw/src/utils/react-frontend.ts b/ccw/src/utils/react-frontend.ts index 560cc7ae..e6e3fd55 100644 --- a/ccw/src/utils/react-frontend.ts +++ b/ccw/src/utils/react-frontend.ts @@ -152,8 +152,23 @@ export async function stopReactFrontend(): Promise { if (reactProcess) { console.log(chalk.yellow(' Stopping React frontend...')); - // Try graceful shutdown first - reactProcess.kill('SIGTERM'); + const pid = reactProcess.pid; + + // On Windows with shell: true, killing the shell process can orphan children. + // Prefer taskkill to terminate the entire process tree. + if (process.platform === 'win32' && pid) { + try { + const { exec } = await import('child_process'); + await new Promise((resolve) => { + exec(`taskkill /T /PID ${pid}`, () => resolve()); + }); + } catch { + // Fall back to SIGTERM below + } + } else { + // Try graceful shutdown first + reactProcess.kill('SIGTERM'); + } // Wait up to 5 seconds for graceful shutdown await new Promise((resolve) => { @@ -168,13 +183,12 @@ export async function stopReactFrontend(): Promise { }); // Force kill if still running - if (reactProcess && !reactProcess.killed) { + if (reactProcess && reactProcess.exitCode === null) { // On Windows with shell: true, we need to kill the entire process group if (process.platform === 'win32') { try { // Use taskkill to forcefully terminate the process tree const { exec } = await import('child_process'); - const pid = reactProcess.pid; if (pid) { await new Promise((resolve) => { exec(`taskkill /F /T /PID ${pid}`, (err) => { @@ -212,4 +226,4 @@ export function getReactFrontendStatus(): { running: boolean; port: number | nul running: reactProcess !== null && !reactProcess.killed, port: reactPort }; -} \ No newline at end of file +} diff --git a/package.json b/package.json index 628422b4..e85e85b6 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,9 @@ "frontend": "npm run dev --workspace=ccw/frontend", "frontend:build": "npm run build --workspace=ccw/frontend", "docs": "npm run start --workspace=ccw/docs-site", + "docs:en": "npm run start --workspace=ccw/docs-site -- --locale en --port 3001 --no-open", + "docs:zh": "npm run start --workspace=ccw/docs-site -- --locale zh --port 3001 --no-open", + "docs:serve": "npm run serve --workspace=ccw/docs-site -- --build --port 3001 --no-open", "docs:build": "npm run build --workspace=ccw/docs-site", "ws:install": "npm install", "ws:all": "concurrently \"npm run frontend\" \"npm run docs\" --names \"FRONTEND,DOCS\" --prefix-colors \"blue,green\"",