diff --git a/.ccw/workflows/cli-templates/schemas/solution-schema.json b/.ccw/workflows/cli-templates/schemas/solution-schema.json index c136d9f2..2bb1bf33 100644 --- a/.ccw/workflows/cli-templates/schemas/solution-schema.json +++ b/.ccw/workflows/cli-templates/schemas/solution-schema.json @@ -24,7 +24,7 @@ "description": "Task breakdown for this solution", "items": { "type": "object", - "required": ["id", "title", "scope", "action", "implementation", "acceptance"], + "required": ["id", "title", "scope", "action", "implementation"], "properties": { "id": { "type": "string", @@ -46,8 +46,26 @@ "type": "string", "description": "1-2 sentences describing what to implement" }, + "files": { + "type": "array", + "description": "Files affected by this task (preferred over modification_points)", + "items": { + "type": "object", + "required": ["path"], + "properties": { + "path": { "type": "string", "description": "File path relative to project root" }, + "action": { "type": "string", "enum": ["modify", "create", "delete"], "description": "Type of file operation" }, + "target": { "type": "string", "description": "Target symbol or location within file" }, + "change": { "type": "string", "description": "Description of the change" }, + "changes": { "type": "array", "items": { "type": "string" }, "description": "Multiple changes to the file" }, + "conflict_risk": { "type": "string", "enum": ["low", "medium", "high"], "description": "Risk of merge conflict" } + } + } + }, "modification_points": { "type": "array", + "deprecated": true, + "description": "DEPRECATED: Use 'files' instead. Legacy field for backward compatibility.", "items": { "type": "object", "properties": { @@ -69,7 +87,9 @@ "unit": { "type": "array", "items": { "type": "string" } }, "integration": { "type": "array", "items": { "type": "string" } }, "commands": { "type": "array", "items": { "type": "string" } }, - "coverage_target": { "type": "number" } + "coverage_target": { "type": "number" }, + "manual_checks": { "type": "array", "items": { "type": "string" }, "description": "Manual verification steps" }, + "success_metrics": { "type": "array", "items": { "type": "string" }, "description": "Success metrics for the task" } } }, "regression": { @@ -77,10 +97,25 @@ "items": { "type": "string" }, "description": "Regression check points" }, + "convergence": { + "type": "object", + "description": "Convergence criteria & verification (preferred over acceptance)", + "required": ["criteria"], + "properties": { + "criteria": { "type": "array", "items": { "type": "string" } }, + "verification": { + "oneOf": [ + { "type": "string" }, + { "type": "array", "items": { "type": "string" } } + ] + }, + "definition_of_done": { "type": "string" } + } + }, "acceptance": { "type": "object", - "description": "Acceptance criteria & verification", - "required": ["criteria", "verification"], + "deprecated": true, + "description": "DEPRECATED: Use 'convergence' instead. Legacy field for backward compatibility.", "properties": { "criteria": { "type": "array", "items": { "type": "string" } }, "verification": { "type": "array", "items": { "type": "string" } }, @@ -105,17 +140,41 @@ }, "estimated_minutes": { "type": "integer", - "description": "Estimated time to complete" + "description": "DEPRECATED: Use 'effort' instead. Estimated time to complete." + }, + "effort": { + "type": "string", + "enum": ["small", "medium", "large", "xlarge"], + "description": "Effort estimate for the task" }, "status": { "type": "string", "description": "Task status (optional, for tracking)" }, "priority": { - "type": "integer", - "minimum": 1, - "maximum": 5, - "default": 3 + "oneOf": [ + { "type": "string", "enum": ["critical", "high", "medium", "low"] }, + { "type": "integer", "minimum": 1, "maximum": 5 } + ], + "default": "medium", + "description": "Task priority. Prefer string enum; integer 1-5 accepted for backward compatibility." + } + }, + "anyOf": [ + { "required": ["convergence"] }, + { "required": ["acceptance"] } + ], + "_migration": { + "description": "Field migration mapping from legacy to current format", + "mappings": { + "modification_points[].file": "files[].path", + "modification_points[].target": "files[].target", + "modification_points[].change": "files[].change", + "acceptance.criteria": "convergence.criteria", + "acceptance.verification": "convergence.verification", + "acceptance.manual_checks": "test.manual_checks", + "priority (integer 1-5)": "priority (string enum)", + "estimated_minutes": "effort" } } } diff --git a/.claude/agents/issue-plan-agent.md b/.claude/agents/issue-plan-agent.md index 8a447458..6aa853fb 100644 --- a/.claude/agents/issue-plan-agent.md +++ b/.claude/agents/issue-plan-agent.md @@ -226,13 +226,13 @@ function decomposeTasks(issue, exploration) { scope: inferScope(group), // Module path action: inferAction(group), // Create | Update | Implement | ... description: group.description, - modification_points: mapModificationPoints(group), + files: mapFiles(group), // [{path, target, change, action?, conflict_risk?}] implementation: generateSteps(group), // Step-by-step guide test: { unit: generateUnitTests(group), commands: ['npm test'] }, - acceptance: { + convergence: { criteria: generateCriteria(group), // Quantified checklist verification: generateVerification(group) }, @@ -242,7 +242,7 @@ function decomposeTasks(issue, exploration) { message_template: generateCommitMsg(group) }, depends_on: inferDependencies(group, tasks), - priority: calculatePriority(group) // 1-5 (1=highest) + priority: calculatePriorityEnum(group) // "critical"|"high"|"medium"|"low" })); // GitHub Reply Task: Add final task if issue has github_url @@ -254,20 +254,20 @@ function decomposeTasks(issue, exploration) { scope: 'github', action: 'Notify', description: `Comment on GitHub issue to report completion status`, - modification_points: [], + files: [], implementation: [ `Generate completion summary (tasks completed, files changed)`, `Post comment via: gh issue comment ${issue.github_number || extractNumber(issue.github_url)} --body "..."`, `Include: solution approach, key changes, verification results` ], test: { unit: [], commands: [] }, - acceptance: { + convergence: { criteria: ['GitHub comment posted successfully', 'Comment includes completion summary'], verification: ['Check GitHub issue for new comment'] }, commit: null, // No commit for notification task depends_on: lastTaskId ? [lastTaskId] : [], // Depends on last implementation task - priority: 5 // Lowest priority (run last) + priority: "low" // Lowest priority (run last) }); } @@ -370,10 +370,10 @@ Each line is a solution JSON containing tasks. Schema: `cat ~/.ccw/workflows/cli ### 3.2 Validation Checklist - [ ] ACE search performed for each issue -- [ ] All modification_points verified against codebase +- [ ] All files[] paths verified against codebase - [ ] Tasks have 2+ implementation steps - [ ] All 5 lifecycle phases present -- [ ] Quantified acceptance criteria with verification +- [ ] Quantified convergence criteria with verification - [ ] Dependencies form valid DAG - [ ] Commit follows conventional commits @@ -389,7 +389,7 @@ Each line is a solution JSON containing tasks. Schema: `cat ~/.ccw/workflows/cli 4. Fetch issue details via `ccw issue status --json` 5. **Analyze failure history**: Check `issue.feedback` for type='failure', stage='execute' 6. **For replanning**: Reference previous failures in `solution.approach`, add prevention steps -7. Quantify acceptance.criteria with testable conditions +7. Quantify convergence.criteria with testable conditions 8. Validate DAG before output 9. Evaluate each solution with `analysis` and `score` 10. Write solutions to `.workflow/issues/solutions/{issue-id}.jsonl` (append mode) diff --git a/.claude/commands/codex-coordinator.md b/.claude/commands/codex-coordinator.md deleted file mode 100644 index 4d0afd23..00000000 --- a/.claude/commands/codex-coordinator.md +++ /dev/null @@ -1,513 +0,0 @@ ---- -name: codex-coordinator -description: Command orchestration tool for Codex - analyze requirements, recommend command chain, execute sequentially with state persistence -argument-hint: "TASK=\"\" [--depth=standard|deep] [--auto-confirm] [--verbose]" ---- - -# Codex Coordinator Command - -Interactive orchestration tool for Codex commands: analyze task → discover commands → recommend chain → execute sequentially → track state. - -**Execution Model**: Intelligent agent-driven workflow. Claude analyzes each phase and orchestrates command execution. - -## Core Concept: Minimum Execution Units (最小执行单元) - -### What is a Minimum Execution Unit? - -**Definition**: A set of commands that must execute together as an atomic group to achieve a meaningful workflow milestone. Splitting these commands breaks the logical flow and creates incomplete states. - -**Why This Matters**: -- **Prevents Incomplete States**: Avoid stopping after task generation without execution -- **User Experience**: User gets complete results, not intermediate artifacts requiring manual follow-up -- **Workflow Integrity**: Maintains logical coherence of multi-step operations - -### Codex Minimum Execution Units - -**Planning + Execution Units** (规划+执行单元): - -| Unit Name | Commands | Purpose | Output | -|-----------|----------|---------|--------| -| **Quick Implementation** | lite-plan-a → execute | Lightweight plan and immediate execution | Working code | -| **Bug Fix** | lite-fix → execute | Quick bug diagnosis and fix execution | Fixed code | -| **Issue Workflow** | issue-discover → issue-plan → issue-queue → issue-execute | Complete issue lifecycle | Completed issues | -| **Discovery & Analysis** | issue-discover → issue-discover-by-prompt | Issue discovery with multiple perspectives | Generated issues | -| **Brainstorm to Execution** | brainstorm-with-file → execute | Brainstorm ideas then implement | Working code | - -**With-File Workflows** (文档化单元): - -| Unit Name | Commands | Purpose | Output | -|-----------|----------|---------|--------| -| **Brainstorm With File** | brainstorm-with-file | Multi-perspective ideation with documentation | brainstorm.md | -| **Debug With File** | debug-with-file | Hypothesis-driven debugging with documentation | understanding.md | -| **Analyze With File** | analyze-with-file | Collaborative analysis with documentation | discussion.md | -| **Clean & Analyze** | clean → analyze-with-file | Cleanup then analyze | Cleaned code + analysis | - -### Command-to-Unit Mapping (命令与最小单元的映射) - -| Command | Precedes | Atomic Units | -|---------|----------|--------------| -| lite-plan-a | execute, brainstorm-with-file | Quick Implementation | -| lite-fix | execute | Bug Fix | -| issue-discover | issue-plan | Issue Workflow | -| issue-plan | issue-queue | Issue Workflow | -| issue-queue | issue-execute | Issue Workflow | -| brainstorm-with-file | execute, issue-execute | Brainstorm to Execution | -| debug-with-file | execute | Debug With File | -| analyze-with-file | (standalone) | Analyze With File | -| clean | analyze-with-file, execute | Clean & Analyze | -| quick-plan-with-file | execute | Quick Planning with File | -| merge-plans-with-file | execute | Merge Multiple Plans | -| unified-execute-with-file | (terminal) | Execute with File Tracking | - -### Atomic Group Rules - -1. **Never Split Units**: Coordinator must recommend complete units, not partial chains -2. **Multi-Unit Participation**: Some commands can participate in multiple units -3. **User Override**: User can explicitly request partial execution (advanced mode) -4. **Visualization**: Pipeline view shows unit boundaries with 【 】markers -5. **Validation**: Before execution, verify all unit commands are included - -**Example Pipeline with Units**: -``` -需求 → 【lite-plan-a → execute】→ 代码 → 【issue-discover → issue-plan → issue-queue → issue-execute】→ 完成 - └──── Quick Implementation ────┘ └────────── Issue Workflow ─────────┘ -``` - -## 3-Phase Workflow - -### Phase 1: Analyze Requirements - -Parse task to extract: goal, scope, complexity, and task type. - -```javascript -function analyzeRequirements(taskDescription) { - return { - goal: extractMainGoal(taskDescription), // e.g., "Fix login bug" - scope: extractScope(taskDescription), // e.g., ["auth", "login"] - complexity: determineComplexity(taskDescription), // 'simple' | 'medium' | 'complex' - task_type: detectTaskType(taskDescription) // See task type patterns below - }; -} - -// Task Type Detection Patterns -function detectTaskType(text) { - // Priority order (first match wins) - if (/fix|bug|error|crash|fail|debug|diagnose/.test(text)) return 'bugfix'; - if (/生成|generate|discover|找出|issue|问题/.test(text)) return 'discovery'; - if (/plan|规划|设计|design|analyze|分析/.test(text)) return 'analysis'; - if (/清理|cleanup|clean|refactor|重构/.test(text)) return 'cleanup'; - if (/头脑|brainstorm|创意|ideation/.test(text)) return 'brainstorm'; - if (/合并|merge|combine|batch/.test(text)) return 'batch-planning'; - return 'feature'; // Default -} - -// Complexity Assessment -function determineComplexity(text) { - let score = 0; - if (/refactor|重构|migrate|迁移|architect|架构|system|系统/.test(text)) score += 2; - if (/multiple|多个|across|跨|all|所有|entire|整个/.test(text)) score += 2; - if (/integrate|集成|api|database|数据库/.test(text)) score += 1; - if (/security|安全|performance|性能|scale|扩展/.test(text)) score += 1; - return score >= 4 ? 'complex' : score >= 2 ? 'medium' : 'simple'; -} -``` - -**Display to user**: -``` -Analysis Complete: - Goal: [extracted goal] - Scope: [identified areas] - Complexity: [level] - Task Type: [detected type] -``` - -### Phase 2: Discover Commands & Recommend Chain - -Dynamic command chain assembly using task type and complexity matching. - -#### Available Codex Commands (Discovery) - -All commands from `~/.codex/prompts/`: -- **Planning**: @~/.codex/prompts/lite-plan-a.md, @~/.codex/prompts/lite-plan-b.md, @~/.codex/prompts/lite-plan-c.md, @~/.codex/prompts/quick-plan-with-file.md, @~/.codex/prompts/merge-plans-with-file.md -- **Execution**: @~/.codex/prompts/execute.md, @~/.codex/prompts/unified-execute-with-file.md -- **Bug Fixes**: @~/.codex/prompts/lite-fix.md, @~/.codex/prompts/debug-with-file.md -- **Discovery**: @~/.codex/prompts/issue-discover.md, @~/.codex/prompts/issue-discover-by-prompt.md, @~/.codex/prompts/issue-plan.md, @~/.codex/prompts/issue-queue.md, @~/.codex/prompts/issue-execute.md -- **Analysis**: @~/.codex/prompts/analyze-with-file.md -- **Brainstorming**: @~/.codex/prompts/brainstorm-with-file.md, @~/.codex/prompts/brainstorm-to-cycle.md -- **Cleanup**: @~/.codex/prompts/clean.md, @~/.codex/prompts/compact.md - -#### Recommendation Algorithm - -```javascript -async function recommendCommandChain(analysis) { - // Step 1: 根据任务类型确定流程 - const { inputPort, outputPort } = determinePortFlow(analysis.task_type, analysis.complexity); - - // Step 2: Claude 根据命令特性和任务特征，智能选择命令序列 - const chain = selectChainByTaskType(analysis); - - return chain; -} - -// 任务类型对应的端口流 -function determinePortFlow(taskType, complexity) { - const flows = { - 'bugfix': { flow: ['lite-fix', 'execute'], depth: complexity === 'complex' ? 'deep' : 'standard' }, - 'discovery': { flow: ['issue-discover', 'issue-plan', 'issue-queue', 'issue-execute'], depth: 'standard' }, - 'analysis': { flow: ['analyze-with-file'], depth: complexity === 'complex' ? 'deep' : 'standard' }, - 'cleanup': { flow: ['clean'], depth: 'standard' }, - 'brainstorm': { flow: ['brainstorm-with-file', 'execute'], depth: complexity === 'complex' ? 'deep' : 'standard' }, - 'batch-planning': { flow: ['merge-plans-with-file', 'execute'], depth: 'standard' }, - 'feature': { flow: complexity === 'complex' ? ['lite-plan-b'] : ['lite-plan-a', 'execute'], depth: complexity === 'complex' ? 'deep' : 'standard' } - }; - return flows[taskType] || flows['feature']; -} -``` - -#### Display to User - -``` -Recommended Command Chain: - -Pipeline (管道视图): -需求 → @~/.codex/prompts/lite-plan-a.md → 计划 → @~/.codex/prompts/execute.md → 代码完成 - -Commands (命令列表): -1. @~/.codex/prompts/lite-plan-a.md -2. @~/.codex/prompts/execute.md - -Proceed? [Confirm / Show Details / Adjust / Cancel] -``` - -### Phase 2b: Get User Confirmation - -Ask user for confirmation before proceeding with execution. - -```javascript -async function getUserConfirmation(chain) { - const response = await AskUserQuestion({ - questions: [{ - question: 'Proceed with this command chain?', - header: 'Confirm Chain', - multiSelect: false, - options: [ - { label: 'Confirm and execute', description: 'Proceed with commands' }, - { label: 'Show details', description: 'View each command' }, - { label: 'Adjust chain', description: 'Remove or reorder' }, - { label: 'Cancel', description: 'Abort' } - ] - }] - }); - - return response; -} -``` - -### Phase 3: Execute Sequential Command Chain - -```javascript -async function executeCommandChain(chain, analysis) { - const sessionId = `codex-coord-${Date.now()}`; - const stateDir = `.workflow/.codex-coordinator/${sessionId}`; - - // Create state directory - const state = { - session_id: sessionId, - status: 'running', - created_at: new Date().toISOString(), - analysis: analysis, - command_chain: chain.map((cmd, idx) => ({ ...cmd, index: idx, status: 'pending' })), - execution_results: [], - }; - - // Save initial state - Write(`${stateDir}/state.json`, JSON.stringify(state, null, 2)); - - for (let i = 0; i < chain.length; i++) { - const cmd = chain[i]; - console.log(`[${i+1}/${chain.length}] Executing: @~/.codex/prompts/${cmd.name}.md`); - - // Update status to running - state.command_chain[i].status = 'running'; - state.updated_at = new Date().toISOString(); - Write(`${stateDir}/state.json`, JSON.stringify(state, null, 2)); - - try { - // Build command with parameters using full path - let commandStr = `@~/.codex/prompts/${cmd.name}.md`; - - // Add parameters based on previous results and task context - if (i > 0 && state.execution_results.length > 0) { - const lastResult = state.execution_results[state.execution_results.length - 1]; - commandStr += ` --resume="${lastResult.session_id || lastResult.artifact}"`; - } - - // For analysis-based commands, add depth parameter - if (analysis.complexity === 'complex' && (cmd.name.includes('analyze') || cmd.name.includes('plan'))) { - commandStr += ` --depth=deep`; - } - - // Add task description for planning commands - if (cmd.type === 'planning' && i === 0) { - commandStr += ` TASK="${analysis.goal}"`; - } - - // Execute command via Bash (spawning as background task) - // Format: @~/.codex/prompts/command-name.md [] parameters - // Note: This simulates the execution; actual implementation uses hook callbacks - console.log(`Executing: ${commandStr}`); - - // Save execution record - state.execution_results.push({ - index: i, - command: cmd.name, - status: 'in-progress', - started_at: new Date().toISOString(), - session_id: null, - artifact: null - }); - - state.command_chain[i].status = 'completed'; - state.updated_at = new Date().toISOString(); - Write(`${stateDir}/state.json`, JSON.stringify(state, null, 2)); - - console.log(`[${i+1}/${chain.length}] ✓ Completed: @~/.codex/prompts/${cmd.name}.md`); - - } catch (error) { - state.command_chain[i].status = 'failed'; - state.updated_at = new Date().toISOString(); - Write(`${stateDir}/state.json`, JSON.stringify(state, null, 2)); - - console.log(`❌ Command failed: ${error.message}`); - break; - } - } - - state.status = 'completed'; - state.updated_at = new Date().toISOString(); - Write(`${stateDir}/state.json`, JSON.stringify(state, null, 2)); - - console.log(`\n✅ Orchestration Complete: ${state.session_id}`); - return state; -} -``` - -## State File Structure - -**Location**: `.workflow/.codex-coordinator/{session_id}/state.json` - -```json -{ - "session_id": "codex-coord-20250129-143025", - "status": "running|waiting|completed|failed", - "created_at": "2025-01-29T14:30:25Z", - "updated_at": "2025-01-29T14:35:45Z", - "analysis": { - "goal": "Fix login authentication bug", - "scope": ["auth", "login"], - "complexity": "medium", - "task_type": "bugfix" - }, - "command_chain": [ - { - "index": 0, - "name": "lite-fix", - "type": "bugfix", - "status": "completed" - }, - { - "index": 1, - "name": "execute", - "type": "execution", - "status": "pending" - } - ], - "execution_results": [ - { - "index": 0, - "command": "lite-fix", - "status": "completed", - "started_at": "2025-01-29T14:30:25Z", - "session_id": "fix-login-2025-01-29", - "artifact": ".workflow/.lite-fix/fix-login-2025-01-29/fix-plan.json" - } - ] -} -``` - -### Status Values - -- `running`: Orchestrator actively executing -- `waiting`: Paused, waiting for external events -- `completed`: All commands finished successfully -- `failed`: Error occurred or user aborted - -## Task Type Routing (Pipeline Summary) - -**Note**: 【 】marks Minimum Execution Units (最小执行单元) - these commands must execute together. - -| Task Type | Pipeline | Minimum Units | -|-----------|----------|---| -| **bugfix** | Bug报告 →【@~/.codex/prompts/lite-fix.md → @~/.codex/prompts/execute.md】→ 修复代码 | Bug Fix | -| **discovery** | 需求 →【@~/.codex/prompts/issue-discover.md → @~/.codex/prompts/issue-plan.md → @~/.codex/prompts/issue-queue.md → @~/.codex/prompts/issue-execute.md】→ 完成 issues | Issue Workflow | -| **analysis** | 需求 → @~/.codex/prompts/analyze-with-file.md → 分析报告 | Analyze With File | -| **cleanup** | 代码库 → @~/.codex/prompts/clean.md → 清理完成 | Cleanup | -| **brainstorm** | 主题 →【@~/.codex/prompts/brainstorm-with-file.md → @~/.codex/prompts/execute.md】→ 实现代码 | Brainstorm to Execution | -| **batch-planning** | 需求集合 →【@~/.codex/prompts/merge-plans-with-file.md → @~/.codex/prompts/execute.md】→ 代码完成 | Merge Multiple Plans | -| **feature** (simple) | 需求 →【@~/.codex/prompts/lite-plan-a.md → @~/.codex/prompts/execute.md】→ 代码 | Quick Implementation | -| **feature** (complex) | 需求 → @~/.codex/prompts/lite-plan-b.md → 详细计划 → @~/.codex/prompts/execute.md → 代码 | Complex Planning | - -## Available Commands Reference - -### Planning Commands - -| Command | Purpose | Usage | Output | -|---------|---------|-------|--------| -| **lite-plan-a** | Lightweight merged-mode planning | `@~/.codex/prompts/lite-plan-a.md TASK="..."` | plan.json | -| **lite-plan-b** | Multi-angle exploration planning | `@~/.codex/prompts/lite-plan-b.md TASK="..."` | plan.json | -| **lite-plan-c** | Parallel angle planning | `@~/.codex/prompts/lite-plan-c.md TASK="..."` | plan.json | -| **quick-plan-with-file** | Quick planning with file tracking | `@~/.codex/prompts/quick-plan-with-file.md TASK="..."` | plan + docs | -| **merge-plans-with-file** | Merge multiple plans | `@~/.codex/prompts/merge-plans-with-file.md PLANS="..."` | merged-plan.json | - -### Execution Commands - -| Command | Purpose | Usage | Output | -|---------|---------|-------|--------| -| **execute** | Execute tasks from plan | `@~/.codex/prompts/execute.md SESSION=".../plan/"` | Working code | -| **unified-execute-with-file** | Execute with file tracking | `@~/.codex/prompts/unified-execute-with-file.md SESSION="..."` | Code + tracking | - -### Bug Fix Commands - -| Command | Purpose | Usage | Output | -|---------|---------|-------|--------| -| **lite-fix** | Quick bug diagnosis and planning | `@~/.codex/prompts/lite-fix.md BUG="..."` | fix-plan.json | -| **debug-with-file** | Hypothesis-driven debugging | `@~/.codex/prompts/debug-with-file.md BUG="..."` | understanding.md | - -### Discovery Commands - -| Command | Purpose | Usage | Output | -|---------|---------|-------|--------| -| **issue-discover** | Multi-perspective issue discovery | `@~/.codex/prompts/issue-discover.md PATTERN="src/**"` | issues.jsonl | -| **issue-discover-by-prompt** | Prompt-based discovery | `@~/.codex/prompts/issue-discover-by-prompt.md PROMPT="..."` | issues | -| **issue-plan** | Plan issue solutions | `@~/.codex/prompts/issue-plan.md --all-pending` | issue-plans.json | -| **issue-queue** | Form execution queue | `@~/.codex/prompts/issue-queue.md --from-plan` | queue.json | -| **issue-execute** | Execute issue queue | `@~/.codex/prompts/issue-execute.md QUEUE="..."` | Completed | - -### Analysis Commands - -| Command | Purpose | Usage | Output | -|---------|---------|-------|--------| -| **analyze-with-file** | Collaborative analysis | `@~/.codex/prompts/analyze-with-file.md TOPIC="..."` | discussion.md | - -### Brainstorm Commands - -| Command | Purpose | Usage | Output | -|---------|---------|-------|--------| -| **brainstorm-with-file** | Multi-perspective brainstorming | `@~/.codex/prompts/brainstorm-with-file.md TOPIC="..."` | brainstorm.md | -| **brainstorm-to-cycle** | Bridge brainstorm to execution | `@~/.codex/prompts/brainstorm-to-cycle.md` | Executable plan | - -### Utility Commands - -| Command | Purpose | Usage | Output | -|---------|---------|-------|--------| -| **clean** | Intelligent code cleanup | `@~/.codex/prompts/clean.md` | Cleaned code | -| **compact** | Compact session memory | `@~/.codex/prompts/compact.md SESSION="..."` | Compressed state | - -## Execution Flow - -``` -User Input: TASK="..." - ↓ -Phase 1: analyzeRequirements(task) - ↓ -Phase 2: recommendCommandChain(analysis) - Display pipeline and commands - ↓ -User Confirmation - ↓ -Phase 3: executeCommandChain(chain, analysis) - ├─ For each command: - │ ├─ Update state to "running" - │ ├─ Build command string with parameters - │ ├─ Execute @command [] with parameters - │ ├─ Save execution results - │ └─ Update state to "completed" - ↓ -Output completion summary -``` - -## Key Design Principles - -1. **Atomic Execution** - Never split minimum execution units -2. **State Persistence** - All state saved to JSON -3. **User Control** - Confirmation before execution -4. **Context Passing** - Parameters chain across commands -5. **Resume Support** - Can resume from state.json -6. **Intelligent Routing** - Task type determines command chain -7. **Complexity Awareness** - Different paths for simple vs complex tasks - -## Command Invocation Format - -**Format**: `@~/.codex/prompts/.md ` - -**Examples**: -```bash -@~/.codex/prompts/lite-plan-a.md TASK="Implement user authentication" -@~/.codex/prompts/execute.md SESSION=".workflow/.lite-plan/..." -@~/.codex/prompts/lite-fix.md BUG="Login fails with 404 error" -@~/.codex/prompts/issue-discover.md PATTERN="src/auth/**" -@~/.codex/prompts/brainstorm-with-file.md TOPIC="Improve user onboarding" -``` - -## Error Handling - -| Situation | Action | -|-----------|--------| -| Unknown task type | Default to feature implementation | -| Command not found | Error: command not available | -| Execution fails | Report error, offer retry or skip | -| Invalid parameters | Validate and ask for correction | -| Circular dependency | Detect and report | -| All commands fail | Report and suggest manual intervention | - -## Session Management - -**Resume Previous Session**: -``` -1. Find session in .workflow/.codex-coordinator/ -2. Load state.json -3. Identify last completed command -4. Restart from next pending command -``` - -**View Session Progress**: -``` -cat .workflow/.codex-coordinator/{session-id}/state.json -``` - ---- - -## Execution Instructions - -The coordinator workflow follows these steps: - -1. **Parse Input**: Extract task description from TASK parameter -2. **Analyze**: Determine goal, scope, complexity, and task type -3. **Recommend**: Build optimal command chain based on analysis -4. **Confirm**: Display pipeline and request user approval -5. **Execute**: Run commands sequentially with state tracking -6. **Report**: Display final results and artifacts - -To use this coordinator, invoke it as a Claude Code command (not a Codex command): - -From the Claude Code CLI, you would call Codex commands like: -```bash -@~/.codex/prompts/lite-plan-a.md TASK="Your task description" -``` - -Or with options: -```bash -@~/.codex/prompts/lite-plan-a.md TASK="..." --depth=deep -``` - -This coordinator orchestrates such Codex commands based on your task requirements. diff --git a/.claude/commands/issue/execute.md b/.claude/commands/issue/execute.md index 5d2edc90..87e2783c 100644 --- a/.claude/commands/issue/execute.md +++ b/.claude/commands/issue/execute.md @@ -337,7 +337,7 @@ Execute each task in order (T1 → T2 → T3 → ...): For each task: - Follow task.implementation steps - Run task.test commands -- Verify task.acceptance criteria +- Verify task.convergence criteria - Do NOT commit after each task ### Step 3: Commit Solution (Once) @@ -380,7 +380,7 @@ On success, run: "tests_passed": true, "verification": { "all_tests_passed": true, - "acceptance_criteria_met": true, + "convergence_criteria_met": true, "regression_checked": true }, "summary": "" diff --git a/.claude/commands/issue/from-brainstorm.md b/.claude/commands/issue/from-brainstorm.md index 9da98a26..3bf461e2 100644 --- a/.claude/commands/issue/from-brainstorm.md +++ b/.claude/commands/issue/from-brainstorm.md @@ -105,12 +105,12 @@ interface Task { description: string; implementation: string[]; // Step-by-step guide - acceptance: { + convergence: { criteria: string[]; // What defines success verification: string[]; // How to verify }; - priority: number; // 1-5 + priority: string; // "critical"|"high"|"medium"|"low" depends_on: string[]; // Task dependencies } ``` @@ -146,7 +146,7 @@ Phase 5: Generate Solution Tasks ├─ T1: Research & Validate (if main_challenges exist) ├─ T2: Design & Specification (if key_strengths exist) ├─ T3+: Implementation tasks (from idea.next_steps) - └─ Each task includes: implementation steps + acceptance criteria + └─ Each task includes: implementation steps + convergence criteria Phase 6: Bind Solution ├─ Write solution to .workflow/issues/solutions/{issue-id}.jsonl @@ -214,7 +214,7 @@ Phase 7: Next Steps - **Title**: `idea.title` - **Scope**: implementation - **Action**: Implement -- **Generic implementation + acceptance criteria** +- **Generic implementation + convergence criteria** ## Priority Calculation diff --git a/.claude/commands/issue/plan.md b/.claude/commands/issue/plan.md index 6d2eee9b..5dd8c67f 100644 --- a/.claude/commands/issue/plan.md +++ b/.claude/commands/issue/plan.md @@ -191,7 +191,7 @@ ${issueList} - Solution ID format: SOL-{issue-id}-{uid} (uid: 4 random alphanumeric chars, e.g., a7x9) - Single solution per issue → auto-bind via ccw issue bind - Multiple solutions → register only, return pending_selection -- Tasks must have quantified acceptance.criteria +- Tasks must have quantified convergence.criteria ### Return Summary {"bound":[{"issue_id":"...","solution_id":"...","task_count":N}],"pending_selection":[{"issue_id":"...","solutions":[{"id":"...","description":"...","task_count":N}]}]} @@ -323,8 +323,8 @@ Before completing, verify: - [ ] All input issues have solutions in `solutions/{issue-id}.jsonl` - [ ] Single solution issues are auto-bound (`bound_solution_id` set) - [ ] Multi-solution issues returned in `pending_selection` for user choice -- [ ] Each solution has executable tasks with `modification_points` -- [ ] Task acceptance criteria are quantified (not vague) +- [ ] Each solution has executable tasks with `files` +- [ ] Task convergence criteria are quantified (not vague) - [ ] Conflicts detected and reported (if multiple issues touch same files) - [ ] Issue status updated to `planned` after binding diff --git a/.claude/commands/issue/queue.md b/.claude/commands/issue/queue.md index d94f19a2..6c2b5cba 100644 --- a/.claude/commands/issue/queue.md +++ b/.claude/commands/issue/queue.md @@ -88,7 +88,7 @@ ccw issue queue delete Delete queue from history Phase 1: Solution Loading & Distribution ├─ Load issues.jsonl, filter by status='planned' + bound_solution_id ├─ Read solutions/{issue-id}.jsonl, find bound solution - ├─ Extract files_touched from task modification_points + ├─ Extract files_touched from task files[] or modification_points (legacy) ├─ Build solution objects array └─ If --queues > 1: Partition solutions into N groups (minimize cross-group file conflicts) diff --git a/.claude/commands/workflow/spec.md b/.claude/commands/workflow/spec.md deleted file mode 100644 index 8f8f7c59..00000000 --- a/.claude/commands/workflow/spec.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -name: spec -description: Specification generator - 6 phase document chain producing product brief, PRD, architecture, and epics. Triggers on "generate spec", "create specification", "spec generator". -argument-hint: "[-y|--yes] [-c|--continue] \"idea or requirement description\"" -allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*) ---- - -## Auto Mode - -When `--yes` or `-y`: Auto-confirm decisions, use recommended defaults, skip interactive validation. - -# Workflow Spec Command (/workflow:spec) - -## Quick Start - -```bash -# Basic usage -/workflow:spec "Build a task management system with real-time collaboration" - -# Auto mode (skip all confirmations) -/workflow:spec -y "User authentication system with OAuth2 and 2FA" - -# Continue existing session -/workflow:spec -c "task management" - -# Combined -/workflow:spec -y -c "task management" -``` - -**Skill**: `spec-generator` -**Output Directory**: `.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/` -**Core Flow**: Discovery -> Product Brief -> PRD -> Architecture -> Epics -> Readiness Check - -## What This Command Does - -Generates a complete specification package through 6 sequential phases: - -1. **Discovery**: Analyze seed idea, explore codebase (optional), establish session -2. **Product Brief**: Multi-CLI analysis (Product/Technical/User perspectives) -3. **Requirements (PRD)**: Functional + non-functional requirements with MoSCoW priorities -4. **Architecture**: Component design, tech stack, ADRs with review -5. **Epics & Stories**: Implementation breakdown with dependency mapping -6. **Readiness Check**: Cross-document validation, quality scoring, handoff - -## Output Artifacts - -| Phase | Artifact | Description | -|-------|----------|-------------| -| 1 | `spec-config.json` | Session configuration and state | -| 1 | `discovery-context.json` | Codebase exploration (optional) | -| 2 | `product-brief.md` | Product brief with multi-perspective synthesis | -| 3 | `requirements/` | `_index.md` + `REQ-NNN-{slug}.md` + `NFR-{type}-NNN-{slug}.md` | -| 4 | `architecture/` | `_index.md` + `ADR-NNN-{slug}.md` | -| 5 | `epics/` | `_index.md` + `EPIC-NNN-{slug}.md` | -| 6 | `readiness-report.md` | Quality validation report | -| 6 | `spec-summary.md` | One-page executive summary | - -## Flags - -| Flag | Description | -|------|-------------| -| `-y`, `--yes` | Auto mode: skip all confirmations, use defaults | -| `-c`, `--continue` | Resume from last completed phase | - -## After Completion - -The readiness check (Phase 6) offers handoff to execution workflows: - -- `/workflow:lite-plan` - Execute one Epic at a time (direct text input) -- `/workflow:req-plan-with-file` - Generate execution roadmap -- `/workflow:plan` - Full planning for entire scope -- `/issue:new` - Create issues per Epic - -### Plan Integration (Automatic Bridge) - -When selecting "Full planning" or "Create roadmap", Phase 6 automatically: - -1. Creates a WFS session via `/workflow:session:start` -2. Generates `.brainstorming/` bridge files in the session directory: - - `guidance-specification.md` — synthesized from spec outputs (product-brief + requirements + architecture key decisions) - - `feature-specs/feature-index.json` — maps each Epic to a Feature entry - - `feature-specs/F-{num}-{slug}.md` — individual feature spec per Epic -3. Invokes the downstream workflow (`/workflow:plan` or `/workflow:req-plan-with-file`) - -The `context-search-agent` auto-discovers these `.brainstorming/` files and populates `context-package.json.brainstorm_artifacts`, which `action-planning-agent` consumes via the standard priority chain: `guidance_specification` → `feature_index` → `feature_specs`. No manual bridging required. - -## When to Use - -- Starting a new product/feature from scratch -- Need structured specification before implementation -- Want multi-perspective analysis of an idea -- Need traceable requirement -> architecture -> story chain -- Replacing ad-hoc brainstorming with structured output - -## Compared to Other Workflows - -| Workflow | Use When | -|----------|----------| -| `/workflow:spec` | Need full specification package before any coding | -| `/workflow:brainstorm-with-file` | Exploring ideas, not ready for structure | -| `/workflow:lite-plan` | Have clear requirements, ready to implement | -| `/workflow:plan` | Have requirements, need detailed task planning | -| `/workflow:req-plan-with-file` | Have requirements, need layered roadmap | - ---- - -**Now execute spec-generator for**: $ARGUMENTS diff --git a/.claude/docs/HOOKS_ANALYSIS_REPORT.md b/.claude/docs/HOOKS_ANALYSIS_REPORT.md deleted file mode 100644 index 00f2d83b..00000000 --- a/.claude/docs/HOOKS_ANALYSIS_REPORT.md +++ /dev/null @@ -1,453 +0,0 @@ -# Claude Code Hooks - 当前实现 vs 官方标准对比报告 - -## 执行摘要 - -当前 CCW 代码库中的钩子实现**不符合 Claude Code 官方标准**。存在以下主要问题： - -1. ❌ **钩子事件名称不符合官方标准** - 使用了错误的事件名称 -2. ❌ **配置结构不同** - 自定义了配置格式，不符合官方规范 -3. ❌ **使用了不存在的事件类型** - 某些事件在官方钩子系统中不存在 -4. ❌ **文档与实现不一致** - 代码中的注释引用的是自定义实现，而非官方标准 - ---- - -## 详细对比 - -### 1. 钩子事件名称对比 - -#### ❌ 当前实现（错误） - -```json -{ - "hooks": { - "session-start": [], // ❌ 错误：应为 SessionStart - "session-end": [], // ❌ 错误：应为 SessionEnd - "file-modified": [], // ❌ 错误：官方不支持此事件 - "context-request": [], // ❌ 错误：官方不支持此事件 - "PostToolUse": [] // ✅ 正确 - } -} -``` - -#### ✅ 官方标准（正确） - -```json -{ - "hooks": { - "SessionStart": [], // ✅ 当会话开始或恢复时触发 - "UserPromptSubmit": [], // ✅ 当用户提交提示词时触发 - "PreToolUse": [], // ✅ 工具调用前触发，可以阻止 - "PermissionRequest": [], // ✅ 权限对话出现时触发 - "PostToolUse": [], // ✅ 工具调用成功后触发 - "PostToolUseFailure": [], // ✅ 工具调用失败时触发 - "Notification": [], // ✅ 通知发送时触发 - "SubagentStart": [], // ✅ 子代理生成时触发 - "SubagentStop": [], // ✅ 子代理完成时触发 - "Stop": [], // ✅ Claude 完成响应时触发 - "PreCompact": [], // ✅ 上下文压缩前触发 - "SessionEnd": [] // ✅ 会话终止时触发 - } -} -``` - -### 2. 配置结构对比 - -#### ❌ 当前实现（自定义结构） - -```json -{ - "hooks": { - "session-start": [ - { - "name": "Progressive Disclosure", - "description": "Injects progressive disclosure index", - "enabled": true, - "handler": "internal:context", - "timeout": 5000, - "failMode": "silent" - } - ] - }, - "hookSettings": { - "globalTimeout": 60000, - "defaultFailMode": "silent", - "allowAsync": true, - "enableLogging": true - } -} -``` - -**问题：** -- 使用了非标准字段：`name`, `description`, `enabled`, `handler`, `failMode` -- 使用了自定义的 `hookSettings` 配置 -- 结构过度复杂化 - -#### ✅ 官方标准（简洁标准） - -```json -{ - "hooks": { - "SessionStart": [ - { - "matcher": "startup|resume|clear|compact", - "hooks": [ - { - "type": "command", - "command": "bash /path/to/script.sh", - "timeout": 600, - "async": false - } - ] - } - ] - } -} -``` - -**优点：** -- 简洁明了的三层结构：事件 → 匹配器 → 处理器 -- 标准的字段集：`type`, `command`, `timeout`, `async` -- 支持三种处理器类型：`command`, `prompt`, `agent` - -### 3. 官方支持的钩子事件及其触发时机 - -| 事件名称 | 触发时机 | 可阻止 | 匹配器支持 | -|---------|---------|--------|-----------| -| `SessionStart` | 会话开始或恢复 | ❌ | startup, resume, clear, compact | -| `UserPromptSubmit` | 用户提交提示词前 | ✅ | ❌ | -| `PreToolUse` | 工具调用前 | ✅ | 工具名称 | -| `PermissionRequest` | 权限对话出现时 | ✅ | 工具名称 | -| `PostToolUse` | 工具调用成功后 | ❌ | 工具名称 | -| `PostToolUseFailure` | 工具调用失败时 | ❌ | 工具名称 | -| `Notification` | 通知发送时 | ❌ | 通知类型 | -| `SubagentStart` | 子代理生成时 | ❌ | 代理类型 | -| `SubagentStop` | 子代理完成时 | ✅ | 代理类型 | -| `Stop` | Claude 完成响应时 | ✅ | ❌ | -| `PreCompact` | 上下文压缩前 | ❌ | manual, auto | -| `SessionEnd` | 会话终止时 | ❌ | 终止原因 | - -**当前实现不支持的事件：** -- ❌ `file-modified` - 官方系统中不存在 -- ❌ `context-request` - 官方系统中不存在 - -### 4. 处理器类型对比 - -#### ❌ 当前实现 - -仅支持一种：`handler: "internal:context"`（自定义内部处理器） - -#### ✅ 官方标准 - -支持三种标准类型： - -1. **Command hooks** (`type: "command"`) - ```json - { - "type": "command", - "command": "bash /path/to/script.sh", - "timeout": 600, - "async": false - } - ``` - -2. **Prompt hooks** (`type: "prompt"`) - ```json - { - "type": "prompt", - "prompt": "Evaluate if this is safe to execute: $ARGUMENTS", - "model": "haiku", - "timeout": 30 - } - ``` - -3. **Agent hooks** (`type: "agent"`) - ```json - { - "type": "agent", - "prompt": "Verify tests pass: $ARGUMENTS", - "model": "haiku", - "timeout": 60 - } - ``` - -### 5. 匹配器对比 - -#### ❌ 当前实现 - -没有明确的匹配器概念，而是使用： -- `handler: "internal:context"` - 内部处理 -- 没有工具级别的过滤 - -#### ✅ 官方标准 - -完整的匹配器系统： - -```json -{ - "PreToolUse": [ - { - "matcher": "Edit|Write", // 仅在 Edit 或 Write 工具时触发 - "hooks": [ ... ] - } - ] -} -``` - -**支持的匹配器：** -- **工具事件**：`Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Task`, `WebFetch`, `WebSearch` -- **MCP工具**：`mcp__memory__.*`, `mcp__.*__write.*` -- **会话事件**：`startup`, `resume`, `clear`, `compact` -- **通知类型**：`permission_prompt`, `idle_prompt`, `auth_success` -- **代理类型**：`Bash`, `Explore`, `Plan` - -### 6. 输入/输出机制对比 - -#### ❌ 当前实现 - -- 未定义标准的 stdin/stdout 通信协议 -- 使用了自定义的环境变量：`$SESSION_ID`, `$FILE_PATH`, `$PROJECT_PATH` - -#### ✅ 官方标准 - -**标准 JSON stdin 输入：** -```json -{ - "session_id": "abc123", - "transcript_path": "/path/to/transcript.jsonl", - "cwd": "/current/dir", - "permission_mode": "default", - "hook_event_name": "PreToolUse", - "tool_name": "Bash", - "tool_input": { - "command": "npm test" - } -} -``` - -**标准 exit code 输出：** -- **exit 0**: 成功，解析 stdout 的 JSON 决策 -- **exit 2**: 阻止性错误，stderr 成为 Claude 的反馈 -- **其他码**: 非阻止性错误，stderr 显示在详细模式 - -**标准 JSON stdout 输出：** -```json -{ - "hookSpecificOutput": { - "hookEventName": "PreToolUse", - "permissionDecision": "allow|deny|ask", - "permissionDecisionReason": "explanation" - } -} -``` - -### 7. 文件位置对比 - -#### 当前实现 - -示例配置文件位置： -- `ccw/src/templates/hooks-config-example.json` - -#### ✅ 官方标准 - -标准配置位置（优先级顺序）： -1. `~/.claude/settings.json` - 全局用户配置 -2. `.claude/settings.json` - 项目配置（可提交） -3. `.claude/settings.local.json` - 项目本地配置（gitignored） -4. 插件 `hooks/hooks.json` - 插件内部 -5. Skill/Agent frontmatter - 技能或代理 - ---- - -## 代码库中的具体问题位置 - -### 1. 错误的配置示例 - -**文件:** `ccw/src/templates/hooks-config-example.json` - -```json -{ - "hooks": { - "session-start": [ ... ], // ❌ 应为 SessionStart - "session-end": [ ... ], // ❌ 应为 SessionEnd - "file-modified": [ ... ], // ❌ 不存在的事件 - "context-request": [ ... ] // ❌ 不存在的事件 - } -} -``` - -**应改为：** - -```json -{ - "hooks": { - "SessionStart": [ - { - "matcher": "startup|resume", - "hooks": [ - { - "type": "command", - "command": "echo 'Session started'" - } - ] - } - ], - "PostToolUse": [ - { - "matcher": "Write|Edit", - "hooks": [ - { - "type": "command", - "command": "prettier --write $FILE_PATH" - } - ] - } - ], - "SessionEnd": [ - { - "matcher": "clear", - "hooks": [ - { - "type": "command", - "command": "echo 'Session ended'" - } - ] - } - ] - } -} -``` - -### 2. 错误的命令注释 - -**文件:** `ccw/src/commands/hook.ts` - -当前代码引用了自定义的钩子处理逻辑，但不符合官方标准。 - ---- - -## 修复建议 - -### 优先级 1：关键修复 - -- [ ] 更新 `hooks-config-example.json` 使用官方事件名称 -- [ ] 更新配置结构以符合官方三层标准 -- [ ] 移除不支持的事件类型：`file-modified`, `context-request` -- [ ] 文档化官方支持的事件列表 - -### 优先级 2：功能对齐 - -- [ ] 实现官方的标准 JSON stdin/stdout 通信 -- [ ] 实现标准的 exit code 处理 -- [ ] 支持标准的匹配器系统 - -### 优先级 3：增强 - -- [ ] 添加对 `prompt` 和 `agent` 处理器类型的支持 -- [ ] 实现标准的异步钩子支持（`async: true`） -- [ ] 添加对环境变量持久化的支持（`CLAUDE_ENV_FILE`） - ---- - -## 官方示例 - -### 例1：格式化代码后自动执行 - -```json -{ - "hooks": { - "PostToolUse": [ - { - "matcher": "Edit|Write", - "hooks": [ - { - "type": "command", - "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" - } - ] - } - ] - } -} -``` - -### 例2：阻止编辑受保护文件 - -```json -{ - "hooks": { - "PreToolUse": [ - { - "matcher": "Edit|Write", - "hooks": [ - { - "type": "command", - "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" - } - ] - } - ] - } -} -``` - -### 例3：会话开始时重新注入上下文 - -```json -{ - "hooks": { - "SessionStart": [ - { - "matcher": "compact", - "hooks": [ - { - "type": "command", - "command": "echo 'Use Bun, not npm. Run bun test before committing.'" - } - ] - } - ] - } -} -``` - -### 例4：基于条件的权限决策 - -```json -{ - "hooks": { - "PreToolUse": [ - { - "matcher": "Bash", - "hooks": [ - { - "type": "prompt", - "prompt": "Is this a safe command to run? $ARGUMENTS" - } - ] - } - ] - } -} -``` - ---- - -## 参考资源 - -- 官方指南：https://code.claude.com/docs/en/hooks-guide -- 官方参考：https://code.claude.com/docs/en/hooks -- 官方示例：https://github.com/anthropics/claude-code/tree/main/examples/hooks - ---- - -## 总结 - -当前 CCW 的钩子实现是基于自定义规范的，**完全不兼容** Claude Code 官方钩子系统。为了与官方标准对齐，需要进行彻底的重构，包括： - -1. ✅ 采用官方的事件名称（已在 `.claude/docs/` 文件中提供） -2. ✅ 采用官方的三层配置结构 -3. ✅ 实现官方的 JSON stdin/stdout 通信协议 -4. ✅ 移除不存在的自定义事件 -5. ✅ 支持官方的三种处理器类型 - -这样才能确保当用户将 CCW 的配置迁移到真实的 Claude Code CLI 时，能够正常工作。 diff --git a/.claude/docs/HOOKS_DOCUMENTATION_INDEX.md b/.claude/docs/HOOKS_DOCUMENTATION_INDEX.md deleted file mode 100644 index 6e23d5b1..00000000 --- a/.claude/docs/HOOKS_DOCUMENTATION_INDEX.md +++ /dev/null @@ -1,224 +0,0 @@ -# Claude Code Hooks - 文档索引 - -本目录包含 Claude Code 官方钩子系统的完整文档和分析报告。 - ---- - -## 📚 官方文档（已下载） - -### 1. HOOKS_OFFICIAL_GUIDE.md -- **来源**: https://code.claude.com/docs/en/hooks-guide -- **内容**: 官方钩子指南，包含快速入门、常见用例、配置教程 -- **适用**: 初次使用钩子系统的开发者 - -### 2. HOOKS_OFFICIAL_REFERENCE.md -- **来源**: https://code.claude.com/docs/en/hooks -- **内容**: 完整的技术参考，包含所有事件的 schema、输入输出格式、配置选项 -- **适用**: 需要查阅具体事件参数和配置细节的开发者 - -### 3. HOOKS_QUICK_REFERENCE.md -- **内容**: 快速查阅指南，包含所有事件列表、配置模板、常见用例 -- **适用**: 需要快速查找特定配置或事件信息的开发者 - ---- - -## 📊 分析报告 - -### 4. HOOKS_ANALYSIS_REPORT.md -- **内容**: 当前 CCW 钩子实现 vs 官方标准对比分析 -- **包含**: - - 当前实现存在的问题 - - 事件名称对比 - - 配置结构对比 - - 修复建议和优先级 -- **适用**: 需要了解当前实现与官方标准差异的开发者 - ---- - -## 💻 示例代码 - -### 5. ../examples/hooks_bash_command_validator.py -- **来源**: https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py -- **内容**: 官方示例 - Bash 命令验证器 -- **功能**: 拦截 Bash 命令，建议使用 ripgrep 替代 grep -- **适用**: 学习如何编写 PreToolUse 钩子的开发者 - ---- - -## 🎯 官方钩子事件列表 - -### 官方支持的 12 个钩子事件 - -| # | 事件名称 | 触发时机 | 可阻止 | -|---|---------|---------|--------| -| 1 | `SessionStart` | 会话开始或恢复 | ❌ | -| 2 | `UserPromptSubmit` | 用户提交提示词前 | ✅ | -| 3 | `PreToolUse` | 工具调用前 | ✅ | -| 4 | `PermissionRequest` | 权限对话出现时 | ✅ | -| 5 | `PostToolUse` | 工具调用成功后 | ❌ | -| 6 | `PostToolUseFailure` | 工具调用失败后 | ❌ | -| 7 | `Notification` | 通知发送时 | ❌ | -| 8 | `SubagentStart` | 子代理生成时 | ❌ | -| 9 | `SubagentStop` | 子代理完成时 | ✅ | -| 10 | `Stop` | Claude完成响应时 | ✅ | -| 11 | `PreCompact` | 上下文压缩前 | ❌ | -| 12 | `SessionEnd` | 会话终止时 | ❌ | - ---- - -## ⚠️ 当前实现的主要问题 - -### 问题 1: 事件名称不符合官方标准 - -❌ **当前使用（错误）:** -```json -{ - "hooks": { - "session-start": [], // 错误 - "session-end": [], // 错误 - "file-modified": [], // 不存在 - "context-request": [] // 不存在 - } -} -``` - -✅ **官方标准（正确）:** -```json -{ - "hooks": { - "SessionStart": [], // 正确 - "SessionEnd": [], // 正确 - "PostToolUse": [], // 使用其他官方事件 - "PreToolUse": [] // 替代自定义事件 - } -} -``` - -### 问题 2: 配置结构不符合官方标准 - -❌ **当前结构（自定义）:** -```json -{ - "hooks": { - "session-start": [ - { - "name": "...", - "enabled": true, - "handler": "internal:context", - "failMode": "silent" - } - ] - } -} -``` - -✅ **官方结构（标准）:** -```json -{ - "hooks": { - "SessionStart": [ - { - "matcher": "startup|resume", - "hooks": [ - { - "type": "command", - "command": "bash script.sh", - "timeout": 600 - } - ] - } - ] - } -} -``` - ---- - -## 🔗 外部资源 - -### 官方资源 -- **官方指南**: https://code.claude.com/docs/en/hooks-guide -- **官方参考**: https://code.claude.com/docs/en/hooks -- **GitHub 示例**: https://github.com/anthropics/claude-code/tree/main/examples/hooks -- **配置博客**: https://claude.com/blog/how-to-configure-hooks - -### 社区资源 -- [Claude Code Hooks 从入门到实战 - 知乎](https://zhuanlan.zhihu.com/p/1969164730326324920) -- [GitHub: claude-code-best-practices](https://github.com/xiaobei930/claude-code-best-practices) -- [Claude Code power user customization](https://claude.com/blog/how-to-configure-hooks) - ---- - -## 📖 推荐阅读顺序 - -### 对于初学者 -1. `HOOKS_QUICK_REFERENCE.md` - 快速了解钩子概念 -2. `HOOKS_OFFICIAL_GUIDE.md` - 学习如何配置和使用 -3. `hooks_bash_command_validator.py` - 查看示例代码 - -### 对于开发者（修复当前实现） -1. `HOOKS_ANALYSIS_REPORT.md` - 了解问题和修复方案 -2. `HOOKS_OFFICIAL_REFERENCE.md` - 查阅技术细节 -3. `HOOKS_OFFICIAL_GUIDE.md` - 学习最佳实践 - -### 对于高级用户 -1. `HOOKS_OFFICIAL_REFERENCE.md` - 完整技术参考 -2. 官方 GitHub 仓库 - 更多示例 -3. `HOOKS_QUICK_REFERENCE.md` - 快速查阅 - ---- - -## 🛠️ 快速开始 - -### 查看当前配置 -```bash -# 在 Claude Code CLI 中 -/hooks -``` - -### 创建第一个钩子（格式化代码） -`.claude/settings.json`: -```json -{ - "hooks": { - "PostToolUse": [ - { - "matcher": "Edit|Write", - "hooks": [ - { - "type": "command", - "command": "jq -r '.tool_input.file_path' | xargs prettier --write" - } - ] - } - ] - } -} -``` - -### 调试钩子 -```bash -claude --debug # 查看详细执行日志 -``` - -在 CLI 中按 `Ctrl+O` 切换详细模式 - ---- - -## 📝 文档更新 - -- **创建时间**: 2026-02-01 -- **官方文档版本**: 最新（截至 2026-02-01） -- **下次更新建议**: 当 Claude Code 发布新版本时 - ---- - -## 🔍 搜索关键词 - -钩子、Hooks、事件、Events、SessionStart、PreToolUse、PostToolUse、配置、Configuration、命令、Command、Prompt、Agent、阻止、Block、通知、Notification - ---- - -**需要帮助？** - -参考 `HOOKS_QUICK_REFERENCE.md` 获取快速答案，或查阅 `HOOKS_OFFICIAL_REFERENCE.md` 获取完整技术细节。 diff --git a/.claude/docs/HOOKS_OFFICIAL_GUIDE.md b/.claude/docs/HOOKS_OFFICIAL_GUIDE.md deleted file mode 100644 index 60fab9a6..00000000 --- a/.claude/docs/HOOKS_OFFICIAL_GUIDE.md +++ /dev/null @@ -1,124 +0,0 @@ -# Claude Code Hooks - Official Guide - -> Complete official documentation from https://code.claude.com/docs/en/hooks-guide - -## Automate workflows with hooks - -Run shell commands automatically when Claude Code edits files, finishes tasks, or needs input. Format code, send notifications, validate commands, and enforce project rules. - -### Hook lifecycle - -Hooks fire at specific points during a Claude Code session. The official hook events are: - -| Event | When it fires | -| :------------------- | :--------------------------------------------------- | -| `SessionStart` | When a session begins or resumes | -| `UserPromptSubmit` | When you submit a prompt, before Claude processes it | -| `PreToolUse` | Before a tool call executes. Can block it | -| `PermissionRequest` | When a permission dialog appears | -| `PostToolUse` | After a tool call succeeds | -| `PostToolUseFailure` | After a tool call fails | -| `Notification` | When Claude Code sends a notification | -| `SubagentStart` | When a subagent is spawned | -| `SubagentStop` | When a subagent finishes | -| `Stop` | When Claude finishes responding | -| `PreCompact` | Before context compaction | -| `SessionEnd` | When a session terminates | - -### Hook handler types - -There are three types of hook handlers: - -1. **Command hooks** (`type: "command"`): Run a shell command -2. **Prompt hooks** (`type: "prompt"`): Use Claude model for single-turn evaluation -3. **Agent hooks** (`type: "agent"`): Spawn subagent with tool access - -### Configuration structure - -```json -{ - "hooks": { - "EventName": [ - { - "matcher": "ToolName|AnotherTool", - "hooks": [ - { - "type": "command", - "command": "bash /path/to/script.sh", - "timeout": 600, - "async": false - } - ] - } - ] - } -} -``` - -### Hook input (stdin) - -Common fields for all events: -- `session_id`: Current session ID -- `transcript_path`: Path to conversation JSON -- `cwd`: Current working directory -- `permission_mode`: Current permission mode -- `hook_event_name`: Name of the event that fired - -Event-specific fields depend on the event type. - -### Hook output (exit codes and stdout) - -- **Exit 0**: Success. Parse stdout for JSON decision -- **Exit 2**: Blocking error. stderr text becomes Claude's feedback -- **Any other code**: Non-blocking error - -### Tool matchers - -Available for: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` - -Tool names: -- Built-in: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Task`, `WebFetch`, `WebSearch` -- MCP tools: `mcp____` (e.g., `mcp__github__search_repositories`) - -### Event matchers - -Different events match on different fields: -- `SessionStart`: `startup`, `resume`, `clear`, `compact` -- `SessionEnd`: `clear`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other` -- `Notification`: `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` -- `SubagentStart`/`SubagentStop`: agent type (e.g., `Bash`, `Explore`, `Plan`) -- `PreCompact`: `manual`, `auto` - -### Hook configuration locations - -| Location | Scope | -|----------|-------| -| `~/.claude/settings.json` | All your projects | -| `.claude/settings.json` | Single project | -| `.claude/settings.local.json` | Single project (gitignored) | -| Plugin `hooks/hooks.json` | When plugin enabled | -| Skill/Agent frontmatter | While component active | - -### Best practices - -✅ **DO:** -- Use command hooks for deterministic actions -- Use prompt hooks for judgment-based decisions -- Use agent hooks when verification requires file inspection -- Quote all shell variables: `"$VAR"` -- Use absolute paths with `$CLAUDE_PROJECT_DIR` -- Set appropriate timeouts -- Use async hooks for long-running operations -- Keep hooks fast (< 10 seconds by default) - -❌ **DON'T:** -- Trust input data blindly -- Use relative paths -- Put sensitive data in hook output -- Create infinite loops in Stop hooks -- Run blocking operations without async - ---- - -See https://code.claude.com/docs/en/hooks-guide for complete guide -See https://code.claude.com/docs/en/hooks for reference documentation diff --git a/.claude/docs/HOOKS_OFFICIAL_REFERENCE.md b/.claude/docs/HOOKS_OFFICIAL_REFERENCE.md deleted file mode 100644 index 88cf7e1a..00000000 --- a/.claude/docs/HOOKS_OFFICIAL_REFERENCE.md +++ /dev/null @@ -1,268 +0,0 @@ -# Claude Code Hooks - Official Reference - -> Complete official reference from https://code.claude.com/docs/en/hooks - -## Hooks reference - -This is the complete technical reference for Claude Code hooks. - -### Hook events reference - -#### SessionStart - -**When it fires:** When a session begins or resumes - -**Matchers:** -- `startup` - New session -- `resume` - `--resume`, `--continue`, or `/resume` -- `clear` - `/clear` -- `compact` - Auto or manual compaction - -**Input schema:** -```json -{ - "session_id": "abc123", - "transcript_path": "/path/to/transcript.jsonl", - "cwd": "/current/working/dir", - "permission_mode": "default", - "hook_event_name": "SessionStart", - "source": "startup|resume|clear|compact", - "model": "claude-sonnet-4-5-20250929" -} -``` - -**Output control:** -- Exit 0: Text written to stdout is added to Claude's context -- Can use `additionalContext` in JSON output -- Cannot block session start - -**Special variables:** -- `CLAUDE_ENV_FILE`: Write `export` statements to persist environment variables - -#### UserPromptSubmit - -**When it fires:** When user submits a prompt, before Claude processes it - -**Input schema:** -```json -{ - "session_id": "abc123", - "hook_event_name": "UserPromptSubmit", - "prompt": "User's prompt text here" -} -``` - -**Output control:** -- Exit 0: Plain text stdout is added as context -- `decision: "block"` prevents prompt processing -- `additionalContext` adds context to Claude - -#### PreToolUse - -**When it fires:** Before a tool call executes - -**Matchers:** Tool names (Bash, Edit, Write, Read, etc.) - -**Tool input schemas:** -- `Bash`: `command`, `description`, `timeout`, `run_in_background` -- `Write`: `file_path`, `content` -- `Edit`: `file_path`, `old_string`, `new_string`, `replace_all` -- `Read`: `file_path`, `offset`, `limit` -- `Glob`: `pattern`, `path` -- `Grep`: `pattern`, `path`, `glob`, `output_mode`, `-i`, `multiline` -- `WebFetch`: `url`, `prompt` -- `WebSearch`: `query`, `allowed_domains`, `blocked_domains` -- `Task`: `prompt`, `description`, `subagent_type`, `model` - -**Output control:** -- `permissionDecision`: `"allow"`, `"deny"`, `"ask"` -- `permissionDecisionReason`: Explanation -- `updatedInput`: Modify tool input before execution -- `additionalContext`: Add context to Claude - -#### PermissionRequest - -**When it fires:** When permission dialog appears - -**Input schema:** Similar to PreToolUse but fires when permission needed - -**Output control:** -- `decision.behavior`: `"allow"` or `"deny"` -- `decision.updatedInput`: Modify input before execution -- `decision.message`: For deny, tells Claude why - -#### PostToolUse - -**When it fires:** After a tool call succeeds - -**Input schema:** Includes both `tool_input` and `tool_response` - -**Output control:** -- `decision: "block"` to flag issue to Claude -- `additionalContext`: Add context -- `updatedMCPToolOutput`: For MCP tools, replace output - -#### PostToolUseFailure - -**When it fires:** After a tool call fails - -**Input schema:** Includes `error` and `is_interrupt` fields - -**Output control:** -- `additionalContext`: Provide context about the failure - -#### Notification - -**When it fires:** When Claude Code sends a notification - -**Matchers:** -- `permission_prompt` - Permission needed -- `idle_prompt` - Claude idle -- `auth_success` - Auth successful -- `elicitation_dialog` - Dialog shown - -**Input schema:** -```json -{ - "hook_event_name": "Notification", - "message": "Notification text", - "title": "Title", - "notification_type": "permission_prompt|idle_prompt|..." -} -``` - -#### SubagentStart - -**When it fires:** When subagent is spawned - -**Matchers:** Agent types (Bash, Explore, Plan, or custom) - -**Input schema:** -```json -{ - "hook_event_name": "SubagentStart", - "agent_id": "agent-abc123", - "agent_type": "Explore" -} -``` - -**Output control:** -- `additionalContext`: Add context to subagent - -#### SubagentStop - -**When it fires:** When subagent finishes - -**Input schema:** Similar to SubagentStart with `stop_hook_active` field - -#### Stop - -**When it fires:** When Claude finishes responding - -**Input schema:** -```json -{ - "hook_event_name": "Stop", - "stop_hook_active": false|true -} -``` - -**Output control:** -- `decision: "block"` prevents Claude from stopping -- `reason`: Required when blocking, tells Claude why to continue -- Check `stop_hook_active` to prevent infinite loops - -#### PreCompact - -**When it fires:** Before context compaction - -**Matchers:** -- `manual` - `/compact` -- `auto` - Auto-compact when context full - -**Input schema:** -```json -{ - "hook_event_name": "PreCompact", - "trigger": "manual|auto", - "custom_instructions": "" -} -``` - -#### SessionEnd - -**When it fires:** When session terminates - -**Matchers:** -- `clear` - `/clear` -- `logout` - User logged out -- `prompt_input_exit` - User exited during prompt -- `bypass_permissions_disabled` - Bypass disabled -- `other` - Other reasons - -**Input schema:** -```json -{ - "hook_event_name": "SessionEnd", - "reason": "clear|logout|..." -} -``` - -### Prompt-based hooks - -**Type:** `"prompt"` - -**Configuration:** -```json -{ - "type": "prompt", - "prompt": "Your prompt here. Use $ARGUMENTS for input JSON", - "model": "haiku", - "timeout": 30 -} -``` - -**Response schema:** -```json -{ - "ok": true|false, - "reason": "Explanation if ok is false" -} -``` - -### Agent-based hooks - -**Type:** `"agent"` - -**Configuration:** -```json -{ - "type": "agent", - "prompt": "Your prompt here. Use $ARGUMENTS for input JSON", - "model": "haiku", - "timeout": 60 -} -``` - -**Response schema:** Same as prompt hooks - -### Async hooks - -**For command hooks only:** -```json -{ - "type": "command", - "command": "...", - "async": true, - "timeout": 300 -} -``` - -- Doesn't block Claude's execution -- Cannot return decisions -- Output delivered on next conversation turn -- Max 50 turns per session - ---- - -See https://code.claude.com/docs/en/hooks for full reference diff --git a/.claude/docs/HOOKS_QUICK_REFERENCE.md b/.claude/docs/HOOKS_QUICK_REFERENCE.md deleted file mode 100644 index 08f70d5c..00000000 --- a/.claude/docs/HOOKS_QUICK_REFERENCE.md +++ /dev/null @@ -1,390 +0,0 @@ -# Claude Code Hooks - 快速参考 - -## 12 个官方钩子事件 - -| # | 事件名称 | 触发时机 | 可阻止 | 匹配器 | -|---|---------|---------|--------|--------| -| 1 | `SessionStart` | 会话开始/恢复 | ❌ | startup, resume, clear, compact | -| 2 | `UserPromptSubmit` | 用户提交提示词前 | ✅ | ❌ 不支持 | -| 3 | `PreToolUse` | 工具调用前 | ✅ | 工具名称 | -| 4 | `PermissionRequest` | 权限对话时 | ✅ | 工具名称 | -| 5 | `PostToolUse` | 工具成功后 | ❌ | 工具名称 | -| 6 | `PostToolUseFailure` | 工具失败后 | ❌ | 工具名称 | -| 7 | `Notification` | 发送通知时 | ❌ | 通知类型 | -| 8 | `SubagentStart` | 子代理开始 | ❌ | 代理类型 | -| 9 | `SubagentStop` | 子代理完成 | ✅ | 代理类型 | -| 10 | `Stop` | Claude完成响应 | ✅ | ❌ 不支持 | -| 11 | `PreCompact` | 上下文压缩前 | ❌ | manual, auto | -| 12 | `SessionEnd` | 会话终止 | ❌ | 终止原因 | - ---- - -## 配置模板 - -### 基础结构 - -```json -{ - "hooks": { - "EventName": [ - { - "matcher": "pattern", - "hooks": [ - { - "type": "command|prompt|agent", - "command": "...", - "timeout": 600, - "async": false - } - ] - } - ] - } -} -``` - ---- - -## 工具名称（用于匹配器） - -### 内置工具 -``` -Bash, Edit, Write, Read, Glob, Grep, Task, WebFetch, WebSearch -``` - -### MCP 工具 -``` -mcp____ -mcp__memory__.* -mcp__.*__write.* -``` - ---- - -## Exit Codes - -| Code | 含义 | Claude反馈 | -|------|------|-----------| -| 0 | 成功 | 解析 stdout JSON，允许操作 | -| 2 | 阻止 | stderr 发送给 Claude，阻止操作 | -| 其他 | 错误 | stderr 仅在详细模式显示 | - ---- - -## 标准 JSON 输入（stdin） - -```json -{ - "session_id": "abc123", - "transcript_path": "/path/to/transcript.jsonl", - "cwd": "/current/dir", - "permission_mode": "default", - "hook_event_name": "PreToolUse", - "tool_name": "Bash", - "tool_input": { - "command": "npm test" - } -} -``` - ---- - -## 标准 JSON 输出（stdout, exit 0） - -### PreToolUse -```json -{ - "hookSpecificOutput": { - "hookEventName": "PreToolUse", - "permissionDecision": "allow|deny|ask", - "permissionDecisionReason": "explanation" - } -} -``` - -### UserPromptSubmit -```json -{ - "decision": "block", - "reason": "explanation", - "hookSpecificOutput": { - "hookEventName": "UserPromptSubmit", - "additionalContext": "context string" - } -} -``` - -### Stop -```json -{ - "decision": "block", - "reason": "Must complete tasks X, Y, Z" -} -``` - ---- - -## 处理器类型 - -### 1. Command Hook -```json -{ - "type": "command", - "command": "bash /path/to/script.sh", - "timeout": 600, - "async": false -} -``` - -### 2. Prompt Hook -```json -{ - "type": "prompt", - "prompt": "Evaluate: $ARGUMENTS", - "model": "haiku", - "timeout": 30 -} -``` - -响应格式： -```json -{ - "ok": true|false, - "reason": "explanation if ok is false" -} -``` - -### 3. Agent Hook -```json -{ - "type": "agent", - "prompt": "Verify tests pass: $ARGUMENTS", - "model": "haiku", - "timeout": 60 -} -``` - -响应格式：与 Prompt Hook 相同 - ---- - -## 环境变量 - -### 标准变量 -```bash -$CLAUDE_PROJECT_DIR # 项目根目录 -$CLAUDE_PLUGIN_ROOT # 插件根目录（插件内部使用） -$CLAUDE_CODE_REMOTE # "true" 在远程环境 -``` - -### SessionStart 特殊变量 -```bash -$CLAUDE_ENV_FILE # 持久化环境变量的文件路径 -``` - -用法： -```bash -#!/bin/bash -if [ -n "$CLAUDE_ENV_FILE" ]; then - echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE" -fi -``` - ---- - -## 常见用例 - -### 1. 格式化代码 -```json -{ - "hooks": { - "PostToolUse": [ - { - "matcher": "Edit|Write", - "hooks": [ - { - "type": "command", - "command": "jq -r '.tool_input.file_path' | xargs prettier --write" - } - ] - } - ] - } -} -``` - -### 2. 阻止危险命令 -```json -{ - "hooks": { - "PreToolUse": [ - { - "matcher": "Bash", - "hooks": [ - { - "type": "command", - "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh" - } - ] - } - ] - } -} -``` - -脚本 `block-rm.sh`: -```bash -#!/bin/bash -COMMAND=$(jq -r '.tool_input.command') -if echo "$COMMAND" | grep -q 'rm -rf'; then - echo "Blocked: rm -rf is not allowed" >&2 - exit 2 -fi -exit 0 -``` - -### 3. 通知用户 -```json -{ - "hooks": { - "Notification": [ - { - "matcher": "permission_prompt", - "hooks": [ - { - "type": "command", - "command": "osascript -e 'display notification \"Claude needs your attention\"'" - } - ] - } - ] - } -} -``` - -### 4. 确认任务完成 -```json -{ - "hooks": { - "Stop": [ - { - "hooks": [ - { - "type": "prompt", - "prompt": "Check if all tasks complete: $ARGUMENTS" - } - ] - } - ] - } -} -``` - -### 5. 异步运行测试 -```json -{ - "hooks": { - "PostToolUse": [ - { - "matcher": "Write", - "hooks": [ - { - "type": "command", - "command": "/path/to/run-tests.sh", - "async": true, - "timeout": 120 - } - ] - } - ] - } -} -``` - -### 6. 会话开始注入上下文 -```json -{ - "hooks": { - "SessionStart": [ - { - "matcher": "compact", - "hooks": [ - { - "type": "command", - "command": "echo 'Reminder: use Bun, not npm'" - } - ] - } - ] - } -} -``` - ---- - -## 配置位置 - -| 位置 | 作用域 | 可共享 | -|------|--------|--------| -| `~/.claude/settings.json` | 全局用户 | ❌ | -| `.claude/settings.json` | 单个项目 | ✅ | -| `.claude/settings.local.json` | 单个项目 | ❌ (gitignored) | -| 插件 `hooks/hooks.json` | 插件启用时 | ✅ | -| Skill/Agent frontmatter | 组件活动时 | ✅ | - ---- - -## 调试技巧 - -### 1. 详细模式 -```bash -claude --debug # 查看完整钩子执行细节 -Ctrl+O # 切换详细模式（实时） -``` - -### 2. 测试钩子脚本 -```bash -echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh -echo $? # 检查退出码 -``` - -### 3. 检查钩子配置 -``` -/hooks # 交互式钩子管理器 -``` - ---- - -## 最佳实践 - -✅ **推荐：** -- 总是引用 shell 变量：`"$VAR"` -- 使用绝对路径：`"$CLAUDE_PROJECT_DIR"/script.sh` -- 设置合理的超时时间 -- 验证和清理输入数据 -- 在 Stop 钩子中检查 `stop_hook_active` -- 使用 async 进行长时间运行的操作 - -❌ **避免：** -- 直接信任输入数据 -- 使用相对路径 -- 在钩子输出中暴露敏感数据 -- 创建无限循环（尤其在 Stop 钩子） -- 没有设置超时的阻塞操作 - ---- - -## 官方资源 - -- **指南**: https://code.claude.com/docs/en/hooks-guide -- **参考**: https://code.claude.com/docs/en/hooks -- **示例**: https://github.com/anthropics/claude-code/tree/main/examples/hooks - ---- - -## 本地文档 - -- `HOOKS_OFFICIAL_GUIDE.md` - 官方指南中文版 -- `HOOKS_OFFICIAL_REFERENCE.md` - 官方参考中文版 -- `HOOKS_ANALYSIS_REPORT.md` - 当前实现对比分析 -- `hooks_bash_command_validator.py` - 官方示例脚本 diff --git a/.claude/examples/hooks_bash_command_validator.py b/.claude/examples/hooks_bash_command_validator.py deleted file mode 100644 index d6e5bedb..00000000 --- a/.claude/examples/hooks_bash_command_validator.py +++ /dev/null @@ -1,85 +0,0 @@ -#!/usr/bin/env python3 -""" -Claude Code Hook: Bash Command Validator -========================================= -This hook runs as a PreToolUse hook for the Bash tool. -It validates bash commands against a set of rules before execution. -In this case it changes grep calls to using rg. - -Read more about hooks here: https://code.claude.com/docs/en/hooks - -Make sure to change your path to your actual script. - -Configuration for .claude/settings.json: - -{ - "hooks": { - "PreToolUse": [ - { - "matcher": "Bash", - "hooks": [ - { - "type": "command", - "command": "python3 /path/to/bash_command_validator.py" - } - ] - } - ] - } -} - -""" - -import json -import re -import sys - -# Define validation rules as a list of (regex pattern, message) tuples -_VALIDATION_RULES = [ - ( - r"^grep\b(?!.*\|)", - "Use 'rg' (ripgrep) instead of 'grep' for better performance and features", - ), - ( - r"^find\s+\S+\s+-name\b", - "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance", - ), -] - - -def _validate_command(command: str) -> list[str]: - issues = [] - for pattern, message in _VALIDATION_RULES: - if re.search(pattern, command): - issues.append(message) - return issues - - -def main(): - try: - input_data = json.load(sys.stdin) - except json.JSONDecodeError as e: - print(f"Error: Invalid JSON input: {e}", file=sys.stderr) - # Exit code 1 shows stderr to the user but not to Claude - sys.exit(1) - - tool_name = input_data.get("tool_name", "") - if tool_name != "Bash": - sys.exit(0) - - tool_input = input_data.get("tool_input", {}) - command = tool_input.get("command", "") - - if not command: - sys.exit(0) - - issues = _validate_command(command) - if issues: - for message in issues: - print(f"• {message}", file=sys.stderr) - # Exit code 2 blocks tool call and shows stderr to Claude - sys.exit(2) - - -if __name__ == "__main__": - main() diff --git a/.claude/skills/brainstorm/SKILL.md b/.claude/skills/brainstorm/SKILL.md new file mode 100644 index 00000000..7f1c9647 --- /dev/null +++ b/.claude/skills/brainstorm/SKILL.md @@ -0,0 +1,381 @@ +--- +name: brainstorm +description: Unified brainstorming skill with dual-mode operation - auto pipeline and single role analysis. Triggers on "brainstorm", "头脑风暴". +allowed-tools: Skill(*), Task(conceptual-planning-agent, context-search-agent), AskUserQuestion(*), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*), Bash(*) +--- + +# Brainstorm + +Unified brainstorming skill combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis into a single entry point with two operational modes. + +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────────────┐ +│ /brainstorm │ +│ Unified Entry Point + Interactive Routing │ +└───────────────────────┬─────────────────────────────────────┘ + │ + ┌─────────┴─────────┐ + ↓ ↓ + ┌─────────────────┐ ┌──────────────────┐ + │ Auto Mode │ │ Single Role Mode │ + │ (自动模式) │ │ (单角色分析模式) │ + └────────┬────────┘ └────────┬─────────┘ + │ │ + ┌────────┼────────┐ │ + ↓ ↓ ↓ ↓ + Phase 2 Phase 3 Phase 4 Phase 3 +Artifacts N×Role Synthesis 1×Role + (7步) Analysis (8步) Analysis + 并行 (4步) +``` + +**Data Flow**: +``` +Auto Mode: + Phase 2 (artifacts) → guidance-specification.md + selected_roles[] + → Phase 3 (N × role-analysis) → {role}/analysis*.md + → Phase 4 (synthesis) → feature-specs/ + feature-index.json + +Single Role Mode: + Phase 3 (1 × role-analysis) → {role}/analysis*.md +``` + +## Key Design Principles + +1. **Dual-Mode Routing**: Interactive mode selection via AskUserQuestion, with parameter-based auto-detection +2. **Progressive Phase Loading**: Phase files loaded on-demand via `Ref:` markers, not all at once +3. **Task Attachment/Collapse**: Sub-tasks attached during phase execution, collapsed after completion +4. **Session Continuity**: All phases share session state via workflow-session.json +5. **Auto-Continue Execution**: Phases chain automatically without user intervention between them + +## Auto Mode + +When `--yes` or `-y`: Auto-select auto mode, skip interactive routing question, auto-select recommended roles, skip all clarification questions, use default answers. + +## Execution Flow + +### Phase 1: Mode Detection & Interactive Routing + Ref: phases/01-mode-routing.md + +Parse arguments, detect mode from flags/parameters, or ask user via AskUserQuestion. + +**Mode Detection Rules**: +1. If `--yes` or `-y` flag present → **Auto Mode** (no question asked) +2. If first arg matches a known role name → **Single Role Mode** (no question asked) +3. If `--session` flag present without role name → **Ask user** +4. Otherwise → **Ask user via AskUserQuestion** + +**Output**: `execution_mode` ("auto" | "single-role"), parsed parameters + +--- + +### Auto Mode Execution (execution_mode = "auto") + +#### Phase 2: Interactive Framework Generation + Ref: phases/02-artifacts.md + +Seven-phase interactive workflow: Context collection → Topic analysis → Role selection → Role questions → Conflict resolution → Final check → Generate specification. + +**Input**: topic description, --count N, --yes flag +**Output**: guidance-specification.md, workflow-session.json (selected_roles[], session_id) + +**TodoWrite**: Attach 7 sub-tasks (Phase 0-5), execute sequentially, collapse on completion. + +#### Phase 3: Parallel Role Analysis + Ref: phases/03-role-analysis.md + +Execute role analysis for EACH selected role in parallel. + +**Input**: selected_roles[] from Phase 2, session_id, guidance-specification.md +**Output**: {role}/analysis*.md for each role + +**Parallel Execution**: Launch N role-analysis calls simultaneously (one message with multiple Skill invokes). Each role with `--skip-questions` flag. + +For ui-designer: append `--style-skill {package}` if provided. + +**TodoWrite**: Attach N parallel sub-tasks, execute concurrently, collapse on completion. + +#### Phase 4: Synthesis Integration + Ref: phases/04-synthesis.md + +Eight-phase cross-role synthesis: Discovery → File discovery → Cross-role analysis → User interaction → Document updates → Feature spec generation → Feature index → Finalization. + +**Input**: session_id from Phase 2, all role analysis files from Phase 3 +**Output**: Updated analyses, feature-specs/, feature-index.json + +**TodoWrite**: Attach synthesis sub-tasks, execute sequentially, collapse on completion. + +--- + +### Single Role Mode Execution (execution_mode = "single-role") + +#### Phase 3: Single Role Analysis + Ref: phases/03-role-analysis.md + +Execute role analysis for ONE specified role with optional interactive context gathering. + +**Input**: role_name, --session, --update, --include-questions, --skip-questions, --style-skill +**Output**: {role}/analysis*.md + +**TodoWrite**: Attach 4 sub-tasks (Detection → Context → Agent → Validation), execute sequentially. + +--- + +**Phase Reference Documents** (read on-demand when phase executes): + +| Phase | Document | Purpose | Used By | +|-------|----------|---------|---------| +| 1 | [phases/01-mode-routing.md](phases/01-mode-routing.md) | Parameter parsing, mode detection, interactive routing | Both modes | +| 2 | [phases/02-artifacts.md](phases/02-artifacts.md) | Interactive framework generation (7 phases) | Auto mode only | +| 3 | [phases/03-role-analysis.md](phases/03-role-analysis.md) | Role-specific analysis generation | Both modes | +| 4 | [phases/04-synthesis.md](phases/04-synthesis.md) | Cross-role synthesis and feature specs | Auto mode only | + +## Core Rules + +1. **Start with Mode Detection**: First action is Phase 1 (parse args + detect mode) +2. **Interactive Routing**: If mode cannot be determined from args, ASK user via AskUserQuestion +3. **No Preliminary Analysis**: Do not analyze topic before Phase 2 - artifacts handles all analysis +4. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 2 +5. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically +6. **Task Attachment Model**: Skill and Task executes attach sub-tasks to current workflow +7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow in auto mode. After executing all attached tasks, immediately collapse them and execute next phase +8. **Parallel Execution**: Auto mode Phase 3 attaches multiple agent tasks simultaneously for concurrent execution +9. **Single Role Independence**: Single role mode operates independently without requiring artifacts or synthesis + +## Input Processing + +### Parameter Parsing + +```javascript +// Parse from user input (argument string) +const args = parseArguments(user_input); + +// Flags +const auto_yes = args.includes('--yes') || args.includes('-y'); +const count = extractFlag(args, '--count', 3); // default 3, max 9 +const session_id = extractFlag(args, '--session', null); +const update_mode = args.includes('--update'); +const include_questions = args.includes('--include-questions'); +const skip_questions = args.includes('--skip-questions'); +const style_skill = extractFlag(args, '--style-skill', null); + +// Role detection +const VALID_ROLES = [ + 'data-architect', 'product-manager', 'product-owner', 'scrum-master', + 'subject-matter-expert', 'system-architect', 'test-strategist', + 'ui-designer', 'ux-expert' +]; +const first_arg = args[0]; // first non-flag argument +const is_role = VALID_ROLES.includes(first_arg); + +// Mode detection +if (auto_yes) { + execution_mode = 'auto'; + topic = extractTopic(args); +} else if (is_role) { + execution_mode = 'single-role'; + role_name = first_arg; +} else { + execution_mode = null; // Ask user + topic = extractTopic(args); +} +``` + +### Usage Examples + +```bash +# Auto mode - full pipeline +/brainstorm "Build real-time collaboration platform" --count 3 +/brainstorm -y "GOAL: Build platform SCOPE: 100 users" --count 5 +/brainstorm "Design payment system" --style-skill material-design + +# Single role mode - individual analysis +/brainstorm system-architect --session WFS-xxx +/brainstorm ux-expert --include-questions +/brainstorm ui-designer --session WFS-xxx --update --style-skill material-design +/brainstorm product-manager --skip-questions + +# Ambiguous - will ask interactively +/brainstorm --session WFS-xxx +/brainstorm +``` + +## Data Flow + +``` +Phase 1 (Mode Routing): + Input: user arguments + Output: execution_mode, parsed_params + ↓ + ┌───────┴───────┐ + Auto Single Role + ↓ ↓ +Phase 2: Phase 3: + Input: topic, count, auto_yes + Output: session_id ─────────────→ Input: role_name, session_id + selected_roles[] skip/include questions + guidance-specification.md style_skill + ↓ Output: {role}/analysis*.md +Phase 3: + Input: selected_roles[], session_id + guidance-specification.md + style_skill (for ui-designer) + Output: {role}/analysis*.md (N files) + ↓ +Phase 4: + Input: session_id, all analysis files + Output: Updated analyses + feature-specs/F-{id}-{slug}.md + feature-index.json +``` + +## TodoWrite Pattern + +### Auto Mode Lifecycle + +``` +Initial → Phase 1 Mode Routing (completed) + → Phase 2 Artifacts (in_progress) + → 7 sub-tasks ATTACHED (Phase 0-5) + → Execute sequentially + → Sub-tasks COLLAPSED + → Phase 3 Parallel Role Analysis (in_progress) + → N role sub-tasks ATTACHED simultaneously + → Execute concurrently + → Sub-tasks COLLAPSED + → Phase 4 Synthesis (in_progress) + → 8 sub-tasks ATTACHED + → Execute sequentially + → Sub-tasks COLLAPSED + → All completed +``` + +### Single Role Mode Lifecycle + +``` +Initial → Phase 1 Mode Routing (completed) + → Phase 3 Role Analysis (in_progress) + → 4 sub-tasks ATTACHED (Detection → Context → Agent → Validation) + → Execute sequentially + → Sub-tasks COLLAPSED + → Completed +``` + +### Initial TodoWrite (Auto Mode) + +```json +[ + {"content": "Phase 1: Mode detection and parameter parsing", "status": "in_progress", "activeForm": "Detecting mode"}, + {"content": "Phase 2: Interactive Framework Generation", "status": "pending", "activeForm": "Generating framework"}, + {"content": "Phase 3: Parallel Role Analysis", "status": "pending", "activeForm": "Executing parallel analysis"}, + {"content": "Phase 4: Synthesis Integration", "status": "pending", "activeForm": "Executing synthesis"} +] +``` + +### Initial TodoWrite (Single Role Mode) + +```json +[ + {"content": "Phase 1: Mode detection and parameter parsing", "status": "in_progress", "activeForm": "Detecting mode"}, + {"content": "Phase 3: Single role analysis for {role_name}", "status": "pending", "activeForm": "Executing role analysis"} +] +``` + +## Session Management + +**⚡ FIRST ACTION**: Check `.workflow/active/` for existing sessions + +**Multiple Sessions Support**: +- Different Claude instances can have different brainstorming sessions +- If multiple sessions found, prompt user to select +- If single session found, use it +- If no session exists: + - Auto mode: Create `WFS-[topic-slug]` + - Single role mode: ERROR if no session (must run auto mode first) + +**Session Continuity**: All phases share session state via `workflow-session.json` + +## Available Roles + +| Role ID | Title | Focus Area | +|---------|-------|------------| +| `data-architect` | 数据架构师 | Data models, storage strategies, data flow | +| `product-manager` | 产品经理 | Product strategy, roadmap, prioritization | +| `product-owner` | 产品负责人 | Backlog management, user stories, acceptance criteria | +| `scrum-master` | 敏捷教练 | Process facilitation, impediment removal | +| `subject-matter-expert` | 领域专家 | Domain knowledge, business rules, compliance | +| `system-architect` | 系统架构师 | Technical architecture, scalability, integration | +| `test-strategist` | 测试策略师 | Test strategy, quality assurance | +| `ui-designer` | UI设计师 | Visual design, mockups, design systems | +| `ux-expert` | UX专家 | User research, information architecture, journey | + +**Role Selection**: Auto mode → handled by artifacts (Phase 2). Single role mode → user specifies directly. + +## Output Structure + +``` +.workflow/active/WFS-{topic}/ +├── workflow-session.json # Session metadata ONLY +├── .process/ +│ └── context-package.json # Phase 0 output (auto mode) +└── .brainstorming/ + ├── guidance-specification.md # Framework (Phase 2, auto mode) + ├── feature-index.json # Feature index (Phase 4, auto mode) + ├── feature-specs/ # Feature specs (Phase 4, auto mode) + │ ├── F-001-{slug}.md + │ └── F-00N-{slug}.md + ├── {role}/ + │ ├── {role}-context.md # Interactive Q&A responses + │ ├── analysis.md # Main/index document + │ ├── analysis-cross-cutting.md # Cross-feature (feature_mode) + │ └── analysis-F-{id}-{slug}.md # Per-feature (feature_mode) + └── synthesis-specification.md # Integration (Phase 4, auto mode) +``` + +## Error Handling + +| Error | Recovery | Mode | +|-------|----------|------| +| Invalid role name | Show valid roles list, ask again | Single Role | +| No active session | Auto mode: create new. Single role: error with guidance | Both | +| Role selection failure | Default to product-manager | Auto | +| Agent execution failure | Agent-specific retry with minimal dependencies | Both | +| Template loading issues | Graceful degradation | Both | +| Synthesis conflicts | Highlight disagreements without forced resolution | Auto | +| Context overflow (>100KB) | Read only analysis.md index files | Auto | + +**Context Overflow Protection**: +- Per-role limits: < 3000 words main, < 2000 words sub-docs, max 5 sub-docs +- Synthesis protection: If total > 100KB, read only `analysis.md` (not sub-documents) +- Recovery: reduce scope (--count 2) → use --summary-only → manual synthesis + +## Coordinator Checklist + +**Pre-Phase Actions**: +- [ ] Read Phase document via `Ref:` marker +- [ ] Verify prerequisites (session exists, required files present) +- [ ] Mark phase as `in_progress` in TodoWrite +- [ ] Attach sub-tasks if applicable + +**Post-Phase Actions**: +- [ ] Validate phase outputs exist +- [ ] Collapse sub-tasks to phase summary +- [ ] Mark phase as `completed` in TodoWrite +- [ ] Auto-continue to next pending phase (auto mode) +- [ ] Report completion (single role mode) + +## Related Commands + +**Prerequisites**: +- `/workflow:session:start` - Start a new workflow session (optional, brainstorm creates its own) + +**Follow-ups** (after brainstorm completes): +- `/workflow:plan --session {sessionId}` - Generate implementation plan +- `/workflow:brainstorm:synthesis --session {sessionId}` - Run synthesis standalone (if skipped) + +## Reference Information + +**Template Source**: `~/.ccw/workflows/cli-templates/planning-roles/` +**Style SKILL Packages**: `.claude/skills/style-{package-name}/` diff --git a/.claude/skills/brainstorm/phases/01-mode-routing.md b/.claude/skills/brainstorm/phases/01-mode-routing.md new file mode 100644 index 00000000..e53568d5 --- /dev/null +++ b/.claude/skills/brainstorm/phases/01-mode-routing.md @@ -0,0 +1,207 @@ +# Phase 1: Mode Detection & Interactive Routing + +Parse user arguments, detect execution mode from flags/parameters, or interactively ask the user which mode to use via AskUserQuestion. + +## Objective + +- Parse all command arguments and flags +- Detect execution mode automatically when possible +- Ask user via AskUserQuestion when mode is ambiguous +- Initialize TodoWrite with mode-appropriate task list +- Route to correct execution path + +## Execution + +### Step 1.1: Parameter Parsing + +```javascript +// Parse from user input (argument string) +const args = parseArguments(user_input); + +// Flags +const auto_yes = args.includes('--yes') || args.includes('-y'); +const count = extractFlag(args, '--count', 3); // default 3, max 9 +if (count > 9) count = 9; // Cap at maximum +const session_id = extractFlag(args, '--session', null); +const update_mode = args.includes('--update'); +const include_questions = args.includes('--include-questions'); +const skip_questions = args.includes('--skip-questions'); +const style_skill = extractFlag(args, '--style-skill', null); + +// Role detection +const VALID_ROLES = [ + 'data-architect', 'product-manager', 'product-owner', 'scrum-master', + 'subject-matter-expert', 'system-architect', 'test-strategist', + 'ui-designer', 'ux-expert' +]; +const first_arg = getFirstNonFlagArg(args); +const is_role = VALID_ROLES.includes(first_arg); + +// Topic extraction (everything that's not a flag or role) +const topic = is_role ? null : extractTopic(args); +``` + +### Step 1.2: Style-Skill Validation + +```javascript +if (style_skill) { + const skill_path = `.claude/skills/style-${style_skill}/SKILL.md`; + if (fileExists(skill_path)) { + style_skill_package = style_skill; + style_reference_path = `.workflow/reference_style/${style_skill}`; + // "✓ Style SKILL package found: style-{style_skill}" + } else { + // "⚠ WARNING: Style SKILL package not found: {style_skill}" + style_skill_package = null; + } +} else { + style_skill_package = null; +} +``` + +### Step 1.3: Mode Detection + +```javascript +// Auto-detection rules (ordered by priority) +if (auto_yes) { + // --yes flag explicitly requests auto mode + execution_mode = 'auto'; +} else if (is_role) { + // First arg is a valid role name → single role mode + execution_mode = 'single-role'; + role_name = first_arg; +} else if (topic && !session_id) { + // Topic provided without session → likely auto mode, but ask + execution_mode = null; // Ask user +} else { + // Ambiguous → ask user + execution_mode = null; +} +``` + +### Step 1.4: Interactive Mode Selection (when mode is null) + +```javascript +if (execution_mode === null) { + AskUserQuestion({ + questions: [{ + question: "请选择头脑风暴模式", + header: "模式选择", + multiSelect: false, + options: [ + { + label: "自动模式 (推荐)", + description: "完整流程：框架生成 → 多角色并行分析 → 跨角色综合。适合新主题的全面分析" + }, + { + label: "单角色分析", + description: "为单个角色生成分析文档。适合补充已有会话的角色视角或迭代更新" + } + ] + }] + }); + + // Route based on user selection + if (user_selected === "自动模式 (推荐)") { + execution_mode = 'auto'; + } else { + execution_mode = 'single-role'; + } +} +``` + +### Step 1.5: Single Role Mode - Role Selection (if needed) + +When entering single-role mode without a role name specified: + +```javascript +if (execution_mode === 'single-role' && !role_name) { + // Need to ask which role + AskUserQuestion({ + questions: [{ + question: "请选择要执行分析的角色", + header: "角色选择", + multiSelect: false, + options: [ + { label: "system-architect", description: "系统架构师 - 技术架构、可扩展性、集成模式" }, + { label: "ux-expert", description: "UX专家 - 用户研究、信息架构、用户旅程" }, + { label: "product-manager", description: "产品经理 - 产品策略、路线图、优先级" }, + { label: "ui-designer", description: "UI设计师 - 视觉设计、高保真原型、设计系统" } + ] + }] + }); + // Note: If user needs a role not in top 4, they select "Other" and type it + role_name = user_selected; + + // Validate role name + if (!VALID_ROLES.includes(role_name)) { + // ERROR with valid roles list + // EXIT + } +} +``` + +### Step 1.6: Session Detection + +```javascript +if (!session_id) { + // Find active sessions + const sessions = Glob('.workflow/active/WFS-*/'); + + if (sessions.length > 1) { + // Multiple sessions → ask user to select + // Use AskUserQuestion with session list + } else if (sessions.length === 1) { + session_id = extractSessionId(sessions[0]); + } else { + if (execution_mode === 'auto') { + // Will be created by artifacts phase + session_id = null; // artifacts handles creation + } else { + // Single role mode requires existing session + // ERROR: "No active session. Run /brainstorm 'topic' first" + // EXIT + } + } +} +``` + +### Step 1.7: Initialize TodoWrite + +```javascript +if (execution_mode === 'auto') { + TodoWrite({ + todos: [ + { content: "Phase 1: Mode detection and parameter parsing", status: "completed", activeForm: "Detecting mode" }, + { content: "Phase 2: Interactive Framework Generation", status: "pending", activeForm: "Generating framework" }, + { content: "Phase 3: Parallel Role Analysis", status: "pending", activeForm: "Executing parallel analysis" }, + { content: "Phase 4: Synthesis Integration", status: "pending", activeForm: "Executing synthesis" } + ] + }); +} else { + TodoWrite({ + todos: [ + { content: "Phase 1: Mode detection and parameter parsing", status: "completed", activeForm: "Detecting mode" }, + { content: `Phase 3: ${role_name} analysis`, status: "pending", activeForm: `Executing ${role_name} analysis` } + ] + }); +} +``` + +## Output + +- **Variable**: `execution_mode` ("auto" | "single-role") +- **Variable**: `role_name` (single-role mode only) +- **Variable**: `topic` (auto mode only) +- **Variable**: `session_id` (may be null for auto mode - artifacts creates it) +- **Variable**: `count` (auto mode, default 3) +- **Variable**: `auto_yes` (boolean) +- **Variable**: `style_skill_package` (optional) +- **Variable**: `update_mode`, `include_questions`, `skip_questions` (single-role flags) +- **TodoWrite**: Phase 1 completed, subsequent phases pending + +## Next Phase + +Return to orchestrator: +- If `execution_mode === 'auto'` → Continue to [Phase 2: Artifacts](02-artifacts.md) +- If `execution_mode === 'single-role'` → Continue to [Phase 3: Role Analysis](03-role-analysis.md) diff --git a/.claude/skills/brainstorm/phases/02-artifacts.md b/.claude/skills/brainstorm/phases/02-artifacts.md new file mode 100644 index 00000000..4b3b66b4 --- /dev/null +++ b/.claude/skills/brainstorm/phases/02-artifacts.md @@ -0,0 +1,457 @@ +# Phase 2: Interactive Framework Generation (Artifacts) + +Seven-phase interactive workflow generating confirmed guidance specification through role-based analysis and synthesis. This phase handles all user interaction for topic exploration, role selection, and decision gathering. + +## Objective + +- Collect project context automatically (Phase 0) +- Analyze topic and extract keywords/challenges (Phase 1) +- Select roles via intelligent recommendation + user confirmation (Phase 2) +- Generate deep role-specific questions (Phase 3) +- Resolve cross-role conflicts (Phase 4) +- Final clarification and feature decomposition (Phase 4.5) +- Generate declarative guidance-specification.md (Phase 5) + +## Auto Mode + +When `--yes` or `-y`: Auto-select recommended roles, skip all clarification questions, use default answers. + +## TodoWrite Integration + +**TodoWrite Rule**: EXTEND auto-parallel's task list (NOT replace/overwrite) + +**When called from auto mode**: +- Find artifacts parent task → Mark "in_progress" +- APPEND sub-tasks (Phase 0-5) → Mark each as completes +- When Phase 5 completes → Mark parent "completed" +- PRESERVE all other auto-parallel tasks + +**Standalone Mode**: +```json +[ + {"content": "Initialize session", "status": "pending", "activeForm": "Initializing"}, + {"content": "Phase 0: Context collection", "status": "pending", "activeForm": "Phase 0"}, + {"content": "Phase 1: Topic analysis (2-4 questions)", "status": "pending", "activeForm": "Phase 1"}, + {"content": "Phase 2: Role selection", "status": "pending", "activeForm": "Phase 2"}, + {"content": "Phase 3: Role questions (per role)", "status": "pending", "activeForm": "Phase 3"}, + {"content": "Phase 4: Conflict resolution", "status": "pending", "activeForm": "Phase 4"}, + {"content": "Phase 4.5: Final clarification + Feature decomposition", "status": "pending", "activeForm": "Phase 4.5"}, + {"content": "Phase 5: Generate specification", "status": "pending", "activeForm": "Phase 5"} +] +``` + +## Execution + +### Session Management + +- Check `.workflow/active/` for existing sessions +- Multiple → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]` +- Parse `--count N` parameter (default: 3) +- Store decisions in `workflow-session.json` + +### Phase 0: Context Collection + +**Goal**: Gather project context BEFORE user interaction + +**Steps**: +1. Check if `context-package.json` exists → Skip if valid +2. Invoke `context-search-agent` (BRAINSTORM MODE - lightweight) +3. Output: `.workflow/active/WFS-{session-id}/.process/context-package.json` + +**Graceful Degradation**: If agent fails, continue to Phase 1 without context + +```javascript +Task( + subagent_type="context-search-agent", + run_in_background=false, + description="Gather project context for brainstorm", + prompt=` +Execute context-search-agent in BRAINSTORM MODE (Phase 1-2 only). + +Session: ${session_id} +Task: ${task_description} +Output: .workflow/${session_id}/.process/context-package.json + +Required fields: metadata, project_context, assets, dependencies, conflict_detection +` +) +``` + +### Phase 1: Topic Analysis + +**Goal**: Extract keywords/challenges enriched by Phase 0 context + +**Steps**: +1. Load Phase 0 context (tech_stack, modules, conflict_risk) +2. Deep topic analysis (entities, challenges, constraints, metrics) +3. Generate 2-4 context-aware probing questions +4. AskUserQuestion → Store to `session.intent_context` + +**Example**: +```javascript +AskUserQuestion({ + questions: [ + { + question: "实时协作平台的主要技术挑战？", + header: "核心挑战", + multiSelect: false, + options: [ + { label: "实时数据同步", description: "100+用户同时在线，状态同步复杂度高" }, + { label: "可扩展性架构", description: "用户规模增长时的系统扩展能力" }, + { label: "冲突解决机制", description: "多用户同时编辑的冲突处理策略" } + ] + }, + { + question: "MVP阶段最关注的指标？", + header: "优先级", + multiSelect: false, + options: [ + { label: "功能完整性", description: "实现所有核心功能" }, + { label: "用户体验", description: "流畅的交互体验和响应速度" }, + { label: "系统稳定性", description: "高可用性和数据一致性" } + ] + } + ] +}) +``` + +**⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation. + +### Phase 2: Role Selection + +**Goal**: User selects roles from intelligent recommendations + +**Available Roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert + +**Steps**: +1. Analyze Phase 1 keywords → Recommend count+2 roles with rationale +2. AskUserQuestion (multiSelect=true) → Store to `session.selected_roles` +3. If count+2 > 4, split into multiple rounds + +**Example**: +```javascript +AskUserQuestion({ + questions: [{ + question: "请选择 3 个角色参与头脑风暴分析", + header: "角色选择", + multiSelect: true, + options: [ + { label: "system-architect", description: "实时同步架构设计和技术选型" }, + { label: "ui-designer", description: "协作界面用户体验和状态展示" }, + { label: "product-manager", description: "功能优先级和MVP范围决策" }, + { label: "data-architect", description: "数据同步模型和存储方案设计" } + ] + }] +}) +``` + +**⚠️ CRITICAL**: User MUST interact. NEVER auto-select without confirmation (unless --yes flag). + +### Phase 3: Role-Specific Questions + +**Goal**: Generate deep questions mapping role expertise to Phase 1 challenges + +**Algorithm**: +1. FOR each selected role: + - Map Phase 1 challenges to role domain + - Generate 3-4 questions (implementation depth, trade-offs, edge cases) + - AskUserQuestion per role → Store to `session.role_decisions[role]` +2. Process roles sequentially (one at a time for clarity) +3. If role needs > 4 questions, split into multiple rounds + +**Example** (system-architect): +```javascript +AskUserQuestion({ + questions: [ + { + question: "100+ 用户实时状态同步方案？", + header: "状态同步", + multiSelect: false, + options: [ + { label: "Event Sourcing", description: "完整事件历史，支持回溯，存储成本高" }, + { label: "集中式状态管理", description: "实现简单，单点瓶颈风险" }, + { label: "CRDT", description: "去中心化，自动合并，学习曲线陡" } + ] + }, + { + question: "两个用户同时编辑冲突如何解决？", + header: "冲突解决", + multiSelect: false, + options: [ + { label: "自动合并", description: "用户无感知，可能产生意外结果" }, + { label: "手动解决", description: "用户控制，增加交互复杂度" }, + { label: "版本控制", description: "保留历史，需要分支管理" } + ] + } + ] +}) +``` + +### Phase 4: Conflict Resolution + +**Goal**: Resolve ACTUAL conflicts from Phase 3 answers + +**Algorithm**: +1. Analyze Phase 3 answers for conflicts: + - Contradictory choices (e.g., "fast iteration" vs "complex Event Sourcing") + - Missing integration (e.g., "Optimistic updates" but no conflict handling) + - Implicit dependencies (e.g., "Live cursors" but no auth defined) +2. Generate clarification questions referencing SPECIFIC Phase 3 choices +3. AskUserQuestion (max 4 per call, multi-round) → Store to `session.cross_role_decisions` +4. If NO conflicts: Skip Phase 4 (inform user: "未检测到跨角色冲突，跳过Phase 4") + +**Example**: +```javascript +AskUserQuestion({ + questions: [{ + question: "CRDT 与 UI 回滚期望冲突，如何解决？\n背景：system-architect选择CRDT，ui-designer期望回滚UI", + header: "架构冲突", + multiSelect: false, + options: [ + { label: "采用 CRDT", description: "保持去中心化，调整UI期望" }, + { label: "显示合并界面", description: "增加用户交互，展示冲突详情" }, + { label: "切换到 OT", description: "支持回滚，增加服务器复杂度" } + ] + }] +}) +``` + +### Phase 4.5: Final Clarification + +**Purpose**: Ensure no important points missed before generating specification + +**Steps**: +1. Ask initial check: + ```javascript + AskUserQuestion({ + questions: [{ + question: "在生成最终规范之前，是否有前面未澄清的重点需要补充？", + header: "补充确认", + multiSelect: false, + options: [ + { label: "无需补充", description: "前面的讨论已经足够完整" }, + { label: "需要补充", description: "还有重要内容需要澄清" } + ] + }] + }) + ``` +2. If "需要补充": + - Analyze user's additional points + - Generate progressive questions (not role-bound, interconnected) + - AskUserQuestion (max 4 per round) → Store to `session.additional_decisions` + - Repeat until user confirms completion +3. If "无需补充": Proceed to Feature Decomposition + +**Progressive Pattern**: Questions interconnected, each round informs next, continue until resolved. + +#### Feature Decomposition + +After final clarification, extract implementable feature units from all Phase 1-4 decisions. + +**Steps**: +1. Analyze all accumulated decisions (`intent_context` + `role_decisions` + `cross_role_decisions` + `additional_decisions`) +2. Extract candidate features: each must be an independently implementable unit with clear boundaries +3. Generate candidate list (max 8 features) with structured format: + - Feature ID: `F-{3-digit}` (e.g., F-001) + - Name: kebab-case slug (e.g., `real-time-sync`, `user-auth`) + - Description: one-sentence summary of the feature's scope + - Related roles: which roles' decisions drive this feature + - Priority: High / Medium / Low +4. Present candidate list to user for confirmation: + ```javascript + AskUserQuestion({ + questions: [{ + question: "以下是从讨论中提取的功能点清单：\n\nF-001: [name] - [description]\nF-002: [name] - [description]\n...\n\n是否需要调整？", + header: "功能点确认", + multiSelect: false, + options: [ + { label: "确认无误", description: "功能点清单完整且合理，继续生成规范" }, + { label: "需要调整", description: "需要增加、删除或修改功能点" } + ] + }] + }) + ``` +5. If "需要调整": Collect adjustments and re-present until user confirms +6. Store confirmed list to `session.feature_list` + +**Constraints**: +- Maximum 8 features (if more candidates, merge related items) +- Each feature MUST be independently implementable (no implicit cross-feature dependencies) +- Feature ID format: `F-{3-digit}` (F-001, F-002, ...) +- Feature slug: kebab-case, descriptive of the feature scope + +**Granularity Guidelines** (用于验证功能点粒度是否合适): + +| Signal | Too Coarse | Just Right | Too Fine | +|--------|-----------|------------|----------| +| 实现范围 | 需要 5+ 个独立模块协同 | 1-3 个模块，边界清晰 | 单个函数或单个 API 端点 | +| 角色关注 | 所有角色都深度涉及 | 2-4 个角色有实质贡献 | 仅 1 个角色关注 | +| 可测试性 | 无法写出清晰的验收标准 | 可定义 3-5 条可测量验收标准 | 验收标准等同于单元测试 | +| 依赖关系 | 与其他功能点循环依赖 | 依赖关系单向且可识别 | 无任何外部依赖（可能遗漏） | + +**Quality Validation** (Step 3 提取候选功能点后，逐条验证): +1. **独立性检查**: 该功能点是否可以在其他功能点未完成时独立交付？若否 → 考虑合并或重新划分 +2. **完整性检查**: 该功能点是否覆盖了一个用户可感知的完整价值？若否 → 可能太细，考虑合并 +3. **粒度均衡检查**: 各功能点之间的复杂度是否大致均衡（最大不超过最小的 3 倍）？若否 → 拆分过大的或合并过小的 +4. **边界清晰检查**: 是否能用一句话描述该功能点的输入和输出？若否 → 边界模糊，需重新定义 + +**Handling Vague Requirements** (当用户需求模糊时的额外步骤): +- 如果 Phase 1-4 的决策不足以支撑功能点分解（如缺少具体业务场景、技术选型未定），在 Step 4 确认时**主动告知用户**哪些功能点的粒度可能不够精确 +- 对不确定的功能点标注 `Priority: TBD`，在后续 synthesis 阶段通过跨角色分析进一步明确 +- 如果候选功能点 ≤ 2 个，可能是需求过于抽象 → 提示用户补充更多具体场景后再分解 + +### Phase 5: Generate Specification + +**Steps**: +1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` + `additional_decisions` + `feature_list` +2. Transform Q&A to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements +3. Generate `guidance-specification.md` +4. Update `workflow-session.json` (metadata only) +5. Validate: No interrogative sentences, all decisions traceable + +## Question Guidelines + +### Core Principle + +**Target**: 开发者（理解技术但需要从用户需求出发） + +**Question Structure**: `[业务场景/需求前提] + [技术关注点]` +**Option Structure**: `标签：[技术方案] + 说明：[业务影响] + [技术权衡]` + +### Quality Rules + +**MUST Include**: +- ✅ All questions in Chinese (用中文提问) +- ✅ 业务场景作为问题前提 +- ✅ 技术选项的业务影响说明 +- ✅ 量化指标和约束条件 + +**MUST Avoid**: +- ❌ 纯技术选型无业务上下文 +- ❌ 过度抽象的用户体验问题 +- ❌ 脱离话题的通用架构问题 + +### Phase-Specific Requirements + +| Phase | Focus | Key Requirements | +|-------|-------|------------------| +| 1 | 意图理解 | Reference topic keywords, 用户场景、业务约束、优先级 | +| 2 | 角色推荐 | Intelligent analysis (NOT keyword mapping), explain relevance | +| 3 | 角色问题 | Reference Phase 1 keywords, concrete options with trade-offs | +| 4 | 冲突解决 | Reference SPECIFIC Phase 3 choices, explain impact on both roles | + +### Multi-Round Execution Pattern + +```javascript +const BATCH_SIZE = 4; +for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) { + const batch = allQuestions.slice(i, i + BATCH_SIZE); + AskUserQuestion({ questions: batch }); + // Store responses before next round +} +``` + +## Output + +### Generated Files + +**File**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` + +```markdown +# [Project] - Confirmed Guidance Specification + +**Metadata**: [timestamp, type, focus, roles] + +## 1. Project Positioning & Goals +**CONFIRMED Objectives**: [from topic + Phase 1] +**CONFIRMED Success Criteria**: [from Phase 1 answers] + +## 2-N. [Role] Decisions +### SELECTED Choices +**[Question topic]**: [User's answer] +- **Rationale**: [From option description] +- **Impact**: [Implications] + +### Cross-Role Considerations +**[Conflict resolved]**: [Resolution from Phase 4] +- **Affected Roles**: [Roles involved] + +## Cross-Role Integration +**CONFIRMED Integration Points**: [API/Data/Auth from multiple roles] + +## Risks & Constraints +**Identified Risks**: [From answers] → Mitigation: [Approach] + +## Next Steps +**⚠️ Automatic Continuation** (when called from auto mode): +- Auto mode assigns agents for role-specific analysis +- Each selected role gets conceptual-planning-agent +- Agents read this guidance-specification.md for context + +## Feature Decomposition + +**Constraints**: Max 8 features | Each independently implementable | ID format: F-{3-digit} + +| Feature ID | Name | Description | Related Roles | Priority | +|------------|------|-------------|---------------|----------| +| F-001 | [kebab-case-slug] | [One-sentence scope] | [role1, role2] | High/Medium/Low | +| F-002 | [kebab-case-slug] | [One-sentence scope] | [role1] | High/Medium/Low | + +## Appendix: Decision Tracking +| Decision ID | Category | Question | Selected | Phase | Rationale | +|-------------|----------|----------|----------|-------|-----------| +| D-001 | Intent | [Q] | [A] | 1 | [Why] | +| D-002 | Roles | [Selected] | [Roles] | 2 | [Why] | +| D-003+ | [Role] | [Q] | [A] | 3 | [Why] | +``` + +### Session Metadata + +```json +{ + "session_id": "WFS-{topic-slug}", + "type": "brainstorming", + "topic": "{original user input}", + "selected_roles": ["system-architect", "ui-designer", "product-manager"], + "phase_completed": "artifacts", + "timestamp": "2025-10-24T10:30:00Z", + "count_parameter": 3, + "style_skill_package": null +} +``` + +**⚠️ Rule**: Session JSON stores ONLY metadata. All guidance content goes to guidance-specification.md. + +### Validation Checklist + +- ✅ No interrogative sentences (use CONFIRMED/SELECTED) +- ✅ Every decision traceable to user answer +- ✅ Cross-role conflicts resolved or documented +- ✅ Next steps concrete and specific +- ✅ No content duplication between .json and .md +- ✅ Feature Decomposition table present with validated entries + +### Governance Rules + +- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections) +- Every decision MUST trace to user answer +- Conflicts MUST be resolved (not marked "TBD") +- Next steps MUST be actionable +- Topic preserved as authoritative reference + +**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance. + +### Update Mechanism + +``` +IF guidance-specification.md EXISTS: + Prompt: "Regenerate completely / Update sections / Cancel" +ELSE: + Run full Phase 0-5 flow +``` + +- **TodoWrite**: Mark Phase 2 completed, collapse sub-tasks to summary + +## Next Phase + +Return to orchestrator, then auto-continue to [Phase 3: Role Analysis](03-role-analysis.md) (auto mode: parallel execution for all selected roles). diff --git a/.codex/skills/workflow-brainstorm-auto-parallel/phases/02-parallel-role-analysis.md b/.claude/skills/brainstorm/phases/03-role-analysis.md similarity index 59% rename from .codex/skills/workflow-brainstorm-auto-parallel/phases/02-parallel-role-analysis.md rename to .claude/skills/brainstorm/phases/03-role-analysis.md index ed906893..48d31d09 100644 --- a/.codex/skills/workflow-brainstorm-auto-parallel/phases/02-parallel-role-analysis.md +++ b/.claude/skills/brainstorm/phases/03-role-analysis.md @@ -1,16 +1,17 @@ -## Overview +# Phase 3: Role Analysis -**Unified command for generating and updating role-specific analysis** with interactive context gathering, framework alignment, and incremental update support. Replaces 9 individual role commands with single parameterized workflow. +Unified role-specific analysis generation with interactive context gathering, framework alignment, and incremental update support. Supports both parallel execution (auto mode, N roles simultaneously) and single-role execution. -### Core Function -- **Multi-Role Support**: Single command supports all 9 brainstorming roles -- **Interactive Context**: Dynamic question generation based on role and framework -- **Incremental Updates**: Merge new insights into existing analyses -- **Framework Alignment**: Address guidance-specification.md discussion points -- **Agent Delegation**: Use conceptual-planning-agent with role-specific templates -- **Explicit Lifecycle**: Manage subagent creation, waiting, and cleanup +## Objective -### Supported Roles +- Validate role name and detect session +- Gather interactive context via role-specific questions (optional) +- Execute conceptual-planning-agent with role template and framework +- Support feature-point output organization when feature list available +- Support incremental updates to existing analyses +- Validate output and update session metadata + +## Supported Roles | Role ID | Title | Focus Area | Context Questions | |---------|-------|------------|-------------------| @@ -24,31 +25,26 @@ | `data-architect` | 数据架构师 | Data models, storage strategies, data flow | 5 | | `api-designer` | API设计师 | API contracts, versioning, integration patterns | 4 | ---- +## Execution -## Usage +### Auto Mode Parallel Execution -```bash -# Generate new analysis with interactive context -role-analysis ux-expert +When called from auto mode, launch N role-analysis calls simultaneously: -# Generate with existing framework + context questions -role-analysis system-architect --session WFS-xxx --include-questions +```javascript +// Single message with multiple Skill invokes for parallelism +// For each selected role: +Skill(skill="workflow:brainstorm:role-analysis", args="{role-name} --session {session-id} --skip-questions") -# Update existing analysis (incremental merge) -role-analysis ui-designer --session WFS-xxx --update - -# Quick generation (skip interactive context) -role-analysis product-manager --session WFS-xxx --skip-questions +// For ui-designer with style-skill: +Skill(skill="workflow:brainstorm:role-analysis", args="ui-designer --session {session-id} --skip-questions --style-skill {style_skill_package}") ``` ---- +**Parallel Safety**: Each role operates independently on its own directory. No cross-agent dependencies. -## Execution Protocol +### Step 3.1: Detection & Validation -### Phase 1: Detection & Validation - -**Step 1.1: Role Validation** +**Step 3.1.1: Role Validation** ```bash VALIDATE role_name IN [ ux-expert, ui-designer, system-architect, product-manager, @@ -60,36 +56,44 @@ IF invalid: EXIT ``` -**Step 1.2: Session Detection** +**Step 3.1.2: Session Detection** ```bash IF --session PROVIDED: session_id = --session - brainstorm_dir = ${projectRoot}/.workflow/active/{session_id}/.brainstorming/ + brainstorm_dir = .workflow/active/{session_id}/.brainstorming/ ELSE: - FIND ${projectRoot}/.workflow/active/WFS-*/ + FIND .workflow/active/WFS-*/ IF multiple: PROMPT user to select ELSE IF single: USE existing ELSE: - ERROR: "No active session. Run Phase 1 (artifacts) first" + ERROR: "No active session. Run /brainstorm 'topic' first" EXIT VALIDATE brainstorm_dir EXISTS ``` -**Step 1.3: Framework Detection** +**Step 3.1.3: Framework Detection & Feature List Extraction** ```bash framework_file = {brainstorm_dir}/guidance-specification.md IF framework_file EXISTS: framework_mode = true LOAD framework_content + # Extract Feature Decomposition table from guidance-specification.md + feature_list = EXTRACT_TABLE(framework_content, "Feature Decomposition") + # feature_list format: [{id: "F-001", slug: "real-time-sync", description: "...", roles: [...], priority: "High"}, ...] + IF feature_list NOT EMPTY: + feature_mode = true # Use feature-point organization for sub-documents + ELSE: + feature_mode = false # Fall back to arbitrary-topic organization ELSE: WARN: "No framework found - will create standalone analysis" framework_mode = false + feature_mode = false ``` -**Step 1.4: Update Mode Detection** +**Step 3.1.4: Update Mode Detection** ```bash existing_analysis = {brainstorm_dir}/{role_name}/analysis*.md IF --update FLAG OR existing_analysis EXISTS: @@ -101,14 +105,14 @@ ELSE: update_mode = false ``` -### Phase 2: Interactive Context Gathering +### Step 3.2: Interactive Context Gathering **Trigger Conditions**: - Default: Always ask unless `--skip-questions` provided - `--include-questions`: Force context gathering even if analysis exists - `--skip-questions`: Skip all interactive questions -**Step 2.1: Load Role Configuration** +**Step 3.2.1: Load Role Configuration** ```javascript const roleConfig = { 'ux-expert': { @@ -179,7 +183,7 @@ const roleConfig = { config = roleConfig[role_name]; ``` -**Step 2.2: Generate Role-Specific Questions** +**Step 3.2.2: Generate Role-Specific Questions** **9-Category Taxonomy**: @@ -218,7 +222,7 @@ async function generateQuestions(role_name, framework_content) { } ``` -**Step 2.3: Multi-Round Question Execution** +**Step 3.2.3: Multi-Round Question Execution** ```javascript const BATCH_SIZE = 4; @@ -231,14 +235,17 @@ for (let i = 0; i < questions.length; i += BATCH_SIZE) { console.log(`\n[Round ${currentRound}/${totalRounds}] ${config.title} 上下文询问\n`); - ASK_USER(batch.map(q => ({ - id: q.category.substring(0, 12), type: "select", - prompt: q.question, - options: q.options.map(opt => ({ - label: opt.label, - description: opt.description + AskUserQuestion({ + questions: batch.map(q => ({ + question: q.question, + header: q.category.substring(0, 12), + multiSelect: false, + options: q.options.map(opt => ({ + label: opt.label, + description: opt.description + })) })) - }))); // BLOCKS (wait for user response) + }); // Store responses before next round for (const answer of responses) { @@ -270,22 +277,24 @@ Write( - ❌ 过度抽象的通用问题 - ❌ 脱离框架的重复询问 -### Phase 3: Agent Execution +### Step 3.3: Agent Execution -**Step 3.1: Load Session Metadata** +**Step 3.3.1: Load Session Metadata** ```bash -session_metadata = Read(${projectRoot}/.workflow/active/{session_id}/workflow-session.json) +session_metadata = Read(.workflow/active/{session_id}/workflow-session.json) original_topic = session_metadata.topic selected_roles = session_metadata.selected_roles ``` -**Step 3.2: Prepare Agent Context** +**Step 3.3.2: Prepare Agent Context** ```javascript const agentContext = { role_name: role_name, role_config: roleConfig[role_name], output_location: `${brainstorm_dir}/${role_name}/`, framework_mode: framework_mode, + feature_mode: feature_mode, + feature_list: feature_mode ? feature_list : null, framework_path: framework_mode ? `${brainstorm_dir}/guidance-specification.md` : null, update_mode: update_mode, user_context: user_context, @@ -294,22 +303,33 @@ const agentContext = { }; ``` -**Step 3.3: Execute Conceptual Planning Agent** +**Step 3.3.3: Execute Conceptual Planning Agent** **Framework-Based Analysis** (when guidance-specification.md exists): ```javascript -// Spawn conceptual-planning-agent -const roleAgentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT +// Build feature list injection block (only when feature_mode is true) +const featureListBlock = feature_mode ? ` +## Feature Point List (from guidance-specification.md Feature Decomposition) +${feature_list.map(f => `- **${f.id}** (${f.slug}): ${f.description} [Priority: ${f.priority}]`).join('\n')} -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- +**IMPORTANT - Feature-Point Output Organization**: +- Generate ONE sub-document per feature: analysis-F-{id}-{slug}.md (e.g., analysis-${feature_list[0].id}-${feature_list[0].slug}.md) +- Generate ONE cross-cutting document: analysis-cross-cutting.md +- analysis.md is a role overview INDEX only (< 1500 words), NOT a full analysis +- Each feature sub-document < 2000 words, cross-cutting < 2000 words +- Total across all files < 15000 words +` : ` +## Output Organization (fallback: no feature list available) +- Generate analysis.md as main document (< 3000 words) +- Optionally split into analysis-{slug}.md sub-documents (max 5, < 2000 words each) +- Total < 15000 words +`; +Task( + subagent_type="conceptual-planning-agent", + run_in_background=false, + description=`Generate ${role_name} analysis`, + prompt=` [FLOW_CONTROL] Execute ${role_name} analysis for existing topic framework @@ -318,6 +338,7 @@ Execute ${role_name} analysis for existing topic framework ASSIGNED_ROLE: ${role_name} OUTPUT_LOCATION: ${agentContext.output_location} ANALYSIS_MODE: ${framework_mode ? "framework_based" : "standalone"} +FEATURE_MODE: ${feature_mode} UPDATE_MODE: ${update_mode} ## Flow Control Steps @@ -333,7 +354,7 @@ UPDATE_MODE: ${update_mode} 3. **load_session_metadata** - Action: Load session metadata and user intent - - Command: Read(${projectRoot}/.workflow/active/${session_id}/workflow-session.json) + - Command: Read(.workflow/active/${session_id}/workflow-session.json) - Output: session_context 4. **load_user_context** (if exists) @@ -348,18 +369,30 @@ UPDATE_MODE: ${update_mode} - Output: existing_analysis_content ` : ''} +${featureListBlock} + ## Analysis Requirements **Primary Reference**: Original user prompt from workflow-session.json is authoritative **Framework Source**: Address all discussion points in guidance-specification.md from ${role_name} perspective **User Context Integration**: Incorporate interactive Q&A responses into analysis **Role Focus**: ${roleConfig[role_name].focus_area} **Template Integration**: Apply role template guidelines within framework structure +${feature_mode ? `**Feature Organization**: Organize analysis by feature points - each feature gets its own sub-document. Cross-cutting concerns go into analysis-cross-cutting.md.` : ''} ## Expected Deliverables +${feature_mode ? ` +1. **analysis.md** - Role overview index (< 1500 words): role perspective summary, feature point index with @-references to sub-documents, cross-cutting summary +2. **analysis-cross-cutting.md** - Cross-feature decisions (< 2000 words): architecture decisions, technology choices, shared patterns that span multiple features +3. **analysis-F-{id}-{slug}.md** - One per feature (< 2000 words each): role-specific analysis, recommendations, considerations for that feature +4. **Framework Reference**: @../guidance-specification.md (if framework_mode) +5. **User Context Reference**: @./${role_name}-context.md (if user context exists) +6. **User Intent Alignment**: Validate against session_context +` : ` 1. **analysis.md** (main document, optionally with analysis-{slug}.md sub-documents) 2. **Framework Reference**: @../guidance-specification.md (if framework_mode) 3. **User Context Reference**: @./${role_name}-context.md (if user context exists) 4. **User Intent Alignment**: Validate against session_context +`} ## Update Requirements (if UPDATE_MODE) - **Preserve Structure**: Maintain existing analysis structure @@ -371,123 +404,18 @@ UPDATE_MODE: ${update_mode} - Address each discussion point from guidance-specification.md with ${role_name} expertise - Provide actionable recommendations from ${role_name} perspective within analysis files - All output files MUST start with "analysis" prefix (no recommendations.md or other naming) +${feature_mode ? `- Each feature from the feature list has a corresponding analysis-F-{id}-{slug}.md file +- analysis-cross-cutting.md exists with cross-feature decisions +- analysis.md serves as index (< 1500 words), NOT a full analysis document` : ''} - Reference framework document using @ notation for integration - Update workflow-session.json with completion status ` -}); - -// Wait for agent completion -const roleResult = wait({ - ids: [roleAgentId], - timeout_ms: 600000 // 10 minutes -}); - -// Check result and cleanup -if (roleResult.timed_out) { - console.warn(`${role_name} analysis timed out`); -} - -// Always close agent -close_agent({ id: roleAgentId }); +); ``` -### Phase 3 (Parallel Mode): Execute Multiple Roles Concurrently +### Step 3.4: Validation & Finalization -**When called from auto-parallel orchestrator**, execute all selected roles in parallel: - -```javascript -// Step 1: Spawn all role agents in parallel -const roleAgents = []; - -selected_roles.forEach((role_name, index) => { - const config = roleConfig[role_name]; - - // For ui-designer, append style-skill if provided - const styleContext = (role_name === 'ui-designer' && style_skill_package) - ? `\n## Style Reference\n**Style SKILL Package**: .codex/skills/style-${style_skill_package}/\n**Load First**: Read SKILL.md from style package for design tokens` - : ''; - - const agentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -## Task Objective -Execute **${role_name}** (${config.title}) analysis for brainstorming session. - -## Assigned Context -- **Role**: ${role_name} -- **Role Focus**: ${config.focus_area} -- **Session ID**: ${session_id} -- **Framework Path**: ${brainstorm_dir}/guidance-specification.md -- **Output Location**: ${brainstorm_dir}/${role_name}/ -- **Role Index**: ${index + 1} of ${selected_roles.length} -${styleContext} - -## Analysis Requirements -**Primary Reference**: Original user prompt from workflow-session.json is authoritative -**Framework Source**: Address all discussion points in guidance-specification.md from ${role_name} perspective -**Role Focus**: ${config.focus_area} - -## Expected Deliverables -1. **analysis.md** (main document) -2. **analysis-{slug}.md** (optional sub-documents, max 5) -3. **Framework Reference**: @../guidance-specification.md - -## Completion Criteria -- Address each framework discussion point with ${role_name} expertise -- Provide actionable recommendations within analysis files -- All output files MUST start with "analysis" prefix -` - }); - - roleAgents.push({ agentId, role_name }); -}); - -// Step 2: Batch wait for all agents -const agentIds = roleAgents.map(a => a.agentId); -const parallelResults = wait({ - ids: agentIds, - timeout_ms: 900000 // 15 minutes for all agents -}); - -// Step 3: Process results and check completion -const completedRoles = []; -const failedRoles = []; - -roleAgents.forEach(({ agentId, role_name }) => { - if (parallelResults.status[agentId]?.completed) { - completedRoles.push(role_name); - } else { - failedRoles.push(role_name); - } -}); - -if (parallelResults.timed_out) { - console.warn('Some role analyses timed out:', failedRoles); -} - -// Step 4: Batch cleanup - IMPORTANT: always close all agents -roleAgents.forEach(({ agentId }) => { - close_agent({ id: agentId }); -}); - -console.log(`Completed: ${completedRoles.length}/${selected_roles.length} roles`); -console.log(`Completed roles: ${completedRoles.join(', ')}`); -if (failedRoles.length > 0) { - console.warn(`Failed roles: ${failedRoles.join(', ')}`); -} -``` - -### Phase 4: Validation & Finalization - -**Step 4.1: Validate Output** +**Step 3.4.1: Validate Output** ```bash VERIFY EXISTS: ${brainstorm_dir}/${role_name}/analysis.md VERIFY CONTAINS: "@../guidance-specification.md" (if framework_mode) @@ -495,7 +423,7 @@ IF user_context EXISTS: VERIFY CONTAINS: "@./${role_name}-context.md" OR "## Clarifications" section ``` -**Step 4.2: Update Session Metadata** +**Step 3.4.2: Update Session Metadata** ```json { "phases": { @@ -504,13 +432,13 @@ IF user_context EXISTS: "status": "${update_mode ? 'updated' : 'completed'}", "completed_at": "timestamp", "framework_addressed": true, - "context_gathered": user_context ? true : false, + "context_gathered": true, "output_location": "${brainstorm_dir}/${role_name}/analysis.md", "update_history": [ { "timestamp": "ISO8601", "mode": "${update_mode ? 'incremental' : 'initial'}", - "context_questions": question_count + "context_questions": "question_count" } ] } @@ -519,7 +447,7 @@ IF user_context EXISTS: } ``` -**Step 4.3: Completion Report** +**Step 3.4.3: Completion Report** ```markdown ✅ ${roleConfig[role_name].title} Analysis Complete @@ -538,29 +466,106 @@ ${update_mode ? ' **Next Steps**: ${selected_roles.length > 1 ? ` - Continue with other roles: ${selected_roles.filter(r => r !== role_name).join(', ')} - - Run synthesis: Phase 3 (synthesis integration) + - Run synthesis: /brainstorm --session ${session_id} (auto mode) ` : ` - - Clarify insights: Phase 3 (synthesis integration) - - Generate plan: workflow:plan --session ${session_id} + - Clarify insights: /brainstorm --session ${session_id} (auto mode) + - Generate plan: /workflow:plan --session ${session_id} `} ``` ---- - -## Output Structure +## Output ### Directory Layout +**Feature-point mode** (when `feature_list` available): ``` -{projectRoot}/.workflow/active/WFS-{session}/.brainstorming/ -├── guidance-specification.md # Framework (if exists) +.workflow/active/WFS-{session}/.brainstorming/ +├── guidance-specification.md +└── {role-name}/ + ├── {role-name}-context.md # Interactive Q&A responses + ├── analysis.md # Role overview INDEX (< 1500 words) + ├── analysis-cross-cutting.md # Cross-feature decisions (< 2000 words) + ├── analysis-F-001-{slug}.md # Per-feature analysis (< 2000 words) + ├── analysis-F-002-{slug}.md + └── analysis-F-00N-{slug}.md # One per feature (max 8) +``` + +**Fallback mode** (when `feature_list` NOT available): +``` +.workflow/active/WFS-{session}/.brainstorming/ +├── guidance-specification.md └── {role-name}/ ├── {role-name}-context.md # Interactive Q&A responses ├── analysis.md # Main analysis (REQUIRED) - └── analysis-{slug}.md # Section documents (optional, max 5) + └── analysis-{slug}.md # Section documents (optional, max 5) ``` -### Analysis Document Structure (New Generation) +### Document Structure Templates + +#### Feature-Point Mode: analysis.md (Role Overview Index, < 1500 words) + +```markdown +# ${roleConfig[role_name].title} Analysis: [Topic from Framework] + +## Framework Reference +**Topic Framework**: @../guidance-specification.md +**Role Focus**: ${roleConfig[role_name].focus_area} +**User Context**: @./${role_name}-context.md + +## Role Perspective Overview +[Brief summary of this role's perspective on the overall project] + +## Feature Point Index +| Feature | Sub-document | Key Insight | +|---------|-------------|-------------| +| F-001: [name] | @./analysis-F-001-{slug}.md | [One-line summary] | +| F-002: [name] | @./analysis-F-002-{slug}.md | [One-line summary] | + +## Cross-Cutting Summary +**Full analysis**: @./analysis-cross-cutting.md +[Brief overview of cross-feature decisions and shared patterns] + +--- +*Generated by ${role_name} analysis addressing structured framework* +``` + +#### Feature-Point Mode: analysis-cross-cutting.md (< 2000 words) + +```markdown +# Cross-Cutting Analysis: ${roleConfig[role_name].title} + +## Architecture Decisions +[Decisions that span multiple features] + +## Technology Choices +[Shared technology selections and rationale] + +## Shared Patterns +[Common patterns, constraints, and conventions across features] + +## ${roleConfig[role_name].title} Recommendations +[Role-wide strategic recommendations] +``` + +#### Feature-Point Mode: analysis-F-{id}-{slug}.md (< 2000 words each) + +```markdown +# Feature ${id}: [Feature Name] - ${roleConfig[role_name].title} Analysis + +## Feature Overview +[Role-specific perspective on this feature's scope and goals] + +## Analysis +[Detailed role-specific analysis for this feature] + +## Recommendations +[Actionable recommendations for this feature from role perspective] + +## Dependencies & Risks +[Cross-feature dependencies and risks from role viewpoint] +``` + +#### Fallback Mode: analysis.md (New Generation) ```markdown # ${roleConfig[role_name].title} Analysis: [Topic from Framework] @@ -602,7 +607,7 @@ ${user_context ? formatContextSummary(user_context) : ''} *Context gathered: ${new Date().toISOString()}* ``` -### Analysis Document Structure (Incremental Update) +#### Incremental Update Structure ```markdown # ${roleConfig[role_name].title} Analysis: [Topic] @@ -626,142 +631,88 @@ ${Object.entries(user_context).map(([q, a]) => ` [Rest of sections updated based on clarifications] ``` ---- +### Parameter Combinations -## Integration with Other Phases +| Scenario | Command | Behavior | +|----------|---------|----------| +| New analysis | `/brainstorm ux-expert` | Generate + ask context questions | +| Quick generation | `/brainstorm ux-expert --skip-questions` | Generate without context | +| Update existing | `/brainstorm ux-expert --update` | Ask clarifications + merge | +| Force questions | `/brainstorm ux-expert --include-questions` | Ask even if exists | +| Specific session | `/brainstorm ux-expert --session WFS-xxx` | Target specific session | -### Called By -- Auto-parallel orchestrator (Phase 2 - parallel role execution) -- Manual invocation for single-role analysis +### Quality Assurance -### Spawns -- `conceptual-planning-agent` (via spawn_agent → wait → close_agent) - -### Coordinates With -- Phase 1 (artifacts) - creates framework for role analysis -- Phase 3 (synthesis) - reads role analyses for integration - ---- - -## Quality Assurance - -### Required Analysis Elements +**Required Analysis Elements**: - [ ] Framework discussion points addressed (if framework_mode) - [ ] User context integrated (if context gathered) - [ ] Role template guidelines applied - [ ] Output files follow naming convention (analysis*.md only) - [ ] Framework reference using @ notation - [ ] Session metadata updated +- [ ] Feature-point organization used when feature_list available (if feature_mode) +- [ ] analysis.md is index only (< 1500 words) when in feature_mode +- [ ] analysis-cross-cutting.md exists when in feature_mode +- [ ] One analysis-F-{id}-{slug}.md per feature when in feature_mode -### Context Quality +**Context Quality**: - [ ] Questions in Chinese with business context - [ ] Options include technical trade-offs - [ ] Categories aligned with role focus - [ ] No generic questions unrelated to framework -### Update Quality (if update_mode) +**Update Quality** (if update_mode): - [ ] "Clarifications" section added with timestamp - [ ] New insights merged without content loss - [ ] Conflicts documented and resolved - [ ] Framework alignment maintained -### Agent Lifecycle Quality -- [ ] All spawn_agent have corresponding close_agent -- [ ] All wait calls have reasonable timeout -- [ ] Parallel agents use batch wait -- [ ] Error paths include agent cleanup - ---- - -## Command Parameters - -### Required Parameters -- `[role-name]`: Role identifier (ux-expert, ui-designer, system-architect, etc.) - -### Optional Parameters -- `--session [session-id]`: Specify brainstorming session (auto-detect if omitted) -- `--update`: Force incremental update mode (auto-detect if analysis exists) -- `--include-questions`: Force context gathering even if analysis exists -- `--skip-questions`: Skip all interactive context gathering -- `--style-skill [package]`: For ui-designer only, load style SKILL package - -### Parameter Combinations - -| Scenario | Command | Behavior | -|----------|---------|----------| -| New analysis | `role-analysis ux-expert` | Generate + ask context questions | -| Quick generation | `role-analysis ux-expert --skip-questions` | Generate without context | -| Update existing | `role-analysis ux-expert --update` | Ask clarifications + merge | -| Force questions | `role-analysis ux-expert --include-questions` | Ask even if exists | -| Specific session | `role-analysis ux-expert --session WFS-xxx` | Target specific session | - ---- +- **TodoWrite**: Mark Phase 3 completed (auto mode: collapse N parallel sub-tasks to summary) ## Error Handling -### Invalid Role Name -``` -ERROR: Unknown role: "ui-expert" -Valid roles: ux-expert, ui-designer, system-architect, product-manager, - product-owner, scrum-master, subject-matter-expert, - data-architect, api-designer +| Error | Recovery | +|-------|----------| +| Invalid role name | Show valid roles list, exit | +| No active session | Error with guidance to run /brainstorm first | +| Missing framework | Warn and generate standalone analysis | +| Agent execution failure | Check error.log, retry with --skip-questions | + +## Advanced Usage + +### Batch Role Generation (via auto mode) +```bash +# Auto mode handles multiple roles in parallel +/brainstorm "topic" --count 3 +# → Internally calls role-analysis for each selected role with --skip-questions ``` -### No Active Session -``` -ERROR: No active brainstorming session found -Run: Phase 1 (artifacts) to create session +### Manual Multi-Role Workflow +```bash +# 1. Create framework +/brainstorm "Build real-time collaboration platform" --count 3 + +# 2. Generate each role with context +/brainstorm system-architect --include-questions +/brainstorm ui-designer --include-questions +/brainstorm product-manager --include-questions + +# 3. Synthesize insights +/brainstorm --session WFS-xxx ``` -### Missing Framework (with warning) -``` -WARN: No guidance-specification.md found -Generating standalone analysis without framework alignment -Recommend: Run Phase 1 (artifacts) first for better results +### Iterative Refinement +```bash +# Initial generation +/brainstorm ux-expert + +# User reviews and wants more depth +/brainstorm ux-expert --update --include-questions +# → Asks clarification questions, merges new insights ``` -### Agent Execution Failure -``` -ERROR: Conceptual planning agent failed -Check: ${brainstorm_dir}/${role_name}/error.log -Action: Retry with --skip-questions or check framework validity -``` +## Next Phase -### Agent Lifecycle Errors -```javascript -// Always ensure cleanup in error paths -try { - const agentId = spawn_agent({ message: "..." }); - const result = wait({ ids: [agentId], timeout_ms: 600000 }); - // ... process result ... - close_agent({ id: agentId }); -} catch (error) { - // Ensure cleanup even on error - if (agentId) close_agent({ id: agentId }); - throw error; -} -``` - ---- - -## Reference Information - -### Role Template Locations -- Templates: `~/.ccw/workflows/cli-templates/planning-roles/` -- Format: `{role-name}.md` (e.g., `ux-expert.md`, `system-architect.md`) - -### Context Package -- Location: `{projectRoot}/.workflow/active/WFS-{session}/.process/context-package.json` -- Used by: `context-search-agent` (Phase 0 of artifacts) -- Contains: Project context, tech stack, conflict risks - ---- - -## Post-Phase Update - -After Phase 2 completes: -- **Output Created**: `[role]/analysis*.md` for each selected role -- **Parallel Execution**: All N roles executed concurrently via spawn_agent + batch wait -- **Agent Cleanup**: All agents closed after wait completes -- **Next Action**: Auto-continue to Phase 3 (synthesis integration) -- **State Update**: Update workflow-session.json with role completion status +Return to orchestrator: +- If auto mode → Continue to [Phase 4: Synthesis](04-synthesis.md) +- If single-role mode → Workflow complete, report results diff --git a/.claude/skills/brainstorm/phases/04-synthesis.md b/.claude/skills/brainstorm/phases/04-synthesis.md new file mode 100644 index 00000000..685044f3 --- /dev/null +++ b/.claude/skills/brainstorm/phases/04-synthesis.md @@ -0,0 +1,783 @@ +# Phase 4: Synthesis Integration + +Eight-phase workflow to eliminate ambiguities, enhance conceptual depth, and generate per-feature specifications through cross-role analysis and user clarification. + +## Objective + +- Discover and validate all role analysis files +- Execute cross-role analysis to identify consensus, conflicts, and gaps +- Present enhancement recommendations and clarification questions to user +- Update role analyses in parallel with enhancements and clarifications +- Generate consolidated feature specifications (feature_mode) +- Generate feature index for downstream consumers (feature_mode) +- Update context package and session metadata + +## Auto Mode + +When `--yes` or `-y`: Auto-select all enhancements, skip clarification questions, use default answers. + +## Quick Reference + +### Phase Summary + +| Phase | Goal | Executor | Output | +|-------|------|----------|--------| +| 1 | Session detection | Main flow | session_id, brainstorm_dir | +| 2 | File discovery | Main flow | role_analysis_paths | +| 3A | Cross-role analysis | Agent | enhancement_recommendations, feature_conflict_map | +| 4 | User interaction | Main flow + AskUserQuestion | update_plan | +| 5 | Document updates | Parallel agents | Updated analysis*.md | +| 6 | Feature spec generation | Parallel agents | feature-specs/F-{id}-{slug}.md [feature_mode] | +| 6.5 | Feature index generation | Main flow | feature-index.json [feature_mode] | +| 7 | Finalization | Main flow | context-package.json, report | + +### AskUserQuestion Pattern + +```javascript +// Enhancement selection (multi-select) +AskUserQuestion({ + questions: [{ + question: "请选择要应用的改进建议", + header: "改进选择", + multiSelect: true, + options: [ + { label: "EP-001: API Contract", description: "添加详细的请求/响应 schema 定义" }, + { label: "EP-002: User Intent", description: "明确用户需求优先级和验收标准" } + ] + }] +}) + +// Clarification questions (single-select, multi-round) +AskUserQuestion({ + questions: [ + { + question: "MVP 阶段的核心目标是什么？", + header: "用户意图", + multiSelect: false, + options: [ + { label: "快速验证", description: "最小功能集，快速上线获取反馈" }, + { label: "技术壁垒", description: "完善架构，为长期发展打基础" }, + { label: "功能完整", description: "覆盖所有规划功能，延迟上线" } + ] + } + ] +}) +``` + +## Task Tracking + +```json +[ + {"content": "Detect session and validate analyses", "status": "pending", "activeForm": "Detecting session"}, + {"content": "Discover role analysis file paths", "status": "pending", "activeForm": "Discovering paths"}, + {"content": "Execute analysis agent (cross-role analysis + feature conflict map)", "status": "pending", "activeForm": "Executing analysis"}, + {"content": "Present enhancements via AskUserQuestion", "status": "pending", "activeForm": "Selecting enhancements"}, + {"content": "Clarification questions via AskUserQuestion", "status": "pending", "activeForm": "Clarifying"}, + {"content": "Execute parallel update agents", "status": "pending", "activeForm": "Updating documents"}, + {"content": "Generate parallel feature specs (feature_mode only)", "status": "pending", "activeForm": "Generating feature specs"}, + {"content": "Generate feature-index.json (feature_mode only)", "status": "pending", "activeForm": "Building feature index"}, + {"content": "Update context package and metadata", "status": "pending", "activeForm": "Finalizing"} +] +``` + +## Execution + +### Phase 1: Discovery & Validation + +1. **Detect Session**: Use `--session` parameter or find `.workflow/active/WFS-*` +2. **Validate Files**: + - `guidance-specification.md` (optional, warn if missing) + - `*/analysis*.md` (required, error if empty) +3. **Load User Intent**: Extract from `workflow-session.json` +4. **Detect Feature Mode**: Check if role analyses use feature-point organization + ```javascript + // Feature mode is active when: + // 1. guidance-specification.md contains Feature Decomposition table + // 2. Role directories contain analysis-F-{id}-*.md files + const has_feature_decomposition = guidanceSpecContent && + guidanceSpecContent.includes('Feature Decomposition'); + const has_feature_subdocs = Glob(`${brainstorm_dir}/*/analysis-F-*-*.md`).length > 0; + const feature_mode = has_feature_decomposition && has_feature_subdocs; + + // Extract feature_list from guidance-spec if feature_mode + if (feature_mode) { + feature_list = extractFeatureDecompositionTable(guidanceSpecContent); + // feature_list: [{id, slug, description, roles, priority}, ...] + } + ``` + +### Phase 2: Role Discovery & Path Preparation + +**Main flow prepares file paths for Agent**: + +1. **Discover Analysis Files**: + - Glob: `.workflow/active/WFS-{session}/.brainstorming/*/analysis*.md` + - Supports: analysis.md + analysis-{slug}.md (max 5) + +2. **Extract Role Information**: + - `role_analysis_paths`: Relative paths + - `participating_roles`: Role names from directories + +3. **Pass to Agent**: session_id, brainstorm_dir, role_analysis_paths, participating_roles + +### Phase 3A: Analysis & Enhancement Agent + +**Agent executes cross-role analysis**: + +**Input Optimization (feature_mode)**: When feature_mode is active, only read `{role}/analysis.md` index files (NOT sub-documents like `analysis-F-{id}-*.md` or `analysis-cross-cutting.md`). This reduces input tokens from ~39K to ~4.5K while preserving the role perspective overview, feature point index, and cross-cutting summary needed for conflict detection. + +**Input (fallback mode)**: When feature_mode is NOT active, read all `{role}/analysis*.md` files as before. + +```javascript +// Prepare input paths based on mode +const analysis_input_paths = feature_mode + ? participating_roles.map(r => `${brainstorm_dir}/${r}/analysis.md`) // Index files only (~4.5K total) + : role_analysis_paths; // All analysis files (fallback) + +Task(conceptual-planning-agent, ` +## Agent Mission +Analyze role documents, identify conflicts/gaps, generate enhancement recommendations. +${feature_mode ? 'Additionally, generate feature_conflict_map for per-feature consensus/conflicts across roles.' : ''} + +## Input +- brainstorm_dir: ${brainstorm_dir} +- analysis_input_paths: ${analysis_input_paths} +- participating_roles: ${participating_roles} +- feature_mode: ${feature_mode} +${feature_mode ? `- guidance_spec_path: ${brainstorm_dir}/guidance-specification.md (read Feature Decomposition section only)` : ''} + +## Flow Control Steps +1. load_session_metadata → Read workflow-session.json +2. load_role_analyses → Read analysis files from analysis_input_paths + ${feature_mode ? '(INDEX files only - each ~500-800 words with role overview, feature index table, cross-cutting summary)' : '(All analysis files)'} +${feature_mode ? `3. load_feature_decomposition → Read Feature Decomposition table from guidance-specification.md +4. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities +5. generate_feature_conflict_map → For each feature in Feature Decomposition, extract per-feature consensus/conflicts/cross-references from role index summaries +6. generate_recommendations → Format as EP-001, EP-002, ...` : `3. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities +4. generate_recommendations → Format as EP-001, EP-002, ...`} + +## Output Format + +### enhancement_recommendations (always) +[ + { + "id": "EP-001", + "title": "API Contract Specification", + "affected_roles": ["system-architect", "api-designer"], + "category": "Architecture", + "current_state": "High-level API descriptions", + "enhancement": "Add detailed contract definitions", + "rationale": "Enables precise implementation", + "priority": "High" + } +] + +${feature_mode ? `### feature_conflict_map (feature_mode only) +Bridge artifact from Phase 3A to Phase 6. One entry per feature from Feature Decomposition. + +{ + "F-001": { + "consensus": [ + "All roles agree on real-time sync via WebSocket", + "Event-driven architecture preferred" + ], + "conflicts": [ + { + "topic": "State management approach", + "views": { + "system-architect": "Server-authoritative with CRDT", + "ux-expert": "Optimistic local-first updates" + }, + "resolution": "Hybrid: optimistic local with server reconciliation via CRDT because balances UX responsiveness with data consistency, tradeoff: increased client complexity", + "confidence": "[RESOLVED]", + "applies_when": "Online mode with collaborative editing" + } + ], + "cross_refs": [ + "F-003 (offline-mode) depends on sync conflict resolution strategy" + ] + } +} + +**feature_conflict_map Rules**: +- One entry per feature ID from guidance-specification.md Feature Decomposition +- consensus[]: Statements where 2+ roles explicitly agree +- conflicts[]: Disagreements with topic, per-role positions, and suggested resolution +- cross_refs[]: References to other features or cross-cutting docs +- If a feature has no conflicts, set conflicts to empty array +- Keep each entry concise: aim for 100-200 words per feature + +**Resolution Quality Requirements**: +1. **Actionable**: resolution must be directly executable. Bad: "需要权衡" → Good: "采用 JWT 无状态认证，RefreshToken 存 HttpOnly Cookie" +2. **Justified**: Explain why. Format: "[方案] because [原因]，tradeoff: [代价]" +3. **Scoped**: If limited scope, mark "Applies when: [条件]" +4. **Confidence**: [RESOLVED] | [SUGGESTED] | [UNRESOLVED] +` : ''} +`) +``` + +**Phase 3A Output Storage**: +```javascript +// Store enhancement_recommendations for Phase 4 +const enhancement_recommendations = agent_output.enhancement_recommendations; + +// Store feature_conflict_map for Phase 6 (feature_mode only) +const feature_conflict_map = feature_mode ? agent_output.feature_conflict_map : null; +``` + +### Phase 4: User Interaction + +**All interactions via AskUserQuestion (Chinese questions)** + +#### Step 1: Enhancement Selection + +```javascript +// If enhancements > 4, split into multiple rounds +const enhancements = [...]; // from Phase 3A +const BATCH_SIZE = 4; + +for (let i = 0; i < enhancements.length; i += BATCH_SIZE) { + const batch = enhancements.slice(i, i + BATCH_SIZE); + + AskUserQuestion({ + questions: [{ + question: `请选择要应用的改进建议 (第${Math.floor(i/BATCH_SIZE)+1}轮)`, + header: "改进选择", + multiSelect: true, + options: batch.map(ep => ({ + label: `${ep.id}: ${ep.title}`, + description: `影响: ${ep.affected_roles.join(', ')} | ${ep.enhancement}` + })) + }] + }) + + // Store selections before next round +} + +// User can also skip: provide "跳过" option +``` + +#### Step 2: Clarification Questions + +```javascript +// Generate questions based on 9-category taxonomy scan +// Categories: User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology + +const clarifications = [...]; // from analysis +const BATCH_SIZE = 4; + +for (let i = 0; i < clarifications.length; i += BATCH_SIZE) { + const batch = clarifications.slice(i, i + BATCH_SIZE); + const currentRound = Math.floor(i / BATCH_SIZE) + 1; + const totalRounds = Math.ceil(clarifications.length / BATCH_SIZE); + + AskUserQuestion({ + questions: batch.map(q => ({ + question: q.question, + header: q.category.substring(0, 12), + multiSelect: false, + options: q.options.map(opt => ({ + label: opt.label, + description: opt.description + })) + })) + }) + + // Store answers before next round +} +``` + +### Question Guidelines + +**Target**: 开发者（理解技术但需要从用户需求出发） + +**Question Structure**: `[跨角色分析发现] + [需要澄清的决策点]` +**Option Structure**: `标签：[具体方案] + 说明：[业务影响] + [技术权衡]` + +**9-Category Taxonomy**: + +| Category | Focus | Example Question Pattern | +|----------|-------|--------------------------| +| User Intent | 用户目标 | "MVP阶段核心目标？" + 验证/壁垒/完整性 | +| Requirements | 需求细化 | "功能优先级如何排序？" + 核心/增强/可选 | +| Architecture | 架构决策 | "技术栈选择考量？" + 熟悉度/先进性/成熟度 | +| UX | 用户体验 | "交互复杂度取舍？" + 简洁/丰富/渐进 | +| Feasibility | 可行性 | "资源约束下的范围？" + 最小/标准/完整 | +| Risk | 风险管理 | "风险容忍度？" + 保守/平衡/激进 | +| Process | 流程规范 | "迭代节奏？" + 快速/稳定/灵活 | +| Decisions | 决策确认 | "冲突解决方案？" + 方案A/方案B/折中 | +| Terminology | 术语统一 | "统一使用哪个术语？" + 术语A/术语B | + +**Quality Rules**: + +**MUST Include**: +- ✅ All questions in Chinese (用中文提问) +- ✅ 基于跨角色分析的具体发现 +- ✅ 选项包含业务影响说明 +- ✅ 解决实际的模糊点或冲突 + +**MUST Avoid**: +- ❌ 与角色分析无关的通用问题 +- ❌ 重复已在 artifacts 阶段确认的内容 +- ❌ 过于细节的实现级问题 + +#### Step 3: Build Update Plan + +```javascript +update_plan = { + "role1": { + "enhancements": ["EP-001", "EP-003"], + "clarifications": [ + {"question": "...", "answer": "...", "category": "..."} + ] + }, + "role2": { + "enhancements": ["EP-002"], + "clarifications": [...] + } +} +``` + +### Phase 5: Parallel Document Update Agents + +**Execute in parallel** (one agent per role): + +```javascript +// Single message with multiple Task calls for parallelism +Task(conceptual-planning-agent, ` +## Agent Mission +Apply enhancements and clarifications to ${role} analysis + +## Input +- role: ${role} +- analysis_path: ${brainstorm_dir}/${role}/analysis.md +- enhancements: ${role_enhancements} +- clarifications: ${role_clarifications} +- original_user_intent: ${intent} + +## Flow Control Steps +1. load_current_analysis → Read analysis file +2. add_clarifications_section → Insert Q&A section +3. apply_enhancements → Integrate into relevant sections +4. resolve_contradictions → Remove conflicts +5. enforce_terminology → Align terminology +6. validate_intent → Verify alignment with user intent +7. write_updated_file → Save changes + +## Output +Updated ${role}/analysis.md +`) +``` + +**Agent Characteristics**: +- **Isolation**: Each agent updates exactly ONE role (parallel safe) +- **Dependencies**: Zero cross-agent dependencies +- **Validation**: All updates must align with original_user_intent + +### Phase 6: Parallel Feature Spec Generation [feature_mode only] + +**Skip condition**: If `feature_mode` is false, skip Phase 6 and Phase 6.5 entirely. Proceed directly to Phase 7. + +**Purpose**: Generate one consolidated feature specification per feature by aggregating all role perspectives. + +#### Step 1: Prepare Feature Spec Directory + +```javascript +const feature_specs_dir = `${brainstorm_dir}/feature-specs`; +// Ensure directory exists (create if not) +``` + +#### Step 2: Build Per-Feature Input Bundles + +```javascript +const feature_bundles = feature_list.map(feature => { + const fid = feature.id; + const slug = feature.slug; + + const role_analysis_files = participating_roles + .map(role => `${brainstorm_dir}/${role}/analysis-${fid}-${slug}.md`) + .filter(path => fileExists(path)); + + return { + feature_id: fid, + feature_slug: slug, + feature_name: feature.description, + feature_priority: feature.priority, + conflict_map_entry: feature_conflict_map[fid], + role_analysis_files: role_analysis_files, + contributing_roles: role_analysis_files.map(f => extractRoleName(f)), + output_path: `${feature_specs_dir}/${fid}-${slug}.md` + }; +}); +``` + +#### Step 3: Execute Parallel Feature Spec Agents + +**Execute in parallel** (one agent per feature): + +```javascript +Task(conceptual-planning-agent, ` +## Agent Mission +Generate consolidated feature specification for ${feature.feature_id}: ${feature.feature_name} +by aggregating all role-specific analyses with conflict resolution. + +## Input +- feature_id: ${feature.feature_id} +- feature_slug: ${feature.feature_slug} +- feature_name: ${feature.feature_name} +- feature_priority: ${feature.feature_priority} +- role_analysis_files: ${feature.role_analysis_files} +- conflict_map_entry: ${JSON.stringify(feature.conflict_map_entry)} +- output_path: ${feature.output_path} +- guidance_spec_feature_section: (Feature Decomposition row for this feature) + +## Flow Control Steps +1. load_role_analyses → Read all role-specific analysis files for this feature + (Each file ~1500-2000 words, total ~6.5K words for 3-4 roles) +2. apply_conflict_map → Use conflict_map_entry to identify resolved/unresolved conflicts +3. four_layer_aggregation → Apply aggregation rules (see below) +4. generate_feature_spec → Write consolidated spec using template +5. write_output → Save to output_path + +## Four-Layer Aggregation Rules + +### Layer 1: Direct Reference +- Quote role analyses directly when consensus exists +- Format: "[Role] recommends: [direct quote]" +- Use for undisputed technical recommendations + +### Layer 2: Structured Extraction +- Extract and organize key information from each role into unified structure +- Merge complementary perspectives +- De-duplicate overlapping content across roles + +### Layer 3: Conflict Distillation +- **[RESOLVED]**: State the resolution directly as a design decision. Format: "**Decision**: [resolution]. **Rationale**: [from conflict.resolution]. **Trade-off**: [tradeoff]." +- **[SUGGESTED]**: Adopt the suggested resolution but mark source. Format: "**Recommended**: [resolution] (suggested by Phase 3A cross-role analysis). **Rationale**: [reason]. **Alternative**: [strongest competing view]." +- **[UNRESOLVED]**: Do NOT pick a side. Present all options neutrally. Format: "**[DECISION NEEDED]**: [topic]. **Options**: [role1: approach1] vs [role2: approach2]. **Evaluation**: [pros/cons of each]. **Impact if deferred**: [consequence]." +- **Unresolved escalation**: If 2+ [UNRESOLVED] conflicts, add warning at top of Section 2 + +### Layer 4: Cross-Feature Annotation +- Add explicit dependency notes with feature IDs +- Document integration points with other features +- Note shared constraints or patterns + +## Feature Spec Template (7 Sections, target 1500-2500 words) + +--- +# Feature Spec: ${feature.feature_id} - ${feature.feature_name} + +**Priority**: ${feature.feature_priority} +**Contributing Roles**: [list of roles] +**Status**: Draft (from synthesis) + +## 1. Requirements Summary +[Consolidated requirements from all role perspectives] +- Functional requirements (from product-manager, product-owner) +- User experience requirements (from ux-expert, ui-designer) +- Technical requirements (from system-architect, data-architect, api-designer) +- Domain requirements (from subject-matter-expert) + +## 2. Design Decisions [CORE SECTION] +[Key architectural and design decisions with rationale - 40%+ of word count] +For each decision: +- **Decision**: [What was decided] +- **Context**: [Why this decision was needed] +- **Options Considered**: [Alternatives from different roles] +- **Chosen Approach**: [Selected option with rationale] +- **Trade-offs**: [What we gain vs. what we sacrifice] +- **Source**: [Which role(s) drove this decision] + +## 3. Interface Contract +[API endpoints, data models, component interfaces] +- External interfaces (API contracts from api-designer) +- Internal interfaces (component boundaries from system-architect) +- Data interfaces (schemas from data-architect) +- User interfaces (interaction patterns from ux-expert/ui-designer) + +## 4. Constraints & Risks +[Technical constraints, business risks, mitigation strategies] +- Performance constraints (from system-architect) +- Data constraints (from data-architect) +- UX constraints (from ux-expert) +- Business/domain constraints (from subject-matter-expert) +- Risk mitigation strategies (from scrum-master) + +## 5. Acceptance Criteria +[Testable criteria for feature completion] +- Functional acceptance (from product-owner user stories) +- Performance acceptance (from system-architect NFRs) +- UX acceptance (from ux-expert usability criteria) +- Data integrity acceptance (from data-architect) + +## 6. Detailed Analysis References +[Pointers back to role-specific analysis documents] +- @../{role}/analysis-${feature.feature_id}-${feature.feature_slug}.md for each contributing role +- @../guidance-specification.md#feature-decomposition + +## 7. Cross-Feature Dependencies +[Dependencies on and from other features] +- **Depends on**: [Feature IDs this feature requires] +- **Required by**: [Feature IDs that depend on this feature] +- **Shared patterns**: References to analysis-cross-cutting.md patterns +- **Integration points**: [Specific interfaces between features] +--- + +## Completion Criteria +- All 7 sections populated with aggregated content +- Section 2 (Design Decisions) is the most detailed section (40%+ of word count) +- All conflicts from conflict_map_entry addressed with resolutions +- Cross-feature dependencies explicitly documented +- Word count between 1500-2500 +- No placeholder text except [DECISION NEEDED] for genuinely unresolved items +`) +``` + +**Agent Characteristics (Phase 6)**: +- **Isolation**: Each agent processes exactly ONE feature (parallel safe) +- **Dependencies**: Requires Phase 3A feature_conflict_map and Phase 5 updated role analyses +- **Input budget**: ~6.5K words per agent (3-4 role sub-docs + conflict map entry) +- **Output budget**: 1500-2500 words per feature spec + +### Phase 6.5: Feature Index Generation [feature_mode only] + +**Skip condition**: Same as Phase 6 - skip if `feature_mode` is false. + +**Purpose**: Collect all Phase 6 outputs and generate structured `feature-index.json`. + +#### Step 1: Collect Feature Spec Outputs + +```javascript +const feature_spec_files = Glob(`${brainstorm_dir}/feature-specs/F-*-*.md`); + +const cross_cutting_specs = participating_roles + .map(role => `${brainstorm_dir}/${role}/analysis-cross-cutting.md`) + .filter(path => fileExists(path)); +``` + +#### Step 2: Generate feature-index.json + +```javascript +const feature_index = { + "version": "1.0", + "generated_at": new Date().toISOString(), + "session_id": session_id, + "feature_mode": true, + "features": feature_list.map(feature => { + const fid = feature.id; + const slug = feature.slug; + const spec_path = `feature-specs/${fid}-${slug}.md`; + const spec_exists = fileExists(`${brainstorm_dir}/${spec_path}`); + + const contributing_roles = participating_roles.filter(role => + fileExists(`${brainstorm_dir}/${role}/analysis-${fid}-${slug}.md`) + ); + + const cross_cutting_refs = feature_conflict_map[fid] + ? feature_conflict_map[fid].cross_refs + : []; + + return { + "id": fid, + "slug": slug, + "name": feature.description, + "priority": feature.priority, + "spec_path": spec_exists ? spec_path : null, + "contributing_roles": contributing_roles, + "cross_cutting_refs": cross_cutting_refs + }; + }), + "cross_cutting_specs": cross_cutting_specs.map(path => + path.replace(brainstorm_dir + '/', '') + ) +}; + +Write( + `${brainstorm_dir}/feature-index.json`, + JSON.stringify(feature_index, null, 2) +); +``` + +#### feature-index.json Schema + +```json +{ + "version": "1.0", + "generated_at": "2026-02-11T10:00:00.000Z", + "session_id": "WFS-xxx", + "feature_mode": true, + "features": [ + { + "id": "F-001", + "slug": "real-time-sync", + "name": "Real-time collaborative synchronization", + "priority": "High", + "spec_path": "feature-specs/F-001-real-time-sync.md", + "contributing_roles": ["system-architect", "ux-expert", "data-architect"], + "cross_cutting_refs": ["F-003 offline-mode depends on sync strategy"] + } + ], + "cross_cutting_specs": [ + "system-architect/analysis-cross-cutting.md", + "ux-expert/analysis-cross-cutting.md" + ] +} +``` + +**Consumers**: `action-planning-agent` reads feature-index.json to generate task JSONs. `code-developer` loads individual feature specs as implementation context. + +### Phase 7: Finalization + +#### Step 1: Update Context Package + +```javascript +const context_pkg = Read(".workflow/active/WFS-{session}/.process/context-package.json") + +// Update guidance-specification if exists +// Update synthesis-specification if exists +// Re-read all role analysis files +// Update metadata timestamps + +// If feature_mode: add feature-index.json and feature-specs paths +if (feature_mode) { + context_pkg.feature_index_path = `${brainstorm_dir}/feature-index.json`; + context_pkg.feature_specs_dir = `${brainstorm_dir}/feature-specs/`; + context_pkg.feature_mode = true; +} + +Write(context_pkg_path, JSON.stringify(context_pkg)) +``` + +#### Step 2: Update Session Metadata + +```json +{ + "phases": { + "BRAINSTORM": { + "status": "clarification_completed", + "clarification_completed": true, + "completed_at": "timestamp", + "participating_roles": ["..."], + "clarification_results": { + "enhancements_applied": ["EP-001", "EP-002"], + "questions_asked": 3, + "categories_clarified": ["Architecture", "UX"], + "roles_updated": ["role1", "role2"] + }, + "feature_spec_results": { + "feature_mode": true, + "features_generated": ["F-001", "F-002", "F-003"], + "feature_index_path": ".brainstorming/feature-index.json", + "feature_specs_dir": ".brainstorming/feature-specs/", + "conflict_map_generated": true + }, + "quality_metrics": { + "user_intent_alignment": "validated", + "ambiguity_resolution": "complete", + "terminology_consistency": "enforced" + } + } + } +} +``` + +**Note**: `feature_spec_results` only present when `feature_mode` is true. + +#### Step 3: Completion Report + +```markdown +## Synthesis Complete + +**Session**: {sessionId} +**Enhancements Applied**: EP-001, EP-002, EP-003 +**Questions Answered**: 3/5 +**Roles Updated**: role1, role2, role3 + +### Feature Specs (feature_mode only) +**Feature Specs Generated**: F-001, F-002, F-003 +**Feature Index**: .brainstorming/feature-index.json +**Spec Directory**: .brainstorming/feature-specs/ + +### Next Steps +PROCEED: `/workflow:plan --session {session-id}` +``` + +## Output + +**Location (role analyses)**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md` +**Location (feature specs)**: `.workflow/active/WFS-{session}/.brainstorming/feature-specs/F-{id}-{slug}.md` [feature_mode] +**Location (feature index)**: `.workflow/active/WFS-{session}/.brainstorming/feature-index.json` [feature_mode] + +**Updated Directory Structure** (feature_mode): +``` +.workflow/active/WFS-{session}/.brainstorming/ +├── guidance-specification.md +├── feature-index.json # Phase 6.5 output +├── feature-specs/ # Phase 6 output directory +│ ├── F-001-{slug}.md # Consolidated feature spec (1500-2500 words) +│ ├── F-002-{slug}.md +│ └── F-00N-{slug}.md +├── {role-1}/ +│ ├── analysis.md # Role overview index (read by Phase 3A) +│ ├── analysis-cross-cutting.md +│ ├── analysis-F-001-{slug}.md # Per-feature detail (read by Phase 6) +│ └── analysis-F-002-{slug}.md +└── {role-N}/ + └── ... +``` + +**Updated Role Analysis Structure**: +```markdown +## Clarifications +### Session {date} +- **Q**: {question} (Category: {category}) + **A**: {answer} + +## {Existing Sections} +{Refined content based on clarifications} +``` + +**Changes**: +- User intent validated/corrected +- Requirements more specific/measurable +- Architecture with rationale +- Ambiguities resolved, placeholders removed +- Consistent terminology +- Feature specs generated with cross-role conflict resolution [feature_mode] +- Feature index provides structured access for downstream consumers [feature_mode] + +## Quality Checklist + +**Content**: +- All role analyses loaded/analyzed +- Cross-role analysis (consensus, conflicts, gaps) +- 9-category ambiguity scan +- Questions prioritized + +**Analysis**: +- User intent validated +- Cross-role synthesis complete +- Ambiguities resolved +- Terminology consistent + +**Documents**: +- Clarifications section formatted +- Sections reflect answers +- No placeholders (TODO/TBD) +- Valid Markdown + +**Feature Specs (feature_mode only)**: +- Phase 3A reads only analysis.md index files (not sub-documents), input token <= 5K words +- feature_conflict_map generated with consensus/conflicts/cross_refs per feature +- Phase 6 parallel agents defined: one per feature, input token <= 7K words each +- Feature spec template has 7 sections, Section 2 (Design Decisions) is core +- Four-layer aggregation rules applied +- Each feature spec is 1500-2500 words +- feature-index.json generated with features[] + cross_cutting_specs[] +- feature-specs/ directory created with F-{id}-{slug}.md files + +- **TodoWrite**: Mark Phase 4 completed, collapse all sub-tasks to summary + +## Next Phase + +Return to orchestrator. Auto mode workflow is now complete. Report final summary to user. diff --git a/.claude/skills/issue-resolve/phases/01-issue-plan.md b/.claude/skills/issue-resolve/phases/01-issue-plan.md index b7e21a1d..d748211b 100644 --- a/.claude/skills/issue-resolve/phases/01-issue-plan.md +++ b/.claude/skills/issue-resolve/phases/01-issue-plan.md @@ -147,7 +147,7 @@ ${issueList} - Solution ID format: SOL-{issue-id}-{uid} (uid: 4 random alphanumeric chars, e.g., a7x9) - Single solution per issue → auto-bind via ccw issue bind - Multiple solutions → register only, return pending_selection -- Tasks must have quantified acceptance.criteria +- Tasks must have quantified convergence.criteria ### Return Summary {"bound":[{"issue_id":"...","solution_id":"...","task_count":N}],"pending_selection":[{"issue_id":"...","solutions":[{"id":"...","description":"...","task_count":N}]}]} @@ -279,8 +279,8 @@ Before completing, verify: - [ ] All input issues have solutions in `solutions/{issue-id}.jsonl` - [ ] Single solution issues are auto-bound (`bound_solution_id` set) - [ ] Multi-solution issues returned in `pending_selection` for user choice -- [ ] Each solution has executable tasks with `modification_points` -- [ ] Task acceptance criteria are quantified (not vague) +- [ ] Each solution has executable tasks with `files` +- [ ] Task convergence criteria are quantified (not vague) - [ ] Conflicts detected and reported (if multiple issues touch same files) - [ ] Issue status updated to `planned` after binding diff --git a/.claude/skills/issue-resolve/phases/02-convert-to-plan.md b/.claude/skills/issue-resolve/phases/02-convert-to-plan.md index 50c10727..0c0960a0 100644 --- a/.claude/skills/issue-resolve/phases/02-convert-to-plan.md +++ b/.claude/skills/issue-resolve/phases/02-convert-to-plan.md @@ -66,13 +66,15 @@ interface Task { scope: string; // Required: module path or feature area action: Action; // Required: Create|Update|Implement|... description?: string; - modification_points?: Array<{file, target, change}>; + files?: Array<{path, target?, change?, action?, conflict_risk?}>; + modification_points?: Array<{file, target, change}>; // Legacy, prefer files implementation: string[]; // Required: step-by-step guide - test?: { unit?, integration?, commands?, coverage_target? }; - acceptance: { criteria: string[], verification: string[] }; // Required + test?: { unit?, integration?, commands?, coverage_target?, manual_checks? }; + convergence: { criteria: string[], verification?: string | string[] }; // Required + acceptance?: { criteria: string[], verification: string[] }; // Legacy, prefer convergence commit?: { type, scope, message_template, breaking? }; depends_on?: string[]; - priority?: number; // 1-5 (default: 3) + priority?: string | number; // "critical"|"high"|"medium"|"low" or 1-5 } type Action = 'Create' | 'Update' | 'Implement' | 'Refactor' | 'Add' | 'Delete' | 'Configure' | 'Test' | 'Fix'; @@ -187,19 +189,16 @@ function extractFromLitePlan(folderPath) { scope: t.scope || '', action: t.action || 'Implement', description: t.description || t.title, - modification_points: t.modification_points || [], + files: t.files || (t.modification_points || []).map(mp => ({path: mp.file, target: mp.target, change: mp.change})), implementation: Array.isArray(t.implementation) ? t.implementation : [t.implementation || ''], test: t.verification ? { unit: t.verification.unit_tests, integration: t.verification.integration_tests, commands: t.verification.manual_checks } : {}, - acceptance: { - criteria: Array.isArray(t.acceptance) ? t.acceptance : [t.acceptance || ''], - verification: t.verification?.manual_checks || [] - }, + convergence: normalizeConvergence(t.acceptance, t.convergence), depends_on: t.depends_on || [], - priority: 3 + priority: t.priority || 'medium' })), metadata: { source_type: 'lite-plan', @@ -243,13 +242,10 @@ function extractFromWorkflowSession(sessionPath) { scope: task.scope || inferScopeFromTask(task), action: capitalizeAction(task.type) || 'Implement', description: task.description, - modification_points: task.implementation?.modification_points || [], + files: task.files || (task.implementation?.modification_points || []).map(mp => ({path: mp.file, target: mp.target, change: mp.change})), implementation: task.implementation?.steps || [], test: task.implementation?.test || {}, - acceptance: { - criteria: task.acceptance_criteria || [], - verification: task.verification_steps || [] - }, + convergence: normalizeConvergence(task.acceptance_criteria, task.convergence), commit: task.commit, depends_on: (task.depends_on || []).map(d => d.replace(/^IMPL-0*/, 'T')), priority: task.priority || 3 @@ -271,10 +267,11 @@ function extractFromWorkflowSession(sessionPath) { } function inferScopeFromTask(task) { - if (task.implementation?.modification_points?.length) { - const files = task.implementation.modification_points.map(m => m.file); - // Find common directory prefix - const dirs = files.map(f => f.split('/').slice(0, -1).join('/')); + // Prefer new files[] field, fall back to legacy modification_points + const filePaths = task.files?.map(f => f.path) || + task.implementation?.modification_points?.map(m => m.file) || []; + if (filePaths.length) { + const dirs = filePaths.map(f => f.split('/').slice(0, -1).join('/')); return [...new Set(dirs)][0] || ''; } return ''; @@ -339,15 +336,12 @@ ${fileContent}`; scope: t.scope || '', action: validateAction(t.action) || 'Implement', description: t.description || t.title, - modification_points: t.modification_points || [], + files: t.files || (t.modification_points || []).map(mp => ({path: mp.file, target: mp.target, change: mp.change})), implementation: Array.isArray(t.implementation) ? t.implementation : [t.implementation || ''], test: t.test || {}, - acceptance: { - criteria: Array.isArray(t.acceptance) ? t.acceptance : [t.acceptance || ''], - verification: t.verification || [] - }, + convergence: normalizeConvergence(t.acceptance, t.convergence), depends_on: t.depends_on || [], - priority: t.priority || 3 + priority: t.priority || 'medium' })); return { @@ -391,12 +385,12 @@ function extractFromJsonFile(filePath) { scope: t.scope || '', action: t.action || 'Implement', description: t.description || t.title, - modification_points: t.modification_points || [], + files: t.files || (t.modification_points || []).map(mp => ({path: mp.file, target: mp.target, change: mp.change})), implementation: Array.isArray(t.implementation) ? t.implementation : [t.implementation || ''], test: t.test || t.verification || {}, - acceptance: normalizeAcceptance(t.acceptance), + convergence: normalizeConvergence(t.acceptance, t.convergence), depends_on: t.depends_on || [], - priority: t.priority || 3 + priority: t.priority || 'medium' })); return { @@ -416,11 +410,13 @@ function extractFromJsonFile(filePath) { throw new Error('E002: JSON file does not contain valid plan structure (missing tasks array)'); } -function normalizeAcceptance(acceptance) { - if (!acceptance) return { criteria: [], verification: [] }; - if (typeof acceptance === 'object' && acceptance.criteria) return acceptance; - if (Array.isArray(acceptance)) return { criteria: acceptance, verification: [] }; - return { criteria: [String(acceptance)], verification: [] }; +function normalizeConvergence(acceptance, convergence) { + // Prefer new convergence field; fall back to legacy acceptance + const source = convergence || acceptance; + if (!source) return { criteria: [], verification: [] }; + if (typeof source === 'object' && source.criteria) return source; + if (Array.isArray(source)) return { criteria: source, verification: [] }; + return { criteria: [String(source)], verification: [] }; } ``` diff --git a/.claude/skills/issue-resolve/phases/03-from-brainstorm.md b/.claude/skills/issue-resolve/phases/03-from-brainstorm.md index 2e6c02f0..dbe1b0b4 100644 --- a/.claude/skills/issue-resolve/phases/03-from-brainstorm.md +++ b/.claude/skills/issue-resolve/phases/03-from-brainstorm.md @@ -93,12 +93,12 @@ interface Task { description: string; implementation: string[]; // Step-by-step guide - acceptance: { + convergence: { criteria: string[]; // What defines success verification: string[]; // How to verify }; - priority: number; // 1-5 + priority: string; // "critical"|"high"|"medium"|"low" depends_on: string[]; // Task dependencies } ``` @@ -152,7 +152,7 @@ Phase 5: Generate Solution Tasks ├─ T1: Research & Validate (if main_challenges exist) ├─ T2: Design & Specification (if key_strengths exist) ├─ T3+: Implementation tasks (from idea.next_steps) - └─ Each task includes: implementation steps + acceptance criteria + └─ Each task includes: implementation steps + convergence criteria ``` ### Step 3.6: Bind Solution @@ -228,7 +228,7 @@ Phase 7: Next Steps - **Title**: `idea.title` - **Scope**: implementation - **Action**: Implement -- **Generic implementation + acceptance criteria** +- **Generic implementation + convergence criteria** ## Priority Calculation diff --git a/.claude/skills/team-skill-designer/SKILL.md b/.claude/skills/team-skill-designer/SKILL.md index b0c28c75..041346d1 100644 --- a/.claude/skills/team-skill-designer/SKILL.md +++ b/.claude/skills/team-skill-designer/SKILL.md @@ -120,13 +120,13 @@ Phase 1 collects ALL roles at once (not one at a time): - Coordinator is always generated - Worker roles collected as a batch -### Pattern 5: Spec Reference (No Duplication) +### Pattern 5: Self-Contained Specs -Design pattern specs are referenced from team-command-designer: +Design pattern specs are included locally in `specs/`: ``` -specs → ../team-command-designer/specs/team-design-patterns.md -specs → ../team-command-designer/specs/collaboration-patterns.md -specs → ../team-command-designer/specs/quality-standards.md +specs/team-design-patterns.md # Infrastructure patterns (8) + collaboration index +specs/collaboration-patterns.md # 10 collaboration patterns with convergence control +specs/quality-standards.md # Quality criteria ``` --- @@ -139,9 +139,9 @@ specs → ../team-command-designer/specs/quality-standards.md | Document | Purpose | When | |----------|---------|------| -| [../team-command-designer/specs/team-design-patterns.md](../team-command-designer/specs/team-design-patterns.md) | Infrastructure patterns (8) + collaboration index | **Must read** | -| [../team-command-designer/specs/collaboration-patterns.md](../team-command-designer/specs/collaboration-patterns.md) | 10 collaboration patterns with convergence control | **Must read** | -| [../team-command-designer/specs/quality-standards.md](../team-command-designer/specs/quality-standards.md) | Quality criteria | Must read before generation | +| [specs/team-design-patterns.md](specs/team-design-patterns.md) | Infrastructure patterns (8) + collaboration index | **Must read** | +| [specs/collaboration-patterns.md](specs/collaboration-patterns.md) | 10 collaboration patterns with convergence control | **Must read** | +| [specs/quality-standards.md](specs/quality-standards.md) | Quality criteria | Must read before generation | ### Template Files (Must read before generation) @@ -166,8 +166,8 @@ specs → ../team-command-designer/specs/quality-standards.md ``` Phase 0: Specification Study (MANDATORY) - -> Read: ../team-command-designer/specs/team-design-patterns.md - -> Read: ../team-command-designer/specs/collaboration-patterns.md + -> Read: specs/team-design-patterns.md + -> Read: specs/collaboration-patterns.md -> Read: templates/skill-router-template.md + templates/role-template.md -> Read: 1-2 existing team commands for reference -> Output: Internalized requirements (in-memory) diff --git a/.claude/skills/team-skill-designer/phases/01-requirements-collection.md b/.claude/skills/team-skill-designer/phases/01-requirements-collection.md index 0260d770..8365b783 100644 --- a/.claude/skills/team-skill-designer/phases/01-requirements-collection.md +++ b/.claude/skills/team-skill-designer/phases/01-requirements-collection.md @@ -13,7 +13,7 @@ Collect team definition and ALL role definitions in one pass. ## Input - User request (`$ARGUMENTS` or interactive input) -- Specification: `../team-command-designer/specs/team-design-patterns.md` (read in Phase 0) +- Specification: `specs/team-design-patterns.md` (read in Phase 0) ## Execution Steps diff --git a/.claude/skills/team-skill-designer/phases/02-pattern-analysis.md b/.claude/skills/team-skill-designer/phases/02-pattern-analysis.md index 23551b95..34268743 100644 --- a/.claude/skills/team-skill-designer/phases/02-pattern-analysis.md +++ b/.claude/skills/team-skill-designer/phases/02-pattern-analysis.md @@ -12,7 +12,7 @@ Analyze applicable patterns for each role in the team. ## Input - Dependency: `team-config.json` (Phase 1) -- Specification: `../team-command-designer/specs/team-design-patterns.md` (read in Phase 0) +- Specification: `specs/team-design-patterns.md` (read in Phase 0) ## Execution Steps diff --git a/.claude/skills/team-skill-designer/phases/05-validation.md b/.claude/skills/team-skill-designer/phases/05-validation.md index efcef35e..9ea83a5d 100644 --- a/.claude/skills/team-skill-designer/phases/05-validation.md +++ b/.claude/skills/team-skill-designer/phases/05-validation.md @@ -12,7 +12,7 @@ Verify quality and deliver the final skill package. ## Input - Dependency: `{workDir}/preview/` (Phase 3), `integration-report.json` (Phase 4) -- Specification: `../team-command-designer/specs/quality-standards.md` +- Specification: `specs/quality-standards.md` ## Execution Steps diff --git a/.claude/skills/team-skill-designer/specs/collaboration-patterns.md b/.claude/skills/team-skill-designer/specs/collaboration-patterns.md new file mode 100644 index 00000000..b59eacb4 --- /dev/null +++ b/.claude/skills/team-skill-designer/specs/collaboration-patterns.md @@ -0,0 +1,1341 @@ +# Collaboration Patterns Specification + +> 10 种团队协作模式，每种具备：收敛性、完整流程、反馈控制 + +--- + +## Pattern Standard Structure + +每种协作模式遵循统一规范： + +``` +┌─────────────────────────────────────────┐ +│ Entry Condition (何时启用) │ +├─────────────────────────────────────────┤ +│ Roles Required (需要哪些角色) │ +├─────────────────────────────────────────┤ +│ Workflow (完整执行流程) │ +├─────────────────────────────────────────┤ +│ Convergence (收敛条件) │ +│ ├─ Success Gate (成功判定) │ +│ ├─ Max Iterations (最大迭代) │ +│ └─ Timeout (超时处理) │ +├─────────────────────────────────────────┤ +│ Feedback Loop (反馈控制) │ +│ ├─ Signal (反馈信号) │ +│ ├─ Handler (处理逻辑) │ +│ └─ Correction (纠正动作) │ +├─────────────────────────────────────────┤ +│ Fallback (降级策略) │ +└─────────────────────────────────────────┘ +``` + +--- + +## CP-1: Linear Pipeline (线性流水线) + +### Description + +最基础的协作模式。任务沿固定顺序在角色间传递，每个阶段有明确的入口和出口条件。上一阶段的输出是下一阶段的输入。 + +### Entry Condition + +- 任务具有清晰的阶段划分（规划 → 实现 → 验证） +- 各阶段之间有天然的依赖关系 +- 适用于大多数标准特性开发 + +### Roles Required + +`coordinator` → `planner` → `executor` → `tester` + +### Workflow + +``` + ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ +需求 ──→ │ PLAN │──→ │ IMPL │──→ │ TEST │──→ │ REPORT │ + │ planner │ │ executor │ │ + REVIEW │ │ coord. │ + └────┬─────┘ └────┬─────┘ └─────┬─────┘ └──────────┘ + │ │ │ + ▼ ▼ ▼ + plan.json code changes test results + review findings +``` + +```javascript +// Coordinator creates task chain +TaskCreate({ subject: "PLAN-001", owner: "planner" }) +TaskCreate({ subject: "IMPL-001", owner: "executor", addBlockedBy: [planId] }) +TaskCreate({ subject: "TEST-001", owner: "tester", addBlockedBy: [implId] }) +TaskCreate({ subject: "REVIEW-001", owner: "tester", addBlockedBy: [implId] }) +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有阶段任务状态 = `completed` | +| **Max Iterations** | 每阶段 1 次（若失败触发 Review-Fix Cycle） | +| **Timeout** | 无显式超时，每阶段内部有各自收敛机制 | + +### Feedback Loop + +``` +┌─ Stage Transition Feedback ─────────────────────────┐ +│ │ +│ Plan rejected? → planner revises → resubmit │ +│ Impl has errors? → executor self-validates → fix │ +│ Tests fail? → tester fix cycle → retry │ +│ Review blocks? → create IMPL-fix → executor fixes │ +│ │ +└──────────────────────────────────────────────────────┘ +``` + +**Signal**: 下一阶段的 reject/fail message +**Handler**: Coordinator 路由消息回上一阶段 +**Correction**: 上一阶段 agent 修订并重新提交 + +### Fallback + +- Plan 拒绝 3+ 次 → Coordinator 自行规划 +- Test 达不到 95% 超过 5 次迭代 → 上报用户 +- Review 发现 critical → 创建 IMPL-fix 任务 + +### Implementation Reference + +当前 `coordinate.md` 即采用此模式。 + +--- + +## CP-2: Review-Fix Cycle (审查修复循环) + +### Description + +两个角色之间的迭代改进循环。一个角色产出工作成果，另一个角色审查，发现问题后退回修复，直到达到质量门控。这是软件开发中 code review 的自然映射。 + +### Entry Condition + +- 工作产出需要质量验证（代码实现、计划、文档） +- 存在明确的质量标准（pass rate、severity threshold、acceptance criteria） +- 需要多轮迭代才能达到质量要求 + +### Roles Required + +`producer` (executor/planner) ↔ `reviewer` (tester/reviewer) + +### Workflow + +``` + ┌─────────┐ ┌──────────┐ + │Producer │ │Reviewer │ + │ │──(1)产出───→│ │ + │ │ │ │ + │ │←─(2)反馈────│ │ + │ │ │ │ + │ │──(3)修订───→│ │ + │ │ │ │ + │ ... │ ...循环 │ ... │ + │ │ │ │ + └─────────┘ └──────────┘ + │ │ + ▼ ▼ + final artifact APPROVE verdict +``` + +```javascript +// Coordinator orchestrates review-fix cycle +function reviewFixCycle(producerRole, reviewerRole, maxIterations) { + let iteration = 0 + let verdict = 'PENDING' + + while (iteration < maxIterations && verdict !== 'APPROVE') { + iteration++ + + // Step 1: Producer delivers (or revises) + if (iteration === 1) { + // Wait for initial delivery + // msg type: impl_complete / plan_ready + } else { + // Wait for revision + // msg type: impl_complete (revision) + } + + // Step 2: Reviewer examines + // Creates REVIEW task, waits for review_result + + // Step 3: Check verdict + verdict = reviewResult.data.verdict // APPROVE | CONDITIONAL | BLOCK + + if (verdict === 'BLOCK') { + // Step 4: Create fix task for producer + TaskCreate({ + subject: `IMPL-fix-${iteration}`, + description: `Fix issues: ${reviewResult.data.findings}`, + owner: producerRole + }) + // Send feedback to producer + team_msg({ type: "fix_required", data: { iteration, findings: reviewResult.data.findings } }) + } + } + + return { verdict, iterations: iteration } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | Reviewer verdict = `APPROVE` 或 `CONDITIONAL`（无 critical findings） | +| **Max Iterations** | 5 轮（可配置）。Producer 修复 → Reviewer 再审 = 1 轮 | +| **Timeout** | 单轮超时 = 阶段超时（由各角色内部控制） | + +### Feedback Loop + +``` +Signal: review_result { verdict: "BLOCK", findings: [...] } + ↓ +Handler: Coordinator 解析 findings，按 severity 分类 + ↓ +Correction: 创建 IMPL-fix 任务，附带 findings 明细 + Producer 收到任务 → 读取 findings → 修复 → 重新提交 + ↓ +Loop: Reviewer 再次审查修订后的产出 +``` + +**反馈信号结构**: +```javascript +{ + verdict: "APPROVE" | "CONDITIONAL" | "BLOCK", + findings: { + critical: [{ file, line, description, suggestion }], + high: [...], + medium: [...], + low: [...] + }, + iteration: 2, + delta: "+3 fixed, -1 new issue" // 对比上一轮的变化 +} +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 达到 max iterations 仍 BLOCK | 上报用户，附带全部 findings 历史 | +| Reviewer 发现 Producer 无法修复的设计问题 | 升级到 CP-5 Escalation，或回退到 CP-1 重新规划 | +| 连续 2 轮 findings 不减少（无改善） | 中断循环，上报用户请求介入 | + +--- + +## CP-3: Parallel Fan-out/Fan-in (并行扇出扇入) + +### Description + +Coordinator 将同一任务或同一类任务广播给多个 agent 并行执行，收集所有结果后聚合。适用于需要多角度分析、分片处理、或冗余验证的场景。 + +### Entry Condition + +- 任务可分解为独立的并行子任务 +- 需要多角度/多维度分析（如安全 + 性能 + 架构审查） +- 大型任务需要分片并行处理 + +### Roles Required + +`coordinator` → `worker-1, worker-2, ... worker-N` → `coordinator` (aggregation) + +### Workflow + +``` + ┌─ worker-1 ─┐ + │ 角度 A │───┐ + broadcast ├─ worker-2 ─┤ │ aggregate +coord ──────────────┤ 角度 B │───┼──── coord + ├─ worker-3 ─┤ │ + │ 角度 C │───┘ + └────────────┘ +``` + +```javascript +// Phase 1: Fan-out - broadcast tasks +const workerTasks = angles.map((angle, i) => { + const taskId = TaskCreate({ + subject: `ANALYZE-${i+1}: ${angle} analysis`, + description: `Analyze from ${angle} perspective: ${requirement}`, + owner: `worker-${i+1}`, + activeForm: `Analyzing ${angle}` + }) + return taskId +}) + +// Phase 2: Wait for all workers (or quorum + timeout) +function waitForCompletion(taskIds, quorumRatio = 1.0, timeoutMs = 300000) { + const startTime = Date.now() + const quorumCount = Math.ceil(taskIds.length * quorumRatio) + let completedCount = 0 + + while (completedCount < quorumCount) { + if (Date.now() - startTime > timeoutMs) break + const tasks = TaskList() + completedCount = taskIds.filter(id => + tasks.find(t => t.id === id && t.status === 'completed') + ).length + // Wait... + } + + return { completed: completedCount, total: taskIds.length, timedOut: completedCount < quorumCount } +} + +// Phase 3: Fan-in - aggregate results +function aggregateResults(taskIds) { + const results = taskIds.map(id => { + const task = TaskGet({ taskId: id }) + return { angle: task.subject, result: task.metadata?.result } + }) + + // Conflict detection + const conflicts = detectConflicts(results) + + return { + results, + conflicts, + consensus: conflicts.length === 0, + summary: synthesize(results) + } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有 worker 完成（或达到 quorum 比例，默认 100%） | +| **Max Iterations** | 1 轮扇出（若聚合后有冲突，可触发 CP-4 Consensus） | +| **Timeout** | 可配置，默认 5 分钟。超时后用已完成的结果聚合 | + +### Feedback Loop + +``` +Signal: 每个 worker 的 {角度}_result message + ↓ +Handler: Coordinator 收集所有结果 + ↓ +Aggregate: 合并结果 + 冲突检测 + ├─ 无冲突 → 直接合成最终结果 + └─ 有冲突 → 升级到 CP-4 Consensus Gate +``` + +**聚合策略**: +- **Union（并集）**: 合并所有发现（适用于安全审查 - 不遗漏任何 finding） +- **Intersection（交集）**: 只保留多个 worker 共同发现的问题（适用于降噪） +- **Weighted（加权）**: 按 worker 的专业权重合并（适用于多专家评审） + +### Fallback + +| Condition | Action | +|-----------|--------| +| Worker 超时未完成 | 用已完成的 worker 结果聚合，标注缺失角度 | +| Worker 返回错误 | 跳过该 worker，用 N-1 结果聚合 | +| 聚合结果有冲突 | 触发 CP-4 Consensus Gate 解决分歧 | + +--- + +## CP-4: Consensus Gate (共识门控) + +### Description + +在做出重要决策前，要求多个 agent 投票表达意见，只有达到 quorum 才能通过。模拟软件开发中的 Design Review、Architecture Decision Record (ADR) 的决策流程。 + +### Entry Condition + +- 架构决策（选择技术方案 A vs B vs C） +- 安全决策（是否可接受某个风险） +- 影响面大的重构（需要多方确认） +- CP-3 扇出结果有冲突需要裁决 + +### Roles Required + +`proposer` → `voter-1, voter-2, ... voter-N` → `coordinator` (tally) + +### Workflow + +``` + ┌─ voter-1 ─────────────┐ + │ APPROVE + rationale │ + proposal ├─ voter-2 ─────────────┤ tally +proposer ─────────→ │ REJECT + rationale │ ────→ coordinator + ├─ voter-3 ─────────────┤ │ + │ APPROVE + conditions │ ▼ + └───────────────────────┘ decision +``` + +```javascript +// Phase 1: Proposal +const proposal = { + id: `PROPOSAL-${Date.now()}`, + title: "Adopt Strategy Pattern for payment gateway", + options: [ + { id: "A", description: "Strategy Pattern with factory", pros: [...], cons: [...] }, + { id: "B", description: "Plugin architecture", pros: [...], cons: [...] } + ], + context: "Payment module needs multi-gateway support", + deadline: Date.now() + 300000 // 5 min +} + +// Phase 2: Broadcast proposal to voters +voters.forEach(voter => { + SendMessage({ + recipient: voter, + content: `## Proposal: ${proposal.title}\n${JSON.stringify(proposal)}`, + summary: "Vote requested" + }) +}) + +// Phase 3: Collect votes +function collectVotes(proposalId, voterCount, quorum, deadline) { + const votes = [] + while (votes.length < voterCount && Date.now() < deadline) { + // Listen for vote messages + const msgs = team_msg({ operation: "list", type: "vote" }) + const newVotes = msgs.filter(m => + m.data.proposalId === proposalId && !votes.find(v => v.from === m.from) + ) + votes.push(...newVotes) + + // Check quorum + if (votes.length >= quorum) break + } + return votes +} + +// Phase 4: Tally and decide +function tallyVotes(votes, quorumRatio = 0.67) { + const approvals = votes.filter(v => v.data.vote === 'APPROVE') + const rejections = votes.filter(v => v.data.vote === 'REJECT') + const conditions = votes.flatMap(v => v.data.conditions || []) + + const approvalRatio = approvals.length / votes.length + const passed = approvalRatio >= quorumRatio + + return { + passed, + approvalRatio, + approvals: approvals.length, + rejections: rejections.length, + conditions: [...new Set(conditions)], + rationales: votes.map(v => ({ from: v.from, vote: v.data.vote, rationale: v.data.rationale })) + } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 赞成率 ≥ quorum（默认 2/3）且无 BLOCK 级别反对 | +| **Max Iterations** | 2 轮。第 1 轮未达 quorum → 修订提案 → 第 2 轮重投 | +| **Timeout** | 5 分钟。超时后以已收到的票数计算（≥ quorum 则通过） | + +### Feedback Loop + +``` +Signal: vote { vote: "REJECT", rationale: "...", conditions: [...] } + ↓ +Handler: Coordinator 聚合所有反对意见和附加条件 + ↓ +Correction: ├─ 未达 quorum → Proposer 修订提案，融合反对意见 → 重投 + ├─ 达到 quorum 但有 conditions → 记录 conditions 作为实施约束 + └─ 明确通过 → 执行决策 +``` + +**投票格式**: +```javascript +team_msg({ + type: "vote", + data: { + proposalId: "PROPOSAL-xxx", + vote: "APPROVE" | "REJECT" | "ABSTAIN", + rationale: "选择方案A因为...", // 必须提供理由 + conditions: ["需要增加向后兼容层"], // 可选附加条件 + confidence: 0.85 // 置信度 0-1 + } +}) +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 2 轮都未达 quorum | 上报用户裁决 | +| 投票截止但票数不足（< N/2） | 延长截止时间 1 轮 | +| 全员 ABSTAIN | 由 Coordinator 做默认决策并记录 | + +--- + +## CP-5: Escalation Chain (逐级升级) + +### Description + +当 agent 遇到无法自行解决的问题时，逐级升级到更高层级的处理能力。模拟软件开发中的 on-call escalation / tiered support。 + +### Entry Condition + +- Agent 自修复失败（尝试 N 次后仍无法解决） +- 问题超出当前角色能力范围 +- 需要更高权限或更广视角的决策 + +### Roles Required + +`agent` → `specialist` → `coordinator` → `user` + +### Workflow + +``` +Level 0 Level 1 Level 2 Level 3 +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Agent │────→│Specialist│────→│Coordinator│───→│ User │ +│ 自修复 │ │ 专家诊断 │ │ 全局视角 │ │ 人工裁决 │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘ + │ │ │ │ + ▼ ▼ ▼ ▼ + retry 2x CLI analysis cross-team fix manual fix +``` + +```javascript +// Escalation state machine +const ESCALATION_LEVELS = [ + { + level: 0, + name: "Self-repair", + handler: "agent", + maxAttempts: 2, + actions: ["Retry with different approach", "Read more context", "Simplify approach"] + }, + { + level: 1, + name: "Specialist diagnosis", + handler: "specialist", + maxAttempts: 1, + actions: ["CLI analysis (gemini/qwen)", "Cross-file dependency trace", "Pattern matching"] + }, + { + level: 2, + name: "Coordinator intervention", + handler: "coordinator", + maxAttempts: 1, + actions: ["Reassign to different agent", "Modify task scope", "Create support task"] + }, + { + level: 3, + name: "User escalation", + handler: "user", + maxAttempts: 1, + actions: ["Present diagnosis chain", "Request manual guidance", "Offer options"] + } +] + +function escalate(issue, currentLevel) { + const nextLevel = ESCALATION_LEVELS[currentLevel + 1] + if (!nextLevel) { + // Already at highest level, wait for user + return { action: "wait", level: currentLevel } + } + + team_msg({ + type: "escalate", + data: { + issue: issue.description, + from_level: currentLevel, + to_level: nextLevel.level, + attempts_at_current: issue.attempts, + diagnosis_chain: issue.diagnosisHistory // 所有层级的诊断记录 + } + }) + + return { action: "escalate", nextHandler: nextLevel.handler, level: nextLevel.level } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 问题在某个层级被解决（agent 报告 issue resolved） | +| **Max Iterations** | 每个层级有独立的 maxAttempts（L0: 2, L1: 1, L2: 1, L3: 1） | +| **Timeout** | L0-L2 无显式超时；L3 用户层需等待用户响应 | + +### Feedback Loop + +``` +Signal: escalate { issue, from_level, diagnosis_chain } + ↓ +Handler: 上级接收问题 + 下级的全部诊断历史 + ↓ +Diagnosis: 上级基于更广视角/更强能力做出诊断 + ↓ +Response: ├─ 解决方案 → 传回原 agent 执行 + ├─ 重新定义问题 → 修改任务描述，agent 重试 + └─ 无法解决 → 继续升级到下一层 +``` + +**诊断链结构** (每层追加): +```javascript +{ + diagnosisHistory: [ + { level: 0, agent: "executor", attempts: 2, diagnosis: "TypeScript类型不匹配", tried: ["修改类型定义", "添加类型断言"] }, + { level: 1, agent: "specialist", attempts: 1, diagnosis: "循环依赖导致类型无法推断", recommendation: "重构模块边界" }, + // ... 每层追加自己的诊断 + ] +} +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| L3 用户无响应 | Agent 尝试最保守的方案继续，标记为 WORKAROUND | +| 诊断链显示根本问题（如架构缺陷） | 回退到 CP-1 重新规划 | +| 升级到 L1 后解决 | 将解决方案记录为 pattern，下次 L0 可直接处理 | + +--- + +## CP-6: Incremental Delivery (增量交付) + +### Description + +将大型任务分解为小的增量，每个增量独立交付并验证后再进行下一个。模拟 CI/CD 中的小批量交付和渐进式部署。 + +### Entry Condition + +- 大型特性（影响 > 10 个文件） +- 高风险变更（需要逐步验证） +- 用户要求渐进可见的进度 + +### Roles Required + +`coordinator` → `executor` (increment) → `validator` (per-increment) → `coordinator` (gate) + +### Workflow + +``` + ┌─────────────────────────────────────────────────┐ + │ Increment 1 Increment 2 Increment N │ + │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ + │ │ Implement│ │ Implement│ │ Implement│ │ + │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ + │ ▼ ▼ ▼ │ + │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ + │ │ Validate │ │ Validate │ │ Validate │ │ + │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ + │ ▼ ▼ ▼ │ + │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ + │ │ Gate ✓ │ │ Gate ✓ │ │ Gate ✓ │ │ + │ └──────────┘ └──────────┘ └──────────┘ │ + └─────────────────────────────────────────────────┘ + │ + ▼ + Full validation +``` + +```javascript +// Coordinator splits plan into increments +function createIncrements(plan) { + // Group tasks by dependency layers + const layers = topologicalSort(plan.tasks) + + return layers.map((layer, i) => ({ + id: `INCREMENT-${i+1}`, + tasks: layer, + gate: { + syntax_clean: true, + no_regression: true, // 已有测试不破坏 + increment_tests_pass: true // 增量相关测试通过 + } + })) +} + +// Execute increment cycle +for (const increment of increments) { + // Step 1: Executor implements increment + TaskCreate({ + subject: `IMPL-inc-${increment.id}`, + description: `Implement increment: ${increment.tasks.map(t => t.title).join(', ')}`, + owner: "executor" + }) + + // Step 2: Wait for implementation + // msg: increment_ready + + // Step 3: Validator checks increment gate + const gateResult = validateIncrement(increment) + + // Step 4: Gate decision + if (gateResult.passed) { + team_msg({ type: "increment_ready", data: { increment: increment.id, status: "PASS" } }) + // Continue to next increment + } else { + // Feedback: which gate criteria failed + team_msg({ type: "fix_required", data: { + increment: increment.id, + failed_gates: gateResult.failures, + suggestion: gateResult.fix_suggestion + }}) + // Executor fixes → re-validate (max 3 retries per increment) + } +} + +// Final: full validation after all increments +TaskCreate({ subject: "TEST-final", description: "Full test suite after all increments" }) +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有增量通过各自的 gate + 最终全量验证通过 | +| **Max Iterations** | 每个增量最多 3 次重试，总增量数由 plan 决定 | +| **Timeout** | 单个增量超时 = 增量任务数 × 单任务超时 | + +### Feedback Loop + +``` +Signal: increment gate failure { failed_gates, affected_files } + ↓ +Handler: Coordinator 定位失败的 gate 条件 + ↓ +Correction: ├─ syntax_clean 失败 → Executor 修复语法 + ├─ no_regression 失败 → Executor 修复回归 + 回滚该增量 + └─ increment_tests 失败 → 触发 CP-2 Review-Fix Cycle +``` + +**增量进度追踪**: +```javascript +{ + total_increments: 4, + completed: 2, + current: 3, + progress_percent: 50, + gate_history: [ + { id: "INCREMENT-1", attempts: 1, status: "PASS" }, + { id: "INCREMENT-2", attempts: 2, status: "PASS" }, + { id: "INCREMENT-3", attempts: 1, status: "IN_PROGRESS" } + ] +} +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 增量重试 3 次仍失败 | 回滚该增量代码，标记为 blocked，继续下一增量 | +| 超过半数增量被 blocked | 停止交付，上报用户评估是否重新规划 | +| 最终全量验证失败 | 识别失败增量组合，逐个回退定位 | + +--- + +## CP-7: Swarming (群策攻关) + +### Description + +当流水线被一个问题阻塞时，暂停正常工作流，所有可用 agent 集中力量解决该问题。模拟敏捷开发中的 swarming / mob debugging。 + +### Entry Condition + +- 关键任务被阻塞超过阈值时间 +- Agent 自修复和 L1 升级都失败 +- 问题影响多个下游任务 + +### Roles Required + +`coordinator` (发起) → `all available agents` (协同) → `coordinator` (裁决) + +### Workflow + +``` + ┌───────────────────────────────────┐ + │ SWARM MODE ACTIVE │ + │ │ + │ ┌────────┐ ┌────────┐ │ + │ │Agent A │ │Agent B │ │ + │ │诊断视角1│ │诊断视角2│ │ + │ └───┬────┘ └───┬────┘ │ + │ │ │ │ + │ ▼ ▼ │ + │ ┌─────────────────────┐ │ + │ │ Coordinator 汇总 │ │ + │ │ 选择最佳诊断 │ │ + │ └─────────┬───────────┘ │ + │ ▼ │ + │ ┌─────────────────────┐ │ + │ │ 指定 Agent 执行修复 │ │ + │ └─────────────────────┘ │ + │ │ + └───────────────────────────────────┘ + │ + ▼ + Resume normal pipeline +``` + +```javascript +// Coordinator initiates swarm +function initiateSwarm(blockingIssue) { + // Step 1: Pause all non-critical tasks + const activeTasks = TaskList().filter(t => t.status === 'in_progress') + activeTasks.forEach(t => { + TaskUpdate({ taskId: t.id, metadata: { paused_for_swarm: true } }) + }) + + // Step 2: Broadcast swarm request + team_msg({ + type: "swarm_join", + data: { + issue: blockingIssue.description, + affected_tasks: blockingIssue.blockedTasks, + diagnosis_so_far: blockingIssue.diagnosisHistory, + assignment: "All agents: diagnose from your expertise angle" + } + }) + + // Step 3: Each agent analyzes from their perspective + // planner: 架构视角诊断 + // executor: 实现细节诊断 + // tester: 测试/环境视角诊断 + + // Step 4: Collect diagnoses (fan-in) + // Uses CP-3 fan-in aggregation + + // Step 5: Coordinator selects best diagnosis + assigns fix + const bestDiagnosis = selectBestDiagnosis(diagnoses) + const fixer = selectBestFixer(bestDiagnosis, availableAgents) + + TaskCreate({ + subject: `SWARM-FIX: ${blockingIssue.summary}`, + description: `Fix based on swarm diagnosis:\n${bestDiagnosis.detail}`, + owner: fixer + }) + + // Step 6: Verify fix, resume pipeline + // ... wait for fix completion ... + + // Step 7: Resume paused tasks + activeTasks.forEach(t => { + TaskUpdate({ taskId: t.id, metadata: { paused_for_swarm: null } }) + }) +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 阻塞问题解决（相关测试通过 / 错误消失） | +| **Max Iterations** | 2 轮诊断。第 1 轮全员诊断 → 修复 → 若失败 → 第 2 轮聚焦诊断 | +| **Timeout** | 10 分钟。超时后以最佳可用诊断尝试修复 | + +### Feedback Loop + +``` +Signal: 每个 agent 的 swarm_diagnosis { perspective, root_cause, confidence, fix_suggestion } + ↓ +Handler: Coordinator 按 confidence 排序，合并互补的诊断 + ↓ +Selection: 选择 confidence 最高且 fix_suggestion 最具体的方案 + ↓ +Execution: 指定最合适的 agent 执行修复 + ↓ +Verify: 修复后重新运行触发阻塞的场景 + ├─ 通过 → 恢复流水线 + └─ 失败 → 第 2 轮，排除已尝试方案 +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 2 轮 swarm 未解决 | 升级到用户（CP-5 L3） | +| 修复引入新问题 | 回滚修复，尝试次优方案 | +| Agent 在 swarm 期间无响应 | 跳过该 agent，用其余 agent 的诊断 | + +--- + +## CP-8: Consulting/Advisory (咨询顾问) + +### Description + +工作中的 agent 暂停当前任务，向拥有特定领域知识的 specialist 请求建议，获得建议后继续工作。不同于升级（CP-5），consulting 不转移问题所有权。 + +### Entry Condition + +- Agent 遇到不熟悉的领域（如安全、性能优化、特定框架用法） +- 需要验证方案的正确性但不需要他人实现 +- 需要领域最佳实践参考 + +### Roles Required + +`requester` (任何工作中的 agent) → `consultant` (specialist agent) → `requester` (继续工作) + +### Workflow + +``` + requester consultant + ┌──────────┐ ┌──────────┐ + │ Working │ │ Idle │ + │ │──(1)请求────→│ │ + │ Paused │ │ 分析中 │ + │ │←─(2)建议────│ │ + │ Resume │ │ Idle │ + │ (应用建议)│ │ │ + └──────────┘ └──────────┘ +``` + +```javascript +// Requester sends consultation request +function requestConsultation(topic, context, urgency = 'normal') { + team_msg({ + type: "consult_request", + from: currentRole, + to: "coordinator", // coordinator routes to appropriate specialist + data: { + topic: topic, // "security", "performance", "database" + question: context.question, // 具体问题 + context: context.codeSnippet, // 相关代码片段 + options: context.options, // 可选方案（如果有） + urgency: urgency // "blocking" | "normal" | "low" + } + }) + // Pause current work, wait for response +} + +// Coordinator routes to specialist +function routeConsultation(request) { + const specialist = selectSpecialist(request.data.topic) + // If no specialist agent exists, use CLI tool as specialist + if (!specialist) { + // Fallback: invoke CLI analysis + Bash(`ccw cli -p "PURPOSE: Expert consultation on ${request.data.topic} +TASK: ${request.data.question} +CONTEXT: ${request.data.context} +EXPECTED: Actionable recommendation with confidence level +" --tool gemini --mode analysis`, { run_in_background: true }) + } +} + +// Consultant provides advice +function provideAdvice(request) { + team_msg({ + type: "consult_response", + from: "consultant", + to: request.from, + data: { + recommendation: "使用 bcrypt 而非 SHA-256 进行密码哈希", + rationale: "bcrypt 内置 salt 和自适应计算成本...", + confidence: 0.95, + references: ["OWASP Password Storage Cheat Sheet"], + caveats: ["需要增加 ~100ms 延迟"], + alternative: "如果延迟敏感，可考虑 Argon2id" + } + }) +} + +// Requester applies advice +function applyAdvice(advice) { + if (advice.data.confidence >= 0.8) { + // Apply recommendation directly + return { action: "apply", recommendation: advice.data.recommendation } + } else { + // Low confidence: request second opinion or escalate + return { action: "second_opinion" } + } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 咨询回复 confidence ≥ 0.8 且 requester 成功应用建议 | +| **Max Iterations** | 1 次主咨询 + 1 次追问（如果首次回复不够清晰） | +| **Timeout** | blocking: 2 分钟, normal: 5 分钟, low: 无超时 | + +### Feedback Loop + +``` +Signal: consult_response { recommendation, confidence, caveats } + ↓ +Handler: Requester 评估建议的适用性 + ├─ confidence ≥ 0.8 → 直接应用 + ├─ confidence < 0.8 → 追问一轮或请求 second opinion + └─ 与当前方案冲突 → 上报 coordinator 裁决 + ↓ +Correction: Requester 基于建议调整实现方案，继续原任务 +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 无可用 specialist | 使用 CLI tool (gemini/qwen) 替代 | +| 咨询超时 | Requester 用自己的最佳判断继续，标注 unverified | +| 建议与当前设计冲突 | 上报 coordinator，触发 CP-4 Consensus | + +--- + +## CP-9: Dual-Track (双轨并行) + +### Description + +两条工作轨道并行推进，在预定义的同步点（checkpoint）对齐。典型应用：设计与实现并行、前端与后端并行、功能开发与测试开发并行。 + +### Entry Condition + +- 任务可分解为两条相对独立的工作流 +- 两条轨道有明确的同步点（interface contract、API spec、schema） +- 并行执行能提升整体效率 + +### Roles Required + +`coordinator` → `track-A` agent + `track-B` agent → `coordinator` (sync) + +### Workflow + +``` + Track A (Design/API) Track B (Implementation) + ┌────────────┐ ┌────────────┐ + │ Phase A-1 │ │ Phase B-1 │ + │ API 设计 │ │ 脚手架搭建 │ + └─────┬──────┘ └─────┬──────┘ + │ │ + ▼ ┌──────────┐ ▼ + ╔═══════════════╗│ SYNC-1 │╔═══════════════╗ + ║ checkpoint 1 ║│ 对齐接口 │║ checkpoint 1 ║ + ╚═══════════════╝└──────────┘╚═══════════════╝ + │ │ + ▼ ▼ + ┌────────────┐ ┌────────────┐ + │ Phase A-2 │ │ Phase B-2 │ + │ 详细设计 │ │ 核心实现 │ + └─────┬──────┘ └─────┬──────┘ + │ │ + ▼ ┌──────────┐ ▼ + ╔═══════════════╗│ SYNC-2 │╔═══════════════╗ + ║ checkpoint 2 ║│ 集成验证 │║ checkpoint 2 ║ + ╚═══════════════╝└──────────┘╚═══════════════╝ +``` + +```javascript +// Coordinator defines sync points +const syncPoints = [ + { + id: "SYNC-1", + name: "Interface Contract", + trackA_deliverable: "API schema / interface definitions", + trackB_deliverable: "Scaffold with interface stubs", + alignment_check: "Both tracks agree on interface signatures" + }, + { + id: "SYNC-2", + name: "Integration Verification", + trackA_deliverable: "Complete design + test specs", + trackB_deliverable: "Core implementation", + alignment_check: "Implementation passes design test specs" + } +] + +// Phase execution with sync barriers +for (const sync of syncPoints) { + // Launch both tracks in parallel + const trackATask = TaskCreate({ + subject: `TRACK-A-${sync.id}: ${sync.trackA_deliverable}`, + owner: "track-a-agent" + }) + const trackBTask = TaskCreate({ + subject: `TRACK-B-${sync.id}: ${sync.trackB_deliverable}`, + owner: "track-b-agent" + }) + + // Wait for both tracks to reach sync point + waitForBoth(trackATask, trackBTask) + + // Sync point: alignment check + const aligned = checkAlignment(sync.alignment_check, trackAResult, trackBResult) + + if (!aligned) { + // Misalignment detected → correction + team_msg({ type: "sync_checkpoint", data: { + sync_id: sync.id, + status: "MISALIGNED", + trackA_state: trackAResult.summary, + trackB_state: trackBResult.summary, + conflicts: aligned.conflicts + }}) + // Coordinator mediates: which track adjusts? + resolveAlignment(aligned.conflicts, trackATask, trackBTask) + } else { + team_msg({ type: "sync_checkpoint", data: { sync_id: sync.id, status: "ALIGNED" } }) + } +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有 sync point 对齐 + 最终集成验证通过 | +| **Max Iterations** | 每个 sync point 最多 2 次对齐尝试 | +| **Timeout** | 先到达 sync point 的 track 等待另一个 track，超时 5 分钟 | + +### Feedback Loop + +``` +Signal: sync_checkpoint { status: "MISALIGNED", conflicts } + ↓ +Handler: Coordinator 分析冲突来源 + ├─ Track A 的设计不合理 → 要求 Track A 调整设计 + ├─ Track B 偏离了接口约定 → 要求 Track B 重新对齐 + └─ 双方都有偏差 → 协商折中方案 + ↓ +Correction: 被要求调整的 track agent 收到 fix 描述 + → 调整产出 → 重新到达 sync point +``` + +### Fallback + +| Condition | Action | +|-----------|--------| +| 一条 track 完全阻塞 | 另一条 track 暂停等待，触发 CP-7 Swarming 解决阻塞 | +| Sync 对齐 2 次失败 | 降级为 CP-1 Linear Pipeline（顺序执行） | +| 两条 track 差距过大（一快一慢） | 快 track 预做下一阶段，慢 track 加速 | + +--- + +## CP-10: Post-Mortem (复盘回顾) + +### Description + +任务完成后，对整个执行过程进行结构化回顾，提取经验教训和改进建议。这些知识可以反馈到项目的 CLAUDE.md 或 core memory 中，提升未来任务的执行质量。 + +### Entry Condition + +- 团队完成一个完整任务周期后（所有 task completed） +- 任务执行过程中出现显著问题（多次失败、多次升级） +- 用户主动请求回顾 + +### Roles Required + +`coordinator` (发起 + 汇总) → `all agents` (提供各自视角) → `coordinator` (文档化) + +### Workflow + +``` + ┌──────────────────────────────────────────┐ + │ POST-MORTEM PHASE │ + │ │ + │ 1. Coordinator 收集执行数据 │ + │ ├─ 任务链完成情况 │ + │ ├─ 消息总线历史 │ + │ └─ 迭代/升级/失败记录 │ + │ │ + │ 2. 每个 Agent 提交回顾 │ + │ ├─ Planner: 规划准确度 │ + │ ├─ Executor: 实现障碍 │ + │ └─ Tester: 质量发现 │ + │ │ + │ 3. Coordinator 汇总 │ + │ ├─ 成功因素 │ + │ ├─ 改进点 │ + │ └─ 行动建议 │ + │ │ + │ 4. 输出到 memory / CLAUDE.md │ + └──────────────────────────────────────────┘ +``` + +```javascript +// Coordinator initiates post-mortem +function conductPostMortem(teamName) { + // Step 1: Collect execution data + const messages = team_msg({ operation: "list", team: teamName }) + const tasks = TaskList() + const completedTasks = tasks.filter(t => t.status === 'completed') + const failedTasks = tasks.filter(t => t.status === 'in_progress' && t.metadata?.stuck) + + const executionData = { + total_tasks: tasks.length, + completed: completedTasks.length, + total_messages: messages.length, + escalations: messages.filter(m => m.type === 'escalate').length, + fix_cycles: messages.filter(m => m.type === 'fix_required').length, + errors: messages.filter(m => m.type === 'error').length + } + + // Step 2: Request agent retrospectives (Fan-out) + // Each agent answers: What went well? What was difficult? What should change? + agents.forEach(agent => { + SendMessage({ + recipient: agent.name, + content: `## Post-Mortem Request +请回顾本次任务，回答: +1. **顺利**: 哪些方面执行顺利？ +2. **困难**: 遇到了什么障碍？ +3. **建议**: 下次如何改进？ +4. **模式**: 发现了什么可复用的模式？`, + summary: "Post-mortem request" + }) + }) + + // Step 3: Aggregate findings + // Collect retro_finding messages from all agents + const findings = collectFindings(agents) + + // Step 4: Generate structured post-mortem report + const report = { + team: teamName, + timestamp: new Date().toISOString(), + execution_summary: executionData, + what_went_well: findings.flatMap(f => f.went_well), + what_was_difficult: findings.flatMap(f => f.difficult), + improvement_actions: findings.flatMap(f => f.suggestions), + reusable_patterns: findings.flatMap(f => f.patterns), + recommendations: generateRecommendations(executionData, findings) + } + + // Step 5: Persist learnings + // Option A: Write to session artifacts + Write(`${sessionFolder}/post-mortem.json`, JSON.stringify(report, null, 2)) + + // Option B: Import to core memory (if significant) + if (report.reusable_patterns.length > 0) { + mcp__ccw-tools__core_memory({ + operation: "import", + text: `Team ${teamName} post-mortem: ${report.reusable_patterns.join('; ')}` + }) + } + + return report +} +``` + +### Convergence + +| Element | Value | +|---------|-------| +| **Success Gate** | 所有 agent 提交回顾 + 报告生成完毕 | +| **Max Iterations** | 1 轮（回顾是单次活动） | +| **Timeout** | Agent 回顾提交超时 3 分钟，超时则仅用已收到的回顾 | + +### Feedback Loop + +``` +Signal: retro_finding { went_well, difficult, suggestions, patterns } + ↓ +Handler: Coordinator 分类、去重、优先级排序 + ↓ +Output: ├─ 高价值 patterns → 写入 core memory / CLAUDE.md + ├─ 改进建议 → 记录到项目 guidelines + └─ 问题根因 → 作为下次任务的预防措施 +``` + +**学习闭环**: Post-mortem 的输出反馈到未来任务的 Phase 2 Context Loading，实现持续改进。 + +### Fallback + +| Condition | Action | +|-----------|--------| +| Agent 无法提供回顾（已关闭） | 从消息总线历史中提取该 agent 的执行数据 | +| 无显著 findings | 生成最小报告，不写入 core memory | +| 执行数据缺失 | 基于现有数据生成部分报告 | + +--- + +## Pattern Composition (模式组合) + +### 常见组合 + +协作模式可以组合使用，形成更复杂的工作流： + +``` +1. Standard Development (标准开发) + CP-1 (Pipeline) + CP-2 (Review-Fix) + CP-10 (Post-Mortem) + +2. High-Risk Feature (高风险特性) + CP-4 (Consensus on design) → CP-6 (Incremental Delivery) → CP-2 (Review-Fix each increment) + +3. Complex Investigation (复杂问题调查) + CP-3 (Fan-out analysis) → CP-4 (Consensus on diagnosis) → CP-7 (Swarm if needed) + +4. Parallel Development (并行开发) + CP-9 (Dual-Track) + CP-2 (Review-Fix per track) + CP-10 (Post-Mortem) + +5. Expert-Guided Development (专家指导开发) + CP-8 (Consulting for design) → CP-1 (Pipeline implementation) → CP-2 (Review-Fix) +``` + +### 组合规则 + +1. **不可重入**: 同一时间只能有一个 CP-7 (Swarming) 实例 +2. **可嵌套**: CP-6 的每个增量可以内部使用 CP-2 +3. **可升级**: CP-2 内发现无法修复的问题可升级到 CP-5 或 CP-7 +4. **可降级**: CP-9 对齐失败可降级到 CP-1 +5. **CP-10 始终在最后**: Post-mortem 只在团队任务完成后执行 + +### State Machine (模式状态机) + +``` + ┌──────────────────────────────────────────┐ + │ COORDINATOR FSM │ + │ │ + 新需求 ────→ [PLAN] ──→ [EXECUTE] ──→ [VALIDATE] ──→ [DONE] │ + │ │ │ │ │ + │ │ │ │ │ + ▼ ▼ ▼ ▼ │ + CP-4? CP-6? CP-2? CP-10 │ + Consensus Incremental Review-Fix Post- │ + Gate Delivery Cycle Mortem │ + │ │ │ │ + ▼ ▼ ▼ │ + [blocked?] [blocked?] [blocked?] │ + │ │ │ │ + ▼ ▼ ▼ │ + CP-5/CP-7 CP-5/CP-7 CP-5/CP-7 │ + Escalate Escalate Escalate │ + /Swarm /Swarm /Swarm │ + └──────────────────────────────────────────┘ +``` + +--- + +## Coordinator Integration Guide + +### Coordinator 如何选择协作模式 + +```javascript +// In coordinate.md Phase 1 (需求澄清) or Phase 4 (协调主循环) + +function selectCollaborationPattern(context) { + const { taskType, complexity, riskLevel, teamSize, hasExpert } = context + + // Rule-based selection + const patterns = ['CP-1'] // CP-1 is always the base + + if (riskLevel === 'high') patterns.push('CP-4') // Consensus for risky decisions + if (complexity === 'High' && taskType === 'feature') patterns.push('CP-6') // Incremental for large features + if (taskType === 'review' || taskType === 'test') patterns.push('CP-2') // Review-Fix for quality + if (hasExpert && complexity !== 'Low') patterns.push('CP-8') // Consulting for expertise + patterns.push('CP-10') // Post-mortem always included + + return patterns +} +``` + +### Coordinator 消息路由表（含协作模式） + +| 消息类型 | 触发模式 | Coordinator 动作 | +|---------|---------|-----------------| +| `plan_ready` | CP-1 | 审批 plan → 通知 executor | +| `impl_complete` | CP-1/CP-6 | 解锁 TEST/REVIEW 或下一增量 | +| `review_result` (BLOCK) | CP-2 | 创建 fix 任务 → 启动 Review-Fix Cycle | +| `vote` | CP-4 | 收集投票 → 达到 quorum 则执行决策 | +| `escalate` | CP-5 | 路由到上一级处理者 | +| `increment_ready` | CP-6 | 验证增量 gate → 允许或拒绝 | +| `swarm_join` | CP-7 | 暂停其他任务 → 聚合诊断 | +| `consult_request` | CP-8 | 路由到 specialist 或 CLI tool | +| `sync_checkpoint` | CP-9 | 检查两条 track 对齐状态 | +| `retro_finding` | CP-10 | 收集回顾 → 生成报告 | diff --git a/.claude/skills/team-skill-designer/specs/quality-standards.md b/.claude/skills/team-skill-designer/specs/quality-standards.md new file mode 100644 index 00000000..e75a188f --- /dev/null +++ b/.claude/skills/team-skill-designer/specs/quality-standards.md @@ -0,0 +1,126 @@ +# Quality Standards for Team Commands + +Quality assessment criteria for generated team command .md files. + +## When to Use + +| Phase | Usage | Section | +|-------|-------|---------| +| Phase 5 | Score generated command | All dimensions | +| Phase 3 | Guide generation quality | Checklist | + +--- + +## Quality Dimensions + +### 1. Completeness (25%) + +| Score | Criteria | +|-------|----------| +| 100% | All 15 required sections present with substantive content | +| 80% | 12+ sections present, minor gaps in non-critical areas | +| 60% | Core sections present (front matter, message bus, 5 phases, error handling) | +| 40% | Missing critical sections | +| 0% | Skeleton only | + +**Required Sections Checklist:** +- [ ] YAML front matter with `group: team` +- [ ] Overview with core capabilities +- [ ] Role Definition (name, responsibility, communication) +- [ ] Message Bus section with team_msg examples +- [ ] Message Types table +- [ ] Execution Process overview diagram +- [ ] Phase 1: Task Discovery implementation +- [ ] Phase 2: Context Loading implementation +- [ ] Phase 3: Core Work implementation +- [ ] Phase 4: Validation/Summary implementation +- [ ] Phase 5: Report + Loop implementation +- [ ] Error Handling table +- [ ] Code examples in all phases + +### 2. Pattern Compliance (25%) + +| Score | Criteria | +|-------|----------| +| 100% | All 8 infrastructure patterns + selected collaboration patterns fully implemented | +| 80% | 6 core infra patterns + at least 1 collaboration pattern with convergence | +| 60% | Minimum 6 infra patterns, collaboration patterns present but incomplete | +| 40% | Missing critical patterns (message bus or task lifecycle) | +| 0% | No pattern compliance | + +**Infrastructure Pattern Checklist:** +- [ ] Pattern 1: Message bus - team_msg before every SendMessage +- [ ] Pattern 1b: CLI fallback - `ccw team` CLI fallback section with parameter mapping +- [ ] Pattern 2: YAML front matter - all fields present, group: team +- [ ] Pattern 3: Task lifecycle - TaskList/Get/Update flow +- [ ] Pattern 4: Five-phase structure - all 5 phases present +- [ ] Pattern 5: Complexity-adaptive (if applicable) +- [ ] Pattern 6: Coordinator spawn compatible +- [ ] Pattern 7: Error handling table +- [ ] Pattern 8: Session files (if applicable) + +**Collaboration Pattern Checklist:** +- [ ] At least one CP selected (CP-1 minimum) +- [ ] Each selected CP has convergence criteria defined +- [ ] Each selected CP has feedback loop mechanism +- [ ] Each selected CP has timeout/fallback behavior +- [ ] CP-specific message types registered in message bus section +- [ ] Escalation path defined (CP-5) for error scenarios + +### 3. Integration (25%) + +| Score | Criteria | +|-------|----------| +| 100% | All integration checks pass, spawn snippet ready | +| 80% | Minor integration notes, no blocking issues | +| 60% | Some checks need attention but functional | +| 40% | Task prefix conflict or missing critical tools | +| 0% | Incompatible with team system | + +### 4. Consistency (25%) + +| Score | Criteria | +|-------|----------| +| 100% | Role name, task prefix, message types consistent throughout | +| 80% | Minor inconsistencies in non-critical areas | +| 60% | Some mixed terminology but intent clear | +| 40% | Confusing or contradictory content | +| 0% | Internally inconsistent | + +--- + +## Quality Gates + +| Gate | Threshold | Action | +|------|-----------|--------| +| PASS | >= 80% | Deliver to `.claude/commands/team/{team-name}/` | +| REVIEW | 60-79% | Fix recommendations, re-validate | +| FAIL | < 60% | Major rework needed, re-run from Phase 3 | + +--- + +## Issue Classification + +### Errors (Must Fix) + +- Missing YAML front matter +- Missing `group: team` +- No message bus section +- No task lifecycle (TaskList/Get/Update) +- No SendMessage to coordinator +- Task prefix conflicts with existing + +### Warnings (Should Fix) + +- Missing error handling table +- Incomplete Phase implementation (skeleton only) +- Missing team_msg before some SendMessage calls +- Missing CLI fallback section (`### CLI 回退` with `ccw team` examples) +- No complexity-adaptive routing when role is complex + +### Info (Nice to Have) + +- Code examples could be more detailed +- Additional message type examples +- Session file structure documentation +- CLI integration examples diff --git a/.claude/skills/team-skill-designer/specs/team-design-patterns.md b/.claude/skills/team-skill-designer/specs/team-design-patterns.md new file mode 100644 index 00000000..e51d4785 --- /dev/null +++ b/.claude/skills/team-skill-designer/specs/team-design-patterns.md @@ -0,0 +1,472 @@ +# Team Command Design Patterns + +> Extracted from 5 production team commands: coordinate, plan, execute, test, review +> Extended with 10 collaboration patterns for diverse team interaction models + +--- + +## Pattern Architecture + +``` +Team Design Patterns +├── Section A: Infrastructure Patterns (8) ← HOW to build a team command +│ ├── Pattern 1: Message Bus Integration +│ ├── Pattern 2: YAML Front Matter +│ ├── Pattern 3: Task Lifecycle +│ ├── Pattern 4: Five-Phase Execution +│ ├── Pattern 5: Complexity-Adaptive Routing +│ ├── Pattern 6: Coordinator Spawn Integration +│ ├── Pattern 7: Error Handling Table +│ └── Pattern 8: Session File Structure +│ +└── Section B: Collaboration Patterns (10) ← HOW agents interact + ├── CP-1: Linear Pipeline (线性流水线) + ├── CP-2: Review-Fix Cycle (审查修复循环) + ├── CP-3: Parallel Fan-out/Fan-in (并行扇出扇入) + ├── CP-4: Consensus Gate (共识门控) + ├── CP-5: Escalation Chain (逐级升级) + ├── CP-6: Incremental Delivery (增量交付) + ├── CP-7: Swarming (群策攻关) + ├── CP-8: Consulting/Advisory (咨询顾问) + ├── CP-9: Dual-Track (双轨并行) + └── CP-10: Post-Mortem (复盘回顾) +``` + +**Section B** collaboration patterns are documented in: [collaboration-patterns.md](collaboration-patterns.md) + +--- + +## When to Use + +| Phase | Usage | Section | +|-------|-------|---------| +| Phase 0 | Understand all patterns before design | All sections | +| Phase 2 | Select applicable infrastructure + collaboration patterns | Pattern catalog | +| Phase 3 | Apply patterns during generation | Implementation details | +| Phase 4 | Verify compliance | Checklists | + +--- + +# Section A: Infrastructure Patterns + +## Pattern 1: Message Bus Integration + +Every teammate must use `mcp__ccw-tools__team_msg` for persistent logging before every `SendMessage`. + +### Structure + +```javascript +// BEFORE every SendMessage, call: +mcp__ccw-tools__team_msg({ + operation: "log", + team: teamName, + from: "", // planner | executor | tester | + to: "coordinator", + type: "", + summary: "", + ref: "", + data: { /* optional structured payload */ } +}) +``` + +### Standard Message Types + +| Type | Direction | Trigger | Payload | +|------|-----------|---------|---------| +| `plan_ready` | planner -> coordinator | Plan generation complete | `{ taskCount, complexity }` | +| `plan_approved` | coordinator -> planner | Plan reviewed | `{ approved: true }` | +| `plan_revision` | planner -> coordinator | Plan modified per feedback | `{ changes }` | +| `task_unblocked` | coordinator -> any | Dependency resolved | `{ taskId }` | +| `impl_complete` | executor -> coordinator | Implementation done | `{ changedFiles, syntaxClean }` | +| `impl_progress` | any -> coordinator | Progress update | `{ batch, total }` | +| `test_result` | tester -> coordinator | Test cycle end | `{ passRate, iterations }` | +| `review_result` | tester -> coordinator | Review done | `{ verdict, findings }` | +| `fix_required` | any -> coordinator | Critical issues | `{ details[] }` | +| `error` | any -> coordinator | Blocking error | `{ message }` | +| `shutdown` | coordinator -> all | Team dissolved | `{}` | + +### Collaboration Pattern Message Types + +| Type | Used By | Direction | Trigger | +|------|---------|-----------|---------| +| `vote` | CP-4 Consensus | any -> coordinator | Agent casts vote on proposal | +| `escalate` | CP-5 Escalation | any -> coordinator | Agent escalates unresolved issue | +| `increment_ready` | CP-6 Incremental | executor -> coordinator | Increment delivered for validation | +| `swarm_join` | CP-7 Swarming | any -> coordinator | Agent joins swarm on blocker | +| `consult_request` | CP-8 Consulting | any -> specialist | Agent requests expert advice | +| `consult_response` | CP-8 Consulting | specialist -> requester | Expert provides advice | +| `sync_checkpoint` | CP-9 Dual-Track | any -> coordinator | Track reaches sync point | +| `retro_finding` | CP-10 Post-Mortem | any -> coordinator | Retrospective insight | + +### Adding New Message Types + +When designing a new role, define role-specific message types following the convention: +- `{action}_ready` - Work product ready for review +- `{action}_complete` - Work phase finished +- `{action}_progress` - Intermediate progress update + +### CLI Fallback + +When `mcp__ccw-tools__team_msg` MCP is unavailable, use `ccw team` CLI as equivalent fallback: + +```javascript +// Fallback: Replace MCP call with Bash CLI (parameters map 1:1) +Bash(`ccw team log --team "${teamName}" --from "" --to "coordinator" --type "" --summary "" [--ref ] [--data ''] --json`) +``` + +**Parameter mapping**: `team_msg(params)` → `ccw team --team [--from/--to/--type/--summary/--ref/--data/--id/--last] [--json]` + +**Coordinator** uses all 4 operations: `log`, `list`, `status`, `read` +**Teammates** primarily use: `log` + +### Message Bus Section Template + +```markdown +## 消息总线 + +每次 SendMessage **前**，必须调用 `mcp__ccw-tools__team_msg` 记录消息： + +\`\`\`javascript +mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "", to: "coordinator", type: "", summary: "" }) +\`\`\` + +### 支持的 Message Types + +| Type | 方向 | 触发时机 | 说明 | +|------|------|----------|------| +| `` | → coordinator | | | + +### CLI 回退 + +当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退： + +\`\`\`javascript +// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应） +Bash(\`ccw team log --team "${teamName}" --from "" --to "coordinator" --type "" --summary "" --json\`) +\`\`\` + +**参数映射**: `team_msg(params)` → `ccw team log --team --from --to coordinator --type --summary "" [--ref ] [--data ''] [--json]` +``` + +--- + +## Pattern 2: YAML Front Matter + +Every team command file must start with standardized YAML front matter. + +### Structure + +```yaml +--- +name: +description: Team - +argument-hint: "" +allowed-tools: SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*), TodoWrite(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), Task(*) +group: team +--- +``` + +### Field Rules + +| Field | Rule | Example | +|-------|------|---------| +| `name` | Lowercase, matches filename | `plan`, `execute`, `test` | +| `description` | `Team -` prefix + Chinese capability list | `Team planner - 多角度代码探索、结构化实现规划` | +| `argument-hint` | Empty string for teammates, has hint for coordinator | `""` | +| `allowed-tools` | Start with `SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*)` | See each role | +| `group` | Always `team` | `team` | + +### Minimum Tool Set (All Teammates) + +``` +SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Grep(*) +``` + +### Role-Specific Additional Tools + +| Role Type | Additional Tools | +|-----------|-----------------| +| Read-only (reviewer, analyzer) | None extra | +| Write-capable (executor, fixer) | `Write(*), Edit(*)` | +| Agent-delegating (planner, executor) | `Task(*)` | + +--- + +## Pattern 3: Task Lifecycle + +All teammates follow the same task discovery and lifecycle pattern. + +### Standard Flow + +```javascript +// Step 1: Find my tasks +const tasks = TaskList() +const myTasks = tasks.filter(t => + t.subject.startsWith('-') && // PLAN-*, IMPL-*, TEST-*, REVIEW-* + t.owner === '' && + t.status === 'pending' && + t.blockedBy.length === 0 // Not blocked +) + +// Step 2: No tasks -> idle +if (myTasks.length === 0) return + +// Step 3: Claim task (lowest ID first) +const task = TaskGet({ taskId: myTasks[0].id }) +TaskUpdate({ taskId: task.id, status: 'in_progress' }) + +// Step 4: Execute work +// ... role-specific logic ... + +// Step 5: Complete and loop +TaskUpdate({ taskId: task.id, status: 'completed' }) + +// Step 6: Check for next task +const nextTasks = TaskList().filter(t => + t.subject.startsWith('-') && + t.owner === '' && + t.status === 'pending' && + t.blockedBy.length === 0 +) +if (nextTasks.length > 0) { + // Continue with next task -> back to Step 3 +} +``` + +### Task Prefix Convention + +| Prefix | Role | Example | +|--------|------|---------| +| `PLAN-` | planner | `PLAN-001: Explore and plan implementation` | +| `IMPL-` | executor | `IMPL-001: Implement approved plan` | +| `TEST-` | tester | `TEST-001: Test-fix cycle` | +| `REVIEW-` | tester | `REVIEW-001: Code review and requirement verification` | +| `-` | new role | Must be unique, uppercase, hyphen-suffixed | + +### Task Chain (defined in coordinate.md) + +``` +PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001 + ↑ blockedBy ↑ blockedBy +``` + +--- + +## Pattern 4: Five-Phase Execution Structure + +Every team command follows a consistent 5-phase internal structure. + +### Standard Phases + +| Phase | Purpose | Common Actions | +|-------|---------|----------------| +| Phase 1: Task Discovery | Find and claim assigned tasks | TaskList, TaskGet, TaskUpdate | +| Phase 2: Context Loading | Load necessary context for work | Read plan/config, detect framework | +| Phase 3: Core Work | Execute primary responsibility | Role-specific logic | +| Phase 4: Validation/Summary | Verify work quality | Syntax check, criteria verification | +| Phase 5: Report + Loop | Report to coordinator, check next | SendMessage, TaskUpdate, TaskList | + +### Phase Structure Template + +```markdown +### Phase N: + +\`\`\`javascript +// Implementation code +\`\`\` +``` + +--- + +## Pattern 5: Complexity-Adaptive Routing + +All roles that process varying-difficulty tasks should implement adaptive routing. + +### Decision Logic + +```javascript +function assessComplexity(description) { + let score = 0 + if (/refactor|architect|restructure|module|system/.test(description)) score += 2 + if (/multiple|across|cross/.test(description)) score += 2 + if (/integrate|api|database/.test(description)) score += 1 + if (/security|performance/.test(description)) score += 1 + return score >= 4 ? 'High' : score >= 2 ? 'Medium' : 'Low' +} +``` + +### Routing Table + +| Complexity | Direct Claude | CLI Agent | Sub-agent | +|------------|---------------|-----------|-----------| +| Low | Direct execution | - | - | +| Medium | - | `cli-explore-agent` / `cli-lite-planning-agent` | - | +| High | - | CLI agent | `code-developer` / `universal-executor` | + +### Sub-agent Delegation Pattern + +```javascript +Task({ + subagent_type: "", + run_in_background: false, + description: "", + prompt: ` +## Task Objective +${taskDescription} + +## Output Location +${sessionFolder}/${outputFile} + +## MANDATORY FIRST STEPS +1. Read: .workflow/project-tech.json (if exists) +2. Read: .workflow/project-guidelines.json (if exists) + +## Expected Output +${expectedFormat} +` +}) +``` + +--- + +## Pattern 6: Coordinator Spawn Integration + +New teammates must be spawnable from coordinate.md using standard pattern. + +### Skill Path Format (Folder-Based) + +Team commands use folder-based organization with colon-separated skill paths: + +``` +File location: .claude/commands/team/{team-name}/{role-name}.md +Skill path: team:{team-name}:{role-name} + +Example: + .claude/commands/team/spec/analyst.md → team:spec:analyst + .claude/commands/team/security/scanner.md → team:security:scanner +``` + +### Spawn Template + +```javascript +Task({ + subagent_type: "general-purpose", + team_name: teamName, + name: "", + prompt: `You are team "${teamName}" . + +When you receive -* tasks, call Skill(skill="team:${teamName}:") to execute. + +Current requirement: ${taskDescription} +Constraints: ${constraints} + +## Message Bus (Required) +Before each SendMessage, call mcp__ccw-tools__team_msg: +mcp__ccw-tools__team_msg({ operation: "log", team: "${teamName}", from: "", to: "coordinator", type: "", summary: "" }) + +Workflow: +1. TaskList -> find -* tasks assigned to you +2. Skill(skill="team:${teamName}:") to execute +3. team_msg log + SendMessage results to coordinator +4. TaskUpdate completed -> check next task` +}) +``` + +--- + +## Pattern 7: Error Handling Table + +Every command ends with a standardized error handling table. + +### Template + +```markdown +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| No tasks available | Idle, wait for coordinator assignment | +| Plan/Context file not found | Notify coordinator, request location | +| Sub-agent failure | Retry once, then fallback to direct execution | +| Max iterations exceeded | Report to coordinator, suggest intervention | +| Critical issue beyond scope | SendMessage fix_required to coordinator | +``` + +--- + +## Pattern 8: Session File Structure + +Roles that produce artifacts follow standard session directory patterns. + +### Convention + +``` +.workflow/.team-/{identifier}-{YYYY-MM-DD}/ +├── +├── manifest.json (if multiple outputs) +└── .task/ (if generating task files) + ├── TASK-001.json + └── TASK-002.json +``` + +--- + +# Section B: Collaboration Patterns + +> Complete specification: [collaboration-patterns.md](collaboration-patterns.md) + +## Collaboration Pattern Quick Reference + +Every collaboration pattern has these standard elements: + +| Element | Description | +|---------|-------------| +| **Entry Condition** | When to activate this pattern | +| **Workflow** | Step-by-step execution flow | +| **Convergence Criteria** | How the pattern terminates successfully | +| **Feedback Loop** | How information flows back to enable correction | +| **Timeout/Fallback** | What happens when the pattern doesn't converge | +| **Max Iterations** | Hard limit on cycles (where applicable) | + +### Pattern Selection Guide + +| Scenario | Recommended Pattern | Why | +|----------|-------------------|-----| +| Standard feature development | CP-1: Linear Pipeline | Well-defined sequential stages | +| Code review with fixes needed | CP-2: Review-Fix Cycle | Iterative improvement until quality met | +| Multi-angle analysis needed | CP-3: Fan-out/Fan-in | Parallel exploration, aggregated results | +| Critical decision (architecture, security) | CP-4: Consensus Gate | Multiple perspectives before committing | +| Agent stuck / self-repair failed | CP-5: Escalation Chain | Progressive expertise levels | +| Large feature (many files) | CP-6: Incremental Delivery | Validated increments reduce risk | +| Blocking issue stalls pipeline | CP-7: Swarming | All resources on one problem | +| Domain-specific expertise needed | CP-8: Consulting | Expert advice without role change | +| Design + Implementation parallel | CP-9: Dual-Track | Faster delivery with sync checkpoints | +| Post-completion learning | CP-10: Post-Mortem | Capture insights for future improvement | + +--- + +## Pattern Summary Checklist + +When designing a new team command, verify: + +### Infrastructure Patterns +- [ ] YAML front matter with `group: team` +- [ ] Message bus section with `team_msg` logging +- [ ] CLI fallback section with `ccw team` CLI examples and parameter mapping +- [ ] Role-specific message types defined +- [ ] Task lifecycle: TaskList -> TaskGet -> TaskUpdate flow +- [ ] Unique task prefix (no collision with existing PLAN/IMPL/TEST/REVIEW, scan `team/**/*.md`) +- [ ] 5-phase execution structure +- [ ] Complexity-adaptive routing (if applicable) +- [ ] Coordinator spawn template integration +- [ ] Error handling table +- [ ] SendMessage communication to coordinator only +- [ ] Session file structure (if producing artifacts) + +### Collaboration Patterns +- [ ] At least one collaboration pattern selected +- [ ] Convergence criteria defined (max iterations / quality gate / timeout) +- [ ] Feedback loop implemented (how results flow back) +- [ ] Timeout/fallback behavior specified +- [ ] Pattern-specific message types registered +- [ ] Coordinator aware of pattern (can route messages accordingly) diff --git a/.claude/skills/workflow-plan/phases/01-session-discovery.md b/.claude/skills/workflow-plan/phases/01-session-discovery.md new file mode 100644 index 00000000..87fa2b53 --- /dev/null +++ b/.claude/skills/workflow-plan/phases/01-session-discovery.md @@ -0,0 +1,99 @@ +# Phase 1: Session Discovery + +Create or discover workflow session and initialize planning notes document. + +## Objective + +- Create a new workflow session via `/workflow:session:start` +- Extract session ID for subsequent phases +- Initialize planning-notes.md with user intent and N+1 context structure + +## Execution + +### Step 1.1: Execute Session Start + +```javascript +Skill(skill="workflow:session:start", args="--auto \"[structured-task-description]\"") +``` + +**Task Description Structure**: +``` +GOAL: [Clear, concise objective] +SCOPE: [What's included/excluded] +CONTEXT: [Relevant background or constraints] +``` + +**Example**: +``` +GOAL: Build JWT-based authentication system +SCOPE: User registration, login, token validation +CONTEXT: Existing user database schema, REST API endpoints +``` + +### Step 1.2: Parse Output + +- Extract: `SESSION_ID: WFS-[id]` (store as `sessionId`) + +**Validation**: +- Session ID successfully extracted +- Session directory `.workflow/active/[sessionId]/` exists + +**Note**: Session directory contains `workflow-session.json` (metadata). Do NOT look for `manifest.json` here - it only exists in `.workflow/archives/` for archived sessions. + +**TodoWrite**: Mark phase 1 completed, phase 2 in_progress + +### Step 1.3: Initialize Planning Notes + +After Phase 1, initialize planning-notes.md with user intent: + +```javascript +// Create planning notes document with N+1 context support +const planningNotesPath = `.workflow/active/${sessionId}/planning-notes.md` +const userGoal = structuredDescription.goal +const userConstraints = structuredDescription.context || "None specified" + +Write(planningNotesPath, `# Planning Notes + +**Session**: ${sessionId} +**Created**: ${new Date().toISOString()} + +## User Intent (Phase 1) + +- **GOAL**: ${userGoal} +- **KEY_CONSTRAINTS**: ${userConstraints} + +--- + +## Context Findings (Phase 2) +(To be filled by context-gather) + +## Conflict Decisions (Phase 3) +(To be filled if conflicts detected) + +## Consolidated Constraints (Phase 4 Input) +1. ${userConstraints} + +--- + +## Task Generation (Phase 4) +(To be filled by action-planning-agent) + +## N+1 Context +### Decisions +| Decision | Rationale | Revisit? | +|----------|-----------|----------| + +### Deferred +- [ ] (For N+1) +`) +``` + +## Output + +- **Variable**: `sessionId` (WFS-xxx) +- **File**: `.workflow/active/[sessionId]/planning-notes.md` +- **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress + +## Next Phase + +Return to orchestrator, then auto-continue to [Phase 2: Context Gathering](02-context-gathering.md). diff --git a/.claude/skills/workflow-plan/phases/02-context-gathering.md b/.claude/skills/workflow-plan/phases/02-context-gathering.md new file mode 100644 index 00000000..47d7e8a3 --- /dev/null +++ b/.claude/skills/workflow-plan/phases/02-context-gathering.md @@ -0,0 +1,105 @@ +# Phase 2: Context Gathering + +Gather project context and analyze codebase via context-gather tool. + +## Objective + +- Gather project context using context-search-agent +- Identify critical files, architecture patterns, and constraints +- Detect conflict risk level for Phase 3 decision +- Update planning-notes.md with findings + +## Execution + +### Step 2.1: Execute Context Gathering + +```javascript +Skill(skill="workflow:tools:context-gather", args="--session [sessionId] \"[structured-task-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 +- `prioritized_context` field exists + +### TodoWrite Update (Phase 2 Skill executed - tasks attached) + +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Phase 2: Context Gathering", "status": "in_progress", "activeForm": "Executing context gathering"}, + {"content": " → Analyze codebase structure", "status": "in_progress", "activeForm": "Analyzing codebase structure"}, + {"content": " → Identify integration points", "status": "pending", "activeForm": "Identifying integration points"}, + {"content": " → Generate context package", "status": "pending", "activeForm": "Generating context package"}, + {"content": "Phase 4: Task Generation", "status": "pending", "activeForm": "Executing task generation"} +] +``` + +**Note**: Skill execute **attaches** context-gather's 3 tasks. Orchestrator **executes** these tasks sequentially. + +### TodoWrite Update (Phase 2 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 4: Task Generation", "status": "pending", "activeForm": "Executing task generation"} +] +``` + +**Note**: Phase 2 tasks completed and collapsed to summary. + +### Step 2.2: Update Planning Notes + +After context gathering completes, update planning-notes.md with findings: + +```javascript +// Read context-package to extract key findings +const contextPackage = JSON.parse(Read(contextPath)) +const conflictRisk = contextPackage.conflict_detection?.risk_level || 'low' +const criticalFiles = (contextPackage.exploration_results?.aggregated_insights?.critical_files || []) + .slice(0, 5).map(f => f.path) +const archPatterns = contextPackage.project_context?.architecture_patterns || [] +const constraints = contextPackage.exploration_results?.aggregated_insights?.constraints || [] + +// Append Phase 2 findings to planning-notes.md +Edit(planningNotesPath, { + old: '## Context Findings (Phase 2)\n(To be filled by context-gather)', + new: `## Context Findings (Phase 2) + +- **CRITICAL_FILES**: ${criticalFiles.join(', ') || 'None identified'} +- **ARCHITECTURE**: ${archPatterns.join(', ') || 'Not detected'} +- **CONFLICT_RISK**: ${conflictRisk} +- **CONSTRAINTS**: ${constraints.length > 0 ? constraints.join('; ') : 'None'}` +}) + +// Append Phase 2 constraints to consolidated list +Edit(planningNotesPath, { + old: '## Consolidated Constraints (Phase 4 Input)', + new: `## Consolidated Constraints (Phase 4 Input) +${constraints.map((c, i) => `${i + 2}. [Context] ${c}`).join('\n')}` +}) +``` + +**Auto-Continue**: Return to user showing Phase 2 results, then auto-continue to Phase 3/4 (depending on `conflictRisk`). + +## Output + +- **Variable**: `contextPath` (path to context-package.json) +- **Variable**: `conflictRisk` (none/low/medium/high) +- **File**: `context-package.json` +- **TodoWrite**: Mark Phase 2 completed, determine Phase 3 or Phase 4 + +## Next Phase + +Return to orchestrator. Orchestrator checks `conflictRisk`: +- If `conflictRisk >= medium` → [Phase 3: Conflict Resolution](03-conflict-resolution.md) +- If `conflictRisk < medium` → [Phase 4: Task Generation](04-task-generation.md) diff --git a/.claude/skills/workflow-plan/phases/03-conflict-resolution.md b/.claude/skills/workflow-plan/phases/03-conflict-resolution.md new file mode 100644 index 00000000..8b0af401 --- /dev/null +++ b/.claude/skills/workflow-plan/phases/03-conflict-resolution.md @@ -0,0 +1,134 @@ +# Phase 3: Conflict Resolution + +Detect and resolve conflicts with CLI analysis. This phase is **conditional** - only executes when `conflict_risk >= medium`. + +## Objective + +- Detect conflicts between planned changes and existing codebase +- Present conflicts to user with resolution strategies +- Apply selected resolution strategies +- Update planning-notes.md with conflict decisions + +## Trigger Condition + +Only execute when context-package.json indicates `conflict_risk` is "medium" or "high". +If `conflict_risk` is "none" or "low", skip directly to Phase 4. + +## Execution + +### Step 3.1: Execute Conflict Resolution + +```javascript +Skill(skill="workflow:tools:conflict-resolution", args="--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) + +**Validation**: +- File `.workflow/active/[sessionId]/.process/conflict-resolution.json` exists (if executed) + +**Skip Behavior**: +- If conflict_risk is "none" or "low", skip directly to Phase 4 +- Display: "No significant conflicts detected, proceeding to task generation" + +### TodoWrite Update (Phase 3 Skill executed - 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: Conflict Resolution", "status": "in_progress", "activeForm": "Resolving conflicts"}, + {"content": " → Detect conflicts with CLI analysis", "status": "in_progress", "activeForm": "Detecting conflicts"}, + {"content": " → Present conflicts to user", "status": "pending", "activeForm": "Presenting conflicts"}, + {"content": " → Apply resolution strategies", "status": "pending", "activeForm": "Applying resolution strategies"}, + {"content": "Phase 4: Task Generation", "status": "pending", "activeForm": "Executing task generation"} +] +``` + +**Note**: Skill execute **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks 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: Conflict Resolution", "status": "completed", "activeForm": "Resolving conflicts"}, + {"content": "Phase 4: Task Generation", "status": "pending", "activeForm": "Executing task generation"} +] +``` + +**Note**: Phase 3 tasks completed and collapsed to summary. + +### Step 3.2: Update Planning Notes + +After conflict resolution completes (if executed), update planning-notes.md: + +```javascript +// If Phase 3 was executed, update planning-notes.md +if (conflictRisk === 'medium' || conflictRisk === 'high') { + const conflictResPath = `.workflow/active/${sessionId}/.process/conflict-resolution.json` + + if (fs.existsSync(conflictResPath)) { + const conflictRes = JSON.parse(Read(conflictResPath)) + const resolved = conflictRes.resolved_conflicts || [] + const modifiedArtifacts = conflictRes.modified_artifacts || [] + const planningConstraints = conflictRes.planning_constraints || [] + + // Update Phase 3 section + Edit(planningNotesPath, { + old: '## Conflict Decisions (Phase 3)\n(To be filled if conflicts detected)', + new: `## Conflict Decisions (Phase 3) + +- **RESOLVED**: ${resolved.map(r => `${r.type} → ${r.strategy}`).join('; ') || 'None'} +- **MODIFIED_ARTIFACTS**: ${modifiedArtifacts.join(', ') || 'None'} +- **CONSTRAINTS**: ${planningConstraints.join('; ') || 'None'}` + }) + + // Append Phase 3 constraints to consolidated list + if (planningConstraints.length > 0) { + const currentNotes = Read(planningNotesPath) + const constraintCount = (currentNotes.match(/^\d+\./gm) || []).length + + Edit(planningNotesPath, { + old: '## Consolidated Constraints (Phase 4 Input)', + new: `## Consolidated Constraints (Phase 4 Input) +${planningConstraints.map((c, i) => `${constraintCount + i + 1}. [Conflict] ${c}`).join('\n')}` + }) + } + } +} +``` + +**Auto-Continue**: Return to user showing conflict resolution results and selected strategies, then auto-continue. + +**Auto Mode (--yes)**: When `--yes` flag is active, conflict-resolution sub-command automatically applies recommended resolution strategies without user confirmation. The orchestrator passes the `--yes` flag through to `workflow:tools:conflict-resolution`. + +### Step 3.3: Memory State Check + +Evaluate current context window usage and memory state: + +- If memory usage is high (>120K tokens or approaching context limits): + +```javascript +Skill(skill="compact") +``` + +- Memory compaction is particularly important after analysis phase which may generate extensive documentation +- Ensures optimal performance and prevents context overflow + +## Output + +- **File**: `conflict-resolution.json` (if conflicts resolved) +- **TodoWrite**: Mark Phase 3 completed, Phase 4 in_progress + +## Next Phase + +Return to orchestrator, then auto-continue to [Phase 4: Task Generation](04-task-generation.md). diff --git a/.claude/skills/workflow-plan/phases/06-replan.md b/.claude/skills/workflow-plan/phases/06-replan.md new file mode 100644 index 00000000..24b615d9 --- /dev/null +++ b/.claude/skills/workflow-plan/phases/06-replan.md @@ -0,0 +1,603 @@ +# Phase 6: Interactive Replan + +Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning. + +## Objective + +- Intelligently replan workflow sessions or individual tasks +- Interactive clarification to define modification boundaries +- Impact analysis with automatic detection of affected files and dependencies +- Backup management with restore capability +- Comprehensive artifact updates (IMPL_PLAN.md, TODO_LIST.md, task JSONs) + +## Entry Point + +Triggered via `/workflow:replan` (Replan Mode). + +## Operation Modes + +### Session Replan Mode + +```bash +# Auto-detect active session +/workflow:replan "requirements text" + +# Explicit session +/workflow:replan --session WFS-oauth "requirements text" + +# File-based input +/workflow:replan --session WFS-oauth requirements-update.md + +# Interactive mode +/workflow:replan --interactive +``` + +### Task Replan Mode + +```bash +# Direct task update +/workflow:replan IMPL-1 "requirements text" + +# Task with explicit session +/workflow:replan --session WFS-oauth IMPL-2 "requirements text" + +# Interactive mode +/workflow:replan IMPL-1 --interactive +``` + +## Language Convention + +Interactive question options use Chinese (user-facing UI text) with English identifiers in parentheses. Structural content uses English. This is intentional for Chinese-language workflows. + +## Execution + +### Input Parsing + +**Parse flags**: +```javascript +const sessionFlag = $ARGUMENTS.match(/--session\s+(\S+)/)?.[1] +const interactive = $ARGUMENTS.includes('--interactive') +const taskIdMatch = $ARGUMENTS.match(/\b(IMPL-\d+(?:\.\d+)?)\b/) +const taskId = taskIdMatch?.[1] +``` + +### Step 6.1: Mode Detection & Session Discovery + +**Process**: +1. **Detect Operation Mode**: + - Check if task ID provided (IMPL-N or IMPL-N.M format) → Task mode + - Otherwise → Session mode + +2. **Discover/Validate Session**: + - Use `--session` flag if provided + - Otherwise auto-detect from `.workflow/active/` + - Validate session exists + +3. **Load Session Context**: + - Read `workflow-session.json` + - List existing tasks + - Read `IMPL_PLAN.md` and `TODO_LIST.md` + +4. **Parse Execution Intent** (from requirements text): + ```javascript + // Dynamic tool detection from cli-tools.json + // Read enabled tools: ["gemini", "qwen", "codex", ...] + const enabledTools = loadEnabledToolsFromConfig(); // See ~/.claude/cli-tools.json + + // Build dynamic patterns from enabled tools + function buildExecPatterns(tools) { + const patterns = { + agent: /改为\s*Agent\s*执行|使用\s*Agent\s*执行/i + }; + tools.forEach(tool => { + // Pattern: "使用 {tool} 执行" or "改用 {tool}" + patterns[`cli_${tool}`] = new RegExp( + `使用\\s*(${tool})\\s*执行|改用\\s*(${tool})`, 'i' + ); + }); + return patterns; + } + + const execPatterns = buildExecPatterns(enabledTools); + + let executionIntent = null + for (const [key, pattern] of Object.entries(execPatterns)) { + if (pattern.test(requirements)) { + executionIntent = key.startsWith('cli_') + ? { method: 'cli', cli_tool: key.replace('cli_', '') } + : { method: 'agent', cli_tool: null } + break + } + } + ``` + +**Output**: Session validated, context loaded, mode determined, **executionIntent parsed** + +--- + +### Auto Mode Support + +When `--yes` or `-y` flag is used, the command skips interactive clarification and uses safe defaults: + +```javascript +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +``` + +**Auto Mode Defaults**: +- **Modification Scope**: `tasks_only` (safest - only update task details) +- **Affected Modules**: All modules related to the task +- **Task Changes**: `update_only` (no structural changes) +- **Dependency Changes**: `no` (preserve existing dependencies) +- **User Confirmation**: Auto-confirm execution + +**Note**: `--interactive` flag overrides `--yes` flag (forces interactive mode). + +--- + +### Step 6.2: Interactive Requirement Clarification + +**Purpose**: Define modification scope through guided questioning + +**Auto Mode Check**: +```javascript +if (autoYes && !interactive) { + // Use defaults and skip to Step 6.3 + console.log(`[--yes] Using safe defaults for replan:`) + console.log(` - Scope: tasks_only`) + console.log(` - Changes: update_only`) + console.log(` - Dependencies: preserve existing`) + + userSelections = { + scope: 'tasks_only', + modules: 'all_affected', + task_changes: 'update_only', + dependency_changes: false + } + // Proceed to Step 6.3 +} +``` + +#### Session Mode Questions + +**Q1: Modification Scope** +```javascript +Options: +- 仅更新任务细节 (tasks_only) +- 修改规划方案 (plan_update) +- 重构任务结构 (task_restructure) +- 全面重规划 (comprehensive) +``` + +**Q2: Affected Modules** (if scope >= plan_update) +```javascript +Options: Dynamically generated from existing tasks' focus_paths +- 认证模块 (src/auth) +- 用户管理 (src/user) +- 全部模块 +``` + +**Q3: Task Changes** (if scope >= task_restructure) +```javascript +Options: +- 添加/删除任务 (add_remove) +- 合并/拆分任务 (merge_split) +- 仅更新内容 (update_only) +// Note: Max 4 options for AskUserQuestion +``` + +**Q4: Dependency Changes** +```javascript +Options: +- 是,需要重新梳理依赖 +- 否,保持现有依赖 +``` + +#### Task Mode Questions + +**Q1: Update Type** +```javascript +Options: +- 需求和验收标准 (requirements & acceptance) +- 实现方案 (implementation_approach) +- 文件范围 (focus_paths) +- 依赖关系 (depends_on) +- 全部更新 +``` + +**Q2: Ripple Effect** +```javascript +Options: +- 是,需要同步更新依赖任务 +- 否,仅影响当前任务 +- 不确定,请帮我分析 +``` + +**Output**: User selections stored, modification boundaries defined + +--- + +### Step 6.3: Impact Analysis & Planning + +**Step 6.3.1: Analyze Required Changes** + +Determine affected files based on clarification: + +```typescript +interface ImpactAnalysis { + affected_files: { + impl_plan: boolean; + todo_list: boolean; + session_meta: boolean; + tasks: string[]; + }; + + operations: { + type: 'create' | 'update' | 'delete' | 'merge' | 'split'; + target: string; + reason: string; + }[]; + + backup_strategy: { + timestamp: string; + files: string[]; + }; +} +``` + +**Step 6.3.2: Generate Modification Plan** + +```markdown +## Modification Plan + +### Impact Scope +- [ ] IMPL_PLAN.md: Update technical section 3 +- [ ] TODO_LIST.md: Add 2 new tasks, delete 1 obsolete task +- [ ] IMPL-001.json: Update implementation approach +- [ ] workflow-session.json: Update task count + +### Change Operations +1. **Create**: IMPL-004.json (2FA implementation) +2. **Update**: IMPL-001.json (add 2FA preparation) +3. **Delete**: IMPL-003.json (replaced by new approach) +``` + +**Step 6.3.3: User Confirmation** + +```javascript +// Parse --yes flag +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +if (autoYes) { + // Auto mode: Auto-confirm execution + console.log(`[--yes] Auto-confirming replan execution`) + userConfirmation = 'confirm' + // Proceed to Step 6.4 +} else { + // Interactive mode: Ask user + AskUserQuestion({ + questions: [{ + question: "Modification plan generated. Confirm action:", + header: "Confirm", + options: [ + { label: "Confirm Execute", description: "Apply all modifications" }, + { label: "Adjust Plan", description: "Re-answer questions to adjust scope" }, + { label: "Cancel", description: "Abort this replan" } + ], + multiSelect: false + }] + }) +} +``` + +**Output**: Modification plan confirmed or adjusted + +--- + +### Step 6.4: Backup Creation + +**Process**: + +1. **Create Backup Directory**: +```bash +timestamp=$(date -u +"%Y-%m-%dT%H-%M-%S") +backup_dir=".workflow/active/$SESSION_ID/.process/backup/replan-$timestamp" +mkdir -p "$backup_dir" +``` + +2. **Backup All Affected Files**: + - IMPL_PLAN.md + - TODO_LIST.md + - workflow-session.json + - Affected task JSONs + +3. **Create Backup Manifest**: +```markdown +# Replan Backup Manifest + +**Timestamp**: {timestamp} +**Reason**: {replan_reason} +**Scope**: {modification_scope} + +## Restoration Command +cp {backup_dir}/* .workflow/active/{session}/ +``` + +**Output**: All files safely backed up with manifest + +--- + +### Step 6.5: Apply Modifications + +**Step 6.5.1: Update IMPL_PLAN.md** (if needed) + +Use Edit tool to modify specific sections: +- Update affected technical sections +- Update modification date + +**Step 6.5.2: Update TODO_LIST.md** (if needed) + +- Add new tasks with `[ ]` checkbox +- Mark deleted tasks as `[x] ~~task~~ (obsolete)` +- Update modified task descriptions + +**Step 6.5.3: Update Task JSONs** + +For each affected task: +```typescript +const updated_task = { + ...task, + context: { + ...task.context, + requirements: [...updated_requirements], + acceptance: [...updated_acceptance] + }, + flow_control: { + ...task.flow_control, + implementation_approach: [...updated_steps] + }, + // Update execution config if intent detected + ...(executionIntent && { + meta: { + ...task.meta, + execution_config: { + method: executionIntent.method, + cli_tool: executionIntent.cli_tool, + enable_resume: executionIntent.method !== 'agent' + } + } + }) +}; + +Write({ + file_path: `.workflow/active/${SESSION_ID}/.task/${task_id}.json`, + content: JSON.stringify(updated_task, null, 2) +}); +``` + +**Note**: Implementation approach steps are NO LONGER modified. CLI execution is controlled by task-level `meta.execution_config` only. + +**Step 6.5.4: Create New Tasks** (if needed) + +Generate complete task JSON with all required fields: +- id, title, status +- meta (type, agent) +- context (requirements, focus_paths, acceptance) +- flow_control (pre_analysis, implementation_approach, target_files) + +**Step 6.5.5: Delete Obsolete Tasks** (if needed) + +Move to backup instead of hard delete: +```bash +mv ".workflow/active/$SESSION_ID/.task/{task-id}.json" "$backup_dir/" +``` + +**Step 6.5.6: Update Session Metadata** + +Update workflow-session.json: +- progress.current_tasks +- progress.last_replan +- replan_history array + +**Output**: All modifications applied, artifacts updated + +--- + +### Step 6.6: Verification & Summary + +**Step 6.6.1: Verify Consistency** + +1. Validate all task JSONs are valid JSON +2. Check task count within limits (max 10) +3. Verify dependency graph is acyclic + +**Step 6.6.2: Generate Change Summary** + +```markdown +## Replan Complete + +### Session Info +- **Session**: {session-id} +- **Timestamp**: {timestamp} +- **Backup**: {backup-path} + +### Change Summary +**Scope**: {scope} +**Reason**: {reason} + +### Modified Files +- IMPL_PLAN.md: {changes} +- TODO_LIST.md: {changes} +- Task JSONs: {count} files updated + +### Task Changes +- **Added**: {task-ids} +- **Deleted**: {task-ids} +- **Updated**: {task-ids} + +### Rollback +cp {backup-path}/* .workflow/active/{session}/ +``` + +**Output**: Summary displayed, replan complete + +## TodoWrite Progress Tracking + +### Session Mode Progress + +```json +[ + {"content": "Mode detection and session discovery", "status": "completed", "activeForm": "Detecting mode and discovering session"}, + {"content": "Interactive requirement clarification", "status": "completed", "activeForm": "Clarifying requirements interactively"}, + {"content": "Impact analysis and plan generation", "status": "completed", "activeForm": "Analyzing impact and generating plan"}, + {"content": "Backup creation", "status": "completed", "activeForm": "Creating backup"}, + {"content": "Apply modifications to artifacts", "status": "completed", "activeForm": "Applying modifications"}, + {"content": "Verify consistency", "status": "completed", "activeForm": "Verifying consistency"} +] +``` + +### Task Mode Progress + +```json +[ + {"content": "Detect session and load task", "status": "completed", "activeForm": "Detecting session and loading task"}, + {"content": "Interactive update confirmation", "status": "completed", "activeForm": "Confirming update interactively"}, + {"content": "Apply task modifications", "status": "completed", "activeForm": "Applying task modifications"} +] +``` + +## Error Handling + +### Session Errors + +```bash +# No active session found +ERROR: No active session found +Run /workflow:session:start to create a session + +# Session not found +ERROR: Session WFS-invalid not found +Available sessions: [list] + +# No changes specified +WARNING: No modifications specified +Use --interactive mode or provide requirements +``` + +### Task Errors + +```bash +# Task not found +ERROR: Task IMPL-999 not found in session +Available tasks: [list] + +# Task completed +WARNING: Task IMPL-001 is completed +Consider creating new task for additional work + +# Circular dependency +ERROR: Circular dependency detected +Resolve dependency conflicts before proceeding +``` + +### Validation Errors + +```bash +# Task limit exceeded +ERROR: Replan would create 12 tasks (limit: 10) +Consider: combining tasks, splitting sessions, or removing tasks + +# Invalid JSON +ERROR: Generated invalid JSON +Backup preserved, rolling back changes +``` + +## File Structure + +``` +.workflow/active/WFS-session-name/ +├── workflow-session.json +├── IMPL_PLAN.md +├── TODO_LIST.md +├── .task/ +│ ├── IMPL-001.json +│ ├── IMPL-002.json +│ └── IMPL-003.json +└── .process/ + ├── context-package.json + └── backup/ + └── replan-{timestamp}/ + ├── MANIFEST.md + ├── IMPL_PLAN.md + ├── TODO_LIST.md + ├── workflow-session.json + └── IMPL-*.json +``` + +## Examples + +### Session Replan - Add Feature + +```bash +/workflow:replan "Add 2FA support" + +# Interactive clarification +Q: Modification scope? +A: Comprehensive replan + +Q: Affected modules? +A: Auth module, API endpoints + +Q: Task changes? +A: Add new tasks, update content + +# Execution +Backup created +IMPL_PLAN.md updated +TODO_LIST.md updated +IMPL-004.json created +IMPL-001.json, IMPL-002.json updated + +Replan complete! Added 1 task, updated 2 tasks +``` + +### Task Replan - Update Requirements + +```bash +/workflow:replan IMPL-002 "Update acceptance criteria to include rate limiting" + +# Interactive clarification +Q: Update type? +A: Requirements and acceptance criteria + +Q: Ripple effect? +A: Yes, sync dependent tasks + +# Execution +Backup created +IMPL-002.json updated + - context.requirements updated + - context.acceptance updated +IMPL-003.json updated (dependent task synced) + +Task requirements updated with ripple effect applied +``` + +### Task Replan - Change Execution Method + +```bash +/workflow:replan IMPL-001 "Use Codex for execution" + +# Semantic parsing detects executionIntent: +# { method: 'cli', cli_tool: 'codex' } + +# Execution (no interactive questions needed) +Backup created +IMPL-001.json updated + - meta.execution_config = { method: 'cli', cli_tool: 'codex', enable_resume: true } + +Task execution method updated: Agent → CLI (codex) +``` + +## Completion + +Phase 6 is a terminal phase. Replan complete with backup and summary. diff --git a/.claude/skills/workflow-tdd-plan/SKILL.md b/.claude/skills/workflow-tdd-plan/SKILL.md deleted file mode 100644 index 082caa9e..00000000 --- a/.claude/skills/workflow-tdd-plan/SKILL.md +++ /dev/null @@ -1,747 +0,0 @@ ---- -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 deleted file mode 100644 index d07a49b8..00000000 --- a/.claude/skills/workflow-tdd-plan/phases/01-test-context-gather.md +++ /dev/null @@ -1,213 +0,0 @@ -# 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 deleted file mode 100644 index 7f18d6ff..00000000 --- a/.claude/skills/workflow-tdd-plan/phases/02-task-generate-tdd.md +++ /dev/null @@ -1,746 +0,0 @@ -## 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**: \`~/.ccw/workflows/cli-templates/prompts/workflow/impl-plan-template.txt\` -- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown -- **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles -- **Context Analysis**: Artifact references and exploration insights -- **Details**: See action-planning-agent.md § TDD Implementation Plan Creation - -##### 3. TODO_LIST.md -- **Location**: \`.workflow/active/{session-id}/TODO_LIST.md\` -- **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor) -- **Status**: ▸ (container), [ ] (pending), [x] (completed) -- **Links**: Task JSON references and summaries -- **Details**: See action-planning-agent.md § TODO List Generation - -### CLI EXECUTION ID REQUIREMENTS (MANDATORY) - -Each task JSON MUST include: -- **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 deleted file mode 100644 index e27c9a93..00000000 --- a/.claude/skills/workflow-tdd-plan/phases/03-tdd-verify.md +++ /dev/null @@ -1,575 +0,0 @@ -# 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 deleted file mode 100644 index bc1a28da..00000000 --- a/.claude/skills/workflow-tdd-plan/phases/04-tdd-coverage-analysis.md +++ /dev/null @@ -1,287 +0,0 @@ -# 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/agents/issue-plan-agent.md b/.codex/agents/issue-plan-agent.md index 8a447458..6aa853fb 100644 --- a/.codex/agents/issue-plan-agent.md +++ b/.codex/agents/issue-plan-agent.md @@ -226,13 +226,13 @@ function decomposeTasks(issue, exploration) { scope: inferScope(group), // Module path action: inferAction(group), // Create | Update | Implement | ... description: group.description, - modification_points: mapModificationPoints(group), + files: mapFiles(group), // [{path, target, change, action?, conflict_risk?}] implementation: generateSteps(group), // Step-by-step guide test: { unit: generateUnitTests(group), commands: ['npm test'] }, - acceptance: { + convergence: { criteria: generateCriteria(group), // Quantified checklist verification: generateVerification(group) }, @@ -242,7 +242,7 @@ function decomposeTasks(issue, exploration) { message_template: generateCommitMsg(group) }, depends_on: inferDependencies(group, tasks), - priority: calculatePriority(group) // 1-5 (1=highest) + priority: calculatePriorityEnum(group) // "critical"|"high"|"medium"|"low" })); // GitHub Reply Task: Add final task if issue has github_url @@ -254,20 +254,20 @@ function decomposeTasks(issue, exploration) { scope: 'github', action: 'Notify', description: `Comment on GitHub issue to report completion status`, - modification_points: [], + files: [], implementation: [ `Generate completion summary (tasks completed, files changed)`, `Post comment via: gh issue comment ${issue.github_number || extractNumber(issue.github_url)} --body "..."`, `Include: solution approach, key changes, verification results` ], test: { unit: [], commands: [] }, - acceptance: { + convergence: { criteria: ['GitHub comment posted successfully', 'Comment includes completion summary'], verification: ['Check GitHub issue for new comment'] }, commit: null, // No commit for notification task depends_on: lastTaskId ? [lastTaskId] : [], // Depends on last implementation task - priority: 5 // Lowest priority (run last) + priority: "low" // Lowest priority (run last) }); } @@ -370,10 +370,10 @@ Each line is a solution JSON containing tasks. Schema: `cat ~/.ccw/workflows/cli ### 3.2 Validation Checklist - [ ] ACE search performed for each issue -- [ ] All modification_points verified against codebase +- [ ] All files[] paths verified against codebase - [ ] Tasks have 2+ implementation steps - [ ] All 5 lifecycle phases present -- [ ] Quantified acceptance criteria with verification +- [ ] Quantified convergence criteria with verification - [ ] Dependencies form valid DAG - [ ] Commit follows conventional commits @@ -389,7 +389,7 @@ Each line is a solution JSON containing tasks. Schema: `cat ~/.ccw/workflows/cli 4. Fetch issue details via `ccw issue status --json` 5. **Analyze failure history**: Check `issue.feedback` for type='failure', stage='execute' 6. **For replanning**: Reference previous failures in `solution.approach`, add prevention steps -7. Quantify acceptance.criteria with testable conditions +7. Quantify convergence.criteria with testable conditions 8. Validate DAG before output 9. Evaluate each solution with `analysis` and `score` 10. Write solutions to `.workflow/issues/solutions/{issue-id}.jsonl` (append mode) diff --git a/.codex/skills/workflow-brainstorm-auto-parallel/SKILL.md b/.codex/skills/workflow-brainstorm-auto-parallel/SKILL.md deleted file mode 100644 index 5045a579..00000000 --- a/.codex/skills/workflow-brainstorm-auto-parallel/SKILL.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -name: workflow-brainstorm-auto-parallel -description: Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives. Triggers on "workflow:brainstorm:auto-parallel". -allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep ---- - -# Workflow Brainstorm Auto-Parallel - -Parallel brainstorming automation orchestrating interactive framework generation, concurrent multi-role analysis, and synthesis integration to produce comprehensive guidance specifications. - -## Architecture Overview - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Auto-Parallel Orchestrator (SKILL.md) │ -│ → Pure coordinator: Execute phases, parse outputs, manage agents│ -└───────────────┬─────────────────────────────────────────────────┘ - │ - ┌───────────┼───────────┬───────────┐ - ↓ ↓ ↓ ↓ -┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ -│ Phase 0 │ │ Phase 1 │ │ Phase 2 │ │ Phase 3 │ -│ Parse │ │Framework│ │Parallel │ │Synthesis│ -│ Params │ │Generate │ │ Roles │ │Integrate│ -└─────────┘ └─────────┘ └─────────┘ └─────────┘ - ↓ ↓ ↓ ↓ - count, guidance- N role synthesis- -style-skill specification analyses specification -``` - -## Key Design Principles - -1. **Pure Orchestrator**: Execute phases in sequence (Phase 1, 3 sequential; Phase 2 parallel) -2. **Auto-Continue**: All phases run autonomously without user intervention between phases -3. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent -4. **Progressive Phase Loading**: Phase docs are read on-demand when phase executes -5. **Parallel Execution**: Phase 2 launches N role agents concurrently -6. **Role Path Loading**: Subagent roles loaded via path reference in MANDATORY FIRST STEPS - -## Auto Mode - -When `--yes` or `-y`: Auto-select recommended roles, skip all clarification questions, use default answers. - -## Execution Flow - -``` -Parameter Parsing: - ├─ Extract --count N (default: 3, max: 9) - ├─ Extract --style-skill package-name (optional, for ui-designer) - └─ Validate style SKILL package exists - -Phase 1: Interactive Framework Generation - └─ Ref: phases/01-interactive-framework.md - ├─ Sub-phases: Phase 0-5 (Context → Topic → Roles → Questions → Conflicts → Spec) - ├─ Output: guidance-specification.md + workflow-session.json - └─ Parse: selected_roles[], session_id - -Phase 2: Parallel Role Analysis - └─ Ref: phases/02-parallel-role-analysis.md - ├─ Spawn N conceptual-planning-agent (concurrent execution) - ├─ For each role: Execute framework-based analysis - ├─ Optional: ui-designer appends --style-skill if provided - ├─ Lifecycle: spawn_agent → batch wait → close_agent - └─ Output: [role]/analysis*.md (one per role) - -Phase 3: Synthesis Integration - └─ Ref: phases/03-synthesis-integration.md - ├─ Spawn cross-role analysis agent - ├─ User interaction: Enhancement selection + clarifications - ├─ Spawn parallel update agents (one per role) - ├─ Lifecycle: spawn_agent → wait → close_agent for each agent - └─ Output: synthesis-specification.md + updated analyses - -Return: - └─ Summary with session info and next steps -``` - -**Phase Reference Documents** (read on-demand when phase executes): - -| Phase | Document | Purpose | -|-------|----------|---------| -| 1 | [phases/01-interactive-framework.md](phases/01-interactive-framework.md) | Interactive clarification generating confirmed guidance specification through role-based analysis | -| 2 | [phases/02-parallel-role-analysis.md](phases/02-parallel-role-analysis.md) | Unified role-specific analysis generation with interactive context gathering and concurrent execution | -| 3 | [phases/03-synthesis-integration.md](phases/03-synthesis-integration.md) | Cross-role synthesis integration with intelligent Q&A and targeted updates | - -## Core Rules - -1. **Start Immediately**: First action is parameter parsing -2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis -3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1 -4. **Auto-Continue**: Execute next pending phase automatically after previous completes -5. **Track Progress**: Phase execution state managed through workflow-session.json -6. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After completing each phase, immediately proceed to next -7. **Parallel Execution**: Phase 2 spawns multiple agent tasks simultaneously for concurrent execution -8. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute -9. **Explicit Lifecycle**: Always close_agent after wait completes to free resources - -## Usage - -```bash -workflow:brainstorm:auto-parallel "" [--count N] [--style-skill package-name] -``` - -**Recommended Structured Format**: -```bash -workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N] [--style-skill package-name] -``` - -**Parameters**: -- `topic` (required): Topic or challenge description (structured format recommended) -- `--count N` (optional): Number of roles to select (default: 3, max: 9) -- `--style-skill package-name` (optional): Style SKILL package to load for ui-designer (located at `.codex/skills/style-{package-name}/`) - -## Data Flow - -### Phase 0 → Phase 1 - -**Input**: -- `topic`: User-provided topic or challenge description -- `count`: Number of roles to select (parsed from --count parameter) -- `style_skill_package`: Style SKILL package name (parsed from --style-skill parameter) - -**Output**: None (in-memory variables) - -### Phase 1 → Phase 2 - -**Input**: `topic`, `count`, `style_skill_package` - -**Output**: -- `session_id`: Workflow session identifier (WFS-{topic-slug}) -- `selected_roles[]`: Array of selected role names -- `guidance-specification.md`: Framework content -- `workflow-session.json`: Session metadata - -**Parsing**: -```javascript -// Read workflow-session.json after Phase 1 -const session_data = Read("${projectRoot}/.workflow/active/WFS-{topic}/workflow-session.json"); -const selected_roles = session_data.selected_roles; -const session_id = session_data.session_id; -const style_skill_package = session_data.style_skill_package || null; -``` - -### Phase 2 → Phase 3 - -**Input**: `session_id`, `selected_roles[]`, `style_skill_package` - -**Output**: -- `[role]/analysis*.md`: One analysis per selected role -- `.superdesign/design_iterations/`: UI design artifacts (if --style-skill provided) - -**Validation**: -```javascript -// Verify all role analyses created -for (const role of selected_roles) { - const analysis_path = `${brainstorm_dir}/${role}/analysis.md`; - if (!exists(analysis_path)) { - ERROR: `Missing analysis for ${role}`; - } -} -``` - -### Phase 3 → Completion - -**Input**: `session_id`, all role analyses, guidance-specification.md - -**Output**: -- `synthesis-specification.md`: Integrated cross-role analysis -- Updated `[role]/analysis*.md` with clarifications - -**Validation**: -```javascript -const synthesis_path = `${brainstorm_dir}/synthesis-specification.md`; -if (!exists(synthesis_path)) { - ERROR: "Synthesis generation failed"; -} -``` - -## 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: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.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 -} - -// Check completion status -if (result.status[agentId].completed) { - const output = result.status[agentId].completed; -} -``` - -### 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 analysis generation. -` -}) -``` - -### close_agent - -Clean up subagent resources (irreversible). - -```javascript -close_agent({ id: agentId }) -``` - -## Session Management - -**⚡ FIRST ACTION**: Check `{projectRoot}/.workflow/active/` for existing sessions before Phase 1 - -**Multiple Sessions Support**: -- Different Codex instances can have different brainstorming sessions -- If multiple sessions found, prompt user to select -- If single session found, use it -- If no session exists, create `WFS-[topic-slug]` - -**Session Continuity**: -- MUST use selected session for all phases -- Each role's context stored in session directory -- Session isolation: Each session maintains independent state - -## Output Structure - -**Phase 1 Output**: -- `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content) -- `{projectRoot}/.workflow/active/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package) - -**Phase 2 Output**: -- `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role) -- `.superdesign/design_iterations/` (ui-designer artifacts, if --style-skill provided) - -**Phase 3 Output**: -- `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis) -- Updated `[role]/analysis*.md` with Enhancements + Clarifications sections - -**⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication) -**⚠️ Style References**: When --style-skill provided, workflow-session.json stores style_skill_package name, ui-designer loads from `.codex/skills/style-{package-name}/` - -## Available Roles - -- data-architect (数据架构师) -- product-manager (产品经理) -- product-owner (产品负责人) -- scrum-master (敏捷教练) -- subject-matter-expert (领域专家) -- system-architect (系统架构师) -- test-strategist (测试策略师) -- ui-designer (UI 设计师) -- ux-expert (UX 专家) - -**Role Selection**: Handled by Phase 1 (artifacts) - intelligent recommendation + user selection - -## Error Handling - -- **Role selection failure**: Phase 1 defaults to product-manager with explanation -- **Agent execution failure**: Agent-specific retry with minimal dependencies -- **Template loading issues**: Agent handles graceful degradation -- **Synthesis conflicts**: Phase 3 highlights disagreements without resolution -- **Context overflow protection**: Per-role limits enforced by conceptual-planning-agent -- **Agent lifecycle errors**: Ensure close_agent in error paths to prevent resource leaks - -## Reference Information - -**File Structure**: -``` -{projectRoot}/.workflow/active/WFS-[topic]/ -├── workflow-session.json # Session metadata ONLY -└── .brainstorming/ - ├── guidance-specification.md # Framework (Phase 1) - ├── {role}/ - │ ├── analysis.md # Main document (with optional @references) - │ └── analysis-{slug}.md # Section documents (max 5) - └── synthesis-specification.md # Integration (Phase 3) -``` - -**Next Steps** (returned to user): -``` -Brainstorming complete for session: {sessionId} -Roles analyzed: {count} -Synthesis: {projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md - -✅ Next Steps: -1. workflow:plan --session {sessionId} # Generate implementation plan -``` diff --git a/.codex/skills/workflow-brainstorm-auto-parallel/phases/01-interactive-framework.md b/.codex/skills/workflow-brainstorm-auto-parallel/phases/01-interactive-framework.md deleted file mode 100644 index 57133384..00000000 --- a/.codex/skills/workflow-brainstorm-auto-parallel/phases/01-interactive-framework.md +++ /dev/null @@ -1,428 +0,0 @@ -## Overview - -Seven-phase workflow: **Context collection** → **Topic analysis** → **Role selection** → **Role questions** → **Conflict resolution** → **Final check** → **Generate specification** - -All user interactions use ASK_USER / CONFIRM pseudo-code (implemented via AskUserQuestion tool) (max 4 questions per call, multi-round). - -**Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]` -**Output**: `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` -**Core Principle**: Questions dynamically generated from project context + topic keywords, NOT generic templates - -**Parameters**: -- `topic` (required): Topic or challenge description (structured format recommended) -- `--count N` (optional): Number of roles to select (system recommends N+2 options, default: 3) - ---- - -## Quick Reference - -### Phase Summary - -| Phase | Goal | ASK_USER | Storage | -|-------|------|-----------------|---------| -| 0 | Context collection | - | context-package.json | -| 1 | Topic analysis | 2-4 questions | intent_context | -| 2 | Role selection | 1 multi-select | selected_roles | -| 3 | Role questions | 3-4 per role | role_decisions[role] | -| 4 | Conflict resolution | max 4 per round | cross_role_decisions | -| 4.5 | Final check | progressive rounds | additional_decisions | -| 5 | Generate spec | - | guidance-specification.md | - -### ASK_USER Pattern - -```javascript -// Single-select (Phase 1, 3, 4) -ASK_USER([ - { - id: "{短标签}", // max 12 chars - type: "select", - prompt: "{问题文本}", - options: [ - { label: "{选项}", description: "{说明和影响}" }, - { label: "{选项}", description: "{说明和影响}" }, - { label: "{选项}", description: "{说明和影响}" } - ] - } - // ... max 4 questions per call -]) // BLOCKS (wait for user response) - -// Multi-select (Phase 2) -ASK_USER([{ - id: "角色选择", type: "multi-select", - prompt: "请选择 {count} 个角色", - options: [/* max 4 options per call */] -}]) // BLOCKS (wait for user response) -``` - -### Multi-Round Execution - -```javascript -const BATCH_SIZE = 4; -for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) { - const batch = allQuestions.slice(i, i + BATCH_SIZE); - ASK_USER(batch); // BLOCKS (wait for user response) - // Store responses before next round -} -``` - ---- - -## Session Management - -- Check `{projectRoot}/.workflow/active/` for existing sessions -- Multiple → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]` -- Parse `--count N` parameter (default: 3) -- Store decisions in `workflow-session.json` - ---- - -## Execution Phases - -### Phase 0: Context Collection - -**Goal**: Gather project context BEFORE user interaction - -**Steps**: -1. Check if `context-package.json` exists → Skip if valid -2. Invoke `context-search-agent` (BRAINSTORM MODE - lightweight) -3. Output: `{projectRoot}/.workflow/active/WFS-{session-id}/.process/context-package.json` - -**Graceful Degradation**: If agent fails, continue to Phase 1 without context - -```javascript -// Spawn context-search-agent -const contextAgentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/context-search-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -## Task Objective -Execute context-search-agent in BRAINSTORM MODE (Phase 1-2 only). - -## Assigned Context -- **Session**: ${session_id} -- **Task**: ${task_description} -- **Output**: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json - -## Required Output Fields -metadata, project_context, assets, dependencies, conflict_detection -` -}); - -// Wait for completion -const contextResult = wait({ - ids: [contextAgentId], - timeout_ms: 300000 // 5 minutes -}); - -// Clean up agent -close_agent({ id: contextAgentId }); - -// Check result -if (contextResult.timed_out) { - console.warn("Context gathering timed out, continuing without context"); -} -``` - -### Phase 1: Topic Analysis - -**Goal**: Extract keywords/challenges enriched by Phase 0 context - -**Steps**: -1. Load Phase 0 context (tech_stack, modules, conflict_risk) -2. Deep topic analysis (entities, challenges, constraints, metrics) -3. Generate 2-4 context-aware probing questions -4. ASK_USER → Store to `session.intent_context` - -**Example**: -```javascript -ASK_USER([ - { - id: "核心挑战", type: "select", - prompt: "实时协作平台的主要技术挑战？", - options: [ - { label: "实时数据同步", description: "100+用户同时在线，状态同步复杂度高" }, - { label: "可扩展性架构", description: "用户规模增长时的系统扩展能力" }, - { label: "冲突解决机制", description: "多用户同时编辑的冲突处理策略" } - ] - }, - { - id: "优先级", type: "select", - prompt: "MVP阶段最关注的指标？", - options: [ - { label: "功能完整性", description: "实现所有核心功能" }, - { label: "用户体验", description: "流畅的交互体验和响应速度" }, - { label: "系统稳定性", description: "高可用性和数据一致性" } - ] - } -]) // BLOCKS (wait for user response) -``` - -**⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation. - -### Phase 2: Role Selection - -**Goal**: User selects roles from intelligent recommendations - -**Available Roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert - -**Steps**: -1. Analyze Phase 1 keywords → Recommend count+2 roles with rationale -2. ASK_USER (type=multi-select) → Store to `session.selected_roles` -3. If count+2 > 4, split into multiple rounds - -**Example**: -```javascript -ASK_USER([{ - id: "角色选择", type: "multi-select", - prompt: "请选择 3 个角色参与头脑风暴分析", - options: [ - { label: "system-architect", description: "实时同步架构设计和技术选型" }, - { label: "ui-designer", description: "协作界面用户体验和状态展示" }, - { label: "product-manager", description: "功能优先级和MVP范围决策" }, - { label: "data-architect", description: "数据同步模型和存储方案设计" } - ] -}]) // BLOCKS (wait for user response) -``` - -**⚠️ CRITICAL**: User MUST interact. NEVER auto-select without confirmation. - -### Phase 3: Role-Specific Questions - -**Goal**: Generate deep questions mapping role expertise to Phase 1 challenges - -**Algorithm**: -1. FOR each selected role: - - Map Phase 1 challenges to role domain - - Generate 3-4 questions (implementation depth, trade-offs, edge cases) - - ASK_USER per role → Store to `session.role_decisions[role]` -2. Process roles sequentially (one at a time for clarity) -3. If role needs > 4 questions, split into multiple rounds - -**Example** (system-architect): -```javascript -ASK_USER([ - { - id: "状态同步", type: "select", - prompt: "100+ 用户实时状态同步方案？", - options: [ - { label: "Event Sourcing", description: "完整事件历史，支持回溯，存储成本高" }, - { label: "集中式状态管理", description: "实现简单，单点瓶颈风险" }, - { label: "CRDT", description: "去中心化，自动合并，学习曲线陡" } - ] - }, - { - id: "冲突解决", type: "select", - prompt: "两个用户同时编辑冲突如何解决？", - options: [ - { label: "自动合并", description: "用户无感知，可能产生意外结果" }, - { label: "手动解决", description: "用户控制，增加交互复杂度" }, - { label: "版本控制", description: "保留历史，需要分支管理" } - ] - } -]) // BLOCKS (wait for user response) -``` - -### Phase 4: Conflict Resolution - -**Goal**: Resolve ACTUAL conflicts from Phase 3 answers - -**Algorithm**: -1. Analyze Phase 3 answers for conflicts: - - Contradictory choices (e.g., "fast iteration" vs "complex Event Sourcing") - - Missing integration (e.g., "Optimistic updates" but no conflict handling) - - Implicit dependencies (e.g., "Live cursors" but no auth defined) -2. Generate clarification questions referencing SPECIFIC Phase 3 choices -3. ASK_USER (max 4 per call, multi-round) → Store to `session.cross_role_decisions` -4. If NO conflicts: Skip Phase 4 (inform user: "未检测到跨角色冲突，跳过Phase 4") - -**Example**: -```javascript -ASK_USER([{ - id: "架构冲突", type: "select", - prompt: "CRDT 与 UI 回滚期望冲突，如何解决？\n背景：system-architect选择CRDT，ui-designer期望回滚UI", - options: [ - { label: "采用 CRDT", description: "保持去中心化，调整UI期望" }, - { label: "显示合并界面", description: "增加用户交互，展示冲突详情" }, - { label: "切换到 OT", description: "支持回滚，增加服务器复杂度" } - ] -}]) // BLOCKS (wait for user response) -``` - -### Phase 4.5: Final Clarification - -**Purpose**: Ensure no important points missed before generating specification - -**Steps**: -1. Ask initial check: - ```javascript - CONFIRM("在生成最终规范之前，是否有前面未澄清的重点需要补充？") // BLOCKS (wait for user response) - // Returns: "无需补充" (前面的讨论已经足够完整) | "需要补充" (还有重要内容需要澄清) - ``` -2. If "需要补充": - - Analyze user's additional points - - Generate progressive questions (not role-bound, interconnected) - - ASK_USER (max 4 per round) → Store to `session.additional_decisions` - - Repeat until user confirms completion -3. If "无需补充": Proceed to Phase 5 - -**Progressive Pattern**: Questions interconnected, each round informs next, continue until resolved. - -### Phase 5: Generate Specification - -**Steps**: -1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` + `additional_decisions` -2. Transform Q&A to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements -3. Generate `guidance-specification.md` -4. Update `workflow-session.json` (metadata only) -5. Validate: No interrogative sentences, all decisions traceable - ---- - -## Question Guidelines - -### Core Principle - -**Target**: 开发者（理解技术但需要从用户需求出发） - -**Question Structure**: `[业务场景/需求前提] + [技术关注点]` -**Option Structure**: `标签：[技术方案] + 说明：[业务影响] + [技术权衡]` - -### Quality Rules - -**MUST Include**: -- ✅ All questions in Chinese (用中文提问) -- ✅ 业务场景作为问题前提 -- ✅ 技术选项的业务影响说明 -- ✅ 量化指标和约束条件 - -**MUST Avoid**: -- ❌ 纯技术选型无业务上下文 -- ❌ 过度抽象的用户体验问题 -- ❌ 脱离话题的通用架构问题 - -### Phase-Specific Requirements - -| Phase | Focus | Key Requirements | -|-------|-------|------------------| -| 1 | 意图理解 | Reference topic keywords, 用户场景、业务约束、优先级 | -| 2 | 角色推荐 | Intelligent analysis (NOT keyword mapping), explain relevance | -| 3 | 角色问题 | Reference Phase 1 keywords, concrete options with trade-offs | -| 4 | 冲突解决 | Reference SPECIFIC Phase 3 choices, explain impact on both roles | - ---- - -## Output & Governance - -### Output Template - -**File**: `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` - -```markdown -# [Project] - Confirmed Guidance Specification - -**Metadata**: [timestamp, type, focus, roles] - -## 1. Project Positioning & Goals -**CONFIRMED Objectives**: [from topic + Phase 1] -**CONFIRMED Success Criteria**: [from Phase 1 answers] - -## 2-N. [Role] Decisions -### SELECTED Choices -**[Question topic]**: [User's answer] -- **Rationale**: [From option description] -- **Impact**: [Implications] - -### Cross-Role Considerations -**[Conflict resolved]**: [Resolution from Phase 4] -- **Affected Roles**: [Roles involved] - -## Cross-Role Integration -**CONFIRMED Integration Points**: [API/Data/Auth from multiple roles] - -## Risks & Constraints -**Identified Risks**: [From answers] → Mitigation: [Approach] - -## Next Steps -**⚠️ Automatic Continuation** (when called from auto-parallel): -- auto-parallel spawns agents for role-specific analysis -- Each selected role gets conceptual-planning-agent -- Agents read this guidance-specification.md for context - -## Appendix: Decision Tracking -| Decision ID | Category | Question | Selected | Phase | Rationale | -|-------------|----------|----------|----------|-------|-----------| -| D-001 | Intent | [Q] | [A] | 1 | [Why] | -| D-002 | Roles | [Selected] | [Roles] | 2 | [Why] | -| D-003+ | [Role] | [Q] | [A] | 3 | [Why] | -``` - -### File Structure - -``` -{projectRoot}/.workflow/active/WFS-[topic]/ -├── workflow-session.json # Metadata ONLY -├── .process/ -│ └── context-package.json # Phase 0 output -└── .brainstorming/ - └── guidance-specification.md # Full guidance content -``` - -### Session Metadata - -```json -{ - "session_id": "WFS-{topic-slug}", - "type": "brainstorming", - "topic": "{original user input}", - "selected_roles": ["system-architect", "ui-designer", "product-manager"], - "phase_completed": "artifacts", - "timestamp": "2025-10-24T10:30:00Z", - "count_parameter": 3 -} -``` - -**⚠️ Rule**: Session JSON stores ONLY metadata. All guidance content goes to guidance-specification.md. - -### Validation Checklist - -- ✅ No interrogative sentences (use CONFIRMED/SELECTED) -- ✅ Every decision traceable to user answer -- ✅ Cross-role conflicts resolved or documented -- ✅ Next steps concrete and specific -- ✅ No content duplication between .json and .md - -### Update Mechanism - -``` -IF guidance-specification.md EXISTS: - Prompt: "Regenerate completely / Update sections / Cancel" -ELSE: - Run full Phase 0-5 flow -``` - -### Governance Rules - -- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections) -- Every decision MUST trace to user answer -- Conflicts MUST be resolved (not marked "TBD") -- Next steps MUST be actionable -- Topic preserved as authoritative reference - -**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance. - ---- - -## Post-Phase Update - -After Phase 1 completes: -- **Output Created**: `guidance-specification.md`, `workflow-session.json` -- **Data Parsed**: `selected_roles[]`, `session_id` -- **Next Action**: Auto-continue to Phase 2 (parallel role analysis) -- **State Update**: Update workflow-session.json with `phase_completed: "artifacts"` diff --git a/.codex/skills/workflow-brainstorm-auto-parallel/phases/03-synthesis-integration.md b/.codex/skills/workflow-brainstorm-auto-parallel/phases/03-synthesis-integration.md deleted file mode 100644 index 9f5eba11..00000000 --- a/.codex/skills/workflow-brainstorm-auto-parallel/phases/03-synthesis-integration.md +++ /dev/null @@ -1,464 +0,0 @@ -## Overview - -Six-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses: - -**Phase 1-2**: Session detection → File discovery → Path preparation -**Phase 3A**: Cross-role analysis agent → Generate recommendations -**Phase 4**: User selects enhancements → User answers clarifications (via ASK_USER) -**Phase 5**: Parallel update agents (one per role) -**Phase 6**: Context package update → Metadata update → Completion report - -All user interactions use ASK_USER / CONFIRM pseudo-code (implemented via AskUserQuestion tool) (max 4 questions per call, multi-round). - -**Document Flow**: -- Input: `[role]/analysis*.md`, `guidance-specification.md`, session metadata -- Output: Updated `[role]/analysis*.md` with Enhancements + Clarifications sections - ---- - -## Quick Reference - -### Phase Summary - -| Phase | Goal | Executor | Output | -|-------|------|----------|--------| -| 1 | Session detection | Main flow | session_id, brainstorm_dir | -| 2 | File discovery | Main flow | role_analysis_paths | -| 3A | Cross-role analysis | spawn_agent | enhancement_recommendations | -| 4 | User interaction | Main flow + ASK_USER | update_plan | -| 5 | Document updates | spawn_agent[] (parallel) | Updated analysis*.md | -| 6 | Finalization | Main flow | context-package.json, report | - -### ASK_USER Pattern - -```javascript -// Enhancement selection (multi-select) -ASK_USER([{ - id: "改进选择", type: "multi-select", - prompt: "请选择要应用的改进建议", - options: [ - { label: "EP-001: API Contract", description: "添加详细的请求/响应 schema 定义" }, - { label: "EP-002: User Intent", description: "明确用户需求优先级和验收标准" } - ] -}]) // BLOCKS (wait for user response) - -// Clarification questions (single-select, multi-round) -ASK_USER([ - { - id: "用户意图", type: "select", - prompt: "MVP 阶段的核心目标是什么？", - options: [ - { label: "快速验证", description: "最小功能集，快速上线获取反馈" }, - { label: "技术壁垒", description: "完善架构，为长期发展打基础" }, - { label: "功能完整", description: "覆盖所有规划功能，延迟上线" } - ] - } -]) // BLOCKS (wait for user response) -``` - ---- - -## Execution Phases - -### Phase 1: Discovery & Validation - -1. **Detect Session**: Use `--session` parameter or find `{projectRoot}/.workflow/active/WFS-*` -2. **Validate Files**: - - `guidance-specification.md` (optional, warn if missing) - - `*/analysis*.md` (required, error if empty) -3. **Load User Intent**: Extract from `workflow-session.json` - -### Phase 2: Role Discovery & Path Preparation - -**Main flow prepares file paths for Agent**: - -1. **Discover Analysis Files**: - - Glob: `{projectRoot}/.workflow/active/WFS-{session}/.brainstorming/*/analysis*.md` - - Supports: analysis.md + analysis-{slug}.md (max 5) - -2. **Extract Role Information**: - - `role_analysis_paths`: Relative paths - - `participating_roles`: Role names from directories - -3. **Pass to Agent**: session_id, brainstorm_dir, role_analysis_paths, participating_roles - -### Phase 3A: Analysis & Enhancement Agent - -**Agent executes cross-role analysis**: - -```javascript -// Spawn analysis agent -const analysisAgentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -## Agent Mission -Analyze role documents, identify conflicts/gaps, generate enhancement recommendations - -## Input -- brainstorm_dir: ${brainstorm_dir} -- role_analysis_paths: ${role_analysis_paths} -- participating_roles: ${participating_roles} - -## Flow Control Steps -1. load_session_metadata → Read workflow-session.json -2. load_role_analyses → Read all analysis files -3. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities -4. generate_recommendations → Format as EP-001, EP-002, ... - -## Output Format -[ - { - "id": "EP-001", - "title": "API Contract Specification", - "affected_roles": ["system-architect", "api-designer"], - "category": "Architecture", - "current_state": "High-level API descriptions", - "enhancement": "Add detailed contract definitions", - "rationale": "Enables precise implementation", - "priority": "High" - } -] -` -}); - -// Wait for analysis completion -const analysisResult = wait({ - ids: [analysisAgentId], - timeout_ms: 600000 // 10 minutes -}); - -// Parse enhancement recommendations -const recommendations = JSON.parse(analysisResult.status[analysisAgentId]?.completed || '[]'); - -// Clean up agent -close_agent({ id: analysisAgentId }); -``` - -### Phase 4: User Interaction - -**All interactions via ASK_USER (Chinese questions)** - -#### Step 1: Enhancement Selection - -```javascript -// If enhancements > 4, split into multiple rounds -const enhancements = recommendations; // from Phase 3A -const BATCH_SIZE = 4; -const selectedEnhancements = []; - -for (let i = 0; i < enhancements.length; i += BATCH_SIZE) { - const batch = enhancements.slice(i, i + BATCH_SIZE); - - ASK_USER([{ - id: "改进选择", type: "multi-select", - prompt: `请选择要应用的改进建议 (第${Math.floor(i/BATCH_SIZE)+1}轮)`, - options: batch.map(ep => ({ - label: `${ep.id}: ${ep.title}`, - description: `影响: ${ep.affected_roles.join(', ')} | ${ep.enhancement}` - })) - }]) // BLOCKS (wait for user response) - - // Store selections before next round - selectedEnhancements.push(...user_selections); -} - -// User can also skip: provide "跳过" option -``` - -#### Step 2: Clarification Questions - -```javascript -// Generate questions based on 9-category taxonomy scan -// Categories: User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology - -const clarifications = [...]; // from analysis -const BATCH_SIZE = 4; -const userAnswers = {}; - -for (let i = 0; i < clarifications.length; i += BATCH_SIZE) { - const batch = clarifications.slice(i, i + BATCH_SIZE); - const currentRound = Math.floor(i / BATCH_SIZE) + 1; - const totalRounds = Math.ceil(clarifications.length / BATCH_SIZE); - - ASK_USER(batch.map(q => ({ - id: q.category.substring(0, 12), type: "select", - prompt: q.question, - options: q.options.map(opt => ({ - label: opt.label, - description: opt.description - })) - }))) // BLOCKS (wait for user response) - - // Store answers before next round - batch.forEach((q, idx) => { - userAnswers[q.id] = { - question: q.question, - answer: responses[idx], - category: q.category - }; - }); -} -``` - -### Question Guidelines - -**Target**: 开发者（理解技术但需要从用户需求出发） - -**Question Structure**: `[跨角色分析发现] + [需要澄清的决策点]` -**Option Structure**: `标签：[具体方案] + 说明：[业务影响] + [技术权衡]` - -**9-Category Taxonomy**: - -| Category | Focus | Example Question Pattern | -|----------|-------|--------------------------| -| User Intent | 用户目标 | "MVP阶段核心目标？" + 验证/壁垒/完整性 | -| Requirements | 需求细化 | "功能优先级如何排序？" + 核心/增强/可选 | -| Architecture | 架构决策 | "技术栈选择考量？" + 熟悉度/先进性/成熟度 | -| UX | 用户体验 | "交互复杂度取舍？" + 简洁/丰富/渐进 | -| Feasibility | 可行性 | "资源约束下的范围？" + 最小/标准/完整 | -| Risk | 风险管理 | "风险容忍度？" + 保守/平衡/激进 | -| Process | 流程规范 | "迭代节奏？" + 快速/稳定/灵活 | -| Decisions | 决策确认 | "冲突解决方案？" + 方案A/方案B/折中 | -| Terminology | 术语统一 | "统一使用哪个术语？" + 术语A/术语B | - -**Quality Rules**: - -**MUST Include**: -- ✅ All questions in Chinese (用中文提问) -- ✅ 基于跨角色分析的具体发现 -- ✅ 选项包含业务影响说明 -- ✅ 解决实际的模糊点或冲突 - -**MUST Avoid**: -- ❌ 与角色分析无关的通用问题 -- ❌ 重复已在 artifacts 阶段确认的内容 -- ❌ 过于细节的实现级问题 - -#### Step 3: Build Update Plan - -```javascript -update_plan = { - "role1": { - "enhancements": ["EP-001", "EP-003"], - "clarifications": [ - {"question": "...", "answer": "...", "category": "..."} - ] - }, - "role2": { - "enhancements": ["EP-002"], - "clarifications": [...] - } -} -``` - -### Phase 5: Parallel Document Update Agents - -**Execute in parallel** (one agent per role): - -```javascript -// Step 1: Spawn all update agents in parallel -const updateAgents = []; - -participating_roles.forEach((role, index) => { - const role_plan = update_plan[role]; - - const agentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -## Agent Mission -Apply enhancements and clarifications to ${role} analysis - -## Input -- role: ${role} -- analysis_path: ${brainstorm_dir}/${role}/analysis.md -- enhancements: ${JSON.stringify(role_plan.enhancements)} -- clarifications: ${JSON.stringify(role_plan.clarifications)} -- original_user_intent: ${intent} - -## Flow Control Steps -1. load_current_analysis → Read analysis file -2. add_clarifications_section → Insert Q&A section -3. apply_enhancements → Integrate into relevant sections -4. resolve_contradictions → Remove conflicts -5. enforce_terminology → Align terminology -6. validate_intent → Verify alignment with user intent -7. write_updated_file → Save changes - -## Output -Updated ${role}/analysis.md -` - }); - - updateAgents.push({ agentId, role }); -}); - -// Step 2: Batch wait for all update agents -const updateIds = updateAgents.map(a => a.agentId); -const updateResults = wait({ - ids: updateIds, - timeout_ms: 900000 // 15 minutes for all updates -}); - -// Step 3: Check completion status -const updatedRoles = []; -const failedUpdates = []; - -updateAgents.forEach(({ agentId, role }) => { - if (updateResults.status[agentId]?.completed) { - updatedRoles.push(role); - } else { - failedUpdates.push(role); - } -}); - -if (updateResults.timed_out) { - console.warn('Some role updates timed out:', failedUpdates); -} - -// Step 4: Batch cleanup - IMPORTANT -updateAgents.forEach(({ agentId }) => { - close_agent({ id: agentId }); -}); - -console.log(`Updated: ${updatedRoles.length}/${participating_roles.length} roles`); -``` - -**Agent Characteristics**: -- **Isolation**: Each agent updates exactly ONE role (parallel safe) -- **Dependencies**: Zero cross-agent dependencies -- **Validation**: All updates must align with original_user_intent -- **Lifecycle**: Explicit spawn → wait → close for each agent - -### Phase 6: Finalization - -#### Step 1: Update Context Package - -```javascript -// Sync updated analyses to context-package.json -const context_pkg = Read("${projectRoot}/.workflow/active/WFS-{session}/.process/context-package.json") - -// Update guidance-specification if exists -// Update synthesis-specification if exists -// Re-read all role analysis files -// Update metadata timestamps - -Write(context_pkg_path, JSON.stringify(context_pkg)) -``` - -#### Step 2: Update Session Metadata - -```json -{ - "phases": { - "BRAINSTORM": { - "status": "clarification_completed", - "clarification_completed": true, - "completed_at": "timestamp", - "participating_roles": [...], - "clarification_results": { - "enhancements_applied": ["EP-001", "EP-002"], - "questions_asked": 3, - "categories_clarified": ["Architecture", "UX"], - "roles_updated": ["role1", "role2"] - }, - "quality_metrics": { - "user_intent_alignment": "validated", - "ambiguity_resolution": "complete", - "terminology_consistency": "enforced" - } - } - } -} -``` - -#### Step 3: Completion Report - -```markdown -## ✅ Clarification Complete - -**Enhancements Applied**: EP-001, EP-002, EP-003 -**Questions Answered**: 3/5 -**Roles Updated**: role1, role2, role3 - -### Next Steps -✅ PROCEED: `workflow:plan --session WFS-{session-id}` -``` - ---- - -## Output - -**Location**: `{projectRoot}/.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md` - -**Updated Structure**: -```markdown -## Clarifications -### Session {date} -- **Q**: {question} (Category: {category}) - **A**: {answer} - -## {Existing Sections} -{Refined content based on clarifications} -``` - -**Changes**: -- User intent validated/corrected -- Requirements more specific/measurable -- Architecture with rationale -- Ambiguities resolved, placeholders removed -- Consistent terminology - ---- - -## Quality Checklist - -**Content**: -- ✅ All role analyses loaded/analyzed -- ✅ Cross-role analysis (consensus, conflicts, gaps) -- ✅ 9-category ambiguity scan -- ✅ Questions prioritized - -**Analysis**: -- ✅ User intent validated -- ✅ Cross-role synthesis complete -- ✅ Ambiguities resolved -- ✅ Terminology consistent - -**Documents**: -- ✅ Clarifications section formatted -- ✅ Sections reflect answers -- ✅ No placeholders (TODO/TBD) -- ✅ Valid Markdown - -**Agent Lifecycle**: -- ✅ All spawn_agent have corresponding close_agent -- ✅ Analysis agent closed before update agents spawn -- ✅ All update agents closed after batch wait -- ✅ Error paths include agent cleanup - ---- - -## Post-Phase Update - -After Phase 3 completes: -- **Output Created**: `synthesis-specification.md`, updated role `analysis*.md` files -- **Cross-Role Integration**: All role insights synthesized and conflicts resolved -- **Agent Cleanup**: All agents (analysis + update) properly closed -- **Next Action**: Workflow complete, recommend `workflow:plan --session {session_id}` -- **State Update**: Update workflow-session.json with synthesis completion status diff --git a/.codex/skills/workflow-execute/SKILL.md b/.codex/skills/workflow-execute/SKILL.md deleted file mode 100644 index da30ebef..00000000 --- a/.codex/skills/workflow-execute/SKILL.md +++ /dev/null @@ -1,806 +0,0 @@ ---- -name: workflow-execute -description: Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking. Triggers on "workflow execute". -allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep ---- - -# Workflow Execute (Codex Version) - -Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. **Executes entire workflow without user interruption** (except initial session selection if multiple active sessions exist), providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking. - -**Also available as**: `workflow:plan` Phase 4 — when running `workflow:plan` with `--yes` or selecting "Start Execution" after Phase 3, the core execution logic runs inline without needing a separate `workflow:execute` call. Use this standalone command for `--resume-session` scenarios or when invoking execution independently. - -**Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session. - -## Architecture Overview - -``` -┌──────────────────────────────────────────────────────────────┐ -│ Workflow Execute Orchestrator (SKILL.md) │ -│ → Parse args → Session discovery → Strategy → Execute tasks │ -└──────────┬───────────────────────────────────────────────────┘ - │ - ┌──────┴──────┐ - │ Normal Mode │──→ Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 - │ Resume Mode │──→ Phase 3 → Phase 4 → Phase 5 - └─────────────┘ - │ - ┌──────┴──────────────────────────────────────────────┐ - │ Phase 1: Discovery (session selection) │ - │ Phase 2: Validation (planning doc checks) │ - │ Phase 3: TodoWrite Gen (progress tracking init) │ - │ Phase 4: Strategy+Execute (lazy load + agent loop) │ - │ Phase 5: Completion (status sync + user choice)│ - └─────────────────────────────────────────────────────┘ -``` - -## Key Design Principles - -1. **Autonomous Execution**: Complete entire workflow without user interruption -2. **Lazy Loading**: Task JSONs read on-demand during execution, not upfront -3. **ONE AGENT = ONE TASK JSON**: Each agent instance executes exactly one task JSON file -4. **IMPL_PLAN-Driven Strategy**: Execution model derived from planning document -5. **Continuous Progress Tracking**: TodoWrite updates throughout entire workflow -6. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent - -## Auto Mode - -When `--yes` or `-y`: -- **Session Selection**: Automatically selects the first (most recent) active session -- **Completion Choice**: Automatically completes session (runs `workflow:session:complete --yes`) - -When `--with-commit`: -- **Auto-Commit**: After each agent task completes, commit changes based on summary document -- **Commit Principle**: Minimal commits - only commit files modified by the completed task -- **Commit Message**: Generated from task summary with format: "feat/fix/refactor: {task-title} - {summary}" - -## Usage - -``` -codex -p "@.codex/prompts/workflow-execute.md" -codex -p "@.codex/prompts/workflow-execute.md [FLAGS]" - -# Flags --y, --yes Skip all confirmations (auto mode) ---resume-session="" Skip discovery, resume specified session ---with-commit Auto-commit after each task completion - -# Examples -codex -p "@.codex/prompts/workflow-execute.md" # Interactive mode -codex -p "@.codex/prompts/workflow-execute.md --yes" # Auto mode -codex -p "@.codex/prompts/workflow-execute.md --resume-session=\"WFS-auth\"" # Resume specific session -codex -p "@.codex/prompts/workflow-execute.md -y --resume-session=\"WFS-auth\"" # Auto + resume -codex -p "@.codex/prompts/workflow-execute.md --with-commit" # With auto-commit -codex -p "@.codex/prompts/workflow-execute.md -y --with-commit" # Auto + commit -codex -p "@.codex/prompts/workflow-execute.md -y --with-commit --resume-session=\"WFS-auth\"" # All flags -``` - -## Execution Flow - -``` -Normal Mode: -Phase 1: Discovery - ├─ Count active sessions - └─ Decision: - ├─ count=0 → ERROR: No active sessions - ├─ count=1 → Auto-select session → Phase 2 - └─ count>1 → ASK_USER (max 4 options) → Phase 2 - -Phase 2: Planning Document Validation - ├─ Check IMPL_PLAN.md exists - ├─ Check TODO_LIST.md exists - └─ Validate .task/ contains IMPL-*.json files - -Phase 3: TodoWrite Generation - ├─ Update session status to "active" (Step 0) - ├─ Parse TODO_LIST.md for task statuses - ├─ Generate TodoWrite for entire workflow - └─ Prepare session context paths - -Phase 4: Execution Strategy & Task Execution - ├─ Step 4A: Parse execution strategy from IMPL_PLAN.md - └─ Step 4B: Execute tasks with lazy loading - └─ Loop: - ├─ Get next in_progress task from TodoWrite - ├─ Lazy load task JSON - ├─ Launch agent (spawn_agent → wait → close_agent) - ├─ Mark task completed (update IMPL-*.json status) - │ # Quick fix: Update task status for ccw dashboard - │ # TS=$(date -Iseconds) && jq --arg ts "$TS" '.status="completed" | .status_history=(.status_history // [])+[{"from":"in_progress","to":"completed","changed_at":$ts}]' IMPL-X.json > tmp.json && mv tmp.json IMPL-X.json - ├─ [with-commit] Commit changes based on summary (minimal principle) - │ # Read summary from .summaries/IMPL-X-summary.md - │ # Extract changed files from summary's "Files Modified" section - │ # Generate commit message: "feat/fix/refactor: {task-title} - {summary}" - │ # git add && git commit -m "" - └─ Advance to next task - -Phase 5: Completion - ├─ Update task statuses in JSON files - ├─ Generate summaries - └─ ASK_USER: Choose next step - ├─ "Enter Review" → workflow:review - └─ "Complete Session" → workflow:session:complete - -Resume Mode (--resume-session): - ├─ Skip Phase 1 & Phase 2 - └─ Entry Point: Phase 3 (TodoWrite Generation) - ├─ Update session status to "active" (if not already) - └─ Continue: Phase 4 → Phase 5 -``` - -## Core Rules - -**Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.** -**Execute all discovered pending tasks until workflow completion or blocking dependency.** -**User-choice completion: When all tasks finished, ask user to choose review or complete.** -**ONE AGENT = ONE TASK JSON: Each agent instance executes exactly one task JSON file - never batch multiple tasks into single agent execution.** -**Explicit Lifecycle: Always close_agent after wait completes to free resources.** - -## 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: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.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 implementation. -` -}) -``` - -### close_agent -Clean up subagent resources (irreversible). - -```javascript -close_agent({ id: agentId }) -``` - -## Core Responsibilities - -- **Session Discovery**: Identify and select active workflow sessions -- **Execution Strategy Parsing**: Extract execution model from IMPL_PLAN.md -- **TodoWrite Progress Tracking**: Maintain real-time execution status throughout entire workflow -- **Agent Orchestration**: Coordinate specialized agents with complete context via spawn_agent lifecycle -- **Status Synchronization**: Update task JSON files and workflow state -- **Autonomous Completion**: Continue execution until all tasks complete or reach blocking state -- **Session User-Choice Completion**: Ask user to choose review or complete when all tasks finished - -## Execution Philosophy - -- **Progress tracking**: Continuous TodoWrite updates throughout entire workflow execution -- **Autonomous completion**: Execute all tasks without user interruption until workflow complete - -## Performance Optimization Strategy - -**Lazy Loading**: Task JSONs read **on-demand** during execution, not upfront. TODO_LIST.md + IMPL_PLAN.md provide metadata for planning. - -**Loading Strategy**: -- **TODO_LIST.md**: Read in Phase 3 (task metadata, status, dependencies for TodoWrite generation) -- **IMPL_PLAN.md**: Check existence in Phase 2 (normal mode), parse execution strategy in Phase 4A -- **Task JSONs**: Lazy loading - read only when task is about to execute (Phase 4B) - -## Execution Lifecycle - -### Phase 1: Discovery -**Applies to**: Normal mode only (skipped in resume mode) - -**Purpose**: Find and select active workflow session with user confirmation when multiple sessions exist - -**Process**: - -#### Step 1.1: Count Active Sessions -```bash -bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l) -``` - -#### Step 1.2: Handle Session Selection - -**Case A: No Sessions** (count = 0) -``` -ERROR: No active workflow sessions found -Run workflow:plan "task description" to create a session -``` - -**Case B: Single Session** (count = 1) -```bash -bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename) -``` -Auto-select and continue to Phase 2. - -**Case C: Multiple Sessions** (count > 1) - -List sessions with metadata and prompt user selection: -```bash -bash(for dir in ${projectRoot}/.workflow/active/WFS-*/; do [ -d "$dir" ] || continue; session=$(basename "$dir"); project=$(jq -r '.project // "Unknown"' "${dir}workflow-session.json" 2>/dev/null || echo "Unknown"); total=$(grep -c '^\- \[' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); completed=$(grep -c '^\- \[x\]' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); if [ "$total" -gt 0 ]; then progress=$((completed * 100 / total)); else progress=0; fi; echo "$session | $project | $completed/$total tasks ($progress%)"; done) -``` - -**Parse --yes flag**: -```javascript -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') -``` - -**Conditional Selection**: -```javascript -if (autoYes) { - // Auto mode: Select first session (most recent) - const firstSession = sessions[0] - console.log(`[--yes] Auto-selecting session: ${firstSession.id}`) - selectedSessionId = firstSession.id - // Continue to Phase 2 -} else { - // Interactive mode: Use ASK_USER to present formatted options (max 4 options shown) - // If more than 4 sessions, show most recent 4 with "Other" option for manual input - const sessions = getActiveSessions() // sorted by last modified - const displaySessions = sessions.slice(0, 4) - - ASK_USER([{ - id: "session", type: "select", - prompt: "Multiple active sessions detected. Select one:", - options: displaySessions.map(s => ({ - label: s.id, - description: `${s.project} | ${s.progress}` - })) - // Note: User can select "Other" to manually enter session ID - }]) // BLOCKS (wait for user response) -} -``` - -**Input Validation**: -- If user selects from options: Use selected session ID -- If user selects "Other" and provides input: Validate session exists -- If validation fails: Show error and re-prompt or suggest available sessions - -Parse user input (supports: number "1", full ID "WFS-auth-system", or partial "auth"), validate selection, and continue to Phase 2. - -#### Step 1.3: Load Session Metadata -```bash -bash(cat ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json) -``` - -**Output**: Store session metadata in memory -**DO NOT read task JSONs yet** - defer until execution phase (lazy loading) - -**Resume Mode**: This entire phase is skipped when `--resume-session="session-id"` flag is provided. - -### Phase 2: Planning Document Validation -**Applies to**: Normal mode only (skipped in resume mode) - -**Purpose**: Validate planning artifacts exist before execution - -**Process**: -1. **Check IMPL_PLAN.md**: Verify file exists (defer detailed parsing to Phase 4A) -2. **Check TODO_LIST.md**: Verify file exists (defer reading to Phase 3) -3. **Validate Task Directory**: Ensure `.task/` contains at least one IMPL-*.json file - -**Key Optimization**: Only existence checks here. Actual file reading happens in later phases. - -**Resume Mode**: This phase is skipped when `--resume-session` flag is provided. Resume mode entry point is Phase 3. - -### Phase 3: TodoWrite Generation -**Applies to**: Both normal and resume modes (resume mode entry point) - -**Step 0: Update Session Status to Active** -Before generating TodoWrite, update session status from "planning" to "active": -```bash -# Update session status (idempotent - safe to run if already active) -jq '.status = "active" | .execution_started_at = (.execution_started_at // now | todate)' \ - ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json > tmp.json && \ - mv tmp.json ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json -``` -This ensures the dashboard shows the session as "ACTIVE" during execution. - -**Process**: -1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs) - - Parse TODO_LIST.md to extract all tasks with current statuses - - Identify first pending task with met dependencies - - Generate comprehensive TodoWrite covering entire workflow -2. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id) -3. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid - -**Resume Mode Behavior**: -- Load existing TODO_LIST.md directly from `{projectRoot}/.workflow/active/{session-id}/` -- Extract current progress from TODO_LIST.md -- Generate TodoWrite from TODO_LIST.md state -- Proceed immediately to agent execution (Phase 4) - -### Phase 4: Execution Strategy Selection & Task Execution -**Applies to**: Both normal and resume modes - -**Step 4A: Parse Execution Strategy from IMPL_PLAN.md** - -Read IMPL_PLAN.md Section 4 to extract: -- **Execution Model**: Sequential | Parallel | Phased | TDD Cycles -- **Parallelization Opportunities**: Which tasks can run in parallel -- **Serialization Requirements**: Which tasks must run sequentially -- **Critical Path**: Priority execution order - -If IMPL_PLAN.md lacks execution strategy, use intelligent fallback (analyze task structure). - -**Step 4B: Execute Tasks with Lazy Loading** - -**Key Optimization**: Read task JSON **only when needed** for execution - -**Execution Loop Pattern**: -``` -while (TODO_LIST.md has pending tasks) { - next_task_id = getTodoWriteInProgressTask() - task_json = Read(${projectRoot}/.workflow/active/{session}/.task/{next_task_id}.json) // Lazy load - executeTaskWithAgent(task_json) // spawn_agent → wait → close_agent - updateTodoListMarkCompleted(next_task_id) - advanceTodoWriteToNextTask() -} -``` - -**Execution Process per Task**: -1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID -2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY -3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control) -4. **Launch Agent**: Invoke specialized agent via spawn_agent with complete context including flow control steps -5. **Wait for Completion**: wait for agent result, handle timeout -6. **Close Agent**: close_agent to free resources -7. **Collect Results**: Gather implementation results and outputs -8. **[with-commit] Auto-Commit**: If `--with-commit` flag enabled, commit changes based on summary - - Read summary from `.summaries/{task-id}-summary.md` - - Extract changed files from summary's "Files Modified" section - - Determine commit type from `meta.type` (feature→feat, bugfix→fix, refactor→refactor) - - Generate commit message: "{type}: {task-title} - {summary-first-line}" - - Commit only modified files (minimal principle): `git add && git commit -m ""` -9. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat - -**Note**: TODO_LIST.md updates are handled by agents (e.g., code-developer.md), not by the orchestrator. - -### Phase 5: Completion -**Applies to**: Both normal and resume modes - -**Process**: -1. **Update Task Status**: Mark completed tasks in JSON files -2. **Generate Summary**: Create task summary in `.summaries/` -3. **Update TodoWrite**: Mark current task complete, advance to next -4. **Synchronize State**: Update session state and workflow status -5. **Check Workflow Complete**: Verify all tasks are completed -6. **User Choice**: When all tasks finished, ask user to choose next step: - -```javascript -// Parse --yes flag -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') - -if (autoYes) { - // Auto mode: Complete session automatically - console.log(`[--yes] Auto-selecting: Complete Session`) - // Execute: workflow:session:complete --yes -} else { - // Interactive mode: Ask user - ASK_USER([{ - id: "next_step", type: "select", - prompt: "All tasks completed. What would you like to do next?", - options: [ - { - label: "Enter Review", - description: "Run specialized review (security/architecture/quality/action-items)" - }, - { - label: "Complete Session", - description: "Archive session and update manifest" - } - ] - }]) // BLOCKS (wait for user response) -} -``` - -**Based on user selection**: -- **"Enter Review"**: Execute `workflow:review` -- **"Complete Session"**: Execute `workflow:session:complete` - -### Post-Completion Expansion - -完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `issue:new "{summary} - {dimension}"` - -## Execution Strategy (IMPL_PLAN-Driven) - -### Strategy Priority - -**IMPL_PLAN-Driven Execution (Recommended)**: -1. **Read IMPL_PLAN.md execution strategy** (Section 4: Implementation Strategy) -2. **Follow explicit guidance**: - - Execution Model (Sequential/Parallel/Phased/TDD) - - Parallelization Opportunities (which tasks can run in parallel) - - Serialization Requirements (which tasks must run sequentially) - - Critical Path (priority execution order) -3. **Use TODO_LIST.md for status tracking** only -4. **IMPL_PLAN decides "HOW"**, execute implements it - -**Intelligent Fallback (When IMPL_PLAN lacks execution details)**: -1. **Analyze task structure**: - - Check `meta.execution_group` in task JSONs - - Analyze `depends_on` relationships - - Understand task complexity and risk -2. **Apply smart defaults**: - - No dependencies + same execution_group → Parallel - - Has dependencies → Sequential (wait for deps) - - Critical/high-risk tasks → Sequential -3. **Conservative approach**: When uncertain, prefer sequential execution - -### Execution Models - -#### 1. Sequential Execution -**When**: IMPL_PLAN specifies "Sequential" OR no clear parallelization guidance -**Pattern**: Execute tasks one by one in TODO_LIST order via spawn_agent → wait → close_agent per task -**TodoWrite**: ONE task marked as `in_progress` at a time - -#### 2. Parallel Execution -**When**: IMPL_PLAN specifies "Parallel" with clear parallelization opportunities -**Pattern**: Execute independent task groups concurrently by spawning multiple agents and batch waiting -**TodoWrite**: MULTIPLE tasks (in same batch) marked as `in_progress` simultaneously -**Agent Instantiation**: spawn one agent per task (respects ONE AGENT = ONE TASK JSON rule), then batch wait - -**Parallel Execution Pattern**: -```javascript -// Step 1: Spawn agents for parallel batch -const batchAgents = []; -parallelTasks.forEach(task => { - const agentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/${task.meta.agent}.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -Implement task ${task.id}: ${task.title} - -[FLOW_CONTROL] - -**Input**: -- Task JSON: ${session.task_json_path} -- Context Package: ${session.context_package_path} - -**Output Location**: -- Workflow: ${session.workflow_dir} -- TODO List: ${session.todo_list_path} -- Summaries: ${session.summaries_dir} - -**Execution**: Read task JSON → Execute pre_analysis → Check execution_config.method → (CLI: handoff to CLI tool | Agent: direct implementation) → Update TODO_LIST.md → Generate summary -` - }); - batchAgents.push({ agentId, taskId: task.id }); -}); - -// Step 2: Batch wait for all agents -const batchResult = wait({ - ids: batchAgents.map(a => a.agentId), - timeout_ms: 600000 -}); - -// Step 3: Check results and handle timeouts -if (batchResult.timed_out) { - console.log('Some parallel tasks timed out, continuing with completed results'); -} - -// Step 4: Close all agents -batchAgents.forEach(a => close_agent({ id: a.agentId })); -``` - -#### 3. Phased Execution -**When**: IMPL_PLAN specifies "Phased" with phase breakdown -**Pattern**: Execute tasks in phases, respect phase boundaries -**TodoWrite**: Within each phase, follow Sequential or Parallel rules - -#### 4. Intelligent Fallback -**When**: IMPL_PLAN lacks execution strategy details -**Pattern**: Analyze task structure and apply smart defaults -**TodoWrite**: Follow Sequential or Parallel rules based on analysis - -### Task Status Logic -``` -pending + dependencies_met → executable -completed → skip -blocked → skip until dependencies clear -``` - -## TodoWrite Coordination - -### TodoWrite Rules (Unified) - -**Rule 1: Initial Creation** -- **Normal Mode**: Generate TodoWrite from discovered pending tasks for entire workflow -- **Resume Mode**: Generate from existing session state and current progress - -**Rule 2: In-Progress Task Count (Execution-Model-Dependent)** -- **Sequential execution**: Mark ONLY ONE task as `in_progress` at a time -- **Parallel batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously -- **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks - -**Rule 3: Status Updates** -- **Immediate Updates**: Update status after each task/batch completion without user interruption -- **Status Synchronization**: Sync with JSON task files after updates -- **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion - -**Rule 4: Workflow Completion Check** -- When all tasks marked `completed`, prompt user to choose review or complete session - -### TodoWrite Tool Usage - -**Example 1: Sequential Execution** -```javascript -TodoWrite({ - todos: [ - { - content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]", - status: "in_progress", // ONE task in progress - activeForm: "Executing IMPL-1.1: Design auth schema" - }, - { - content: "Execute IMPL-1.2: Implement auth logic [code-developer] [FLOW_CONTROL]", - status: "pending", - activeForm: "Executing IMPL-1.2: Implement auth logic" - } - ] -}); -``` - -**Example 2: Parallel Batch Execution** -```javascript -TodoWrite({ - todos: [ - { - content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]", - status: "in_progress", // Batch task 1 - activeForm: "Executing IMPL-1.1: Build Auth API" - }, - { - content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]", - status: "in_progress", // Batch task 2 (running concurrently) - activeForm: "Executing IMPL-1.2: Build User UI" - }, - { - content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]", - status: "in_progress", // Batch task 3 (running concurrently) - activeForm: "Executing IMPL-1.3: Setup Database" - }, - { - content: "Execute IMPL-2.1: Integration Tests [test-fix-agent] [depends_on: IMPL-1.1, IMPL-1.2, IMPL-1.3]", - status: "pending", // Next batch (waits for current batch completion) - activeForm: "Executing IMPL-2.1: Integration Tests" - } - ] -}); -``` - -## Agent Execution Pattern - -### Flow Control Execution -**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation. - -**Note**: Orchestrator does NOT execute flow control steps - Agent interprets and executes them autonomously. - -### Agent Prompt Template (Sequential) -**Path-Based Invocation**: Pass paths and trigger markers, let agent parse task JSON autonomously. - -```javascript -// Step 1: Spawn agent -const agentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/${meta.agent}.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -Implement task ${task.id}: ${task.title} - -[FLOW_CONTROL] - -**Input**: -- Task JSON: ${session.task_json_path} -- Context Package: ${session.context_package_path} - -**Output Location**: -- Workflow: ${session.workflow_dir} -- TODO List: ${session.todo_list_path} -- Summaries: ${session.summaries_dir} - -**Execution**: Read task JSON → Execute pre_analysis → Check execution_config.method → (CLI: handoff to CLI tool | Agent: direct implementation) → Update TODO_LIST.md → Generate summary -` -}); - -// Step 2: Wait for completion -const result = wait({ - ids: [agentId], - timeout_ms: 600000 // 10 minutes per task -}); - -// Step 3: Close agent (IMPORTANT: always close) -close_agent({ id: agentId }); -``` - -**Key Markers**: -- `Implement` keyword: Triggers tech stack detection and guidelines loading -- `[FLOW_CONTROL]`: Triggers flow_control.pre_analysis execution - -**Why Path-Based**: Agent (code-developer.md) autonomously: -- Reads and parses task JSON (requirements, acceptance, flow_control, execution_config) -- Executes pre_analysis steps (Phase 1: context gathering) -- Checks execution_config.method (Phase 2: determine mode) -- CLI mode: Builds handoff prompt and executes via ccw cli with resume strategy -- Agent mode: Directly implements using modification_points and logic_flow -- Generates structured summary with integration points - -Embedding task content in prompt creates duplication and conflicts with agent's parsing logic. - -### Agent Assignment Rules -``` -meta.agent specified → Use specified agent -meta.agent missing → Infer from meta.type: - - "feature" → @code-developer (role: ~/.codex/agents/code-developer.md) - - "test-gen" → @code-developer (role: ~/.codex/agents/code-developer.md) - - "test-fix" → @test-fix-agent (role: ~/.codex/agents/test-fix-agent.md) - - "review" → @universal-executor (role: ~/.codex/agents/universal-executor.md) - - "docs" → @doc-generator (role: ~/.codex/agents/doc-generator.md) -``` - -## Data Flow - -``` -Phase 1 (Discovery) → selectedSessionId, sessionMetadata - ↓ -Phase 2 (Validation) → validated paths (IMPL_PLAN.md, TODO_LIST.md, .task/) - ↓ -Phase 3 (TodoWrite Gen) → todoWriteList, sessionContextPaths - ↓ -Phase 4 (Execute) → per-task: taskJson (lazy), spawn_agent → wait → close_agent, summaryDoc - ↓ -Phase 5 (Completion) → updatedStatuses, userChoice (review|complete) -``` - -## Workflow File Structure Reference -``` -{projectRoot}/.workflow/active/WFS-[topic-slug]/ -├── workflow-session.json # Session state and metadata -├── IMPL_PLAN.md # Planning document and requirements -├── TODO_LIST.md # Progress tracking (updated by agents) -├── .task/ # Task definitions (JSON only) -│ ├── IMPL-1.json # Main task definitions -│ └── IMPL-1.1.json # Subtask definitions -├── .summaries/ # Task completion summaries -│ ├── IMPL-1-summary.md # Task completion details -│ └── IMPL-1.1-summary.md # Subtask completion details -└── .process/ # Planning artifacts - ├── context-package.json # Smart context package - └── ANALYSIS_RESULTS.md # Planning analysis results -``` - -## Auto-Commit Mode (--with-commit) - -**Behavior**: After each agent task completes, automatically commit changes based on summary document. - -**Minimal Principle**: Only commit files modified by the completed task. - -**Commit Message Format**: `{type}: {task-title} - {summary}` - -**Type Mapping** (from `meta.type`): -- `feature` → `feat` | `bugfix` → `fix` | `refactor` → `refactor` -- `test-gen` → `test` | `docs` → `docs` | `review` → `chore` - -**Implementation**: -```bash -# 1. Read summary from .summaries/{task-id}-summary.md -# 2. Extract files from "Files Modified" section -# 3. Commit: git add && git commit -m "{type}: {title} - {summary}" -``` - -**Error Handling**: Skip commit on no changes/missing summary, log errors, continue workflow. - -## Error Handling & Recovery - -### Common Errors & Recovery - -| Error Type | Cause | Recovery Strategy | Max Attempts | -|-----------|-------|------------------|--------------| -| **Discovery Errors** | -| No active session | No sessions in `{projectRoot}/.workflow/active/` | Create or resume session: `workflow:plan "project"` | N/A | -| Multiple sessions | Multiple sessions in `{projectRoot}/.workflow/active/` | Prompt user selection | N/A | -| Corrupted session | Invalid JSON files | Recreate session structure or validate files | N/A | -| **Execution Errors** | -| Agent failure | Agent crash/timeout | Retry with simplified context (close_agent first, then spawn new) | 2 | -| Flow control error | Command failure | Skip optional, fail critical | 1 per step | -| Context loading error | Missing dependencies | Reload from JSON, use defaults | 3 | -| JSON file corruption | File system issues | Restore from backup/recreate | 1 | -| **Lifecycle Errors** | -| Agent timeout | wait timed out | send_input to prompt completion, or close_agent and retry | 2 | -| Orphaned agent | Agent not closed after error | Ensure close_agent in error paths | N/A | - -### Error Prevention -- **Pre-flight Checks**: Validate session integrity before execution -- **Backup Strategy**: Create task snapshots before major operations -- **Atomic Updates**: Update JSON files atomically to prevent corruption -- **Dependency Validation**: Check all depends_on references exist -- **Context Verification**: Ensure all required context is available -- **Lifecycle Cleanup**: Always close_agent in both success and error paths - -### Error Recovery with Lifecycle Management -```javascript -// Safe agent execution pattern with error handling -let agentId = null; -try { - agentId = spawn_agent({ message: taskPrompt }); - const result = wait({ ids: [agentId], timeout_ms: 600000 }); - - if (result.timed_out) { - // Option 1: Send prompt to complete - send_input({ id: agentId, message: "Please wrap up and generate summary." }); - const retryResult = wait({ ids: [agentId], timeout_ms: 120000 }); - } - - // Process results... - close_agent({ id: agentId }); -} catch (error) { - // Ensure cleanup on error - if (agentId) close_agent({ id: agentId }); - // Handle error (retry or skip task) -} -``` - -## Flag Parsing - -```javascript -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') -const withCommit = $ARGUMENTS.includes('--with-commit') -``` - -## Related Commands - -**Prerequisite Commands**: -- `workflow:plan` - Create workflow session with planning documents - -**Follow-up Commands**: -- `workflow:review` - Run specialized post-implementation review -- `workflow:session:complete` - Archive session and update manifest -- `issue:new` - Create issue for post-completion expansion diff --git a/.codex/skills/workflow-lite-plan-execute/SKILL.md b/.codex/skills/workflow-lite-plan-execute/SKILL.md deleted file mode 100644 index 7d495ddd..00000000 --- a/.codex/skills/workflow-lite-plan-execute/SKILL.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -name: workflow-lite-plan-execute -description: Lightweight planning + execution workflow. Serial CLI exploration → Search verification → Clarification → Planning → .task/*.json multi-file output → Execution via unified-execute. -allowed-tools: AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, mcp__ace-tool__search_context ---- - -# Planning Workflow - -Lite Plan produces `plan.json` (plan overview) + `.task/TASK-*.json` (one file per task) implementation plan via serial CLI exploration and direct planning, then hands off to unified-execute-with-file for task execution. - -> **Schema**: `cat ~/.ccw/workflows/cli-templates/schemas/task-schema.json` - -## Key Design Principles - -1. **Serial Execution**: All phases execute serially inline, no agent delegation -2. **CLI Exploration**: Multi-angle codebase exploration via `ccw cli` calls (default gemini, fallback claude) -3. **Search Verification**: Verify CLI findings with ACE search / Grep / Glob before incorporating -4. **Multi-File Task Output**: Produces `.task/TASK-*.json` (one file per task) compatible with `collaborative-plan-with-file` and `unified-execute-with-file` -5. **Progressive Phase Loading**: Only load phase docs when about to execute - -## Auto Mode - -When `--yes` or `-y`: -- Auto-approve plan and use default execution settings -- Skip non-critical clarifications; still ask minimal clarifications if required for safety/correctness - -## Usage (Pseudo) - -This section describes the skill input shape; actual invocation depends on the host runtime. - -``` -$workflow-lite-plan-execute -$workflow-lite-plan-execute [FLAGS] "" - -# Flags --y, --yes Skip confirmations (auto mode) --e, --explore Force exploration phase -``` - -Examples: -``` -$workflow-lite-plan-execute "Implement JWT authentication" -$workflow-lite-plan-execute -y "Add user profile page" -$workflow-lite-plan-execute -e "Refactor payment module" -$workflow-lite-plan-execute "docs/todo.md" -``` - -> **Implementation sketch**: 编排器内部使用 `$workflow-lite-plan-execute "..."` 接口调用，此为伪代码示意，非命令行语法。 - -## Phase Reference Documents (Read On Demand) - -| Phase | Document | Purpose | -|-------|----------|---------| -| 1 | `phases/01-lite-plan.md` | Serial CLI exploration, clarification, plan generation → .task/TASK-*.json | -| 2 | `phases/02-lite-execute.md` | Handoff to unified-execute-with-file for task execution | - -## Orchestrator Logic - -```javascript -// Flag parsing -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') -const forceExplore = $ARGUMENTS.includes('--explore') || $ARGUMENTS.includes('-e') - -// Task extraction rule: -// - Strip known flags: -y/--yes, -e/--explore -// - Remaining args are joined as the task description -// - Treat it as a file path ONLY if (a) exactly one arg remains AND (b) the path exists -function extractTaskDescription(args) { - const knownFlags = new Set(['--yes', '-y', '--explore', '-e']) - const rest = args.filter(a => !knownFlags.has(a)) - if (rest.length === 1 && file_exists(rest[0])) return rest[0] - return rest.join(' ').trim() -} - -const taskDescription = extractTaskDescription($ARGUMENTS) - -// Phase 1: Lite Plan → .task/TASK-*.json -Read('phases/01-lite-plan.md') -// Execute planning phase... - -// Gate: only continue when confirmed (or --yes) -if (planResult?.userSelection?.confirmation !== 'Allow' && !autoYes) { - // Stop: user cancelled or requested modifications - return -} - -// Phase 2: Handoff to unified-execute-with-file -Read('phases/02-lite-execute.md') -// Invoke unified-execute-with-file with .task/ directory path -``` - -## Output Contract - -Phase 1 produces `plan.json` (plan overview, following `plan-overview-base-schema.json`) + `.task/TASK-*.json` (one file per task) — compatible with `collaborative-plan-with-file` and consumable by `unified-execute-with-file`. - -> **Schema**: `cat ~/.ccw/workflows/cli-templates/schemas/task-schema.json` - -**Output Directory**: `{projectRoot}/.workflow/.lite-plan/{session-id}/` - -``` -{projectRoot}/.workflow/.lite-plan/{session-id}/ -├── exploration-{angle1}.md # Per-angle CLI exploration results -├── exploration-{angle2}.md # (1-4 files based on complexity) -├── explorations-manifest.json # Exploration index -├── exploration-notes.md # Synthesized exploration notes -├── requirement-analysis.json # Complexity assessment -├── plan.json # ⭐ Plan overview (plan-overview-base-schema.json) -├── .task/ # Task JSON files (one per task) -│ ├── TASK-001.json # Individual task definition -│ ├── TASK-002.json -│ └── ... -└── plan.md # Human-readable summary -``` - -**Task JSON Format** (one file per task, following task-schema.json): - -```javascript -// File: .task/TASK-001.json -{ - "id": "TASK-001", - "title": "string", - "description": "string", - "type": "feature|fix|refactor|enhancement|testing|infrastructure", - "priority": "high|medium|low", - "effort": "small|medium|large", - "scope": "string", - "depends_on": ["TASK-xxx"], - "convergence": { - "criteria": ["string"], // Testable conditions - "verification": "string", // Executable command or manual steps - "definition_of_done": "string" // Business language - }, - "files": [{ - "path": "string", - "action": "modify|create|delete", - "changes": ["string"], - "conflict_risk": "low|medium|high" - }], - "source": { - "tool": "workflow-lite-plan-execute", - "session_id": "string", - "original_id": "string" - } -} -``` - -## TodoWrite Pattern - -Initialization: -```json -[ - {"content": "Lite Plan - Planning", "status": "in_progress", "activeForm": "Planning"}, - {"content": "Execution (unified-execute)", "status": "pending", "activeForm": "Executing tasks"} -] -``` - -After planning completes: -```json -[ - {"content": "Lite Plan - Planning", "status": "completed", "activeForm": "Planning"}, - {"content": "Execution (unified-execute)", "status": "in_progress", "activeForm": "Executing tasks"} -] -``` - -## Core Rules - -1. **Planning phase NEVER modifies project code** — it may write planning artifacts, but all implementation is delegated to unified-execute -2. **All phases serial, no agent delegation** — everything runs inline, no spawn_agent -3. **CLI exploration with search verification** — CLI calls produce findings, ACE/Grep/Glob verify them -4. **`.task/*.json` is the output contract** — individual task JSON files passed to unified-execute-with-file -5. **Progressive loading**: Read phase doc only when about to execute -6. **File-path detection**: Treat input as a file path only if the path exists; do not infer from file extensions - -## Error Handling - -| Error | Resolution | -|-------|------------| -| CLI exploration failure | Skip angle, continue with remaining; fallback gemini → claude | -| Planning phase failure | Display error, offer retry | -| .task/ directory empty | Error: planning phase did not produce output | -| Phase file not found | Error with file path for debugging | - -## Related Skills - -- Collaborative planning: `../collaborative-plan-with-file/SKILL.md` -- Unified execution: `../unified-execute-with-file/SKILL.md` -- Full planning workflow: `../workflow-plan-execute/SKILL.md` diff --git a/.codex/skills/workflow-lite-plan-execute/phases/01-lite-plan.md b/.codex/skills/workflow-lite-plan-execute/phases/01-lite-plan.md deleted file mode 100644 index 09b1586e..00000000 --- a/.codex/skills/workflow-lite-plan-execute/phases/01-lite-plan.md +++ /dev/null @@ -1,595 +0,0 @@ -# Phase 1: Lite Plan - -## Overview - -Serial lightweight planning with CLI-powered exploration and search verification. Produces `.task/TASK-*.json` (one file per task) compatible with `collaborative-plan-with-file` output format, consumable by `unified-execute-with-file`. - -**Core capabilities:** -- Intelligent task analysis with automatic exploration detection -- Serial CLI exploration (ccw cli, default gemini / fallback claude) per angle -- Search verification after each CLI exploration (ACE search, Grep, Glob) -- Interactive clarification after exploration to gather missing information -- Direct planning by Claude (all complexity levels, no agent delegation) -- Unified multi-file task output (`.task/TASK-*.json`) with convergence criteria - -## 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}.md` | Per-angle CLI exploration results (verified) | -| `explorations-manifest.json` | Index of all exploration files | -| `exploration-notes.md` | Synthesized exploration notes (all angles combined) | -| `requirement-analysis.json` | Complexity assessment and session metadata | -| `plan.json` | Plan overview (plan-overview-base-schema) | -| `.task/TASK-*.json` | Multi-file task output (one JSON file per task) | -| `plan.md` | Human-readable summary with execution command | - -**Output Directory**: `{projectRoot}/.workflow/.lite-plan/{session-id}/` - -## Auto Mode Defaults - -When `--yes` or `-y` flag is used: -- **Clarification Questions**: Skipped (no clarification phase) -- **Plan Confirmation**: Auto-selected "Allow" - -**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) - └─ Decision: - ├─ needsExploration=true → Serial CLI exploration (1-4 angles) - │ └─ For each angle: CLI call → Search verification → Save results - └─ needsExploration=false → Skip to Phase 2/3 - -Phase 2: Clarification (optional, multi-round) - ├─ Extract clarification needs from exploration results - ├─ Deduplicate similar questions - └─ ASK_USER (max 4 questions per round, multiple rounds) - -Phase 3: Planning → .task/*.json (NO CODE EXECUTION) - ├─ Load exploration notes + clarifications + project context - ├─ Direct Claude planning (following unified task JSON schema) - ├─ Generate .task/TASK-*.json (one file per task) - └─ Generate plan.md (human-readable summary) - -Phase 4: Confirmation - ├─ Display plan summary (tasks, complexity, dependencies) - └─ ASK_USER: Allow / Modify / Cancel - -Phase 5: Handoff - └─ → unified-execute-with-file with .task/ directory -``` - -## Implementation - -### Phase 1: Serial CLI Exploration with Search Verification - -#### Session Setup (MANDATORY) - -##### Step 0: Determine Project Root - -检测项目根目录，确保 `.workflow/` 产物位置正确： - -```bash -PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd) -``` - -优先通过 git 获取仓库根目录；非 git 项目回退到 `pwd` 取当前绝对路径。 -存储为 `{projectRoot}`，后续所有 `.workflow/` 路径必须以此为前缀。 - -##### Step 1: Generate Session ID - -Generate session ID and create session folder: - -- **Session ID format**: `{task-slug}-{YYYY-MM-DD}` - - `task-slug`: lowercase task description, non-alphanumeric replaced with `-`, max 40 chars - - Date: UTC+8 (China Standard Time), format `2025-11-29` - - Example: `implement-jwt-refresh-2025-11-29` -- **Session Folder**: `{projectRoot}/.workflow/.lite-plan/{session-id}/` -- Create folder via `mkdir -p` and verify existence - -#### Exploration Decision - -Exploration is needed when **ANY** of these conditions are met: - -- `--explore` / `-e` flag is set -- Task mentions specific files -- Task requires codebase context understanding -- Task needs architecture understanding -- Task modifies existing code - -If none apply → skip to Phase 2 (Clarification) or Phase 3 (Planning). - -**⚠️ Context Protection**: If file reading would exceed ≥50k chars → force CLI exploration to delegate context gathering. - -#### Complexity Assessment - -Analyze task complexity based on four dimensions: - -| Dimension | Low | Medium | High | -|-----------|-----|--------|------| -| **Scope** | Single file, isolated | Multiple files, some dependencies | Cross-module, architectural | -| **Depth** | Surface change | Moderate structural impact | Architectural impact | -| **Risk** | Minimal | Moderate | High risk of breaking | -| **Dependencies** | None | Some interconnection | Highly interconnected | - -#### Exploration Angle Selection - -Angles are assigned based on task type keyword matching, then sliced by complexity: - -| Task Type | Keywords | Angle Presets (priority order) | -|-----------|----------|-------------------------------| -| Architecture | refactor, architect, restructure, modular | architecture, dependencies, modularity, integration-points | -| Security | security, auth, permission, access | security, auth-patterns, dataflow, validation | -| Performance | performance, slow, optimi, cache | performance, bottlenecks, caching, data-access | -| Bugfix | fix, bug, error, issue, broken | error-handling, dataflow, state-management, edge-cases | -| Feature (default) | — | patterns, integration-points, testing, dependencies | - -**Angle count by complexity**: Low → 1, Medium → 3, High → 4 - -Display exploration plan summary (complexity, selected angles) before starting. - -#### Serial CLI Exploration Loop - -For each selected exploration angle, execute the following three steps **serially**: - -##### Step A: CLI Exploration Call - -Execute `ccw cli` to explore codebase from the specific angle: - -```bash -ccw cli -p "PURPOSE: Explore codebase from {angle} perspective for task planning context; success = actionable findings with file:line references verified against actual code -TASK: • Analyze project structure relevant to {angle} • Identify files and modules related to {angle} • Discover existing patterns and conventions for {angle} • Find integration points and dependencies (with file:line locations) • Identify constraints and risks from {angle} viewpoint • List questions needing user clarification -MODE: analysis -CONTEXT: @**/* | Memory: Task: {task_description} -EXPECTED: Structured analysis with sections: 1) Project structure overview 2) Relevant files with relevance assessment (high/medium/low) 3) Existing patterns (with code examples) 4) Dependencies 5) Integration points (file:line) 6) Constraints 7) Clarification questions -CONSTRAINTS: Focus on {angle} perspective | Analysis only | Include file:line references" --tool gemini --mode analysis --rule analysis-analyze-code-patterns -``` - -**CLI Tool Selection**: -- Default: `--tool gemini` (gemini-2.5-flash) -- Fallback: `--tool claude` (if gemini fails or is unavailable) - -**Execution Mode**: `Bash({ command: "ccw cli ...", run_in_background: true })` → Wait for completion - -##### Step B: Search Verification - -After CLI exploration returns, verify key findings inline using search tools: - -``` -For each key finding from CLI result: -├─ Files mentioned → Glob to verify existence, Read to verify content -├─ Patterns mentioned → Grep to verify pattern presence in codebase -├─ Integration points → mcp__ace-tool__search_context to verify context accuracy -└─ Dependencies → Grep to verify import/export relationships - -Verification rules: -├─ File exists? → Mark as ✅ verified -├─ File not found? → Mark as ⚠️ unverified, note in output -├─ Pattern confirmed? → Include with code reference -└─ Pattern not found? → Exclude or mark as uncertain -``` - -**Verification Checklist**: -- [ ] All mentioned files verified to exist -- [ ] Patterns described match actual code -- [ ] Integration points confirmed at correct file:line locations -- [ ] Dependencies are accurate (imports/exports verified) - -##### Step C: Save Verified Exploration Results - -Save verified exploration results as Markdown: - -```markdown -# Exploration: {angle} - -**Task**: {task_description} -**Timestamp**: {ISO timestamp} -**CLI Tool**: gemini / claude - ---- - -## Findings - -### Project Structure -{verified structure relevant to this angle} - -### Relevant Files - -| File | Relevance | Rationale | Verified | -|------|-----------|-----------|----------| -| `src/auth/login.ts` | high | Core authentication logic | ✅ | -| `src/middleware/auth.ts` | medium | Auth middleware chain | ✅ | - -### Patterns -{verified patterns with actual code examples from codebase} - -### Integration Points -{verified integration points with file:line references} - -### Dependencies -{verified dependency relationships} - -### Constraints -{angle-specific constraints discovered} - -### Clarification Needs -{questions that need user input, with suggested options} -``` - -**Write**: `{sessionFolder}/exploration-{angle}.md` - -#### Manifest Generation - -After all angle explorations complete: - -1. **Build manifest** — Create `explorations-manifest.json`: - ```javascript - { - session_id: sessionId, - task_description: taskDescription, - timestamp: getUtc8ISOString(), - complexity: complexity, - exploration_count: selectedAngles.length, - explorations: selectedAngles.map((angle, i) => ({ - angle: angle, - file: `exploration-${angle}.md`, - path: `${sessionFolder}/exploration-${angle}.md`, - index: i - })) - } - ``` -2. **Write** — Save to `{sessionFolder}/explorations-manifest.json` - -#### Generate Exploration Notes - -Synthesize all exploration Markdown files into a unified notes document. - -**Steps**: - -1. **Load** all exploration Markdown files via manifest -2. **Extract core files** — Collect all "Relevant Files" tables, deduplicate by path, sort by relevance -3. **Build exploration notes** — 6-part Markdown document (structure below) -4. **Write** to `{sessionFolder}/exploration-notes.md` - -**Exploration Notes Structure** (`exploration-notes.md`): - -```markdown -# Exploration Notes: {task_description} - -**Generated**: {timestamp} | **Complexity**: {complexity} -**Exploration Angles**: {angles} - ---- - -## Part 1: Multi-Angle Exploration Summary -Per angle: Key Files (priority sorted), Code Patterns, Integration Points, Dependencies, Constraints - -## Part 2: Core Files Index -Top 10 files across all angles, with cross-references and structural details - -## Part 3: Architecture Reasoning -Synthesized architectural insights from all angles - -## Part 4: Risks and Mitigations -Derived from explorations and core file analysis - -## Part 5: Clarification Questions Summary -Aggregated from all exploration angles, deduplicated - -## Part 6: Key Code Location Index - -| Component | File Path | Key Lines | Purpose | -|-----------|-----------|-----------|---------| -``` - ---- - -### Phase 2: Clarification (Optional, Multi-Round) - -**Skip Conditions**: No exploration performed OR clarification needs empty across all explorations - -**⚠️ CRITICAL**: ASK_USER limits max 4 questions per call. **MUST execute multiple rounds** to exhaust all clarification needs — do NOT stop at round 1. - -**Flow**: - -``` -1. Load all exploration Markdown files - -2. Extract clarification needs - └─ For each exploration → collect "Clarification Needs" section items - -3. Deduplicate - └─ Intelligent merge: identify similar intent across angles - → combine options, consolidate context - → produce unique-intent questions only - -4. Route by mode: - ├─ --yes mode → Skip all clarifications, log count, proceed to Phase 3 - └─ Interactive mode → Multi-round clarification: - ├─ Batch size: 4 questions per round - ├─ Per round: display "Round N/M", present via ASK_USER - │ └─ Each question: [source_angle] question + context - ├─ Store responses in clarificationContext after each round - └─ Repeat until all questions exhausted -``` - -**Output**: `clarificationContext` (in-memory, keyed by question) - ---- - -### Phase 3: Planning → .task/*.json - -**IMPORTANT**: Phase 3 is **planning only** — NO code execution. All implementation happens via unified-execute-with-file. - -#### Step 3.1: Gather Planning Context - -1. **Read** all exploration Markdown files and `exploration-notes.md` -2. **Read** `{projectRoot}/.workflow/project-tech.json` (if exists) -3. **Read** `{projectRoot}/.workflow/project-guidelines.json` (if exists) -4. **Collect** clarificationContext (if any) - -#### Step 3.2: Generate requirement-analysis.json - -```javascript -Write(`${sessionFolder}/requirement-analysis.json`, JSON.stringify({ - session_id: sessionId, - original_requirement: taskDescription, - complexity: complexity, - exploration_angles: selectedAngles, - total_explorations: selectedAngles.length, - timestamp: getUtc8ISOString() -}, null, 2)) -``` - -#### Step 3.3: Generate .task/*.json - -Direct Claude planning — synthesize exploration findings and clarifications into individual task JSON files: - -**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 -3. **Minimize task count**: Simple, related tasks grouped together (target 2-7 tasks) -4. **Substantial tasks**: Each task should represent meaningful work -5. **True dependencies only**: Only use depends_on when Task B cannot start without Task A's output -6. **Prefer parallel**: Most tasks should be independent (no depends_on) - -**Unified Task JSON Format** (one JSON file per task, stored in `.task/` directory): - -```javascript -{ - id: "TASK-001", // Padded 3-digit ID - title: "...", - description: "...", // Scope/goal + implementation approach - type: "feature", // feature|infrastructure|enhancement|fix|refactor|testing - priority: "medium", // high|medium|low - effort: "medium", // small|medium|large - scope: "...", // Brief scope description - depends_on: [], // TASK-xxx references (empty if independent) - convergence: { - criteria: [ // Testable conditions (2-5 items) - "File src/auth/login.ts exports authenticateUser function", - "Unit test covers both success and failure paths" - ], - verification: "npm test -- --grep auth", // Executable command or manual steps - definition_of_done: "Users can log in with JWT tokens and receive refresh tokens" - }, - files: [ // Files to modify (from exploration findings) - { - path: "src/auth/login.ts", - action: "modify", // modify|create|delete - changes: ["Add JWT token generation", "Add refresh token logic"], - conflict_risk: "low" // low|medium|high - } - ], - source: { - tool: "workflow-lite-plan-execute", - session_id: sessionId, - original_id: "TASK-001" - } -} -``` - -**Write .task/*.json**: -```javascript -// Create .task/ directory -Bash(`mkdir -p ${sessionFolder}/.task`) - -// Write each task as an individual JSON file -tasks.forEach(task => { - Write(`${sessionFolder}/.task/${task.id}.json`, JSON.stringify(task, null, 2)) -}) -``` - -#### Step 3.3.5: Generate plan.json (plan-overview-base-schema) - -Generate plan overview as structured index for `.task/` directory: - -```javascript -// Guard: skip plan.json if no tasks generated -if (tasks.length === 0) { - console.warn('No tasks generated; skipping plan.json') -} else { - -// Build plan overview following plan-overview-base-schema.json -const planOverview = { - summary: requirementUnderstanding, // 2-3 sentence overview from exploration synthesis - approach: approach, // High-level implementation strategy - task_ids: tasks.map(t => t.id), // ["TASK-001", "TASK-002", ...] - task_count: tasks.length, - complexity: complexity, // "Low" | "Medium" | "High" - recommended_execution: "Agent", - _metadata: { - timestamp: getUtc8ISOString(), - source: "direct-planning", - planning_mode: "direct", - plan_type: "feature", - schema_version: "2.0", - exploration_angles: selectedAngles - } -} -Write(`${sessionFolder}/plan.json`, JSON.stringify(planOverview, null, 2)) - -} // end guard -``` - -#### Step 3.4: Generate plan.md - -Create human-readable summary: - -```javascript -const planMd = `# Lite Plan - -**Session**: ${sessionId} -**Requirement**: ${taskDescription} -**Created**: ${getUtc8ISOString()} -**Complexity**: ${complexity} -**Exploration Angles**: ${selectedAngles.join(', ')} - -## 需求理解 - -${requirementUnderstanding} - -## 任务概览 - -| # | ID | Title | Type | Priority | Effort | Dependencies | -|---|-----|-------|------|----------|--------|--------------| -${tasks.map((t, i) => `| ${i+1} | ${t.id} | ${t.title} | ${t.type} | ${t.priority} | ${t.effort} | ${t.depends_on.join(', ') || '-'} |`).join('\n')} - -## 任务详情 - -${tasks.map(t => `### ${t.id}: ${t.title} -- **范围**: ${t.scope} -- **修改文件**: ${t.files.map(f => \`\\\`${f.path}\\\` (${f.action})\`).join(', ')} -- **收敛标准**: -${t.convergence.criteria.map(c => \` - ${c}\`).join('\n')} -- **验证方式**: ${t.convergence.verification} -- **完成定义**: ${t.convergence.definition_of_done} -`).join('\n')} - -## 执行 - -\`\`\`bash -$unified-execute-with-file PLAN="${sessionFolder}/.task/" -\`\`\` - -**Session artifacts**: \`${sessionFolder}/\` -` -Write(`${sessionFolder}/plan.md`, planMd) -``` - ---- - -### Phase 4: Task Confirmation - -#### Step 4.1: Display Plan - -Read `{sessionFolder}/.task/` directory and display summary: - -- **Summary**: Overall approach (from requirement understanding) -- **Tasks**: Numbered list with ID, title, type, effort -- **Complexity**: Assessment result -- **Total tasks**: Count -- **Dependencies**: Graph overview - -#### Step 4.2: Collect Confirmation - -**Route by mode**: - -``` -├─ --yes mode → Auto-confirm: -│ └─ Confirmation: "Allow" -│ -└─ Interactive mode → ASK_USER: - └─ Confirm plan? ({N} tasks, {complexity}) - ├─ Allow (proceed as-is) - ├─ Modify (adjust before execution) - └─ Cancel (abort workflow) -``` - -**Output**: `userSelection` — `{ confirmation: "Allow" | "Modify" | "Cancel" }` - -**Modify Loop**: If "Modify" selected, display current `.task/*.json` content, accept user edits (max 3 rounds), regenerate plan.md, re-confirm. - ---- - -### Phase 5: Handoff to Execution - -**CRITICAL**: lite-plan NEVER executes code directly. ALL execution goes through unified-execute-with-file. - -→ Hand off to Phase 2: `phases/02-lite-execute.md` which invokes `unified-execute-with-file` - -## Session Folder Structure - -``` -{projectRoot}/.workflow/.lite-plan/{session-id}/ -├── exploration-{angle1}.md # CLI exploration angle 1 -├── exploration-{angle2}.md # CLI exploration angle 2 -├── exploration-{angle3}.md # (if applicable) -├── exploration-{angle4}.md # (if applicable) -├── explorations-manifest.json # Exploration index -├── exploration-notes.md # Synthesized exploration notes -├── requirement-analysis.json # Complexity assessment -├── plan.json # ⭐ Plan overview (plan-overview-base-schema.json) -├── .task/ # Task JSON files (one per task) -│ ├── TASK-001.json -│ ├── TASK-002.json -│ └── ... -└── plan.md # Human-readable summary -``` - -**Example**: -``` -{projectRoot}/.workflow/.lite-plan/implement-jwt-refresh-2025-11-25/ -├── exploration-patterns.md -├── exploration-integration-points.md -├── exploration-testing.md -├── explorations-manifest.json -├── exploration-notes.md -├── requirement-analysis.json -├── plan.json -├── .task/ -│ ├── TASK-001.json -│ ├── TASK-002.json -│ └── ... -└── plan.md -``` - -## Error Handling - -| Error | Resolution | -|-------|------------| -| CLI exploration failure | Skip angle, continue with remaining; fallback gemini → claude | -| CLI tool unavailable | Try fallback tool; if all fail, proceed without exploration | -| Search verification failure | Note unverified findings, continue with caution marker | -| Planning failure | Display error, offer retry | -| Clarification timeout | Use exploration findings as-is | -| Confirmation timeout | Save artifacts, display resume instructions | -| Modify loop > 3 times | Suggest using full planning workflow (workflow-plan-execute/SKILL.md) | - ---- - -## Post-Phase Update - -After Phase 1 (Lite Plan) completes: -- **Output Created**: `.task/TASK-*.json` + `plan.md` + exploration artifacts in session folder -- **Session Artifacts**: All files in `{projectRoot}/.workflow/.lite-plan/{session-id}/` -- **Next Action**: Auto-continue to [Phase 2: Execution Handoff](02-lite-execute.md) -- **TodoWrite**: Mark "Lite Plan - Planning" as completed, start "Execution (unified-execute)" diff --git a/.codex/skills/workflow-lite-plan-execute/phases/02-lite-execute.md b/.codex/skills/workflow-lite-plan-execute/phases/02-lite-execute.md deleted file mode 100644 index 9177c379..00000000 --- a/.codex/skills/workflow-lite-plan-execute/phases/02-lite-execute.md +++ /dev/null @@ -1,635 +0,0 @@ -# Phase 2: Execution - -## Overview - -消费 Phase 1 产出的 `.task/*.json` (multi-file task definitions)，串行执行任务并进行收敛验证，通过 `execution.md` + `execution-events.md` 跟踪进度。 - -**Core workflow**: Load .task/*.json → Validate → Pre-Execution Analysis → Execute → Verify Convergence → Track Progress - -**Key features**: -- **Single format**: 只消费 `.task/*.json` (one JSON file per task) -- **Convergence-driven**: 每个任务执行后验证收敛标准 -- **Serial execution**: 按拓扑序串行执行，依赖跟踪 -- **Dual progress tracking**: `execution.md` (概览) + `execution-events.md` (事件流) -- **Auto-commit**: 可选的每任务 conventional commits -- **Dry-run mode**: 模拟执行，不做实际修改 - -## Invocation - -```javascript -$unified-execute-with-file PLAN="${sessionFolder}/.task/" - -// With options -$unified-execute-with-file PLAN="${sessionFolder}/.task/" --auto-commit -$unified-execute-with-file PLAN="${sessionFolder}/.task/" --dry-run -``` - -## Output Structure - -``` -${projectRoot}/.workflow/.execution/EXEC-{slug}-{date}-{random}/ -├── execution.md # Plan overview + task table + summary statistics -└── execution-events.md # Unified event log (single source of truth) -``` - -Additionally, the source `.task/*.json` files are updated in-place with execution states (`status`, `executed_at`, `result`). - ---- - -## Session Initialization - -```javascript -const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() -const projectRoot = Bash(`git rev-parse --show-toplevel 2>/dev/null || pwd`).trim() - -// Parse arguments -const autoCommit = $ARGUMENTS.includes('--auto-commit') -const dryRun = $ARGUMENTS.includes('--dry-run') -const planMatch = $ARGUMENTS.match(/PLAN="([^"]+)"/) || $ARGUMENTS.match(/PLAN=(\S+)/) -let planPath = planMatch ? planMatch[1] : null - -// Auto-detect if no PLAN specified -if (!planPath) { - // Search in order (most recent first): - // .workflow/.lite-plan/*/.task/ - // .workflow/.req-plan/*/.task/ - // .workflow/.planning/*/.task/ - // .workflow/.analysis/*/.task/ - // .workflow/.brainstorm/*/.task/ -} - -// Resolve path -planPath = path.isAbsolute(planPath) ? planPath : `${projectRoot}/${planPath}` - -// Generate session ID -const slug = path.basename(path.dirname(planPath)).toLowerCase().substring(0, 30) -const dateStr = getUtc8ISOString().substring(0, 10) -const random = Math.random().toString(36).substring(2, 9) -const sessionId = `EXEC-${slug}-${dateStr}-${random}` -const sessionFolder = `${projectRoot}/.workflow/.execution/${sessionId}` - -Bash(`mkdir -p ${sessionFolder}`) -``` - ---- - -## Phase 1: Load & Validate - -**Objective**: Parse `.task/*.json` files, validate schema and dependencies, build execution order. - -### Step 1.1: Parse Task JSON Files - -```javascript -// Read all JSON files from .task/ directory -const taskFiles = Glob(`${planPath}/*.json`).sort() -const tasks = taskFiles.map((file, i) => { - try { return JSON.parse(Read(file)) } - catch (e) { throw new Error(`File ${file}: Invalid JSON — ${e.message}`) } -}) - -if (tasks.length === 0) throw new Error('No task files found in .task/ directory') -``` - -### Step 1.2: Validate Schema - -```javascript -const errors = [] -tasks.forEach((task, i) => { - // Required fields - if (!task.id) errors.push(`Task ${i + 1}: missing 'id'`) - if (!task.title) errors.push(`Task ${i + 1}: missing 'title'`) - if (!task.description) errors.push(`Task ${i + 1}: missing 'description'`) - if (!Array.isArray(task.depends_on)) errors.push(`${task.id}: missing 'depends_on' array`) - - // Convergence required - if (!task.convergence) { - errors.push(`${task.id}: missing 'convergence'`) - } else { - if (!task.convergence.criteria?.length) errors.push(`${task.id}: empty convergence.criteria`) - if (!task.convergence.verification) errors.push(`${task.id}: missing convergence.verification`) - if (!task.convergence.definition_of_done) errors.push(`${task.id}: missing convergence.definition_of_done`) - } -}) - -if (errors.length) { - // Report errors, stop execution -} -``` - -### Step 1.3: Build Execution Order - -```javascript -// 1. Validate dependency references -const taskIds = new Set(tasks.map(t => t.id)) -tasks.forEach(task => { - task.depends_on.forEach(dep => { - if (!taskIds.has(dep)) errors.push(`${task.id}: depends on unknown task '${dep}'`) - }) -}) - -// 2. Detect cycles (DFS) -function detectCycles(tasks) { - const graph = new Map(tasks.map(t => [t.id, t.depends_on || []])) - const visited = new Set(), inStack = new Set(), cycles = [] - function dfs(node, path) { - if (inStack.has(node)) { cycles.push([...path, node].join(' → ')); return } - if (visited.has(node)) return - visited.add(node); inStack.add(node) - ;(graph.get(node) || []).forEach(dep => dfs(dep, [...path, node])) - inStack.delete(node) - } - tasks.forEach(t => { if (!visited.has(t.id)) dfs(t.id, []) }) - return cycles -} -const cycles = detectCycles(tasks) -if (cycles.length) errors.push(`Circular dependencies: ${cycles.join('; ')}`) - -// 3. Topological sort -function topoSort(tasks) { - const inDegree = new Map(tasks.map(t => [t.id, 0])) - tasks.forEach(t => t.depends_on.forEach(dep => { - inDegree.set(t.id, (inDegree.get(t.id) || 0) + 1) - })) - const queue = tasks.filter(t => inDegree.get(t.id) === 0).map(t => t.id) - const order = [] - while (queue.length) { - const id = queue.shift() - order.push(id) - tasks.forEach(t => { - if (t.depends_on.includes(id)) { - inDegree.set(t.id, inDegree.get(t.id) - 1) - if (inDegree.get(t.id) === 0) queue.push(t.id) - } - }) - } - return order -} -const executionOrder = topoSort(tasks) -``` - -### Step 1.4: Initialize Execution Artifacts - -```javascript -// execution.md -const executionMd = `# Execution Overview - -## Session Info -- **Session ID**: ${sessionId} -- **Plan Source**: ${planPath} -- **Started**: ${getUtc8ISOString()} -- **Total Tasks**: ${tasks.length} -- **Mode**: ${dryRun ? 'Dry-run (no changes)' : 'Direct inline execution'} -- **Auto-Commit**: ${autoCommit ? 'Enabled' : 'Disabled'} - -## Task Overview - -| # | ID | Title | Type | Priority | Effort | Dependencies | Status | -|---|-----|-------|------|----------|--------|--------------|--------| -${tasks.map((t, i) => `| ${i+1} | ${t.id} | ${t.title} | ${t.type || '-'} | ${t.priority || '-'} | ${t.effort || '-'} | ${t.depends_on.join(', ') || '-'} | pending |`).join('\n')} - -## Pre-Execution Analysis -> Populated in Phase 2 - -## Execution Timeline -> Updated as tasks complete - -## Execution Summary -> Updated after all tasks complete -` -Write(`${sessionFolder}/execution.md`, executionMd) - -// execution-events.md -Write(`${sessionFolder}/execution-events.md`, `# Execution Events - -**Session**: ${sessionId} -**Started**: ${getUtc8ISOString()} -**Source**: ${planPath} - ---- - -`) -``` - ---- - -## Phase 2: Pre-Execution Analysis - -**Objective**: Validate feasibility and identify issues before execution. - -### Step 2.1: Analyze File Conflicts - -```javascript -const fileTaskMap = new Map() // file → [taskIds] -tasks.forEach(task => { - (task.files || []).forEach(f => { - const key = f.path - if (!fileTaskMap.has(key)) fileTaskMap.set(key, []) - fileTaskMap.get(key).push(task.id) - }) -}) - -const conflicts = [] -fileTaskMap.forEach((taskIds, file) => { - if (taskIds.length > 1) { - conflicts.push({ file, tasks: taskIds, resolution: 'Execute in dependency order' }) - } -}) - -// Check file existence -const missingFiles = [] -tasks.forEach(task => { - (task.files || []).forEach(f => { - if (f.action !== 'create' && !file_exists(f.path)) { - missingFiles.push({ file: f.path, task: task.id }) - } - }) -}) -``` - -### Step 2.2: Append to execution.md - -```javascript -// Replace "Pre-Execution Analysis" section with: -// - File Conflicts (list or "No conflicts") -// - Missing Files (list or "All files exist") -// - Dependency Validation (errors or "No issues") -// - Execution Order (numbered list) -``` - -### Step 2.3: User Confirmation - -```javascript -if (!dryRun) { - AskUserQuestion({ - questions: [{ - question: `Execute ${tasks.length} tasks?\n\n${conflicts.length ? `⚠ ${conflicts.length} file conflicts\n` : ''}Execution order:\n${executionOrder.map((id, i) => ` ${i+1}. ${id}: ${tasks.find(t => t.id === id).title}`).join('\n')}`, - header: "Confirm", - multiSelect: false, - options: [ - { label: "Execute", description: "Start serial execution" }, - { label: "Dry Run", description: "Simulate without changes" }, - { label: "Cancel", description: "Abort execution" } - ] - }] - }) -} -``` - ---- - -## Phase 3: Serial Execution + Convergence Verification - -**Objective**: Execute tasks sequentially, verify convergence after each task, track all state. - -**Execution Model**: Direct inline execution — main process reads, edits, writes files directly. No CLI delegation. - -### Step 3.1: Execution Loop - -```javascript -const completedTasks = new Set() -const failedTasks = new Set() -const skippedTasks = new Set() - -for (const taskId of executionOrder) { - const task = tasks.find(t => t.id === taskId) - const startTime = getUtc8ISOString() - - // 1. Check dependencies - const unmetDeps = task.depends_on.filter(dep => !completedTasks.has(dep)) - if (unmetDeps.length) { - appendToEvents(task, 'BLOCKED', `Unmet dependencies: ${unmetDeps.join(', ')}`) - skippedTasks.add(task.id) - task.status = 'skipped' - task.executed_at = startTime - task.result = { success: false, error: `Blocked by: ${unmetDeps.join(', ')}` } - continue - } - - // 2. Record START event - appendToEvents(`## ${getUtc8ISOString()} — ${task.id}: ${task.title} - -**Type**: ${task.type || '-'} | **Priority**: ${task.priority || '-'} | **Effort**: ${task.effort || '-'} -**Status**: ⏳ IN PROGRESS -**Files**: ${(task.files || []).map(f => f.path).join(', ') || 'To be determined'} -**Description**: ${task.description} -**Convergence Criteria**: -${task.convergence.criteria.map(c => `- [ ] ${c}`).join('\n')} - -### Execution Log -`) - - if (dryRun) { - // Simulate: mark as completed without changes - appendToEvents(`\n**Status**: ⏭ DRY RUN (no changes)\n\n---\n`) - task.status = 'completed' - task.executed_at = startTime - task.result = { success: true, summary: 'Dry run — no changes made' } - completedTasks.add(task.id) - continue - } - - // 3. Execute task directly - // - Read each file in task.files (if specified) - // - Analyze what changes satisfy task.description + task.convergence.criteria - // - If task.files has detailed changes, use them as guidance - // - Apply changes using Edit (preferred) or Write (for new files) - // - Use Grep/Glob/mcp__ace-tool for discovery if needed - // - Use Bash for build/test commands - - // 4. Verify convergence - const convergenceResults = verifyConvergence(task) - - const endTime = getUtc8ISOString() - const filesModified = getModifiedFiles() - - if (convergenceResults.allPassed) { - // 5a. Record SUCCESS - appendToEvents(` -**Status**: ✅ COMPLETED -**Duration**: ${calculateDuration(startTime, endTime)} -**Files Modified**: ${filesModified.join(', ')} - -#### Changes Summary -${changeSummary} - -#### Convergence Verification -${task.convergence.criteria.map((c, i) => `- [${convergenceResults.verified[i] ? 'x' : ' '}] ${c}`).join('\n')} -- **Verification**: ${convergenceResults.verificationOutput} -- **Definition of Done**: ${task.convergence.definition_of_done} - ---- -`) - task.status = 'completed' - task.executed_at = endTime - task.result = { - success: true, - files_modified: filesModified, - summary: changeSummary, - convergence_verified: convergenceResults.verified - } - completedTasks.add(task.id) - } else { - // 5b. Record FAILURE - handleTaskFailure(task, convergenceResults, startTime, endTime) - } - - // 6. Auto-commit if enabled - if (autoCommit && task.status === 'completed') { - autoCommitTask(task, filesModified) - } -} -``` - -### Step 3.2: Convergence Verification - -```javascript -function verifyConvergence(task) { - const results = { - verified: [], // boolean[] per criterion - verificationOutput: '', // output of verification command - allPassed: true - } - - // 1. Check each criterion - // For each criterion in task.convergence.criteria: - // - If it references a testable condition, check it - // - If it's manual, mark as verified based on changes made - // - Record true/false per criterion - task.convergence.criteria.forEach(criterion => { - const passed = evaluateCriterion(criterion, task) - results.verified.push(passed) - if (!passed) results.allPassed = false - }) - - // 2. Run verification command (if executable) - const verification = task.convergence.verification - if (isExecutableCommand(verification)) { - try { - const output = Bash(verification, { timeout: 120000 }) - results.verificationOutput = `${verification} → PASS` - } catch (e) { - results.verificationOutput = `${verification} → FAIL: ${e.message}` - results.allPassed = false - } - } else { - results.verificationOutput = `Manual: ${verification}` - } - - return results -} - -function isExecutableCommand(verification) { - // Detect executable patterns: npm, npx, jest, tsc, curl, pytest, go test, etc. - return /^(npm|npx|jest|tsc|eslint|pytest|go\s+test|cargo\s+test|curl|make)/.test(verification.trim()) -} -``` - -### Step 3.3: Failure Handling - -```javascript -function handleTaskFailure(task, convergenceResults, startTime, endTime) { - appendToEvents(` -**Status**: ❌ FAILED -**Duration**: ${calculateDuration(startTime, endTime)} -**Error**: Convergence verification failed - -#### Failed Criteria -${task.convergence.criteria.map((c, i) => `- [${convergenceResults.verified[i] ? 'x' : ' '}] ${c}`).join('\n')} -- **Verification**: ${convergenceResults.verificationOutput} - ---- -`) - - task.status = 'failed' - task.executed_at = endTime - task.result = { - success: false, - error: 'Convergence verification failed', - convergence_verified: convergenceResults.verified - } - failedTasks.add(task.id) - - // Ask user - AskUserQuestion({ - questions: [{ - question: `Task ${task.id} failed convergence verification. How to proceed?`, - header: "Failure", - multiSelect: false, - options: [ - { label: "Skip & Continue", description: "Skip this task, continue with next" }, - { label: "Retry", description: "Retry this task" }, - { label: "Accept", description: "Mark as completed despite failure" }, - { label: "Abort", description: "Stop execution, keep progress" } - ] - }] - }) -} -``` - -### Step 3.4: Auto-Commit - -```javascript -function autoCommitTask(task, filesModified) { - Bash(`git add ${filesModified.join(' ')}`) - - const commitType = { - fix: 'fix', refactor: 'refactor', feature: 'feat', - enhancement: 'feat', testing: 'test', infrastructure: 'chore' - }[task.type] || 'chore' - - const scope = inferScope(filesModified) - - Bash(`git commit -m "$(cat <<'EOF' -${commitType}(${scope}): ${task.title} - -Task: ${task.id} -Source: ${path.basename(planPath)} -EOF -)"`) - - appendToEvents(`**Commit**: \`${commitType}(${scope}): ${task.title}\`\n`) -} -``` - ---- - -## Phase 4: Completion - -**Objective**: Finalize all artifacts, write back execution state, offer follow-up actions. - -### Step 4.1: Finalize execution.md - -Append summary statistics to execution.md: - -```javascript -const summary = ` -## Execution Summary - -- **Completed**: ${getUtc8ISOString()} -- **Total Tasks**: ${tasks.length} -- **Succeeded**: ${completedTasks.size} -- **Failed**: ${failedTasks.size} -- **Skipped**: ${skippedTasks.size} -- **Success Rate**: ${Math.round(completedTasks.size / tasks.length * 100)}% - -### Task Results - -| ID | Title | Status | Convergence | Files Modified | -|----|-------|--------|-------------|----------------| -${tasks.map(t => { - const ex = t || {} - const convergenceStatus = ex.result?.convergence_verified - ? `${ex.result.convergence_verified.filter(v => v).length}/${ex.result.convergence_verified.length}` - : '-' - return `| ${t.id} | ${t.title} | ${ex.status || 'pending'} | ${convergenceStatus} | ${(ex.result?.files_modified || []).join(', ') || '-'} |` -}).join('\n')} - -${failedTasks.size > 0 ? `### Failed Tasks - -${[...failedTasks].map(id => { - const t = tasks.find(t => t.id === id) - return `- **${t.id}**: ${t.title} — ${t.result?.error || 'Unknown'}` -}).join('\n')} -` : ''} -### Artifacts -- **Plan Source**: ${planPath} -- **Execution Overview**: ${sessionFolder}/execution.md -- **Execution Events**: ${sessionFolder}/execution-events.md -` -// Append to execution.md -``` - -### Step 4.2: Finalize execution-events.md - -```javascript -appendToEvents(` ---- - -# Session Summary - -- **Session**: ${sessionId} -- **Completed**: ${getUtc8ISOString()} -- **Tasks**: ${completedTasks.size} completed, ${failedTasks.size} failed, ${skippedTasks.size} skipped -- **Total Events**: ${completedTasks.size + failedTasks.size + skippedTasks.size} -`) -``` - -### Step 4.3: Write Back .task/*.json with Execution State - -Update each task JSON file in-place with execution state: - -```javascript -tasks.forEach(task => { - const taskFile = `${planPath}/${task.id}.json` - Write(taskFile, JSON.stringify(task, null, 2)) -}) -// Each task now has status, executed_at, result fields -``` - -**Execution State** (added to each task JSON file): - -```javascript -{ - // ... original task fields ... - status: "completed" | "failed" | "skipped", - executed_at: "ISO timestamp", - result: { - success: boolean, - files_modified: string[], // list of modified file paths - summary: string, // change description - convergence_verified: boolean[], // per criterion - error: string // if failed - } -} -``` - -### Step 4.4: Post-Completion Options - -```javascript -AskUserQuestion({ - questions: [{ - question: `Execution complete: ${completedTasks.size}/${tasks.length} succeeded (${Math.round(completedTasks.size / tasks.length * 100)}%).\nNext step:`, - header: "Post-Execute", - multiSelect: false, - options: [ - { label: "Retry Failed", description: `Re-execute ${failedTasks.size} failed tasks` }, - { label: "View Events", description: "Display execution-events.md" }, - { label: "Create Issue", description: "Create issue from failed tasks" }, - { label: "Done", description: "End workflow" } - ] - }] -}) -``` - -| Selection | Action | -|-----------|--------| -| Retry Failed | Filter tasks with `status === 'failed'`, re-execute, append `[RETRY]` events | -| View Events | Display execution-events.md content | -| Create Issue | `$issue:new` from failed task details | -| Done | Display artifact paths, end workflow | - ---- - -## Error Handling & Recovery - -| Situation | Action | Recovery | -|-----------|--------|----------| -| .task/ directory not found | Report error with path | Check path, verify planning phase output | -| Invalid JSON file | Report filename and error | Fix task JSON file manually | -| Missing convergence | Report validation error | Add convergence fields to tasks | -| Circular dependency | Stop, report cycle path | Fix dependencies in task files | -| Task execution fails | Record in events, ask user | Retry, skip, accept, or abort | -| Convergence verification fails | Mark task failed, ask user | Fix code and retry, or accept | -| Verification command timeout | Mark as unverified | Manual verification needed | -| File conflict during execution | Document in events | Resolve in dependency order | -| All tasks fail | Report, suggest plan review | Re-analyze or manual intervention | - ---- - -## Post-Completion - -After execution completes, the workflow is finished. - -- **TodoWrite**: Mark "Execution (unified-execute)" as completed -- **Summary**: Display execution statistics (succeeded/failed/skipped counts) -- **Artifacts**: Point user to execution.md and execution-events.md paths diff --git a/.codex/skills/workflow-plan-execute/SKILL.md b/.codex/skills/workflow-plan-execute/SKILL.md deleted file mode 100644 index 67315094..00000000 --- a/.codex/skills/workflow-plan-execute/SKILL.md +++ /dev/null @@ -1,453 +0,0 @@ ---- -name: workflow-plan-execute -description: 4-phase planning+execution workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs, optional Phase 4 execution. Triggers on "workflow:plan". -allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep ---- - -# Workflow Plan - -4-phase workflow that orchestrates session discovery, context gathering (with inline conflict resolution), task generation, and conditional execution to produce and implement plans (IMPL_PLAN.md, task JSONs, TODO_LIST.md). - -## Architecture Overview - -``` -┌──────────────────────────────────────────────────────────────────────┐ -│ Workflow Plan Orchestrator (SKILL.md) │ -│ → Pure coordinator: Execute phases, parse outputs, pass context │ -└───────────────┬──────────────────────────────────────────────────────┘ - │ - ┌───────────┼───────────┬───────────┬───────────┐ - ↓ ↓ ↓ ↓ ↓ -┌─────────┐ ┌──────────────────┐ ┌─────────┐ ┌─────────┐ -│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │ -│ Session │ │ Context Gather │ │ Task │ │Execute │ -│Discovery│ │& Conflict Resolve│ │Generate │ │(optional)│ -└─────────┘ └──────────────────┘ └─────────┘ └─────────┘ - ↓ ↓ ↓ ↓ - sessionId contextPath IMPL_PLAN.md summaries - conflict_risk task JSONs completed - resolved TODO_LIST.md tasks -``` - -## 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. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent -4. **Progressive Phase Loading**: Phase docs are read on-demand, not all at once -5. **Inline Conflict Resolution**: Conflicts detected and resolved within Phase 2 (not a separate phase) -6. **Role Path Loading**: Subagent roles loaded via path reference in MANDATORY FIRST STEPS - -## Auto Mode - -When `--yes` or `-y`: Auto-continue all phases (skip confirmations), use recommended conflict resolutions, auto-execute Phase 4. - -When `--with-commit`: Auto-commit after each task completion in Phase 4. - -## Prep Package Integration - -When `plan-prep-package.json` exists at `{projectRoot}/.workflow/.prep/plan-prep-package.json`, the skill consumes it with 6-point validation: - -1. **Phase 1**: Use `task.structured` (GOAL/SCOPE/CONTEXT) for session creation, enrich planning-notes.md with source_refs and quality dimensions -2. **Phase 2**: Feed verified source_refs as supplementary docs for exploration agents -3. **Phase 3**: Auto-populate Phase 0 User Configuration (execution_method, preferred_cli_tool, supplementary_materials) — skip interactive questions -4. **Phase 4**: Apply `execution.with_commit` flag - -Prep packages are generated by the interactive prompt `/prompts:prep-plan`. See [phases/00-prep-checklist.md](phases/00-prep-checklist.md) for schema and validation rules. - -## Execution Flow - -``` -Input Parsing: - └─ Convert user input to structured format (GOAL/SCOPE/CONTEXT) - -Phase 1: Session Discovery - └─ Ref: phases/01-session-discovery.md - └─ Output: sessionId (WFS-xxx) - -Phase 2: Context Gathering & Conflict Resolution - └─ Ref: phases/02-context-gathering.md - ├─ Step 1: Context-Package Detection - ├─ Step 2: Complexity Assessment & Parallel Explore (conflict-aware) - ├─ Step 3: Inline Conflict Resolution (conditional, if significant conflicts) - ├─ Step 4: Invoke Context-Search Agent (with exploration + conflict results) - ├─ Step 5: Output Verification - └─ Output: contextPath + conflict_risk + optional conflict-resolution.json - -Phase 3: Task Generation - └─ Ref: phases/03-task-generation.md - └─ Output: plan.json, IMPL_PLAN.md, task JSONs, TODO_LIST.md - └─ Schema: plan.json follows plan-overview-base-schema.json; .task/IMPL-*.json follows task-schema.json - -User Decision (or --yes auto): - └─ "Start Execution" → Phase 4 - └─ "Verify Plan Quality" → workflow:plan-verify - └─ "Review Status Only" → workflow:status - -Phase 4: Execution (Conditional) - └─ Ref: phases/04-execution.md - └─ Output: completed tasks, summaries, session completion -``` - -**Phase Reference Documents** (read on-demand when phase executes): - -| Phase | Document | Purpose | -|-------|----------|---------| -| 1 | [phases/01-session-discovery.md](phases/01-session-discovery.md) | Session creation/discovery with intelligent session management | -| 2 | [phases/02-context-gathering.md](phases/02-context-gathering.md) | Context collection + inline conflict resolution | -| 3 | [phases/03-task-generation.md](phases/03-task-generation.md) | Implementation plan and task JSON generation | -| 4 | [phases/04-execution.md](phases/04-execution.md) | Task execution (conditional, triggered by user or --yes) | - -## Core Rules - -1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution -2. **No Preliminary Analysis**: Do not read files, analyze structure, or gather context before Phase 1 -3. **Parse Every Output**: Extract required data from each phase output 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. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute -7. **DO NOT STOP**: Continuous multi-phase workflow. After completing each phase, immediately proceed to next -8. **Explicit Lifecycle**: Always close_agent after wait completes to free resources - -## 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: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.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 }) -``` - -## Input Processing - -**Convert User Input to Structured Format**: - -1. **Simple Text** → Structure it: - ``` - User: "Build authentication system" - - Structured: - GOAL: Build authentication system - SCOPE: Core authentication features - CONTEXT: New implementation - ``` - -2. **Detailed Text** → Extract components: - ``` - User: "Add JWT authentication with email/password login and token refresh" - - Structured: - GOAL: Implement JWT-based authentication - SCOPE: Email/password login, token generation, token refresh endpoints - CONTEXT: JWT token-based security, refresh token rotation - ``` - -3. **File Reference** (e.g., `requirements.md`) → Read and structure: - - Read file content - - Extract goal, scope, requirements - - Format into structured description - -## Data Flow - -``` -User Input (task description) - ↓ -[Convert to Structured Format] - ↓ Structured Description: - ↓ GOAL: [objective] - ↓ SCOPE: [boundaries] - ↓ CONTEXT: [background] - ↓ -Phase 1: session:start --auto "structured-description" - ↓ Output: sessionId - ↓ Write: planning-notes.md (User Intent section) - ↓ -Phase 2: context-gather --session sessionId "structured-description" - ↓ Input: sessionId + structured description - ↓ Step 2: Parallel exploration (with conflict detection) - ↓ Step 3: Inline conflict resolution (if significant conflicts detected) - ↓ Step 4: Context-search-agent packaging - ↓ Output: contextPath (context-package.json with prioritized_context) - ↓ + optional conflict-resolution.json - ↓ Update: planning-notes.md (Context Findings + Conflict Decisions + Consolidated Constraints) - ↓ -Phase 3: task-generate-agent --session sessionId - ↓ Input: sessionId + planning-notes.md + context-package.json + brainstorm artifacts - ↓ Output: plan.json, IMPL_PLAN.md, task JSONs, TODO_LIST.md - ↓ -User Decision: "Start Execution" / --yes auto - ↓ -Phase 4: Execute tasks (conditional) - ↓ Input: sessionId + IMPL_PLAN.md + TODO_LIST.md + .task/*.json - ↓ Loop: lazy load → spawn_agent → wait → close_agent → commit (optional) - ↓ Output: completed tasks, summaries, session completion -``` - -**Session Memory Flow**: Each phase receives session ID, which provides access to: -- Previous task summaries -- Existing context and analysis -- Brainstorming artifacts (potentially modified by Phase 2 conflict resolution) -- Session-specific configuration - -## TodoWrite Pattern - -**Core Concept**: Dynamic task attachment and collapse for real-time visibility into workflow execution. - -### Key Principles - -1. **Task Attachment** (when phase executed): - - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite - - **Phase 2**: Multiple sub-tasks attached (e.g., explore, conflict resolution, context packaging) - - **Phase 3**: Single agent task attached - - First attached task marked as `in_progress`, others as `pending` - - Orchestrator **executes** these attached tasks sequentially - -2. **Task Collapse** (after sub-tasks complete): - - **Applies to Phase 2**: Remove detailed sub-tasks from TodoWrite - - **Collapse** to high-level phase summary - - **Phase 3**: No collapse needed (single task, just mark completed) - - Maintains clean orchestrator-level view - -3. **Continuous Execution**: - - After completion, automatically proceed to next pending phase - - No user intervention required between phases - - TodoWrite dynamically reflects current execution state - -**Lifecycle**: Initial pending tasks → Phase executed (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED) → Next phase begins → Repeat until all phases complete. - -## Phase-Specific TodoWrite Updates - -### Phase 2 (Tasks Attached): -```json -[ - {"content": "Phase 1: Session Discovery", "status": "completed"}, - {"content": "Phase 2: Context Gathering & Conflict Resolution", "status": "in_progress"}, - {"content": " → Parallel exploration (conflict-aware)", "status": "in_progress"}, - {"content": " → Inline conflict resolution (if needed)", "status": "pending"}, - {"content": " → Context-search-agent packaging", "status": "pending"}, - {"content": "Phase 3: Task Generation", "status": "pending"} -] -``` - -### Phase 2 (Collapsed): -```json -[ - {"content": "Phase 1: Session Discovery", "status": "completed"}, - {"content": "Phase 2: Context Gathering & Conflict Resolution", "status": "completed"}, - {"content": "Phase 3: Task Generation", "status": "pending"} -] -``` - -### Phase 4 (Tasks Attached, conditional): -```json -[ - {"content": "Phase 1: Session Discovery", "status": "completed"}, - {"content": "Phase 2: Context Gathering & Conflict Resolution", "status": "completed"}, - {"content": "Phase 3: Task Generation", "status": "completed"}, - {"content": "Phase 4: Execution", "status": "in_progress"}, - {"content": " → IMPL-1: [task title]", "status": "in_progress"}, - {"content": " → IMPL-2: [task title]", "status": "pending"}, - {"content": " → IMPL-3: [task title]", "status": "pending"} -] -``` - -## Planning Notes Template - -After Phase 1, create `planning-notes.md` with this structure: - -```markdown -# Planning Notes - -**Session**: ${sessionId} -**Created**: ${timestamp} - -## User Intent (Phase 1) - -- **GOAL**: ${userGoal} -- **KEY_CONSTRAINTS**: ${userConstraints} - ---- - -## Context Findings (Phase 2) -(To be filled by context-gather) - -## Conflict Decisions (Phase 2) -(To be filled if conflicts detected) - -## Consolidated Constraints (Phase 3 Input) -1. ${userConstraints} - ---- - -## Task Generation (Phase 3) -(To be filled by action-planning-agent) - -## N+1 Context -### Decisions -| Decision | Rationale | Revisit? | -|----------|-----------|----------| - -### Deferred -- [ ] (For N+1) -``` - -## Post-Phase Updates - -### After Phase 2 - -Read context-package to extract key findings, update planning-notes.md: -- `Context Findings (Phase 2)`: CRITICAL_FILES, ARCHITECTURE, CONFLICT_RISK, CONSTRAINTS -- `Conflict Decisions (Phase 2)`: RESOLVED, CUSTOM_HANDLING, CONSTRAINTS (if conflicts were resolved inline) -- `Consolidated Constraints`: Append Phase 2 constraints (context + conflict) - -### Memory State Check - -After Phase 2, evaluate context window usage. If memory usage is high (>120K tokens): -```javascript -// Codex: Use compact command if available -codex compact -``` - -## Phase 3 User Decision - -After Phase 3 completes, present user with action choices. - -**Auto Mode** (`--yes`): Skip user decision, directly enter Phase 4 (Execution). - -```javascript -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') - -if (autoYes) { - // Auto mode: Skip decision, proceed to Phase 4 - console.log(`[--yes] Auto-continuing to Phase 4: Execution`) - // Read phases/04-execution.md and execute Phase 4 -} else { - ASK_USER([{ - id: "phase3-next-action", - type: "select", - prompt: "Planning complete. What would you like to do next?", - options: [ - { - label: "Verify Plan Quality (Recommended)", - description: "Run quality verification to catch issues before execution." - }, - { - label: "Start Execution", - description: "Begin implementing tasks immediately (Phase 4)." - }, - { - label: "Review Status Only", - description: "View task breakdown and session status without taking further action." - } - ] - }]) // BLOCKS (wait for user response) -} - -// Execute based on user choice -// "Verify Plan Quality" → workflow:plan-verify --session sessionId -// "Start Execution" → Read phases/04-execution.md, execute Phase 4 inline -// "Review Status Only" → workflow:status --session sessionId -``` - -## Error Handling - -- **Parsing Failure**: If output parsing fails, retry command once, then report error -- **Validation Failure**: If validation fails, report which file/data is missing -- **Command Failure**: Keep phase `in_progress`, report error to user, do not proceed to next phase -- **Subagent Timeout**: If wait times out, evaluate whether to continue waiting or send_input to prompt completion - -## Coordinator Checklist - -- **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT) -- Parse flags: `--yes`, `--with-commit` -- Initialize TodoWrite before any command -- Execute Phase 1 immediately with structured description -- Parse session ID from Phase 1 output, store in memory -- Pass session ID and structured description to Phase 2 command -- Parse context path from Phase 2 output, store in memory -- **Phase 2 handles conflict resolution inline** (no separate Phase 3 decision needed) -- **Build Phase 3 command**: workflow:tools:task-generate-agent --session [sessionId] -- Verify all Phase 3 outputs -- **Phase 3 User Decision**: Present choices or auto-continue if `--yes` -- **Phase 4 (conditional)**: If user selects "Start Execution" or `--yes`, read phases/04-execution.md and execute -- Pass `--with-commit` flag to Phase 4 if present -- Update TodoWrite after each phase -- After each phase, automatically continue to next phase based on TodoList status -- **Always close_agent after wait completes** - -## Task JSON Schema Compatibility - -Phase 3 generates `.task/IMPL-*.json` files using the **6-field schema** defined in `action-planning-agent.md`. These task JSONs are a **superset** of the unified `task-schema.json` (located at `.ccw/workflows/cli-templates/schemas/task-schema.json`). - -**Key field mappings** (6-field → unified schema): -- `context.acceptance` → `convergence.criteria` -- `context.requirements` → `description` + `implementation` -- `context.depends_on` → `depends_on` (top-level) -- `context.focus_paths` → `focus_paths` (top-level) -- `meta.type` → `type` (top-level) -- `flow_control.target_files` → `files[].path` - -All existing 6-field schema fields are preserved. The unified schema fields are accepted as optional aliases for cross-tool interoperability. See `action-planning-agent.md` Section 2.1 "Schema Compatibility" for the full mapping table. - -## Related Commands - -**Prerequisite Commands**: -- `workflow:brainstorm:artifacts` - Optional: Generate role-based analyses before planning -- `workflow:brainstorm:synthesis` - Optional: Refine brainstorm analyses with clarifications - -**Follow-up Commands**: -- `workflow:plan-verify` - Recommended: Verify plan quality before execution -- `workflow:status` - Review task breakdown and current progress -- `workflow:execute` - Begin implementation (also available via Phase 4 inline execution) diff --git a/.codex/skills/workflow-plan-execute/phases/00-prep-checklist.md b/.codex/skills/workflow-plan-execute/phases/00-prep-checklist.md deleted file mode 100644 index 3a0e8f3c..00000000 --- a/.codex/skills/workflow-plan-execute/phases/00-prep-checklist.md +++ /dev/null @@ -1,181 +0,0 @@ -# Prep Package Schema & Integration Spec - -Schema definition for `plan-prep-package.json` and integration points with the workflow-plan-execute skill. - -## File Location - -``` -{projectRoot}/.workflow/.prep/plan-prep-package.json -``` - -Generated by: `/prompts:prep-plan` (interactive prompt) -Consumed by: Phase 1 (Session Discovery) → feeds into Phase 2, 3, 4 - -## JSON Schema - -```json -{ - "version": "1.0.0", - "generated_at": "ISO8601", - "prep_status": "ready | needs_refinement | blocked", - "target_skill": "workflow-plan-execute", - - "environment": { - "project_root": "/path/to/project", - "prerequisites": { - "required_passed": true, - "recommended_passed": true, - "warnings": ["string"] - }, - "tech_stack": "string", - "test_framework": "string", - "has_project_tech": true, - "has_project_guidelines": true - }, - - "task": { - "original": "raw user input", - "structured": { - "goal": "GOAL string (objective + success criteria)", - "scope": "SCOPE string (boundaries)", - "context": "CONTEXT string (constraints + tech context)" - }, - "quality_score": 8, - "dimensions": { - "objective": { "score": 2, "value": "..." }, - "success_criteria": { "score": 2, "value": "..." }, - "scope": { "score": 2, "value": "..." }, - "constraints": { "score": 1, "value": "..." }, - "context": { "score": 1, "value": "..." } - }, - "source_refs": [ - { - "path": "docs/prd.md", - "type": "local_file | url | auto_detected", - "status": "verified | linked | not_found", - "preview": "first ~20 lines (local_file only)" - } - ] - }, - - "execution": { - "auto_yes": true, - "with_commit": true, - "execution_method": "agent | cli | hybrid", - "preferred_cli_tool": "codex | gemini | qwen | auto", - "supplementary_materials": { - "type": "none | paths | inline", - "content": [] - } - } -} -``` - -## Validation Rules (6 checks) - -Phase 1 对 plan-prep-package.json 执行 **6 项验证**，全部通过才加载： - -| # | 检查项 | 条件 | 失败处理 | -|---|--------|------|----------| -| 1 | prep_status | `=== "ready"` | 跳过 prep | -| 2 | target_skill | `=== "workflow-plan-execute"` | 跳过 prep（防错误 skill） | -| 3 | project_root | 与当前 projectRoot 一致 | 跳过 prep（防错误项目） | -| 4 | quality_score | `>= 6` | 跳过 prep（任务质量不达标） | -| 5 | 时效性 | generated_at 在 24h 以内 | 跳过 prep（可能过期） | -| 6 | 必需字段 | task.structured.goal, execution 全部存在 | 跳过 prep | - -## Phase 1 Integration (Session Discovery) - -After session creation, enrich planning-notes.md with prep data: - -```javascript -const prepPath = `${projectRoot}/.workflow/.prep/plan-prep-package.json` -let prepPackage = null - -if (fs.existsSync(prepPath)) { - const raw = JSON.parse(Read(prepPath)) - const checks = validatePlanPrepPackage(raw, projectRoot) - - if (checks.valid) { - prepPackage = raw - // Use structured task for session creation - structuredDescription = { - goal: prepPackage.task.structured.goal, - scope: prepPackage.task.structured.scope, - context: prepPackage.task.structured.context - } - console.log(`✓ Prep package loaded: score=${prepPackage.task.quality_score}/10`) - } else { - console.warn(`⚠ Prep package validation failed, using defaults`) - } -} - -// After session created, enrich planning-notes.md: -if (prepPackage) { - // 1. Add source refs section - const sourceRefsSection = prepPackage.task.source_refs - ?.filter(r => r.status === 'verified' || r.status === 'linked') - .map(r => `- **${r.type}**: ${r.path}`) - .join('\n') || 'None' - - // 2. Add quality dimensions - const dimensionsSection = Object.entries(prepPackage.task.dimensions) - .map(([k, v]) => `- **${k}**: ${v.value} (score: ${v.score}/2)`) - .join('\n') - - // Append to planning-notes.md under User Intent - Edit(planningNotesPath, { - old: `- **KEY_CONSTRAINTS**: ${userConstraints}`, - new: `- **KEY_CONSTRAINTS**: ${userConstraints} - -### Requirement Sources (from prep) -${sourceRefsSection} - -### Quality Dimensions (from prep) -${dimensionsSection}` - }) -} -``` - -## Phase 3 Integration (Task Generation - Phase 0 User Config) - -Prep package auto-populates Phase 0 user configuration: - -```javascript -// In Phase 3, Phase 0 (User Configuration): -if (prepPackage) { - // Auto-answer all Phase 0 questions from prep - userConfig = { - supplementaryMaterials: prepPackage.execution.supplementary_materials, - executionMethod: prepPackage.execution.execution_method, - preferredCliTool: prepPackage.execution.preferred_cli_tool, - enableResume: true - } - console.log(`✓ Phase 0 auto-configured from prep: ${userConfig.executionMethod} (${userConfig.preferredCliTool})`) - // Skip interactive questions, proceed to Phase 1 (Context Prep) -} -``` - -## Phase 2 Integration (Context Gathering) - -Source refs from prep feed into exploration context: - -```javascript -// In Phase 2, Step 2 (spawn explore agents): -// Add source_refs as supplementary context for exploration -if (prepPackage?.task?.source_refs?.length > 0) { - const verifiedRefs = prepPackage.task.source_refs.filter(r => r.status === 'verified') - // Include verified local docs in exploration agent prompt - explorationAgentPrompt += `\n## SUPPLEMENTARY REQUIREMENT DOCUMENTS\n` - explorationAgentPrompt += verifiedRefs.map(r => `Read and analyze: ${r.path}`).join('\n') -} -``` - -## Phase 4 Integration (Execution) - -Commit flag from prep: - -```javascript -// In Phase 4: -const withCommit = prepPackage?.execution?.with_commit || $ARGUMENTS.includes('--with-commit') -``` diff --git a/.codex/skills/workflow-plan-execute/phases/01-session-discovery.md b/.codex/skills/workflow-plan-execute/phases/01-session-discovery.md deleted file mode 100644 index fa003423..00000000 --- a/.codex/skills/workflow-plan-execute/phases/01-session-discovery.md +++ /dev/null @@ -1,379 +0,0 @@ -# Phase 1: Session Discovery - -Discover existing sessions or start new workflow session with intelligent session management and conflict detection. - -## Objective - -- Ensure project-level state exists (first-time initialization) -- Create or discover workflow session for the planning workflow -- Generate unique session ID (WFS-xxx format) -- Initialize session directory structure - -## Step 0.0: Load Prep Package (if exists) - -```javascript -// Load plan-prep-package.json (generated by /prompts:prep-plan) -let prepPackage = null -const prepPath = `${projectRoot}/.workflow/.prep/plan-prep-package.json` - -if (fs.existsSync(prepPath)) { - const raw = JSON.parse(Read(prepPath)) - const checks = validatePlanPrepPackage(raw, projectRoot) - - if (checks.valid) { - prepPackage = raw - console.log(`✓ Prep package loaded: score=${prepPackage.task.quality_score}/10, exec=${prepPackage.execution.execution_method}`) - console.log(` Checks passed: ${checks.passed.join(', ')}`) - } else { - console.warn(`⚠ Prep package found but failed validation:`) - checks.failures.forEach(f => console.warn(` ✗ ${f}`)) - console.warn(` → Falling back to default behavior (prep-package ignored)`) - prepPackage = null - } -} - -/** - * Validate plan-prep-package.json integrity before consumption. - */ -function validatePlanPrepPackage(prep, projectRoot) { - const passed = [] - const failures = [] - - // Check 1: prep_status - if (prep.prep_status === 'ready') passed.push('status=ready') - else failures.push(`prep_status is "${prep.prep_status}", expected "ready"`) - - // Check 2: target_skill - if (prep.target_skill === 'workflow-plan-execute') passed.push('target_skill match') - else failures.push(`target_skill is "${prep.target_skill}", expected "workflow-plan-execute"`) - - // Check 3: project_root - if (prep.environment?.project_root === projectRoot) passed.push('project_root match') - else failures.push(`project_root mismatch: "${prep.environment?.project_root}" vs "${projectRoot}"`) - - // Check 4: quality_score >= 6 - if ((prep.task?.quality_score || 0) >= 6) passed.push(`quality=${prep.task.quality_score}/10`) - else failures.push(`quality_score ${prep.task?.quality_score || 0} < 6`) - - // Check 5: generated_at within 24h - const hoursSince = (Date.now() - new Date(prep.generated_at).getTime()) / 3600000 - if (hoursSince <= 24) passed.push(`age=${Math.round(hoursSince)}h`) - else failures.push(`prep-package is ${Math.round(hoursSince)}h old (max 24h)`) - - // Check 6: required fields - const required = ['task.structured.goal', 'task.structured.scope', 'execution.execution_method'] - const missing = required.filter(p => !p.split('.').reduce((o, k) => o?.[k], prep)) - if (missing.length === 0) passed.push('fields complete') - else failures.push(`missing: ${missing.join(', ')}`) - - return { valid: failures.length === 0, passed, failures } -} - -// Build structured description from prep or raw input -let structuredDescription -if (prepPackage) { - structuredDescription = { - goal: prepPackage.task.structured.goal, - scope: prepPackage.task.structured.scope, - context: prepPackage.task.structured.context - } -} else { - structuredDescription = null // Will be parsed from user input later -} -``` - -## Step 0: Initialize Project State (First-time Only) - -**Executed before all modes** - Ensures project-level state files exist by calling `workflow:init`. - -### Check and Initialize -```bash -# Check if project state exists (both files required) -bash(test -f ${projectRoot}/.workflow/project-tech.json && echo "TECH_EXISTS" || echo "TECH_NOT_FOUND") -bash(test -f ${projectRoot}/.workflow/project-guidelines.json && echo "GUIDELINES_EXISTS" || echo "GUIDELINES_NOT_FOUND") -``` - -**If either NOT_FOUND**, delegate to `workflow:init`: -```javascript -// Codex: Execute workflow:init command for intelligent project analysis -codex workflow:init - -// Wait for init completion -// project-tech.json and project-guidelines.json will be created -``` - -**Output**: -- If BOTH_EXIST: `PROJECT_STATE: initialized` -- If NOT_FOUND: Calls `workflow:init` → creates: - - `{projectRoot}/.workflow/project-tech.json` with full technical analysis - - `{projectRoot}/.workflow/project-guidelines.json` with empty scaffold - -**Note**: `workflow:init` uses cli-explore-agent to build comprehensive project understanding (technology stack, architecture, key components). This step runs once per project. Subsequent executions skip initialization. - -## Execution - -### Step 1.1: Execute Session Start - -```javascript -// Codex: Execute session start command -codex workflow:session:start --auto "[structured-task-description]" -``` - -**Task Description Structure**: -``` -GOAL: [Clear, concise objective] -SCOPE: [What's included/excluded] -CONTEXT: [Relevant background or constraints] -``` - -**Example**: -``` -GOAL: Build JWT-based authentication system -SCOPE: User registration, login, token validation -CONTEXT: Existing user database schema, REST API endpoints -``` - -### Step 1.2: Parse Output - -- Extract: `SESSION_ID: WFS-[id]` (store as `sessionId`) - -### Step 1.3: Validate - -- Session ID successfully extracted -- Session directory `{projectRoot}/.workflow/active/[sessionId]/` exists - -**Note**: Session directory contains `workflow-session.json` (metadata). Do NOT look for `manifest.json` here - it only exists in `{projectRoot}/.workflow/archives/` for archived sessions. - -### Step 1.4: Initialize Planning Notes - -Create `planning-notes.md` with N+1 context support, enriched with prep data: - -```javascript -const planningNotesPath = `${projectRoot}/.workflow/active/${sessionId}/planning-notes.md` -const userGoal = structuredDescription?.goal || taskDescription -const userScope = structuredDescription?.scope || "Not specified" -const userConstraints = structuredDescription?.context || "None specified" - -// Build source refs section from prep -const sourceRefsSection = (prepPackage?.task?.source_refs?.length > 0) - ? prepPackage.task.source_refs - .filter(r => r.status === 'verified' || r.status === 'linked') - .map(r => `- **${r.type}**: ${r.path}`) - .join('\n') - : 'None' - -// Build quality dimensions section from prep -const dimensionsSection = prepPackage?.task?.dimensions - ? Object.entries(prepPackage.task.dimensions) - .map(([k, v]) => `- **${k}**: ${v.value} (${v.score}/2)`) - .join('\n') - : '' - -Write(planningNotesPath, `# Planning Notes - -**Session**: ${sessionId} -**Created**: ${new Date().toISOString()} -${prepPackage ? `**Prep Package**: plan-prep-package.json (score: ${prepPackage.task.quality_score}/10)` : ''} - -## User Intent (Phase 1) - -- **GOAL**: ${userGoal} -- **SCOPE**: ${userScope} -- **KEY_CONSTRAINTS**: ${userConstraints} -${sourceRefsSection !== 'None' ? ` -### Requirement Sources (from prep) -${sourceRefsSection} -` : ''}${dimensionsSection ? ` -### Quality Dimensions (from prep) -${dimensionsSection} -` : ''} ---- - -## Context Findings (Phase 2) -(To be filled by context-gather) - -## Conflict Decisions (Phase 2) -(To be filled if conflicts detected) - -## Consolidated Constraints (Phase 3 Input) -1. ${userConstraints} - ---- - -## Task Generation (Phase 3) -(To be filled by action-planning-agent) - -## N+1 Context -### Decisions -| Decision | Rationale | Revisit? | -|----------|-----------|----------| - -### Deferred -- [ ] (For N+1) -`) -``` - -## Session Types - -The `--type` parameter classifies sessions for CCW dashboard organization: - -| Type | Description | Default For | -|------|-------------|-------------| -| `workflow` | Standard implementation (default) | `workflow:plan` | -| `review` | Code review sessions | `workflow:review-module-cycle` | -| `tdd` | TDD-based development | `workflow:tdd-plan` | -| `test` | Test generation/fix sessions | `workflow:test-fix-gen` | -| `docs` | Documentation sessions | `memory:docs` | - -**Validation**: If `--type` is provided with invalid value, return error: -``` -ERROR: Invalid session type. Valid types: workflow, review, tdd, test, docs -``` - -## Mode 1: Discovery Mode (Default) - -### Usage -```bash -workflow:session:start -``` - -### Step 1: List Active Sessions -```bash -bash(ls -1 ${projectRoot}/.workflow/active/ 2>/dev/null | head -5) -``` - -### Step 2: Display Session Metadata -```bash -bash(cat ${projectRoot}/.workflow/active/WFS-promptmaster-platform/workflow-session.json) -``` - -### Step 4: User Decision -Present session information and wait for user to select or create session. - -**Output**: `SESSION_ID: WFS-[user-selected-id]` - -## Mode 2: Auto Mode (Intelligent) - -### Usage -```bash -workflow:session:start --auto "task description" -``` - -### Step 1: Check Active Sessions Count -```bash -bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l) -``` - -### Step 2a: No Active Sessions → Create New -```bash -# Generate session slug -bash(echo "implement OAuth2 auth" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50) - -# Create directory structure -bash(mkdir -p ${projectRoot}/.workflow/active/WFS-implement-oauth2-auth/.process) -bash(mkdir -p ${projectRoot}/.workflow/active/WFS-implement-oauth2-auth/.task) -bash(mkdir -p ${projectRoot}/.workflow/active/WFS-implement-oauth2-auth/.summaries) - -# Create metadata (include type field, default to "workflow" if not specified) -bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning","type":"workflow","created_at":"2024-12-04T08:00:00Z"}' > ${projectRoot}/.workflow/active/WFS-implement-oauth2-auth/workflow-session.json) -``` - -**Output**: `SESSION_ID: WFS-implement-oauth2-auth` - -### Step 2b: Single Active Session → Check Relevance -```bash -# Extract session ID -bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename) - -# Read project name from metadata -bash(cat ${projectRoot}/.workflow/active/WFS-promptmaster-platform/workflow-session.json | grep -o '"project":"[^"]*"' | cut -d'"' -f4) - -# Check keyword match (manual comparison) -# If task contains project keywords → Reuse session -# If task unrelated → Create new session (use Step 2a) -``` - -**Output (reuse)**: `SESSION_ID: WFS-promptmaster-platform` -**Output (new)**: `SESSION_ID: WFS-[new-slug]` - -### Step 2c: Multiple Active Sessions → Use First -```bash -# Get first active session -bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename) - -# Output warning and session ID -# WARNING: Multiple active sessions detected -# SESSION_ID: WFS-first-session -``` - -## Mode 3: Force New Mode - -### Usage -```bash -workflow:session:start --new "task description" -``` - -### Step 1: Generate Unique Session Slug -```bash -# Convert to slug -bash(echo "fix login bug" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50) - -# Check if exists, add counter if needed -bash(ls ${projectRoot}/.workflow/active/WFS-fix-login-bug 2>/dev/null && echo "WFS-fix-login-bug-2" || echo "WFS-fix-login-bug") -``` - -### Step 2: Create Session Structure -```bash -bash(mkdir -p ${projectRoot}/.workflow/active/WFS-fix-login-bug/.process) -bash(mkdir -p ${projectRoot}/.workflow/active/WFS-fix-login-bug/.task) -bash(mkdir -p ${projectRoot}/.workflow/active/WFS-fix-login-bug/.summaries) -``` - -### Step 3: Create Metadata -```bash -# Include type field from --type parameter (default: "workflow") -bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning","type":"workflow","created_at":"2024-12-04T08:00:00Z"}' > ${projectRoot}/.workflow/active/WFS-fix-login-bug/workflow-session.json) -``` - -**Output**: `SESSION_ID: WFS-fix-login-bug` - -## Execution Guideline - -- **Non-interrupting**: When called from other commands, this command completes and returns control to the caller without interrupting subsequent tasks. - -## Session ID Format - -- Pattern: `WFS-[lowercase-slug]` -- Characters: `a-z`, `0-9`, `-` only -- Max length: 50 characters -- Uniqueness: Add numeric suffix if collision (`WFS-auth-2`, `WFS-auth-3`) - -## Output Format Specification - -### Success -``` -SESSION_ID: WFS-session-slug -``` - -### Error -``` -ERROR: --auto mode requires task description -ERROR: Failed to create session directory -``` - -### Analysis (Auto Mode) -``` -ANALYSIS: Task relevance = high -DECISION: Reusing existing session -SESSION_ID: WFS-promptmaster-platform -``` - -## Output - -- **Variable**: `sessionId` (e.g., `WFS-implement-oauth2-auth`) -- **File**: `{projectRoot}/.workflow/active/{sessionId}/planning-notes.md` -- **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress - -## Next Phase - -Return to orchestrator showing Phase 1 results, then auto-continue to [Phase 2: Context Gathering](02-context-gathering.md). diff --git a/.codex/skills/workflow-plan-execute/phases/02-context-gathering.md b/.codex/skills/workflow-plan-execute/phases/02-context-gathering.md deleted file mode 100644 index 9a27342d..00000000 --- a/.codex/skills/workflow-plan-execute/phases/02-context-gathering.md +++ /dev/null @@ -1,942 +0,0 @@ -# Phase 2: Context Gathering & Conflict Resolution - -Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON. When conflicts are detected, resolve them inline before packaging. - -## Objective - -- Check for existing valid context-package before executing -- Assess task complexity and launch parallel exploration agents (with conflict detection) -- Detect and resolve conflicts inline (conditional, when conflict indicators found) -- Invoke context-search-agent to analyze codebase -- Generate standardized `context-package.json` with prioritized context - -## Core Philosophy - -- **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution -- **Detection-First**: Check for existing context-package before executing -- **Conflict-Aware Exploration**: Explore agents detect conflict indicators during exploration -- **Inline Resolution**: Conflicts resolved as sub-step within this phase, not a separate phase -- **Conditional Trigger**: Conflict resolution only executes when exploration results contain conflict indicators -- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode) -- **Standardized Output**: Generate `{projectRoot}/.workflow/active/{session}/.process/context-package.json` -- **Explicit Lifecycle**: Manage subagent creation, waiting, and cleanup - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session - └─ Parse: task_description (required) - -Step 1: Context-Package Detection - └─ Decision (existing package): - ├─ Valid package exists → Return existing (skip execution) - └─ No valid package → Continue to Step 2 - -Step 2: Complexity Assessment & Parallel Explore (conflict-aware) - ├─ Analyze task_description → classify Low/Medium/High - ├─ Select exploration angles (1-4 based on complexity) - ├─ Launch N cli-explore-agents in parallel (spawn_agent) - │ └─ Each outputs: exploration-{angle}.json (includes conflict_indicators) - ├─ Wait for all agents (batch wait) - ├─ Close all agents - └─ Generate explorations-manifest.json - -Step 3: Inline Conflict Resolution (conditional) - ├─ 3.1 Aggregate conflict_indicators from all explorations - ├─ 3.2 Decision: No significant conflicts → Skip to Step 4 - ├─ 3.3 Spawn conflict-analysis agent (cli-execution-agent) - │ └─ Gemini/Qwen CLI analysis → conflict strategies - ├─ 3.4 Iterative user clarification (send_input loop, max 10 rounds) - │ ├─ Display conflict + strategy ONE BY ONE - │ ├─ ASK_USER for user selection - │ └─ send_input → agent re-analysis → confirm uniqueness - ├─ 3.5 Generate conflict-resolution.json - └─ 3.6 Close conflict agent - -Step 4: Invoke Context-Search Agent (enhanced) - ├─ Receives exploration results + resolved conflicts (if any) - └─ Generates context-package.json with exploration_results + conflict status - -Step 5: Output Verification (enhanced) - └─ Verify context-package.json contains exploration_results + conflict resolution -``` - -## Execution Flow - -### Step 1: Context-Package Detection - -**Execute First** - Check if valid package already exists: - -```javascript -const contextPackagePath = `${projectRoot}/.workflow/active/${session_id}/.process/context-package.json`; - -if (file_exists(contextPackagePath)) { - const existing = Read(contextPackagePath); - - // Validate package belongs to current session - if (existing?.metadata?.session_id === session_id) { - console.log("Valid context-package found for session:", session_id); - console.log("Stats:", existing.statistics); - console.log("Conflict Risk:", existing.conflict_detection.risk_level); - return existing; // Skip execution, return existing - } else { - console.warn("Invalid session_id in existing package, re-generating..."); - } -} -``` - -### Step 2: Complexity Assessment & Parallel Explore - -**Only execute if Step 1 finds no valid package** - -```javascript -// 2.1 Complexity Assessment -function analyzeTaskComplexity(taskDescription) { - const text = taskDescription.toLowerCase(); - if (/architect|refactor|restructure|modular|cross-module/.test(text)) return 'High'; - if (/multiple|several|integrate|migrate|extend/.test(text)) return 'Medium'; - return 'Low'; -} - -const ANGLE_PRESETS = { - architecture: ['architecture', 'dependencies', 'modularity', 'integration-points'], - security: ['security', 'auth-patterns', 'dataflow', 'validation'], - performance: ['performance', 'bottlenecks', 'caching', 'data-access'], - bugfix: ['error-handling', 'dataflow', 'state-management', 'edge-cases'], - feature: ['patterns', 'integration-points', 'testing', 'dependencies'], - refactor: ['architecture', 'patterns', 'dependencies', 'testing'] -}; - -function selectAngles(taskDescription, complexity) { - const text = taskDescription.toLowerCase(); - let preset = 'feature'; - if (/refactor|architect|restructure/.test(text)) preset = 'architecture'; - else if (/security|auth|permission/.test(text)) preset = 'security'; - else if (/performance|slow|optimi/.test(text)) preset = 'performance'; - else if (/fix|bug|error|issue/.test(text)) preset = 'bugfix'; - - const count = complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1); - return ANGLE_PRESETS[preset].slice(0, count); -} - -const complexity = analyzeTaskComplexity(task_description); -const selectedAngles = selectAngles(task_description, complexity); -const sessionFolder = `${projectRoot}/.workflow/active/${session_id}/.process`; - -// 2.2 Launch Parallel Explore Agents (with conflict detection) -const explorationAgents = []; - -// Load source_refs from prep-package for supplementary context -const prepPath = `${projectRoot}/.workflow/.prep/plan-prep-package.json` -const prepSourceRefs = fs.existsSync(prepPath) - ? (JSON.parse(Read(prepPath))?.task?.source_refs || []).filter(r => r.status === 'verified') - : [] -const sourceRefsDirective = prepSourceRefs.length > 0 - ? `\n## SUPPLEMENTARY REQUIREMENT DOCUMENTS (from prep)\nRead these before exploration:\n${prepSourceRefs.map((r, i) => `${i + 1}. Read: ${r.path} (${r.type})`).join('\n')}\nCross-reference findings against these source documents.\n` - : '' - -// Spawn all agents in parallel -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: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.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. - -**CONFLICT DETECTION**: Additionally detect conflict indicators including module overlaps, breaking changes, incompatible patterns, and scenario boundary ambiguities. -${sourceRefsDirective} - -## Assigned Context -- **Exploration Angle**: ${angle} -- **Task Description**: ${task_description} -- **Session ID**: ${session_id} -- **Exploration Index**: ${index + 1} of ${selectedAngles.length} -- **Output File**: ${sessionFolder}/exploration-${angle}.json - -## MANDATORY FIRST STEPS (Execute by Agent) -**You (cli-explore-agent) MUST execute these steps in order:** -1. Run: ccw tool exec get_modules_by_depth '{}' (project structure) -2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files) -3. Execute: cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference) - -## Exploration Strategy (${angle} focus) - -**Step 1: Structural Scan** (Bash) -- get_modules_by_depth.sh → identify modules related to ${angle} -- find/rg → locate files relevant to ${angle} aspect -- Analyze imports/dependencies from ${angle} perspective - -**Step 2: Semantic Analysis** (Gemini CLI) -- How does existing code handle ${angle} concerns? -- What patterns are used for ${angle}? -- Where would new code integrate from ${angle} viewpoint? -- **Detect conflict indicators**: module overlaps, breaking changes, incompatible patterns - -**Step 3: Write Output** -- Consolidate ${angle} findings into JSON -- Identify ${angle}-specific clarification needs -- **Include conflict_indicators array** with detected conflicts - -## Expected Output - -**File**: ${sessionFolder}/exploration-${angle}.json - -**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly - -**Required Fields** (all ${angle} focused): -- project_structure: Modules/architecture relevant to ${angle} -- relevant_files: Files affected from ${angle} perspective - **MANDATORY**: Every file MUST use structured object format with ALL required fields: - \`[{path: "src/file.ts", relevance: 0.85, rationale: "Contains AuthService.login() - entry point for JWT token generation", role: "modify_target", discovery_source: "bash-scan", key_symbols: ["AuthService", "login"]}]\` - - **rationale** (required): Specific selection basis tied to ${angle} topic (>10 chars, not generic) - - **role** (required): modify_target|dependency|pattern_reference|test_target|type_definition|integration_point|config|context_only - - **discovery_source** (recommended): bash-scan|cli-analysis|ace-search|dependency-trace|manual - - **key_symbols** (recommended): Key functions/classes/types in the file relevant to the task - - Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low -- patterns: ${angle}-related patterns to follow -- dependencies: Dependencies relevant to ${angle} -- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations) -- constraints: ${angle}-specific limitations/conventions -- clarification_needs: ${angle}-related ambiguities (options array + recommended index) -- **conflict_indicators**: Array of detected conflicts from ${angle} perspective - \`[{type: "ModuleOverlap|BreakingChange|PatternConflict", severity: "high|medium|low", description: "...", affected_files: [...]}]\` -- _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 specific rationale + role -- [ ] Every file has rationale >10 chars (not generic like "Related to ${angle}") -- [ ] Every file has role classification (modify_target/dependency/etc.) -- [ ] Patterns are actionable (code examples, not generic advice) -- [ ] Integration points include file:line locations -- [ ] Constraints are project-specific to ${angle} -- [ ] conflict_indicators populated (empty array if none detected) -- [ ] JSON output follows schema exactly -- [ ] clarification_needs includes options + recommended - -## Output -Write: ${sessionFolder}/exploration-${angle}.json -Return: 2-3 sentence summary of ${angle} findings + conflict indicators count -` - }); - - explorationAgents.push(agentId); -}); - -// 2.3 Batch wait for all exploration agents -const explorationResults = wait({ - ids: explorationAgents, - timeout_ms: 600000 // 10 minutes -}); - -// Check for timeouts -if (explorationResults.timed_out) { - console.log('Some exploration agents timed out - continuing with completed results'); -} - -// 2.4 Close all exploration agents -explorationAgents.forEach(agentId => { - close_agent({ id: agentId }); -}); - -// 2.5 Generate Manifest after all complete -const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`).split('\n').filter(f => f.trim()); -const explorationManifest = { - session_id, - task_description, - timestamp: new Date().toISOString(), - complexity, - exploration_count: selectedAngles.length, - angles_explored: selectedAngles, - explorations: explorationFiles.map(file => { - const data = JSON.parse(Read(file)); - return { angle: data._metadata.exploration_angle, file: file.split('/').pop(), path: file, index: data._metadata.exploration_index }; - }) -}; -Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2)); -``` - -### Step 3: Inline Conflict Resolution - -**Conditional execution** - Only runs when exploration results contain significant conflict indicators. - -#### 3.1 Aggregate Conflict Indicators - -```javascript -// Aggregate conflict_indicators from all explorations -const allConflictIndicators = []; -explorationFiles.forEach(file => { - const data = JSON.parse(Read(file)); - if (data.conflict_indicators?.length > 0) { - allConflictIndicators.push(...data.conflict_indicators.map(ci => ({ - ...ci, - source_angle: data._metadata.exploration_angle - }))); - } -}); - -const hasSignificantConflicts = allConflictIndicators.some(ci => ci.severity === 'high') || - allConflictIndicators.filter(ci => ci.severity === 'medium').length >= 2; -``` - -#### 3.2 Decision Gate - -```javascript -if (!hasSignificantConflicts) { - console.log(`No significant conflicts detected (${allConflictIndicators.length} low indicators). Skipping conflict resolution.`); - // Skip to Step 4 -} else { - console.log(`Significant conflicts detected: ${allConflictIndicators.length} indicators. Launching conflict analysis...`); - // Continue to 3.3 -} -``` - -#### 3.3 Spawn Conflict-Analysis Agent - -```javascript -const conflictAgentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/cli-execution-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -## Context -- Session: ${session_id} -- Conflict Indicators: ${JSON.stringify(allConflictIndicators)} -- Files: ${existing_files_list} - -## Exploration Context (from exploration results) -- Exploration Count: ${explorationManifest.exploration_count} -- Angles Analyzed: ${JSON.stringify(explorationManifest.angles_explored)} -- Pre-identified Conflict Indicators: ${JSON.stringify(allConflictIndicators)} -- Critical Files: ${JSON.stringify(explorationFiles.flatMap(f => JSON.parse(Read(f)).relevant_files?.filter(rf => rf.relevance >= 0.7).map(rf => rf.path) || []))} - -## Analysis Steps - -### 0. Load Output Schema (MANDATORY) -Execute: cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json - -### 1. Load Context -- Read existing files from conflict indicators -- Load exploration results and use aggregated insights for enhanced analysis - -### 2. Execute CLI Analysis (Enhanced with Exploration + Scenario Uniqueness) - -Primary (Gemini): -ccw cli -p " -PURPOSE: Detect conflicts between plan and codebase, using exploration insights -TASK: -• **Review pre-identified conflict_indicators from exploration results** -• Compare architectures (use exploration key_patterns) -• Identify breaking API changes -• Detect data model incompatibilities -• Assess dependency conflicts -• **Analyze module scenario uniqueness** - - Cross-validate with exploration critical_files - - Generate clarification questions for boundary definition -MODE: analysis -CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @${projectRoot}/.workflow/active/${session_id}/**/* -EXPECTED: Conflict list with severity ratings, including: - - Validation of exploration conflict_indicators - - ModuleOverlap conflicts with overlap_analysis - - Targeted clarification questions -CONSTRAINTS: Focus on breaking changes, migration needs, and functional overlaps | Prioritize exploration-identified conflicts | analysis=READ-ONLY -" --tool gemini --mode analysis --rule analysis-code-patterns --cd ${project_root} - -Fallback: Qwen (same prompt) → Claude (manual analysis) - -### 3. Generate Strategies (2-4 per conflict) - -Template per conflict: -- Severity: Critical/High/Medium -- Category: Architecture/API/Data/Dependency/ModuleOverlap -- Affected files + impact -- **For ModuleOverlap**: Include overlap_analysis with existing modules and scenarios -- Options with pros/cons, effort, risk -- **For ModuleOverlap strategies**: Add clarification_needed questions for boundary definition -- Recommended strategy + rationale - -### 4. Return Structured Conflict Data - -**Schema Reference**: Execute \`cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json\` to get full schema - -Return JSON following the schema above. Key requirements: -- Minimum 2 strategies per conflict, max 4 -- All text in Chinese for user-facing fields (brief, name, pros, cons, modification_suggestions) -- modifications.old_content: 20-100 chars for unique Edit tool matching -- modifications.new_content: preserves markdown formatting -- modification_suggestions: 2-5 actionable suggestions for custom handling - -### 5. Planning Notes Record (REQUIRED) -After analysis complete, append a brief execution record to planning-notes.md: - -**File**: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md -**Location**: Under "## Conflict Decisions (Phase 2)" section -**Format**: -\`\`\` -### [Conflict-Resolution Agent] YYYY-MM-DD -- **Note**: [brief summary of conflict types, resolution strategies, key decisions] -\`\`\` -` -}); - -// Wait for initial analysis -const analysisResult = wait({ - ids: [conflictAgentId], - timeout_ms: 600000 // 10 minutes -}); - -// Parse conflicts from result -const conflicts = parseConflictsFromResult(analysisResult); -``` - -#### Conflict Categories - -| Category | Description | -|----------|-------------| -| **Architecture** | Incompatible design patterns, module structure changes, pattern migration | -| **API** | Breaking contract changes, signature modifications, public interface impacts | -| **Data Model** | Schema modifications, type breaking changes, data migration needs | -| **Dependency** | Version incompatibilities, setup conflicts, breaking updates | -| **ModuleOverlap** | Functional overlap, scenario boundary ambiguity, duplicate responsibility | - -#### 3.4 Iterative User Clarification - -```javascript -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') -const resolvedConflicts = []; -const customConflicts = []; - -FOR each conflict: - round = 0, clarified = false, userClarifications = [] - - WHILE (!clarified && round++ < 10): - // 1. Display conflict info (text output for context) - displayConflictSummary(conflict) // id, brief, severity, overlap_analysis if ModuleOverlap - - // 2. Strategy selection - if (autoYes) { - console.log(`[--yes] Auto-selecting recommended strategy`) - selectedStrategy = conflict.strategies[conflict.recommended || 0] - clarified = true // Skip clarification loop - } else { - ASK_USER([{ - id: `conflict-${conflict.id}-strategy`, - type: "select", - prompt: formatStrategiesForDisplay(conflict.strategies), - options: [ - ...conflict.strategies.map((s, i) => ({ - label: `${s.name}${i === conflict.recommended ? ' (推荐)' : ''}`, - description: `${s.complexity}复杂度 | ${s.risk}风险${s.clarification_needed?.length ? ' | 需澄清' : ''}` - })), - { label: "自定义修改", description: `建议: ${conflict.modification_suggestions?.slice(0,2).join('; ')}` } - ] - }]) // BLOCKS (wait for user response) - - // 3. Handle selection - if (userChoice === "自定义修改") { - customConflicts.push({ id, brief, category, suggestions, overlap_analysis }) - break - } - - selectedStrategy = findStrategyByName(userChoice) - } - - // 4. Clarification (if needed) - using send_input for agent re-analysis - if (!autoYes && selectedStrategy.clarification_needed?.length > 0) { - for (batch of chunk(selectedStrategy.clarification_needed, 4)) { - ASK_USER(batch.map((q, i) => ({ - id: `clarify-${conflict.id}-${i+1}`, - type: "select", - prompt: q, - options: [{ label: "详细说明", description: "提供答案" }] - }))) // BLOCKS (wait for user response) - userClarifications.push(...collectAnswers(batch)) - } - - // 5. Agent re-analysis via send_input (key: agent stays active) - send_input({ - id: conflictAgentId, - message: ` -## CLARIFICATION ANSWERS -Conflict: ${conflict.id} -Strategy: ${selectedStrategy.name} -User Clarifications: ${JSON.stringify(userClarifications)} - -## REQUEST -Based on the clarifications above, update the strategy assessment. -Output: { uniqueness_confirmed: boolean, rationale: string, updated_strategy: {...}, remaining_questions: [...] } -` - }); - - // Wait for re-analysis result - const reanalysisResult = wait({ - ids: [conflictAgentId], - timeout_ms: 300000 // 5 minutes - }); - - const parsedResult = parseReanalysisResult(reanalysisResult); - - if (parsedResult.uniqueness_confirmed) { - selectedStrategy = { ...parsedResult.updated_strategy, clarifications: userClarifications } - clarified = true - } else { - selectedStrategy.clarification_needed = parsedResult.remaining_questions - } - } else { - clarified = true - } - - if (clarified) resolvedConflicts.push({ conflict, strategy: selectedStrategy }) - END WHILE -END FOR - -selectedStrategies = resolvedConflicts.map(r => ({ - conflict_id: r.conflict.id, strategy: r.strategy, clarifications: r.strategy.clarifications || [] -})) -``` - -**Key Points**: -- ASK_USER: max 4 questions/call, batch if more -- Strategy options: 2-4 strategies + "自定义修改" -- Clarification loop via send_input: max 10 rounds, agent determines uniqueness_confirmed -- Agent stays active throughout interaction (no close_agent until Step 3.6) -- Custom conflicts: record overlap_analysis for subsequent manual handling - -#### 3.5 Generate conflict-resolution.json - -```javascript -// Apply modifications from resolved strategies -const modifications = []; -selectedStrategies.forEach(item => { - if (item.strategy && item.strategy.modifications) { - modifications.push(...item.strategy.modifications.map(mod => ({ - ...mod, - conflict_id: item.conflict_id, - clarifications: item.clarifications - }))); - } -}); - -console.log(`\nApplying ${modifications.length} modifications...`); - -const appliedModifications = []; -const failedModifications = []; -const fallbackConstraints = []; - -modifications.forEach((mod, idx) => { - try { - console.log(`[${idx + 1}/${modifications.length}] Modifying ${mod.file}...`); - - if (!file_exists(mod.file)) { - console.log(` File not found, recording as constraint`); - fallbackConstraints.push({ - source: "conflict-resolution", - conflict_id: mod.conflict_id, - target_file: mod.file, - section: mod.section, - change_type: mod.change_type, - content: mod.new_content, - rationale: mod.rationale - }); - return; - } - - if (mod.change_type === "update") { - Edit({ file_path: mod.file, old_string: mod.old_content, new_string: mod.new_content }); - } else if (mod.change_type === "add") { - const fileContent = Read(mod.file); - const updated = insertContentAfterSection(fileContent, mod.section, mod.new_content); - Write(mod.file, updated); - } else if (mod.change_type === "remove") { - Edit({ file_path: mod.file, old_string: mod.old_content, new_string: "" }); - } - - appliedModifications.push(mod); - } catch (error) { - failedModifications.push({ ...mod, error: error.message }); - } -}); - -// Generate conflict-resolution.json -const resolutionOutput = { - session_id: session_id, - resolved_at: new Date().toISOString(), - summary: { - total_conflicts: conflicts.length, - resolved_with_strategy: selectedStrategies.length, - custom_handling: customConflicts.length, - fallback_constraints: fallbackConstraints.length - }, - resolved_conflicts: selectedStrategies.map(s => ({ - conflict_id: s.conflict_id, - strategy_name: s.strategy.name, - strategy_approach: s.strategy.approach, - clarifications: s.clarifications || [], - modifications_applied: s.strategy.modifications?.filter(m => - appliedModifications.some(am => am.conflict_id === s.conflict_id) - ) || [] - })), - custom_conflicts: customConflicts.map(c => ({ - id: c.id, brief: c.brief, category: c.category, - suggestions: c.suggestions, overlap_analysis: c.overlap_analysis || null - })), - planning_constraints: fallbackConstraints, - failed_modifications: failedModifications -}; - -const resolutionPath = `${projectRoot}/.workflow/active/${session_id}/.process/conflict-resolution.json`; -Write(resolutionPath, JSON.stringify(resolutionOutput, null, 2)); - -// Output custom conflict summary (if any) -if (customConflicts.length > 0) { - customConflicts.forEach(conflict => { - console.log(`[${conflict.category}] ${conflict.id}: ${conflict.brief}`); - if (conflict.category === 'ModuleOverlap' && conflict.overlap_analysis) { - console.log(` New module: ${conflict.overlap_analysis.new_module.name}`); - conflict.overlap_analysis.existing_modules.forEach(mod => { - console.log(` Overlaps: ${mod.name} (${mod.file})`); - }); - } - conflict.suggestions.forEach(s => console.log(` - ${s}`)); - }); -} -``` - -#### 3.6 Close Conflict Agent - -```javascript -close_agent({ id: conflictAgentId }); -``` - -### Step 4: Invoke Context-Search Agent - -**Execute after Step 2 (and Step 3 if triggered)** - -```javascript -// Load user intent from planning-notes.md (from Phase 1) -const planningNotesPath = `${projectRoot}/.workflow/active/${session_id}/planning-notes.md`; -let userIntent = { goal: task_description, key_constraints: "None specified" }; - -if (file_exists(planningNotesPath)) { - const notesContent = Read(planningNotesPath); - const goalMatch = notesContent.match(/\*\*GOAL\*\*:\s*(.+)/); - const constraintsMatch = notesContent.match(/\*\*KEY_CONSTRAINTS\*\*:\s*(.+)/); - if (goalMatch) userIntent.goal = goalMatch[1].trim(); - if (constraintsMatch) userIntent.key_constraints = constraintsMatch[1].trim(); -} - -// Prepare conflict resolution context for agent -const conflictContext = hasSignificantConflicts - ? `Conflict Resolution: ${resolutionPath} (${selectedStrategies.length} resolved, ${customConflicts.length} custom)` - : `Conflict Resolution: None needed (no significant conflicts detected)`; - -// Spawn context-search-agent -const contextAgentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/context-search-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -## Execution Mode -**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution with priority sorting - -## Session Information -- **Session ID**: ${session_id} -- **Task Description**: ${task_description} -- **Output Path**: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json - -## User Intent (from Phase 1 - Planning Notes) -**GOAL**: ${userIntent.goal} -**KEY_CONSTRAINTS**: ${userIntent.key_constraints} - -This is the PRIMARY context source - all subsequent analysis must align with user intent. - -## Exploration Input (from Step 2) -- **Manifest**: ${sessionFolder}/explorations-manifest.json -- **Exploration Count**: ${explorationManifest.exploration_count} -- **Angles**: ${explorationManifest.angles_explored.join(', ')} -- **Complexity**: ${complexity} - -## Conflict Resolution Input (from Step 3) -- **${conflictContext}** -${hasSignificantConflicts ? `- **Resolution File**: ${resolutionPath} -- **Resolved Conflicts**: ${selectedStrategies.length} -- **Custom Conflicts**: ${customConflicts.length} -- **Planning Constraints**: ${fallbackConstraints.length}` : ''} - -## Mission -Execute complete context-search-agent workflow for implementation planning: - -### Phase 1: Initialization & Pre-Analysis -1. **Project State Loading**: - - Read and parse \`${projectRoot}/.workflow/project-tech.json\`. Use its \`overview\` section as the foundational \`project_context\`. This is your primary source for architecture, tech stack, and key components. - - Read and parse \`${projectRoot}/.workflow/project-guidelines.json\`. Load \`conventions\`, \`constraints\`, and \`learnings\` into a \`project_guidelines\` section. - - If files don't exist, proceed with fresh analysis. -2. **Detection**: Check for existing context-package (early exit if valid) -3. **Foundation**: Initialize CodexLens, get project structure, load docs -4. **Analysis**: Extract keywords, determine scope, classify complexity based on task description and project state - -### Phase 2: Multi-Source Context Discovery -Execute all discovery tracks (WITH USER INTENT INTEGRATION): -- **Track -1**: User Intent & Priority Foundation (EXECUTE FIRST) - - Load user intent (GOAL, KEY_CONSTRAINTS) from session input - - Map user requirements to codebase entities (files, modules, patterns) - - Establish baseline priority scores based on user goal alignment - - Output: user_intent_mapping.json with preliminary priority scores - -- **Track 0**: Exploration Synthesis (load ${sessionFolder}/explorations-manifest.json, prioritize critical_files, deduplicate patterns/integration_points) -- **Track 1**: Historical archive analysis (query manifest.json for lessons learned) -- **Track 2**: Reference documentation (CLAUDE.md, architecture docs) -- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs) -- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests) - -### Phase 3: Synthesis, Assessment & Packaging -1. Apply relevance scoring and build dependency graph -2. **Synthesize 5-source data** (including Track -1): Merge findings from all sources - - Priority order: User Intent > Archive > Docs > Exploration > Code > Web - - **Prioritize the context from \`project-tech.json\`** for architecture and tech stack unless code analysis reveals it's outdated -3. **Context Priority Sorting**: - a. Combine scores from Track -1 (user intent alignment) + relevance scores + exploration critical_files - b. Classify files into priority tiers: - - **Critical** (score >= 0.85): Directly mentioned in user goal OR exploration critical_files - - **High** (0.70-0.84): Key dependencies, patterns required for goal - - **Medium** (0.50-0.69): Supporting files, indirect dependencies - - **Low** (< 0.50): Contextual awareness only - c. Generate dependency_order: Based on dependency graph + user goal sequence - d. Document sorting_rationale: Explain prioritization logic - -4. **Populate \`project_context\`**: Directly use the \`overview\` from \`project-tech.json\` to fill the \`project_context\` section. Include description, technology_stack, architecture, and key_components. -5. **Populate \`project_guidelines\`**: Load conventions, constraints, and learnings from \`project-guidelines.json\` into a dedicated section. -6. Integrate brainstorm artifacts (if .brainstorming/ exists, read content) -7. Perform conflict detection with risk assessment -8. **Inject conflict resolution results** (if conflict-resolution.json exists) into conflict_detection -9. **Generate prioritized_context section**: - \`\`\`json - { - "prioritized_context": { - "user_intent": { - "goal": "...", - "scope": "...", - "key_constraints": ["..."] - }, - "priority_tiers": { - "critical": [{ "path": "...", "relevance": 0.95, "rationale": "..." }], - "high": [...], - "medium": [...], - "low": [...] - }, - "dependency_order": ["module1", "module2", "module3"], - "sorting_rationale": "Based on user goal alignment (Track -1), exploration critical files, and dependency graph analysis" - } - } - \`\`\` -10. Generate and validate context-package.json with prioritized_context field - -## Output Requirements -Complete context-package.json with: -- **metadata**: task_description, keywords, complexity, tech_stack, session_id -- **project_context**: description, technology_stack, architecture, key_components (sourced from \`project-tech.json\`) -- **project_guidelines**: {conventions, constraints, quality_rules, learnings} (sourced from \`project-guidelines.json\`) -- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores -- **dependencies**: {internal[], external[]} with dependency graph -- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content -- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[], resolution_file (if exists)} -- **exploration_results**: {manifest_path, exploration_count, angles, explorations[], aggregated_insights} (from Track 0) -- **prioritized_context**: {user_intent, priority_tiers{critical, high, medium, low}, dependency_order[], sorting_rationale} - -## Quality Validation -Before completion verify: -- [ ] Valid JSON format with all required fields -- [ ] File relevance accuracy >80% -- [ ] Dependency graph complete (max 2 transitive levels) -- [ ] Conflict risk level calculated correctly -- [ ] No sensitive data exposed -- [ ] Total files <=50 (prioritize high-relevance) - -## Planning Notes Record (REQUIRED) -After completing context-package.json, append a brief execution record to planning-notes.md: - -**File**: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md -**Location**: Under "## Context Findings (Phase 2)" section -**Format**: -\`\`\` -### [Context-Search Agent] YYYY-MM-DD -- **Note**: [brief summary of key findings] -\`\`\` - -Execute autonomously following agent documentation. -Report completion with statistics. -` -}); - -// Wait for context agent to complete -const contextResult = wait({ - ids: [contextAgentId], - timeout_ms: 900000 // 15 minutes -}); - -// Close context agent -close_agent({ id: contextAgentId }); -``` - -### Step 5: Output Verification - -After agent completes, verify output: - -```javascript -// Verify file was created -const outputPath = `${projectRoot}/.workflow/active/${session_id}/.process/context-package.json`; -if (!file_exists(outputPath)) { - throw new Error("Agent failed to generate context-package.json"); -} - -// Verify exploration_results included -const pkg = JSON.parse(Read(outputPath)); -if (pkg.exploration_results?.exploration_count > 0) { - console.log(`Exploration results aggregated: ${pkg.exploration_results.exploration_count} angles`); -} - -// Verify conflict resolution status -if (hasSignificantConflicts) { - const resolutionFileRef = pkg.conflict_detection?.resolution_file; - if (resolutionFileRef) { - console.log(`Conflict resolution integrated: ${resolutionFileRef}`); - } -} -``` - -## Parameter Reference - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `--session` | string | Yes | Workflow session ID (e.g., WFS-user-auth) | -| `task_description` | string | Yes | Detailed task description for context extraction | - -## Auto Mode - -When `--yes` or `-y`: Auto-select recommended strategy for each conflict in Step 3, skip clarification questions. - -## Post-Phase Update - -After context-gather completes, update planning-notes.md: - -```javascript -const contextPackage = JSON.parse(Read(contextPath)) -const conflictRisk = contextPackage.conflict_detection?.risk_level || 'low' -const criticalFiles = (contextPackage.exploration_results?.aggregated_insights?.critical_files || []) - .slice(0, 5).map(f => f.path) -const archPatterns = contextPackage.project_context?.architecture_patterns || [] -const constraints = contextPackage.exploration_results?.aggregated_insights?.constraints || [] - -// Update Phase 2 section -Edit(planningNotesPath, { - old: '## Context Findings (Phase 2)\n(To be filled by context-gather)', - new: `## Context Findings (Phase 2) - -- **CRITICAL_FILES**: ${criticalFiles.join(', ') || 'None identified'} -- **ARCHITECTURE**: ${archPatterns.join(', ') || 'Not detected'} -- **CONFLICT_RISK**: ${conflictRisk} -- **CONSTRAINTS**: ${constraints.length > 0 ? constraints.join('; ') : 'None'}` -}) - -// If conflicts were resolved inline, update conflict decisions section -if (hasSignificantConflicts && file_exists(resolutionPath)) { - const conflictRes = JSON.parse(Read(resolutionPath)) - const resolved = conflictRes.resolved_conflicts || [] - const planningConstraints = conflictRes.planning_constraints || [] - - Edit(planningNotesPath, { - old: '## Conflict Decisions (Phase 2)\n(To be filled if conflicts detected)', - new: `## Conflict Decisions (Phase 2) - -- **RESOLVED**: ${resolved.map(r => `${r.conflict_id} → ${r.strategy_name}`).join('; ') || 'None'} -- **CUSTOM_HANDLING**: ${conflictRes.custom_conflicts?.map(c => c.id).join(', ') || 'None'} -- **CONSTRAINTS**: ${planningConstraints.map(c => c.content).join('; ') || 'None'}` - }) - - // Append conflict constraints to consolidated list - if (planningConstraints.length > 0) { - Edit(planningNotesPath, { - old: '## Consolidated Constraints (Phase 3 Input)', - new: `## Consolidated Constraints (Phase 3 Input) -${planningConstraints.map((c, i) => `${constraintCount + i + 1}. [Conflict] ${c.content}`).join('\n')}` - }) - } -} - -// Append Phase 2 constraints to consolidated list -Edit(planningNotesPath, { - old: '## Consolidated Constraints (Phase 3 Input)', - new: `## Consolidated Constraints (Phase 3 Input) -${constraints.map((c, i) => `${i + 2}. [Context] ${c}`).join('\n')}` -}) -``` - -## Error Handling - -### Recovery Strategy -``` -1. Pre-check: Verify exploration results before conflict analysis -2. Monitor: Track agents via wait with timeout -3. Validate: Parse agent JSON output -4. Recover: - - Agent failure → check logs + report error - - Invalid JSON → retry once with Claude fallback - - CLI failure → fallback to Claude analysis - - Edit tool failure → report affected files + rollback option - - User cancels → mark as "unresolved", continue to Step 4 -5. Degrade: If conflict analysis fails, skip and continue with context packaging -6. Cleanup: Always close_agent even on error path -``` - -### Rollback Handling -``` -If Edit tool fails mid-application: -1. Log all successfully applied modifications -2. Output rollback option via text interaction -3. If rollback selected: restore files from git or backups -4. If continue: mark partial resolution in context-package.json -``` - -## Notes - -- **Detection-first**: Always check for existing package before invoking agent -- **User intent integration**: Load user intent from planning-notes.md (Phase 1 output) -- **Conflict-aware exploration**: Explore agents detect conflict indicators during their work -- **Inline conflict resolution**: Conflicts resolved within this phase when significant indicators found -- **Output**: Generates `context-package.json` with `prioritized_context` field + optional `conflict-resolution.json` -- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call -- **Explicit Lifecycle**: Always close_agent after wait to free resources -- **Batch Wait**: Use single wait call for multiple parallel agents for efficiency - -## Output - -- **Variable**: `contextPath` (e.g., `{projectRoot}/.workflow/active/WFS-xxx/.process/context-package.json`) -- **Variable**: `conflictRisk` (none/low/medium/high/resolved) -- **File**: Updated `planning-notes.md` with context findings + conflict decisions (if applicable) -- **File**: Optional `conflict-resolution.json` (when conflicts resolved inline) - -## Next Phase - -Return to orchestrator, then auto-continue to [Phase 3: Task Generation](03-task-generation.md). diff --git a/.codex/skills/workflow-plan-execute/phases/03-task-generation.md b/.codex/skills/workflow-plan-execute/phases/03-task-generation.md deleted file mode 100644 index cb94a4b2..00000000 --- a/.codex/skills/workflow-plan-execute/phases/03-task-generation.md +++ /dev/null @@ -1,793 +0,0 @@ -# Phase 3: Task Generation - -Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation. - -## Auto Mode - -When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor, Codex CLI tool). - -## Core Philosophy - -- **Planning Only**: Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - does NOT implement code -- **Agent-Driven Document Generation**: Delegate plan generation to action-planning-agent -- **NO Redundant Context Sorting**: Context priority sorting is ALREADY completed in context-gather Phase 2 - - Use `context-package.json.prioritized_context` directly - - DO NOT re-sort files or re-compute priorities - - `priority_tiers` and `dependency_order` are pre-computed and ready-to-use -- **N+1 Parallel Planning**: Auto-detect multi-module projects, enable parallel planning (2+1 or 3+1 mode) -- **Progressive Loading**: Load context incrementally (Core → Selective → On-Demand) due to analysis.md file size -- **Memory-First**: Reuse loaded documents from conversation memory -- **Smart Selection**: Load synthesis_output OR guidance + relevant role analyses, NOT all role analyses -- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research -- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`) -- **Explicit Lifecycle**: Manage subagent lifecycle with spawn_agent → wait → close_agent - -## Execution Process - -``` -Input Parsing: - ├─ Parse flags: --session - └─ Validation: session_id REQUIRED - -Phase 0: User Configuration (Interactive) - ├─ Question 1: Supplementary materials/guidelines? - ├─ Question 2: Execution method preference (Agent/CLI/Hybrid) - ├─ Question 3: CLI tool preference (if CLI selected) - └─ Store: userConfig for agent prompt - -Phase 1: Context Preparation & Module Detection (Command) - ├─ Assemble session paths (metadata, context package, output dirs) - ├─ Provide metadata (session_id, execution_mode, mcp_capabilities) - ├─ Auto-detect modules from context-package + directory structure - └─ Decision: - ├─ modules.length == 1 → Single Agent Mode (Phase 2A) - └─ modules.length >= 2 → Parallel Mode (Phase 2B + Phase 3) - -Phase 2A: Single Agent Planning (Original Flow) - ├─ Spawn action-planning-agent - ├─ Wait for completion - ├─ Close agent - ├─ Outputs: Task JSONs, IMPL_PLAN.md, TODO_LIST.md - └─ Lifecycle: spawn_agent → wait → close_agent - -Phase 2B: N Parallel Planning (Multi-Module) - ├─ Spawn N action-planning-agents simultaneously (one per module) - ├─ Wait for all agents (batch wait) - ├─ Close all agents - ├─ Each generates module-scoped tasks (IMPL-{prefix}{seq}.json) - ├─ Task ID format: IMPL-A1, IMPL-A2... / IMPL-B1, IMPL-B2... - └─ Each module limited to ≤9 tasks - -Phase 3: Integration (+1 Coordinator, Multi-Module Only) - ├─ Spawn coordinator agent - ├─ Wait for completion - ├─ Close agent - ├─ Collect all module task JSONs - ├─ Resolve cross-module dependencies (CROSS::{module}::{pattern} → actual ID) - ├─ Generate unified IMPL_PLAN.md (grouped by module) - └─ Generate TODO_LIST.md (hierarchical: module → tasks) -``` - -## Document Generation Lifecycle - -### Phase 0: User Configuration (Interactive) - -**Purpose**: Collect user preferences before task generation to ensure generated tasks match execution expectations. - -**Auto Mode Check**: -```javascript -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') - -// Check for prep-package auto-configuration (from /prompts:prep-plan) -const prepPath = `${projectRoot}/.workflow/.prep/plan-prep-package.json` -const prepExec = fs.existsSync(prepPath) ? JSON.parse(Read(prepPath))?.execution : null - -if (autoYes || prepExec) { - const source = prepExec ? 'prep-package' : '--yes flag' - console.log(`[${source}] Using defaults: ${prepExec?.execution_method || 'agent'} executor, ${prepExec?.preferred_cli_tool || 'codex'} CLI`) - userConfig = { - supplementaryMaterials: prepExec?.supplementary_materials || { type: "none", content: [] }, - executionMethod: prepExec?.execution_method || "agent", - preferredCliTool: prepExec?.preferred_cli_tool || "codex", - enableResume: true - } - // Skip to Phase 1 -} -``` - -**User Questions** (skipped if autoYes): -```javascript -if (!autoYes) ASK_USER([ - { - id: "materials", - type: "select", - prompt: "Do you have supplementary materials or guidelines to include?", - 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" } - ] - }, - { - id: "execution-method", - type: "select", - prompt: "Select execution method for generated tasks:", - options: [ - { label: "Agent (Recommended)", description: "Claude agent executes tasks directly" }, - { label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps" }, - { label: "CLI Only", description: "All execution via CLI tools (codex/gemini/qwen)" } - ] - }, - { - id: "cli-tool", - type: "select", - prompt: "If using CLI, which tool do you prefer?", - options: [ - { label: "Codex (Recommended)", description: "Best for implementation tasks" }, - { label: "Gemini", description: "Best for analysis and large context" }, - { label: "Qwen", description: "Alternative analysis tool" }, - { label: "Auto", description: "Let agent decide per-task" } - ] - } -]) // BLOCKS (wait for user response) -``` - -**Handle Materials Response** (skipped if autoYes): -```javascript -if (!autoYes && userConfig.materials === "Provide file paths") { - // Follow-up question for file paths - const pathsResponse = ASK_USER([{ - id: "material-paths", - type: "input", - prompt: "Enter file paths to include (comma-separated or one per line):", - options: [ - { label: "Enter paths", description: "Provide paths in text input" } - ] - }]) // BLOCKS (wait for user response) - userConfig.supplementaryPaths = parseUserPaths(pathsResponse) -} -``` - -**Build userConfig**: -```javascript -const userConfig = { - supplementaryMaterials: { - type: "none|paths|inline", - content: [...], // Parsed paths or inline content - }, - executionMethod: "agent|hybrid|cli", - preferredCliTool: "codex|gemini|qwen|auto", - enableResume: true // Always enable resume for CLI executions -} -``` - -**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2A/2B. - -### Phase 1: Context Preparation & Module Detection (Command Responsibility) - -**Command prepares session paths, metadata, detects module structure. Context priority sorting is NOT performed here - it's already completed in context-gather Phase 2.** - -**Session Path Structure**: -``` -{projectRoot}/.workflow/active/WFS-{session-id}/ -├── workflow-session.json # Session metadata -├── planning-notes.md # Consolidated planning notes -├── .process/ -│ └── context-package.json # Context package with artifact catalog -├── .task/ # Output: Task JSON files -│ ├── IMPL-A1.json # Multi-module: prefixed by module -│ ├── IMPL-A2.json -│ ├── IMPL-B1.json -│ └── ... -├── plan.json # Output: Plan overview (plan-overview-base-schema.json) -├── IMPL_PLAN.md # Output: Implementation plan (grouped by module) -└── TODO_LIST.md # Output: TODO list (hierarchical) -``` - -**Command Preparation**: -1. **Assemble Session Paths** for agent prompt: - - `session_metadata_path` - - `context_package_path` - - Output directory paths - -2. **Provide Metadata** (simple values): - - `session_id` - - `mcp_capabilities` (available MCP tools) - -3. **Auto Module Detection** (determines single vs parallel mode): - ```javascript - function autoDetectModules(contextPackage, projectRoot) { - // === Complexity Gate: Only parallelize for High complexity === - const complexity = contextPackage.metadata?.complexity || 'Medium'; - if (complexity !== 'High') { - // Force single agent mode for Low/Medium complexity - // This maximizes agent context reuse for related tasks - return [{ name: 'main', prefix: '', paths: ['.'] }]; - } - - // Priority 1: Explicit frontend/backend separation - if (exists('src/frontend') && exists('src/backend')) { - return [ - { name: 'frontend', prefix: 'A', paths: ['src/frontend'] }, - { name: 'backend', prefix: 'B', paths: ['src/backend'] } - ]; - } - - // Priority 2: Monorepo structure - if (exists('packages/*') || exists('apps/*')) { - return detectMonorepoModules(); // Returns 2-3 main packages - } - - // Priority 3: Context-package dependency clustering - const modules = clusterByDependencies(contextPackage.dependencies?.internal); - if (modules.length >= 2) return modules.slice(0, 3); - - // Default: Single module (original flow) - return [{ name: 'main', prefix: '', paths: ['.'] }]; - } - ``` - -**Decision Logic**: -- `complexity !== 'High'` → Force Phase 2A (Single Agent, maximize context reuse) -- `modules.length == 1` → Phase 2A (Single Agent, original flow) -- `modules.length >= 2 && complexity == 'High'` → Phase 2B + Phase 3 (N+1 Parallel) - -**Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description, not by flags. - -### Phase 2A: Single Agent Planning (Original Flow) - -**Condition**: `modules.length == 1` (no multi-module detected) - -**Purpose**: Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT code implementation. - -**Agent Invocation**: -```javascript -// Spawn action-planning-agent -const planningAgentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -## TASK OBJECTIVE -Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session - -IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code. - -CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size) - -## PLANNING NOTES (PHASE 1-2 CONTEXT) -Load: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md - -This document contains: -- User Intent: Original GOAL and KEY_CONSTRAINTS from Phase 1 -- Context Findings: Critical files, architecture, and constraints from Phase 2 -- Conflict Decisions: Resolved conflicts and planning constraints from Phase 2 -- Consolidated Constraints: All constraints from all phases - -**USAGE**: Read planning-notes.md FIRST. Use Consolidated Constraints list to guide task sequencing and dependencies. - -## SESSION PATHS -Input: - - Session Metadata: ${projectRoot}/.workflow/active/${session_id}/workflow-session.json - - Planning Notes: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md - - Context Package: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json - -Output: - - Task Dir: ${projectRoot}/.workflow/active/${session_id}/.task/ - - IMPL_PLAN: ${projectRoot}/.workflow/active/${session_id}/IMPL_PLAN.md - - TODO_LIST: ${projectRoot}/.workflow/active/${session_id}/TODO_LIST.md - -## CONTEXT METADATA -Session ID: ${session_id} -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 implementation_approach steps directly - -"cli" → - meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true } - Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt() - -"hybrid" → - Per-task decision: Analyze task complexity, set method to "agent" OR "cli" per task - - Simple tasks (≤3 files, straightforward logic) → method: "agent" - - Complex tasks (>3 files, complex logic, refactoring) → method: "cli" - CLI tool: userConfig.preferredCliTool, enable_resume: true - -IMPORTANT: Do NOT add command field to implementation_approach steps. Execution routing is controlled by task-level meta.execution_config.method only. - -## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED -Context sorting is ALREADY COMPLETED in context-gather Phase 2. DO NOT re-sort. -Direct usage: -- **user_intent**: Use goal/scope/key_constraints for task alignment -- **priority_tiers.critical**: These files are PRIMARY focus for task generation -- **priority_tiers.high**: These files are SECONDARY focus -- **dependency_order**: Use this for task sequencing - already computed -- **sorting_rationale**: Reference for understanding priority decisions - -## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY -If prioritized_context is incomplete, fall back to exploration_results: -- Load exploration_results from context-package.json -- Use aggregated_insights.critical_files for focus_paths generation -- Apply aggregated_insights.constraints to acceptance criteria -- Reference aggregated_insights.all_patterns for implementation approach -- Use aggregated_insights.all_integration_points for precise modification locations -- Use conflict_indicators for risk-aware task sequencing - -## CONFLICT RESOLUTION CONTEXT (if exists) -- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path -- If exists, load .process/conflict-resolution.json: - - Apply planning_constraints as task constraints (for brainstorm-less workflows) - - Reference resolved_conflicts for implementation approach alignment - - Handle custom_conflicts with explicit task notes - -## EXPECTED DELIVERABLES -1. Task JSON Files (.task/IMPL-*.json) - - 6-field schema (id, title, status, context_package_path, meta, context, flow_control) - - Quantified requirements with explicit counts - - Artifacts integration from context package - - **focus_paths generated directly from prioritized_context.priority_tiers (critical + high)** - - NO re-sorting or re-prioritization - use pre-computed tiers as-is - - Critical files are PRIMARY focus, High files are SECONDARY - - Flow control with pre_analysis steps (use prioritized_context.dependency_order for task sequencing) - - **CLI Execution IDs and strategies (MANDATORY)** - -2. Implementation Plan (IMPL_PLAN.md) - - Context analysis and artifact references - - Task breakdown and execution strategy - - Complete structure per agent definition - -3. TODO List (TODO_LIST.md) - - Hierarchical structure (containers, pending, completed markers) - - Links to task JSONs and summaries - - Matches task JSON hierarchy - -## CLI EXECUTION ID REQUIREMENTS (MANDATORY) -Each task JSON MUST include: -- **cli_execution_id**: Unique ID for CLI execution (format: \`{session_id}-{task_id}\`) -- **cli_execution**: Strategy object based on depends_on: - - No deps → \`{ "strategy": "new" }\` - - 1 dep (single child) → \`{ "strategy": "resume", "resume_from": "parent-cli-id" }\` - - 1 dep (multiple children) → \`{ "strategy": "fork", "resume_from": "parent-cli-id" }\` - - N deps → \`{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }\` - -**CLI Execution Strategy Rules**: -1. **new**: Task has no dependencies - starts fresh CLI conversation -2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation -3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context -4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation - -**Execution Command Patterns**: -- new: \`ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]\` -- resume: \`ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write\` -- fork: \`ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write\` -- merge_fork: \`ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write\` - -## QUALITY STANDARDS -Hard Constraints: - - Task count <= 18 (hard limit - request re-scope if exceeded) - - All requirements quantified (explicit counts and enumerated lists) - - Acceptance criteria measurable (include verification commands) - - Artifact references mapped from context package - - All documents follow agent-defined structure - -## SUCCESS CRITERIA -- All planning documents generated successfully: - - Task JSONs valid and saved to .task/ directory - - IMPL_PLAN.md created with complete structure - - TODO_LIST.md generated matching task JSONs -- Return completion status with document count and task breakdown summary - -## PLANNING NOTES RECORD (REQUIRED) -After completing, update planning-notes.md: - -**File**: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md - -1. **Task Generation (Phase 3)**: Task count and key tasks -2. **N+1 Context**: Key decisions (with rationale) + deferred items - -\`\`\`markdown -## Task Generation (Phase 3) -### [Action-Planning Agent] YYYY-MM-DD -- **Tasks**: [count] ([IDs]) - -## N+1 Context -### Decisions -| Decision | Rationale | Revisit? | -|----------|-----------|----------| -| [choice] | [why] | [Yes/No] | - -### Deferred -- [ ] [item] - [reason] -\`\`\` -` -}); - -// Wait for planning agent to complete -const planningResult = wait({ - ids: [planningAgentId], - timeout_ms: 900000 // 15 minutes -}); - -// Close planning agent -close_agent({ id: planningAgentId }); -``` - -### Phase 2B: N Parallel Planning (Multi-Module) - -**Condition**: `modules.length >= 2` (multi-module detected) - -**Purpose**: Launch N action-planning-agents simultaneously, one per module, for parallel task JSON generation. - -**Note**: Phase 2B agents generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md are generated by Phase 3 Coordinator. - -**Parallel Agent Invocation**: -```javascript -// Spawn N agents in parallel (one per module) -const moduleAgents = []; - -modules.forEach(module => { - const agentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -## TASK OBJECTIVE -Generate task JSON files for ${module.name} module within workflow session - -IMPORTANT: This is PLANNING ONLY - generate task JSONs, NOT implementing code. -IMPORTANT: Generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md by Phase 3 Coordinator. - -CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size) - -## PLANNING NOTES (PHASE 1-2 CONTEXT) -Load: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md - -This document contains consolidated constraints and user intent to guide module-scoped task generation. - -## MODULE SCOPE -- Module: ${module.name} (${module.type}) -- Focus Paths: ${module.paths.join(', ')} -- Task ID Prefix: IMPL-${module.prefix} -- Task Limit: ≤6 tasks (hard limit for this module) -- Other Modules: ${otherModules.join(', ')} (reference only, do NOT generate tasks for them) - -## SESSION PATHS -Input: - - Session Metadata: ${projectRoot}/.workflow/active/${session_id}/workflow-session.json - - Planning Notes: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md - - Context Package: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json - -Output: - - Task Dir: ${projectRoot}/.workflow/active/${session_id}/.task/ - -## CONTEXT METADATA -Session ID: ${session_id} -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 implementation_approach steps directly - -"cli" → - meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true } - Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt() - -"hybrid" → - Per-task decision: Analyze task complexity, set method to "agent" OR "cli" per task - - Simple tasks (≤3 files, straightforward logic) → method: "agent" - - Complex tasks (>3 files, complex logic, refactoring) → method: "cli" - CLI tool: userConfig.preferredCliTool, enable_resume: true - -IMPORTANT: Do NOT add command field to implementation_approach steps. Execution routing is controlled by task-level meta.execution_config.method only. - -## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED -Context sorting is ALREADY COMPLETED in context-gather Phase 2. DO NOT re-sort. -Filter by module scope (${module.paths.join(', ')}): -- **user_intent**: Use for task alignment within module -- **priority_tiers.critical**: Filter for files in ${module.paths.join(', ')} → PRIMARY focus -- **priority_tiers.high**: Filter for files in ${module.paths.join(', ')} → SECONDARY focus -- **dependency_order**: Use module-relevant entries for task sequencing - -## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY -If prioritized_context is incomplete for this module, fall back to exploration_results: -- Load exploration_results from context-package.json -- Filter for ${module.name} module: Use aggregated_insights.critical_files matching ${module.paths.join(', ')} -- Apply module-relevant constraints from aggregated_insights.constraints -- Reference aggregated_insights.all_patterns applicable to ${module.name} -- Use aggregated_insights.all_integration_points for precise modification locations within module scope -- Use conflict_indicators for risk-aware task sequencing - -## CONFLICT RESOLUTION CONTEXT (if exists) -- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path -- If exists, load .process/conflict-resolution.json: - - Apply planning_constraints relevant to ${module.name} as task constraints - - Reference resolved_conflicts affecting ${module.name} for implementation approach alignment - - Handle custom_conflicts with explicit task notes - -## CROSS-MODULE DEPENDENCIES -- For dependencies ON other modules: Use placeholder depends_on: ["CROSS::{module}::{pattern}"] -- Example: depends_on: ["CROSS::B::api-endpoint"] (this module depends on B's api-endpoint task) -- Phase 3 Coordinator resolves to actual task IDs -- For dependencies FROM other modules: Document in task context as "provides_for" annotation - -## EXPECTED DELIVERABLES -Task JSON Files (.task/IMPL-${module.prefix}*.json): - - 6-field schema (id, title, status, context_package_path, meta, context, flow_control) - - Task ID format: IMPL-${module.prefix}1, IMPL-${module.prefix}2, ... - - Quantified requirements with explicit counts - - Artifacts integration from context package (filtered for ${module.name}) - - **focus_paths generated directly from prioritized_context.priority_tiers filtered by ${module.paths.join(', ')}** - - NO re-sorting - use pre-computed tiers filtered for this module - - Critical files are PRIMARY focus, High files are SECONDARY - - Flow control with pre_analysis steps (use prioritized_context.dependency_order for module task sequencing) - - **CLI Execution IDs and strategies (MANDATORY)** - - Focus ONLY on ${module.name} module scope - -## CLI EXECUTION ID REQUIREMENTS (MANDATORY) -Each task JSON MUST include: -- **cli_execution_id**: Unique ID for CLI execution (format: \`{session_id}-IMPL-${module.prefix}{seq}\`) -- **cli_execution**: Strategy object based on depends_on: - - No deps → \`{ "strategy": "new" }\` - - 1 dep (single child) → \`{ "strategy": "resume", "resume_from": "parent-cli-id" }\` - - 1 dep (multiple children) → \`{ "strategy": "fork", "resume_from": "parent-cli-id" }\` - - N deps → \`{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }\` - - Cross-module dep → \`{ "strategy": "cross_module_fork", "resume_from": "CROSS::{module}::{pattern}" }\` - -**CLI Execution Strategy Rules**: -1. **new**: Task has no dependencies - starts fresh CLI conversation -2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation -3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context -4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation -5. **cross_module_fork**: Task depends on task from another module - Phase 3 resolves placeholder - -**Execution Command Patterns**: -- new: \`ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]\` -- resume: \`ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write\` -- fork: \`ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write\` -- merge_fork: \`ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write\` -- cross_module_fork: (Phase 3 resolves placeholder, then uses fork pattern) - -## QUALITY STANDARDS -Hard Constraints: - - Task count <= 9 for this module (hard limit - coordinate with Phase 3 if exceeded) - - All requirements quantified (explicit counts and enumerated lists) - - Acceptance criteria measurable (include verification commands) - - Artifact references mapped from context package (module-scoped filter) - - Focus paths use absolute paths or clear relative paths from project root - - Cross-module dependencies use CROSS:: placeholder format - -## SUCCESS CRITERIA -- Task JSONs saved to .task/ with IMPL-${module.prefix}* naming -- All task JSONs include cli_execution_id and cli_execution strategy -- Cross-module dependencies use CROSS:: placeholder format consistently -- Focus paths scoped to ${module.paths.join(', ')} only -- Return: task count, task IDs, dependency summary (internal + cross-module) - -## PLANNING NOTES RECORD (REQUIRED) -After completing, append to planning-notes.md: - -\`\`\`markdown -### [${module.name}] YYYY-MM-DD -- **Tasks**: [count] ([IDs]) -- **CROSS deps**: [placeholders used] -\`\`\` - ` - }); - - moduleAgents.push(agentId); -}); - -// Batch wait for all module agents -const moduleResults = wait({ - ids: moduleAgents, - timeout_ms: 900000 // 15 minutes -}); - -// Close all module agents -moduleAgents.forEach(agentId => { - close_agent({ id: agentId }); -}); -``` - -**Output Structure** (direct to .task/): -``` -.task/ -├── IMPL-A1.json # Module A (e.g., frontend) -├── IMPL-A2.json -├── IMPL-B1.json # Module B (e.g., backend) -├── IMPL-B2.json -└── IMPL-C1.json # Module C (e.g., shared) -``` - -**Task ID Naming**: -- Format: `IMPL-{prefix}{seq}.json` -- Prefix: A, B, C... (assigned by detection order) -- Sequence: 1, 2, 3... (per-module increment) - -### Phase 3: Integration (+1 Coordinator Agent, Multi-Module Only) - -**Condition**: Only executed when `modules.length >= 2` - -**Purpose**: Collect all module tasks, resolve cross-module dependencies, generate unified IMPL_PLAN.md and TODO_LIST.md documents. - -**Coordinator Agent Invocation**: -```javascript -// Wait for all Phase 2B agents to complete (already done above) - -// Spawn +1 Coordinator Agent -const coordinatorAgentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -## TASK OBJECTIVE -Integrate all module task JSONs, resolve cross-module dependencies, and generate unified IMPL_PLAN.md and TODO_LIST.md - -IMPORTANT: This is INTEGRATION ONLY - consolidate existing task JSONs, NOT creating new tasks. - -## SESSION PATHS -Input: - - Session Metadata: ${projectRoot}/.workflow/active/${session_id}/workflow-session.json - - Context Package: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json - - Task JSONs: ${projectRoot}/.workflow/active/${session_id}/.task/IMPL-*.json (from Phase 2B) -Output: - - Updated Task JSONs: ${projectRoot}/.workflow/active/${session_id}/.task/IMPL-*.json (resolved dependencies) - - IMPL_PLAN: ${projectRoot}/.workflow/active/${session_id}/IMPL_PLAN.md - - TODO_LIST: ${projectRoot}/.workflow/active/${session_id}/TODO_LIST.md - -## CONTEXT METADATA -Session ID: ${session_id} -Modules: ${modules.map(m => m.name + '(' + m.prefix + ')').join(', ')} -Module Count: ${modules.length} - -## INTEGRATION STEPS -1. Collect all .task/IMPL-*.json, group by module prefix -2. Resolve CROSS:: dependencies → actual task IDs, update task JSONs -3. Generate IMPL_PLAN.md (multi-module format per agent specification) -4. Generate TODO_LIST.md (hierarchical format per agent specification) - -## CROSS-MODULE DEPENDENCY RESOLUTION -- Pattern: CROSS::{module}::{pattern} → IMPL-{module}* matching title/context -- Example: CROSS::B::api-endpoint → IMPL-B1 (if B1 title contains "api-endpoint") -- Log unresolved as warnings - -## EXPECTED DELIVERABLES -1. Updated Task JSONs with resolved dependency IDs -2. IMPL_PLAN.md - multi-module format with cross-dependency section -3. TODO_LIST.md - hierarchical by module with cross-dependency section - -## SUCCESS CRITERIA -- No CROSS:: placeholders remaining in task JSONs -- IMPL_PLAN.md and TODO_LIST.md generated with multi-module structure -- Return: task count, per-module breakdown, resolved dependency count - -## PLANNING NOTES RECORD (REQUIRED) -After integration, update planning-notes.md: - -\`\`\`markdown -### [Coordinator] YYYY-MM-DD -- **Total**: [count] tasks -- **Resolved**: [CROSS:: resolutions] - -## N+1 Context -### Decisions -| Decision | Rationale | Revisit? | -|----------|-----------|----------| -| CROSS::X → IMPL-Y | [why this resolution] | [Yes/No] | - -### Deferred -- [ ] [unresolved CROSS or conflict] - [reason] -\`\`\` - ` -}); - -// Wait for coordinator agent to complete -const coordinatorResult = wait({ - ids: [coordinatorAgentId], - timeout_ms: 600000 // 10 minutes -}); - -// Close coordinator agent -close_agent({ id: coordinatorAgentId }); -``` - -**Dependency Resolution Algorithm**: -```javascript -function resolveCrossModuleDependency(placeholder, allTasks) { - const [, targetModule, pattern] = placeholder.match(/CROSS::(\w+)::(.+)/); - const candidates = allTasks.filter(t => - t.id.startsWith(`IMPL-${targetModule}`) && - (t.title.toLowerCase().includes(pattern.toLowerCase()) || - t.context?.description?.toLowerCase().includes(pattern.toLowerCase())) - ); - return candidates.length > 0 - ? candidates.sort((a, b) => a.id.localeCompare(b.id))[0].id - : placeholder; // Keep for manual resolution -} -``` - -## Generate plan.json (plan-overview-base-schema) - -After all task JSONs and IMPL_PLAN.md are generated (both single-agent and multi-module paths), generate `plan.json` as structured index: - -```javascript -// Scan generated task files -const taskFiles = Glob(`${sessionFolder}/.task/IMPL-*.json`) -const taskIds = taskFiles.map(f => JSON.parse(Read(f)).id).sort() - -// Guard: skip plan.json if no tasks generated -if (taskIds.length === 0) { - console.warn('No tasks generated; skipping plan.json') -} else { - -const planOverview = { - summary: implPlanSummary, // From IMPL_PLAN.md overview section - approach: implPlanApproach, // From IMPL_PLAN.md approach/strategy - task_ids: taskIds, // ["IMPL-001", "IMPL-002", ...] or ["IMPL-A1", "IMPL-B1", ...] - task_count: taskIds.length, - complexity: complexity, // From Phase 1 assessment - recommended_execution: userConfig.executionMethod === "cli" ? "Codex" : "Agent", - _metadata: { - timestamp: getUtc8ISOString(), - source: "action-planning-agent", - planning_mode: "agent-based", - plan_type: "feature", - schema_version: "2.0" - } -} -Write(`${sessionFolder}/plan.json`, JSON.stringify(planOverview, null, 2)) - -} // end guard -``` - -## Output - -- **Files**: - - `{projectRoot}/.workflow/active/{sessionId}/plan.json` - - `{projectRoot}/.workflow/active/{sessionId}/IMPL_PLAN.md` - - `{projectRoot}/.workflow/active/{sessionId}/.task/IMPL-*.json` - - `{projectRoot}/.workflow/active/{sessionId}/TODO_LIST.md` -- **Updated**: `planning-notes.md` with task generation record and N+1 context - -## Next Step - -Return to orchestrator. Present user with action choices (or auto-continue if `--yes`): -1. Verify Plan Quality (Recommended) → `workflow:plan-verify` -2. Start Execution → Phase 4 (phases/04-execution.md) -3. Review Status Only → `workflow:status` diff --git a/.codex/skills/workflow-plan-execute/phases/04-execution.md b/.codex/skills/workflow-plan-execute/phases/04-execution.md deleted file mode 100644 index 81f03c58..00000000 --- a/.codex/skills/workflow-plan-execute/phases/04-execution.md +++ /dev/null @@ -1,452 +0,0 @@ -# Phase 4: Execution (Conditional) - -Execute implementation tasks using agent orchestration with lazy loading, progress tracking, and optional auto-commit. This phase is triggered conditionally after Phase 3 completes. - -## Trigger Conditions - -- **User Selection**: User chooses "Start Execution" in Phase 3 User Decision -- **Auto Mode** (`--yes`): Automatically enters Phase 4 after Phase 3 completes - -## Auto Mode - -When `--yes` or `-y`: -- **Completion Choice**: Automatically completes session (runs `workflow:session:complete --yes`) - -When `--with-commit`: -- **Auto-Commit**: After each agent task completes, commit changes based on summary document -- **Commit Principle**: Minimal commits - only commit files modified by the completed task -- **Commit Message**: Generated from task summary with format: "feat/fix/refactor: {task-title} - {summary}" - -## Key Design Principles - -1. **No Redundant Discovery**: Session ID and planning docs already available from Phase 1-3 -2. **Autonomous Execution**: Complete entire workflow without user interruption -3. **Lazy Loading**: Task JSONs read on-demand during execution, not upfront -4. **ONE AGENT = ONE TASK JSON**: Each agent instance executes exactly one task JSON file -5. **IMPL_PLAN-Driven Strategy**: Execution model derived from planning document -6. **Continuous Progress Tracking**: TodoWrite updates throughout entire workflow -7. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent - -## Execution Flow - -``` -Step 1: TodoWrite Generation - ├─ Update session status to "active" - ├─ Parse TODO_LIST.md for task statuses - ├─ Generate TodoWrite for entire workflow - └─ Prepare session context paths - -Step 2: Execution Strategy Parsing - ├─ Parse IMPL_PLAN.md Section 4 (Execution Model) - └─ Fallback: Analyze task structure for smart defaults - -Step 3: Task Execution Loop - ├─ Get next in_progress task from TodoWrite - ├─ Lazy load task JSON - ├─ Launch agent (spawn_agent → wait → close_agent) - ├─ Mark task completed (update IMPL-*.json status) - ├─ [with-commit] Auto-commit changes - └─ Advance to next task - -Step 4: Completion - ├─ Synchronize all statuses - ├─ Generate summaries - └─ ASK_USER: Review or Complete Session -``` - -## Step 1: TodoWrite Generation - -### Step 1.0: Update Session Status to Active - -Before generating TodoWrite, update session status from "planning" to "active": -```bash -# Update session status (idempotent - safe to run if already active) -jq '.status = "active" | .execution_started_at = (.execution_started_at // now | todate)' \ - ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json > tmp.json && \ - mv tmp.json ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json -``` -This ensures the dashboard shows the session as "ACTIVE" during execution. - -### Step 1.1: Parse TODO_LIST.md - -``` -1. Create TodoWrite List: Generate task list from TODO_LIST.md (not from task JSONs) - - Parse TODO_LIST.md to extract all tasks with current statuses - - Identify first pending task with met dependencies - - Generate comprehensive TodoWrite covering entire workflow -2. Prepare Session Context: Inject workflow paths for agent use -3. Validate Prerequisites: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid -``` - -**Performance Optimization**: TODO_LIST.md provides task metadata and status. Task JSONs are NOT loaded here - deferred to Step 3 (lazy loading). - -## Step 2: Execution Strategy Parsing - -### Step 2A: Parse Execution Strategy from IMPL_PLAN.md - -Read IMPL_PLAN.md Section 4 to extract: -- **Execution Model**: Sequential | Parallel | Phased | TDD Cycles -- **Parallelization Opportunities**: Which tasks can run in parallel -- **Serialization Requirements**: Which tasks must run sequentially -- **Critical Path**: Priority execution order - -### Step 2B: Intelligent Fallback - -If IMPL_PLAN.md lacks execution strategy, use intelligent fallback: -1. **Analyze task structure**: - - Check `meta.execution_group` in task JSONs - - Analyze `depends_on` relationships - - Understand task complexity and risk -2. **Apply smart defaults**: - - No dependencies + same execution_group → Parallel - - Has dependencies → Sequential (wait for deps) - - Critical/high-risk tasks → Sequential -3. **Conservative approach**: When uncertain, prefer sequential execution - -### Execution Models - -#### 1. Sequential Execution -**When**: IMPL_PLAN specifies "Sequential" OR no clear parallelization guidance -**Pattern**: Execute tasks one by one in TODO_LIST order via spawn_agent → wait → close_agent per task -**TodoWrite**: ONE task marked as `in_progress` at a time - -#### 2. Parallel Execution -**When**: IMPL_PLAN specifies "Parallel" with clear parallelization opportunities -**Pattern**: Execute independent task groups concurrently by spawning multiple agents and batch waiting -**TodoWrite**: MULTIPLE tasks (in same batch) marked as `in_progress` simultaneously -**Agent Instantiation**: spawn one agent per task (respects ONE AGENT = ONE TASK JSON rule), then batch wait - -#### 3. Phased Execution -**When**: IMPL_PLAN specifies "Phased" with phase breakdown -**Pattern**: Execute tasks in phases, respect phase boundaries -**TodoWrite**: Within each phase, follow Sequential or Parallel rules - -## Step 3: Task Execution Loop - -### Execution Loop Pattern -``` -while (TODO_LIST.md has pending tasks) { - next_task_id = getTodoWriteInProgressTask() - task_json = Read(${projectRoot}/.workflow/active/{session}/.task/{next_task_id}.json) // Lazy load - executeTaskWithAgent(task_json) // spawn_agent → wait → close_agent - updateTodoListMarkCompleted(next_task_id) - advanceTodoWriteToNextTask() -} -``` - -### Execution Process per Task -1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID -2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY -3. **Validate Task Structure**: Ensure all required fields exist (id, title, status, meta, context, flow_control) -4. **Launch Agent**: Invoke specialized agent via spawn_agent with complete context including flow control steps -5. **Wait for Completion**: wait for agent result, handle timeout -6. **Close Agent**: close_agent to free resources -7. **Collect Results**: Gather implementation results and outputs -8. **[with-commit] Auto-Commit**: If `--with-commit` flag enabled, commit changes based on summary -9. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat - -**Note**: TODO_LIST.md updates are handled by agents (e.g., code-developer.md), not by the orchestrator. - -### Agent Prompt Template (Sequential) - -**Path-Based Invocation**: Pass paths and trigger markers, let agent parse task JSON autonomously. - -```javascript -// Step 1: Spawn agent -const agentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/${meta.agent}.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -Implement task ${task.id}: ${task.title} - -[FLOW_CONTROL] - -**Input**: -- Task JSON: ${session.task_json_path} -- Context Package: ${session.context_package_path} - -**Output Location**: -- Workflow: ${session.workflow_dir} -- TODO List: ${session.todo_list_path} -- Summaries: ${session.summaries_dir} - -**Execution**: Read task JSON → Execute pre_analysis → Check execution_config.method → (CLI: handoff to CLI tool | Agent: direct implementation) → Update TODO_LIST.md → Generate summary -` -}); - -// Step 2: Wait for completion -const result = wait({ - ids: [agentId], - timeout_ms: 600000 // 10 minutes per task -}); - -// Step 3: Close agent (IMPORTANT: always close) -close_agent({ id: agentId }); -``` - -**Key Markers**: -- `Implement` keyword: Triggers tech stack detection and guidelines loading -- `[FLOW_CONTROL]`: Triggers flow_control.pre_analysis execution - -### Parallel Execution Pattern - -```javascript -// Step 1: Spawn agents for parallel batch -const batchAgents = []; -parallelTasks.forEach(task => { - const agentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/${task.meta.agent}.md (MUST read first) -2. Read: ${projectRoot}/.workflow/project-tech.json -3. Read: ${projectRoot}/.workflow/project-guidelines.json - ---- - -Implement task ${task.id}: ${task.title} - -[FLOW_CONTROL] - -**Input**: -- Task JSON: ${session.task_json_path} -- Context Package: ${session.context_package_path} - -**Output Location**: -- Workflow: ${session.workflow_dir} -- TODO List: ${session.todo_list_path} -- Summaries: ${session.summaries_dir} - -**Execution**: Read task JSON → Execute pre_analysis → Check execution_config.method → (CLI: handoff to CLI tool | Agent: direct implementation) → Update TODO_LIST.md → Generate summary -` - }); - batchAgents.push({ agentId, taskId: task.id }); -}); - -// Step 2: Batch wait for all agents -const batchResult = wait({ - ids: batchAgents.map(a => a.agentId), - timeout_ms: 600000 -}); - -// Step 3: Check results and handle timeouts -if (batchResult.timed_out) { - console.log('Some parallel tasks timed out, continuing with completed results'); -} - -// Step 4: Close all agents -batchAgents.forEach(a => close_agent({ id: a.agentId })); -``` - -### Agent Assignment Rules -``` -meta.agent specified → Use specified agent -meta.agent missing → Infer from meta.type: - - "feature" → @code-developer (role: ~/.codex/agents/code-developer.md) - - "test-gen" → @code-developer (role: ~/.codex/agents/code-developer.md) - - "test-fix" → @test-fix-agent (role: ~/.codex/agents/test-fix-agent.md) - - "review" → @universal-executor (role: ~/.codex/agents/universal-executor.md) - - "docs" → @doc-generator (role: ~/.codex/agents/doc-generator.md) -``` - -### Task Status Logic -``` -pending + dependencies_met → executable -completed → skip -blocked → skip until dependencies clear -``` - -## Step 4: Completion - -### Process -1. **Update Task Status**: Mark completed tasks in JSON files -2. **Generate Summary**: Create task summary in `.summaries/` -3. **Update TodoWrite**: Mark current task complete, advance to next -4. **Synchronize State**: Update session state and workflow status -5. **Check Workflow Complete**: Verify all tasks are completed -6. **User Choice**: When all tasks finished, ask user to choose next step: - -```javascript -// Parse --yes flag -const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') - -if (autoYes) { - // Auto mode: Complete session automatically - console.log(`[--yes] Auto-selecting: Complete Session`) - // Execute: workflow:session:complete --yes -} else { - // Interactive mode: Ask user - ASK_USER([{ - id: "completion-next-step", - type: "select", - prompt: "All tasks completed. What would you like to do next?", - options: [ - { - label: "Enter Review", - description: "Run specialized review (security/architecture/quality/action-items)" - }, - { - label: "Complete Session", - description: "Archive session and update manifest" - } - ] - }]) // BLOCKS (wait for user response) -} -``` - -**Based on user selection**: -- **"Enter Review"**: Execute `workflow:review` -- **"Complete Session"**: Execute `workflow:session:complete` - -### Post-Completion Expansion - -After completion, ask user whether to expand to issues (test/enhance/refactor/doc). Selected items invoke `issue:new "{summary} - {dimension}"`. - -## Auto-Commit Mode (--with-commit) - -**Behavior**: After each agent task completes, automatically commit changes based on summary document. - -**Minimal Principle**: Only commit files modified by the completed task. - -**Commit Message Format**: `{type}: {task-title} - {summary}` - -**Type Mapping** (from `meta.type`): -- `feature` → `feat` | `bugfix` → `fix` | `refactor` → `refactor` -- `test-gen` → `test` | `docs` → `docs` | `review` → `chore` - -**Implementation**: -```bash -# 1. Read summary from .summaries/{task-id}-summary.md -# 2. Extract files from "Files Modified" section -# 3. Commit: git add && git commit -m "{type}: {title} - {summary}" -``` - -**Error Handling**: Skip commit on no changes/missing summary, log errors, continue workflow. - -## TodoWrite Coordination - -### TodoWrite Rules - -**Rule 1: Initial Creation** -- Generate TodoWrite from TODO_LIST.md pending tasks - -**Rule 2: In-Progress Task Count (Execution-Model-Dependent)** -- **Sequential execution**: Mark ONLY ONE task as `in_progress` at a time -- **Parallel batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously -- **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks - -**Rule 3: Status Updates** -- **Immediate Updates**: Update status after each task/batch completion without user interruption -- **Status Synchronization**: Sync with JSON task files after updates -- **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion - -**Rule 4: Workflow Completion Check** -- When all tasks marked `completed`, prompt user to choose review or complete session - -### TodoWrite Examples - -**Sequential Execution**: -```javascript -TodoWrite({ - todos: [ - { - content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]", - status: "in_progress", // ONE task in progress - activeForm: "Executing IMPL-1.1: Design auth schema" - }, - { - content: "Execute IMPL-1.2: Implement auth logic [code-developer] [FLOW_CONTROL]", - status: "pending", - activeForm: "Executing IMPL-1.2: Implement auth logic" - } - ] -}); -``` - -**Parallel Batch Execution**: -```javascript -TodoWrite({ - todos: [ - { - content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]", - status: "in_progress", - activeForm: "Executing IMPL-1.1: Build Auth API" - }, - { - content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]", - status: "in_progress", - activeForm: "Executing IMPL-1.2: Build User UI" - }, - { - content: "Execute IMPL-2.1: Integration Tests [test-fix-agent] [depends_on: IMPL-1.1, IMPL-1.2]", - status: "pending", - activeForm: "Executing IMPL-2.1: Integration Tests" - } - ] -}); -``` - -## Error Handling & Recovery - -### Common Errors & Recovery - -| Error Type | Cause | Recovery Strategy | Max Attempts | -|-----------|-------|------------------|--------------| -| **Execution Errors** | -| Agent failure | Agent crash/timeout | Retry with simplified context (close_agent first, then spawn new) | 2 | -| Flow control error | Command failure | Skip optional, fail critical | 1 per step | -| Context loading error | Missing dependencies | Reload from JSON, use defaults | 3 | -| JSON file corruption | File system issues | Restore from backup/recreate | 1 | -| **Lifecycle Errors** | -| Agent timeout | wait timed out | send_input to prompt completion, or close_agent and retry | 2 | -| Orphaned agent | Agent not closed after error | Ensure close_agent in error paths | N/A | - -### Error Recovery with Lifecycle Management -```javascript -// Safe agent execution pattern with error handling -let agentId = null; -try { - agentId = spawn_agent({ message: taskPrompt }); - const result = wait({ ids: [agentId], timeout_ms: 600000 }); - - if (result.timed_out) { - // Option 1: Send prompt to complete - send_input({ id: agentId, message: "Please wrap up and generate summary." }); - const retryResult = wait({ ids: [agentId], timeout_ms: 120000 }); - } - - // Process results... - close_agent({ id: agentId }); -} catch (error) { - // Ensure cleanup on error - if (agentId) close_agent({ id: agentId }); - // Handle error (retry or skip task) -} -``` - -### Error Prevention -- **Lazy Loading**: Reduces upfront memory usage and validation errors -- **Atomic Updates**: Update JSON files atomically to prevent corruption -- **Dependency Validation**: Check all depends_on references exist -- **Context Verification**: Ensure all required context is available -- **Lifecycle Cleanup**: Always close_agent in both success and error paths - -## Output - -- **Updated**: Task JSON status fields (completed) -- **Created**: `.summaries/IMPL-*-summary.md` per task -- **Updated**: `TODO_LIST.md` (by agents) -- **Updated**: `workflow-session.json` status -- **Created**: Git commits (if `--with-commit`) - -## Next Step - -Return to orchestrator. Orchestrator handles completion summary output. diff --git a/.codex/skills/workflow-tdd-plan/SKILL.md b/.codex/skills/workflow-tdd-plan/SKILL.md deleted file mode 100644 index d13c46f0..00000000 --- a/.codex/skills/workflow-tdd-plan/SKILL.md +++ /dev/null @@ -1,868 +0,0 @@ ---- -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: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep ---- - -# 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. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent -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) -7. **Role Path Loading**: Subagent roles loaded via path reference in MANDATORY FIRST STEPS - -**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. - -## 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: {projectRoot}/.workflow/project-tech.json -3. Read: {projectRoot}/.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 }) -``` - -## Usage - -``` -workflow-tdd-plan -workflow-tdd-plan [-y|--yes] "" - -# Flags --y, --yes Skip all confirmations (auto mode) - -# Arguments - Task description text, TDD-structured format, or path to .md file - -# Examples -workflow-tdd-plan "Build user authentication with tests" # Simple TDD task -workflow-tdd-plan "Add JWT auth with email/password and token refresh" # Detailed task -workflow-tdd-plan -y "Implement payment processing" # Auto mode -workflow-tdd-plan "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 -9. **Explicit Lifecycle**: Always close_agent after wait completes to free resources - -## Execution Flow - -``` -Input Parsing: - └─ Convert user input to TDD-structured format (TDD:/GOAL/SCOPE/CONTEXT/TEST_FOCUS) - -Phase 1: Session Discovery - └─ Ref: workflow-plan-execute/phases/01-session-discovery.md (external) - └─ Output: sessionId (WFS-xxx) - -Phase 2: Context Gathering - └─ Ref: workflow-plan-execute/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 → Inline conflict resolution (within Phase 2) - │ ├─ 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, plan.json ← COLLAPSED - └─ Schema: .task/IMPL-*.json follows 6-field superset of task-schema.json - -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-execute skill): - -| Phase | Document | Purpose | -|-------|----------|---------| -| Phase 1 | workflow-plan-execute/phases/01-session-discovery.md | Session creation/discovery | -| Phase 2 | workflow-plan-execute/phases/02-context-gathering.md | Project context collection + inline conflict resolution | - -**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-execute/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-execute/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: `{projectRoot}/.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 (`{projectRoot}/.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 - -Conflict resolution is handled inline within Phase 2 (context-gathering). When conflict_risk >= medium, Phase 2 automatically performs detection and resolution. - -**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 `{projectRoot}/.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"} -] -``` - -**Step 5.4: Generate plan.json** (plan-overview-base-schema) - -After task generation completes, generate `plan.json` as a machine-readable plan overview: - -```javascript -// Generate plan.json after task generation -const sessionFolder = `${projectRoot}/.workflow/active/${sessionId}` -const taskFiles = Glob(`${sessionFolder}/.task/IMPL-*.json`) -const taskIds = taskFiles.map(f => JSON.parse(Read(f)).id).sort() - -// Guard: skip plan.json if no tasks generated -if (taskIds.length === 0) { - console.warn('No tasks generated; skipping plan.json') -} else { - -const planOverview = { - summary: `TDD plan for: ${taskDescription}`, - approach: `Red-Green-Refactor cycles across ${taskIds.length} implementation tasks`, - task_ids: taskIds, - task_count: taskIds.length, - complexity: complexity, - recommended_execution: "Agent", - _metadata: { - timestamp: getUtc8ISOString(), - source: "tdd-planning-agent", - planning_mode: "agent-based", - plan_type: "tdd", - schema_version: "2.0" - } -} -Write(`${sessionFolder}/plan.json`, JSON.stringify(planOverview, null, 2)) - -} // end guard -``` - -**Validate**: `plan.json` exists and contains valid JSON with `task_ids` matching generated IMPL-*.json files. - ---- - -### 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 ${projectRoot}/.workflow/active/[sessionId]/{IMPL_PLAN.md,TODO_LIST.md,plan.json} -ls -la ${projectRoot}/.workflow/active/[sessionId]/.task/IMPL-*.json - -# Count generated artifacts -echo "IMPL tasks: $(ls ${projectRoot}/.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 ${projectRoot}/.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 | -| Plan overview | `jq .task_count plan.json` | plan.json exists with valid task_ids | -| 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: {projectRoot}/.workflow/active/[sessionId]/IMPL_PLAN.md - (includes TDD Implementation Tasks section with workflow_type: "tdd") -- Plan Overview: {projectRoot}/.workflow/active/[sessionId]/plan.json - (plan-overview-base-schema with task IDs, complexity, and execution metadata) -- Task List: {projectRoot}/.workflow/active/[sessionId]/TODO_LIST.md - (with internal TDD phase indicators and CLI execution strategies) -- Task JSONs: {projectRoot}/.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, plan.json - ↓ -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-execute/phases/01-session-discovery.md --auto -│ └─ Returns: sessionId -│ -├─ Phase 2: Context Gathering -│ └─ workflow-plan-execute/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: -│ └─ Inline within Phase 2 context-gathering ← 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, plan.json ← 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 -- **Subagent timeout**: Retry wait or send_input to prompt completion, then close_agent - -### 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-execute/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 | -| Subagent unresponsive | wait timed_out | send_input to prompt, or close_agent and spawn new | - -## 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. - -## Task JSON Schema Compatibility - -Phase 5 generates `.task/IMPL-*.json` files using the **6-field schema** defined in `action-planning-agent.md`. These task JSONs are a **superset** of the unified `task-schema.json` (located at `.ccw/workflows/cli-templates/schemas/task-schema.json`). - -**Key field mappings** (6-field → unified schema): -- `context.acceptance` → `convergence.criteria` -- `context.requirements` → `description` + `implementation` -- `context.depends_on` → `depends_on` (top-level) -- `context.focus_paths` → `focus_paths` (top-level) -- `meta.type` → `type` (top-level) -- `flow_control.target_files` → `files[].path` - -All existing 6-field schema fields are preserved. TDD-specific extensions (`meta.tdd_workflow`, `tdd_phase` in implementation_approach steps) are additive and do not conflict with the unified schema. See `action-planning-agent.md` Section 2.1 "Schema Compatibility" for the full mapping table. - -## Related Skills - -**Prerequisite**: -- None - TDD planning is self-contained (can optionally run brainstorm before) - -**Called by This Skill** (6 phases): -- workflow-plan-execute/phases/01-session-discovery.md - Phase 1: Create or discover TDD workflow session -- workflow-plan-execute/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 -- Inline conflict resolution within Phase 2 - 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/.codex/skills/workflow-tdd-plan/phases/01-test-context-gather.md b/.codex/skills/workflow-tdd-plan/phases/01-test-context-gather.md deleted file mode 100644 index 40c8f77b..00000000 --- a/.codex/skills/workflow-tdd-plan/phases/01-test-context-gather.md +++ /dev/null @@ -1,240 +0,0 @@ -# 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 `{projectRoot}/.workflow/active/{test_session_id}/.process/test-context-package.json` -- **Explicit Lifecycle**: Always close_agent after wait completes to free resources - -## 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 = `${projectRoot}/.workflow/active/${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 -// Spawn test-context-search-agent -const agentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/test-context-search-agent.md (MUST read first) -2. Read: {projectRoot}/.workflow/project-tech.json -3. Read: {projectRoot}/.workflow/project-guidelines.json - ---- - -## Execution Mode -**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution - -## Session Information -- **Test Session ID**: ${test_session_id} -- **Output Path**: ${projectRoot}/.workflow/active/${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. -` -}); - -// Wait for agent completion -const result = wait({ - ids: [agentId], - timeout_ms: 300000 // 5 minutes -}); - -// Handle timeout -if (result.timed_out) { - console.warn("Test context gathering timed out, sending prompt..."); - send_input({ - id: agentId, - message: "Please complete test-context-package.json generation and report results." - }); - const retryResult = wait({ ids: [agentId], timeout_ms: 120000 }); -} - -// Clean up agent resources -close_agent({ id: agentId }); -``` - -### Step 3: Output Verification - -After agent completes, verify output: - -```javascript -// Verify file was created -const outputPath = `${projectRoot}/.workflow/active/${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 `{projectRoot}/.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` via spawn_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 -- **Explicit lifecycle**: Always close_agent after wait completes - ---- - -## Post-Phase Update - -After Phase 1 (Test Context Gather) completes: -- **Output Created**: `test-context-package.json` in `{projectRoot}/.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/.codex/skills/workflow-tdd-plan/phases/02-task-generate-tdd.md b/.codex/skills/workflow-tdd-plan/phases/02-task-generate-tdd.md deleted file mode 100644 index 330519aa..00000000 --- a/.codex/skills/workflow-tdd-plan/phases/02-task-generate-tdd.md +++ /dev/null @@ -1,771 +0,0 @@ -## 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 -- **Explicit Lifecycle**: Always close_agent after wait completes to free resources - -## 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 via spawn_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 -if (AUTO_YES) { - // --yes/-y: skip user questions, use defaults - userConfig = { materials: "No additional materials", execution: "Agent (Recommended)", cliTool: "Auto" } -} else { - ASK_USER([ - { - id: "Materials", type: "select", - prompt: "Do you have supplementary materials or guidelines to include?", - 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" } - ] - }, - { - id: "Execution", type: "select", - prompt: "Select execution method for generated TDD tasks:", - options: [ - { label: "Agent (Recommended)", description: "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)" } - ] - }, - { - id: "CLI Tool", type: "select", - prompt: "If using CLI, which tool do you prefer?", - 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" } - ] - } - ]) // BLOCKS (wait for user response) -} -``` - -**Handle Materials Response**: -```javascript -if (userConfig.materials === "Provide file paths") { - // Follow-up question for file paths - const pathsResponse = ASK_USER([{ - id: "Paths", type: "input", - prompt: "Enter file paths to include (comma-separated or one per line):", - options: [ - { label: "Enter paths", description: "Provide paths in text input" } - ] - }]) // BLOCKS (wait for user response) - 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): -``` -${projectRoot}/.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`: `${projectRoot}/.workflow/active/{session-id}/workflow-session.json` - - `context_package_path`: `${projectRoot}/.workflow/active/{session-id}/.process/context-package.json` - - `test_context_package_path`: `${projectRoot}/.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 ASK_USER - } -} -``` - -**Discovery Actions**: -1. **Load Session Context** (if not in memory) - ```javascript - if (!memory.has("workflow-session.json")) { - Read(${projectRoot}/.workflow/active/{session-id}/workflow-session.json) - } - ``` - -2. **Load Context Package** (if not in memory) - ```javascript - if (!memory.has("context-package.json")) { - Read(${projectRoot}/.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(${projectRoot}/.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 -// Spawn action-planning-agent -const agentId = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first) -2. Read: {projectRoot}/.workflow/project-tech.json -3. Read: {projectRoot}/.workflow/project-guidelines.json - ---- - -## 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: ${projectRoot}/.workflow/active/{session-id}/workflow-session.json - - Context Package: ${projectRoot}/.workflow/active/{session-id}/.process/context-package.json - - Test Context: ${projectRoot}/.workflow/active/{session-id}/.process/test-context-package.json - -Output: - - Task Dir: ${projectRoot}/.workflow/active/{session-id}/.task/ - - IMPL_PLAN: ${projectRoot}/.workflow/active/{session-id}/IMPL_PLAN.md - - TODO_LIST: ${projectRoot}/.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**: \`${projectRoot}/.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**: \`${projectRoot}/.workflow/active/{session-id}/IMPL_PLAN.md\` -- **Template**: \`~/.ccw/workflows/cli-templates/prompts/workflow/impl-plan-template.txt\` -- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown -- **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles -- **Context Analysis**: Artifact references and exploration insights -- **Details**: See action-planning-agent.md § TDD Implementation Plan Creation - -##### 3. TODO_LIST.md -- **Location**: \`${projectRoot}/.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 -` -}); - -// Wait for agent completion -const result = wait({ - ids: [agentId], - timeout_ms: 600000 // 10 minutes -}); - -// Handle timeout -if (result.timed_out) { - console.warn("TDD task generation timed out, prompting completion..."); - send_input({ - id: agentId, - message: "Please finalize document generation and report completion status." - }); - const retryResult = wait({ ids: [agentId], timeout_ms: 300000 }); -} - -// Clean up agent resources (IMPORTANT: must always call) -close_agent({ id: agentId }); -``` - -### 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: "${projectRoot}/.workflow/active/WFS-{id}/workflow-session.json", - context_package_path: "${projectRoot}/.workflow/active/WFS-{id}/.process/context-package.json", - test_context_package_path: "${projectRoot}/.workflow/active/WFS-{id}/.process/test-context-package.json", - output_task_dir: "${projectRoot}/.workflow/active/WFS-{id}/.task/", - output_impl_plan: "${projectRoot}/.workflow/active/WFS-{id}/IMPL_PLAN.md", - output_todo_list: "${projectRoot}/.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 -``` -${projectRoot}/.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 | -| Agent timeout | Large context or complex planning | Retry with send_input, or spawn new agent | - -## Integration - -**Called By**: SKILL.md (Phase 5: TDD Task Generation) -**Invokes**: `action-planning-agent` via spawn_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/.codex/skills/workflow-tdd-plan/phases/03-tdd-verify.md b/.codex/skills/workflow-tdd-plan/phases/03-tdd-verify.md deleted file mode 100644 index 97bf489d..00000000 --- a/.codex/skills/workflow-tdd-plan/phases/03-tdd-verify.md +++ /dev/null @@ -1,575 +0,0 @@ -# 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 `{projectRoot}/.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 ${projectRoot}/.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 ${projectRoot}/.workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename) - ELSE: - session_id = basename(active_sessions[0]) - -# Derive paths -session_dir = ${projectRoot}/.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 ${projectRoot}/.workflow/active/{session_id}/.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 -``` -${projectRoot}/.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-execute/` (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-{session_id} -**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/.codex/skills/workflow-tdd-plan/phases/04-tdd-coverage-analysis.md b/.codex/skills/workflow-tdd-plan/phases/04-tdd-coverage-analysis.md deleted file mode 100644 index b26a6194..00000000 --- a/.codex/skills/workflow-tdd-plan/phases/04-tdd-coverage-analysis.md +++ /dev/null @@ -1,287 +0,0 @@ -# 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 ${projectRoot}/.workflow/active/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '(.focus_paths // .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 > ${projectRoot}/.workflow/active/{session_id}/.process/test-results.json - -# Python -pytest --cov --json-report > ${projectRoot}/.workflow/active/{session_id}/.process/test-results.json - -# Other frameworks (detect from project) -[test_command] --coverage --json-output ${projectRoot}/.workflow/active/{session_id}/.process/test-results.json -``` - -**Output**: test-results.json with coverage data - -### Phase 3: Parse Coverage Data -```bash -jq '.coverage' ${projectRoot}/.workflow/active/{session_id}/.process/test-results.json > ${projectRoot}/.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 ${projectRoot}/.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 ${projectRoot}/.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 ${projectRoot}/.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 `${projectRoot}/.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 -``` -${projectRoot}/.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/ccw/frontend/src/components/mcp/AllProjectsTable.tsx b/ccw/frontend/src/components/mcp/AllProjectsTable.tsx index c01e5d1e..78dc3829 100644 --- a/ccw/frontend/src/components/mcp/AllProjectsTable.tsx +++ b/ccw/frontend/src/components/mcp/AllProjectsTable.tsx @@ -3,7 +3,7 @@ // ======================================== // Table component displaying all recent projects with MCP server statistics -import { useState, useEffect } from 'react'; +import { useState, useEffect, useMemo } from 'react'; import { useIntl } from 'react-intl'; import { Folder, Clock, Database, ExternalLink } from 'lucide-react'; import { Card } from '@/components/ui/Card'; @@ -55,8 +55,11 @@ export function AllProjectsTable({ const { projects, currentProject, isLoading } = useProjectOperations(); // Use provided project paths or default to all projects - const targetProjectPaths = propProjectPaths ?? projects; - const displayProjects = maxProjects ? targetProjectPaths.slice(0, maxProjects) : targetProjectPaths; + // Memoize to stabilize the array reference and prevent useEffect infinite loops + const displayProjects = useMemo(() => { + const target = propProjectPaths ?? projects; + return maxProjects ? target.slice(0, maxProjects) : target; + }, [propProjectPaths, projects, maxProjects]); // Fetch real project server stats on mount useEffect(() => { diff --git a/ccw/frontend/src/hooks/useMcpServers.ts b/ccw/frontend/src/hooks/useMcpServers.ts index bbd1ce05..a4e905f2 100644 --- a/ccw/frontend/src/hooks/useMcpServers.ts +++ b/ccw/frontend/src/hooks/useMcpServers.ts @@ -473,6 +473,8 @@ export interface UseProjectOperationsReturn { isFetchingServers: boolean; } +const EMPTY_PROJECTS: string[] = []; + /** * Combined hook for project operations (all projects, cross-CLI copy, other projects' servers) */ @@ -519,7 +521,7 @@ export function useProjectOperations(): UseProjectOperationsReturn { }; return { - projects: projectsQuery.data?.projects ?? [], + projects: projectsQuery.data?.projects ?? EMPTY_PROJECTS, currentProject: projectsQuery.data?.currentProject ?? projectPath ?? undefined, isLoading: projectsQuery.isLoading, error: projectsQuery.error, diff --git a/ccw/src/commands/issue.ts b/ccw/src/commands/issue.ts index 02e0e575..fae8a222 100644 --- a/ccw/src/commands/issue.ts +++ b/ccw/src/commands/issue.ts @@ -70,13 +70,16 @@ interface TaskTest { integration?: string[]; // Integration test requirements commands?: string[]; // Test commands to run coverage_target?: number; // Minimum coverage % (optional) + manual_checks?: string[]; // Manual verification steps (migrated from acceptance) + success_metrics?: string[]; // Success metrics (task-schema convention) } -interface TaskAcceptance { - criteria: string[]; // Acceptance criteria (testable) - verification: string[]; // How to verify each criterion - manual_checks?: string[]; // Manual verification steps if needed +interface TaskConvergence { + criteria: string[]; // Convergence criteria (testable) + verification?: string | string[]; // How to verify (string or array) + definition_of_done?: string; // Definition of done (optional) } +type TaskAcceptance = TaskConvergence; // Backward compat alias interface TaskCommit { type: 'feat' | 'fix' | 'refactor' | 'test' | 'docs' | 'chore'; @@ -91,19 +94,26 @@ interface SolutionTask { scope: string; action: string; description?: string; + + // New fields (preferred) + files?: { path: string; action?: string; target?: string; change?: string; changes?: string[]; conflict_risk?: string }[]; + convergence?: TaskConvergence; + + // Legacy fields (backward compat read) modification_points?: { file: string; target: string; change: string }[]; + acceptance?: TaskAcceptance; // Lifecycle phases (closed-loop) implementation: string[]; // Implementation steps test: TaskTest; // Test requirements regression: string[]; // Regression check points - acceptance: TaskAcceptance; // Acceptance criteria & verification commit: TaskCommit; // Commit specification depends_on: string[]; estimated_minutes?: number; + effort?: string; // Effort estimate (task-schema: "small"|"medium"|"large"|"xlarge") status?: string; - priority?: number; + priority?: string | number; // String enum or legacy number(1-5) } interface Solution { @@ -119,6 +129,17 @@ interface Solution { bound_at?: string; } +/** Extract file paths from a task (dual-read: new `files` field or legacy `modification_points`) */ +function getTaskFiles(task: SolutionTask): string[] { + if (task.files && task.files.length > 0) { + return task.files.map(f => f.path).filter(Boolean); + } + if (task.modification_points) { + return task.modification_points.map(mp => mp.file).filter(Boolean); + } + return []; +} + // Structured failure detail for debugging interface FailureDetail { task_id?: string; // Which task failed within the solution @@ -1290,15 +1311,13 @@ async function solutionAction(issueId: string | undefined, options: IssueOptions } } - // Brief mode: extract files_touched from modification_points + // Brief mode: extract files_touched from files/modification_points if (options.brief) { const briefSolutions = targetSolutions.map(sol => { const filesTouched = new Set(); for (const task of sol.tasks) { - if (task.modification_points) { - for (const mp of task.modification_points) { - if (mp.file) filesTouched.add(mp.file); - } + for (const f of getTaskFiles(task)) { + filesTouched.add(f); } } return { @@ -1374,10 +1393,8 @@ async function solutionsAction(options: IssueOptions): Promise { if (boundSolution) { const filesTouched = new Set(); for (const task of boundSolution.tasks) { - if (task.modification_points) { - for (const mp of task.modification_points) { - if (mp.file) filesTouched.add(mp.file); - } + for (const f of getTaskFiles(task)) { + filesTouched.add(f); } } @@ -2198,8 +2215,8 @@ async function queueAction(subAction: string | undefined, issueId: string | unde const solution = findSolution(item.issue_id, item.solution_id); if (solution?.tasks) { for (const task of solution.tasks) { - for (const mp of task.modification_points || []) { - solutionFiles.push(mp.file); + for (const f of getTaskFiles(task)) { + solutionFiles.push(f); } } } @@ -2377,8 +2394,8 @@ async function queueAction(subAction: string | undefined, issueId: string | unde // Collect all files touched by this solution const filesTouched = new Set(); for (const task of solution.tasks || []) { - for (const mp of task.modification_points || []) { - filesTouched.add(mp.file); + for (const f of getTaskFiles(task)) { + filesTouched.add(f); } } diff --git a/ccw/tests/issue-command.test.ts b/ccw/tests/issue-command.test.ts index e07f7631..8448810a 100644 --- a/ccw/tests/issue-command.test.ts +++ b/ccw/tests/issue-command.test.ts @@ -620,6 +620,19 @@ describe('issue command module', async () => { describe('Queue Formation', () => { function makeSolutionWithFiles(id: string, files: string[], isBound = true): MockSolution { + return createMockSolution({ + id, + is_bound: isBound, + tasks: [ + { + id: 'T1', + files: files.map((file) => ({ path: file, target: 'x', change: 'y' })), + }, + ], + }); + } + + function makeSolutionWithLegacyFiles(id: string, files: string[], isBound = true): MockSolution { return createMockSolution({ id, is_bound: isBound, @@ -712,7 +725,7 @@ describe('issue command module', async () => { assert.equal(items[0].solution_id, solutionId); }); - it('deduplicates files_touched extracted from modification_points', async () => { + it('deduplicates files_touched extracted from files (new format)', async () => { issueModule ??= await import(issueCommandUrl); assert.ok(env); @@ -735,6 +748,29 @@ describe('issue command module', async () => { assert.deepEqual(items[0].files_touched?.sort(), ['src/dup.ts', 'src/other.ts']); }); + it('extracts files_touched from legacy modification_points format', async () => { + issueModule ??= await import(issueCommandUrl); + assert.ok(env); + + mock.method(console, 'log', () => {}); + mock.method(console, 'error', () => {}); + + const issueId = 'ISS-QUEUE-LEGACY'; + const solutionId = 'SOL-ISS-QUEUE-LEGACY-1'; + const files = ['src/legacy-a.ts', 'src/legacy-b.ts']; + + issueModule.writeIssues([createMockIssue({ id: issueId, status: 'planned', bound_solution_id: solutionId })]); + issueModule.writeSolutions(issueId, [makeSolutionWithLegacyFiles(solutionId, files, true)]); + + await issueModule.issueCommand('queue', ['add', issueId], {}); + + const queue = issueModule.readQueue(); + assert.ok(queue); + const items = queue.solutions || []; + assert.equal(items.length, 1); + assert.deepEqual(items[0].files_touched?.sort(), files.slice().sort()); + }); + it('adds multiple issues to the same active queue with incrementing item IDs', async () => { issueModule ??= await import(issueCommandUrl); assert.ok(env);