diff --git a/.codex/skills/ccw-loop-b/README.md b/.codex/skills/ccw-loop-b/README.md deleted file mode 100644 index aeb708a4..00000000 --- a/.codex/skills/ccw-loop-b/README.md +++ /dev/null @@ -1,301 +0,0 @@ -# CCW Loop-B: Hybrid Orchestrator Pattern - -Iterative development workflow using coordinator + specialized workers architecture. - -## Overview - -CCW Loop-B implements a flexible orchestration pattern: -- **Coordinator**: Main agent managing state, user interaction, worker scheduling -- **Workers**: Specialized agents (init, develop, debug, validate, complete) -- **Modes**: Interactive / Auto / Parallel execution - -## Architecture - -``` -Coordinator (Main Agent) - | - +-- Spawns Workers - | - ccw-loop-b-init.md - | - ccw-loop-b-develop.md - | - ccw-loop-b-debug.md - | - ccw-loop-b-validate.md - | - ccw-loop-b-complete.md - | - +-- Batch Wait (parallel mode) - +-- Sequential Wait (auto/interactive) - +-- State Management - +-- User Interaction -``` - -## Subagent API - -Core APIs for worker orchestration: - -| API | 作用 | -|-----|------| -| `spawn_agent({ message })` | 创建 worker，返回 `agent_id` | -| `wait({ ids, timeout_ms })` | 等待结果（唯一取结果入口） | -| `send_input({ id, message })` | 继续交互 | -| `close_agent({ id })` | 关闭回收 | - -**可用模式**: 单 agent 深度交互 / 多 agent 并行 / 混合模式 - -## Execution Modes - -### Interactive Mode (default) - -Coordinator displays menu, user selects action, spawns corresponding worker. - -```bash -/ccw-loop-b TASK="Implement feature X" -``` - -**Flow**: -1. Init: Parse task, create breakdown -2. Menu: Show options to user -3. User selects action (develop/debug/validate) -4. Spawn worker for selected action -5. Wait for result -6. Display result, back to menu -7. Repeat until complete - -### Auto Mode - -Automated sequential execution following predefined workflow. - -```bash -/ccw-loop-b --mode=auto TASK="Fix bug Y" -``` - -**Flow**: -1. Init → 2. Develop → 3. Validate → 4. Complete - -If issues found: loop back to Debug → Develop → Validate - -### Parallel Mode - -Spawn multiple workers simultaneously, batch wait for results. - -```bash -/ccw-loop-b --mode=parallel TASK="Analyze module Z" -``` - -**Flow**: -1. Init: Create analysis plan -2. Spawn workers in parallel: [develop, debug, validate] -3. Batch wait: `wait({ ids: [w1, w2, w3] })` -4. Merge results -5. Coordinator decides next action -6. Complete - -## Session Structure - -``` -.workflow/.loop/ -+-- {loopId}.json # Master state -+-- {loopId}.workers/ # Worker outputs -| +-- init.output.json -| +-- develop.output.json -| +-- debug.output.json -| +-- validate.output.json -| +-- complete.output.json -+-- {loopId}.progress/ # Human-readable logs - +-- develop.md - +-- debug.md - +-- validate.md - +-- summary.md -``` - -## Worker Responsibilities - -| Worker | Role | Specialization | -|--------|------|----------------| -| **init** | Session initialization | Task parsing, breakdown, planning | -| **develop** | Code implementation | File operations, pattern matching, incremental development | -| **debug** | Problem diagnosis | Root cause analysis, hypothesis testing, fix recommendations | -| **validate** | Testing & verification | Test execution, coverage analysis, quality gates | -| **complete** | Session finalization | Summary generation, commit preparation, cleanup | - -## Usage Examples - -### Example 1: Simple Feature Implementation - -```bash -/ccw-loop-b TASK="Add user logout function" -``` - -**Auto flow**: -- Init: Parse requirements -- Develop: Implement logout in `src/auth.ts` -- Validate: Run tests -- Complete: Generate commit message - -### Example 2: Bug Investigation - -```bash -/ccw-loop-b TASK="Fix memory leak in WebSocket handler" -``` - -**Interactive flow**: -1. Init: Parse issue -2. User selects "debug" → Spawn debug worker -3. Debug: Root cause analysis → recommends fix -4. User selects "develop" → Apply fix -5. User selects "validate" → Verify fix works -6. User selects "complete" → Generate summary - -### Example 3: Comprehensive Analysis - -```bash -/ccw-loop-b --mode=parallel TASK="Analyze payment module for improvements" -``` - -**Parallel flow**: -- Spawn [develop, debug, validate] workers simultaneously -- Develop: Analyze code quality and patterns -- Debug: Identify potential issues -- Validate: Check test coverage -- Wait for all three to complete -- Merge findings into comprehensive report - -### Example 4: Resume Existing Loop - -```bash -/ccw-loop-b --loop-id=loop-b-20260122-abc123 -``` - -Continues from previous state, respects status (running/paused). - -## Key Features - -### 1. Worker Specialization - -Each worker focuses on one domain: -- **No overlap**: Clear boundaries between workers -- **Reusable**: Same worker for different tasks -- **Composable**: Combine workers for complex workflows - -### 2. Flexible Coordination - -Coordinator adapts to mode: -- **Interactive**: Menu-driven, user controls flow -- **Auto**: Predetermined sequence -- **Parallel**: Concurrent execution with batch wait - -### 3. State Management - -Unified state at `.workflow/.loop/{loopId}.json`: -- **API compatible**: Works with CCW API -- **Extension fields**: Skill-specific data in `skill_state` -- **Worker outputs**: Structured JSON for each action - -### 4. Progress Tracking - -Human-readable logs: -- **Per-worker progress**: `{action}.md` files -- **Summary**: Consolidated achievements -- **Commit-ready**: Formatted commit messages - -## Best Practices - -1. **Start with Init**: Always initialize before execution -2. **Use appropriate mode**: - - Interactive: Complex tasks needing user decisions - - Auto: Well-defined workflows - - Parallel: Independent analysis tasks -3. **Clean up workers**: `close_agent()` after each worker completes -4. **Batch wait wisely**: Use in parallel mode for efficiency -5. **Track progress**: Document in progress files -6. **Validate often**: After each develop phase - -## Implementation Patterns - -### Pattern 1: Single Worker Deep Interaction - -```javascript -const workerId = spawn_agent({ message: workerPrompt }) -const result1 = wait({ ids: [workerId] }) - -// Continue with same worker -send_input({ id: workerId, message: "Continue with next task" }) -const result2 = wait({ ids: [workerId] }) - -close_agent({ id: workerId }) -``` - -### Pattern 2: Multi-Worker Parallel - -```javascript -const workers = { - develop: spawn_agent({ message: developPrompt }), - debug: spawn_agent({ message: debugPrompt }), - validate: spawn_agent({ message: validatePrompt }) -} - -// Batch wait -const results = wait({ ids: Object.values(workers), timeout_ms: 900000 }) - -// Process all results -Object.values(workers).forEach(id => close_agent({ id })) -``` - -### Pattern 3: Sequential Worker Chain - -```javascript -const actions = ['init', 'develop', 'validate', 'complete'] - -for (const action of actions) { - const workerId = spawn_agent({ message: buildPrompt(action) }) - const result = wait({ ids: [workerId] }) - - updateState(action, result) - close_agent({ id: workerId }) -} -``` - -## Error Handling - -| Error | Recovery | -|-------|----------| -| Worker timeout | `send_input` request convergence | -| Worker fails | Log error, coordinator decides retry strategy | -| Partial results | Use completed workers, mark incomplete | -| State corruption | Rebuild from progress files | - -## File Structure - -``` -.codex/skills/ccw-loop-b/ -+-- SKILL.md # Entry point -+-- README.md # This file -+-- phases/ -| +-- state-schema.md # State structure definition -+-- specs/ - +-- action-catalog.md # Action reference - -.codex/agents/ -+-- ccw-loop-b-init.md # Worker: Init -+-- ccw-loop-b-develop.md # Worker: Develop -+-- ccw-loop-b-debug.md # Worker: Debug -+-- ccw-loop-b-validate.md # Worker: Validate -+-- ccw-loop-b-complete.md # Worker: Complete -``` - -## Comparison: ccw-loop vs ccw-loop-b - -| Aspect | ccw-loop | ccw-loop-b | -|--------|----------|------------| -| Pattern | Single agent, multi-phase | Coordinator + workers | -| Worker model | Single agent handles all | Specialized workers per action | -| Parallelization | Sequential only | Supports parallel mode | -| Flexibility | Fixed sequence | Mode-based (interactive/auto/parallel) | -| Best for | Simple linear workflows | Complex tasks needing specialization | - -## Contributing - -To add new workers: -1. Create worker role file in `.codex/agents/` -2. Define clear responsibilities -3. Update `action-catalog.md` -4. Add worker to coordinator spawn logic -5. Test integration with existing workers diff --git a/.codex/skills/ccw-loop-b/SKILL.md b/.codex/skills/ccw-loop-b/SKILL.md deleted file mode 100644 index 05554fb2..00000000 --- a/.codex/skills/ccw-loop-b/SKILL.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -name: CCW Loop-B -description: Hybrid orchestrator pattern for iterative development. Coordinator + specialized workers with batch wait support. Triggers on "ccw-loop-b". -argument-hint: TASK="" [--loop-id=] [--mode=] ---- - -# CCW Loop-B - Hybrid Orchestrator Pattern - -协调器 + 专用 worker 的迭代开发工作流。支持单 agent 深度交互、多 agent 并行、混合模式灵活切换。 - -## Arguments - -| Arg | Required | Description | -|-----|----------|-------------| -| TASK | No | Task description (for new loop) | -| --loop-id | No | Existing loop ID to continue | -| --mode | No | `interactive` (default) / `auto` / `parallel` | - -## Architecture - -``` -+------------------------------------------------------------+ -| Main Coordinator | -| 职责: 状态管理 + worker 调度 + 结果汇聚 + 用户交互 | -+------------------------------------------------------------+ - | - +--------------------+--------------------+ - | | | - v v v -+----------------+ +----------------+ +----------------+ -| Worker-Develop | | Worker-Debug | | Worker-Validate| -| 专注: 代码实现 | | 专注: 问题诊断 | | 专注: 测试验证 | -+----------------+ +----------------+ +----------------+ -``` - -## Execution Modes - -### Mode: Interactive (default) - -协调器展示菜单，用户选择 action，spawn 对应 worker 执行。 - -``` -Coordinator -> Show menu -> User selects -> spawn worker -> wait -> Display result -> Loop -``` - -### Mode: Auto - -自动按预设顺序执行，worker 完成后自动切换到下一阶段。 - -``` -Init -> Develop -> [if issues] Debug -> Validate -> [if fail] Loop back -> Complete -``` - -### Mode: Parallel - -并行 spawn 多个 worker 分析不同维度，batch wait 汇聚结果。 - -``` -Coordinator -> spawn [develop, debug, validate] in parallel -> wait({ ids: all }) -> Merge -> Decide -``` - -## Session Structure - -``` -.workflow/.loop/ -+-- {loopId}.json # Master state -+-- {loopId}.workers/ # Worker outputs -| +-- develop.output.json -| +-- debug.output.json -| +-- validate.output.json -+-- {loopId}.progress/ # Human-readable progress - +-- develop.md - +-- debug.md - +-- validate.md - +-- summary.md -``` - -## Subagent API - -| API | 作用 | -|-----|------| -| `spawn_agent({ message })` | 创建 agent，返回 `agent_id` | -| `wait({ ids, timeout_ms })` | 等待结果（唯一取结果入口） | -| `send_input({ id, message })` | 继续交互 | -| `close_agent({ id })` | 关闭回收 | - -## Implementation - -### Coordinator Logic - -```javascript -// ==================== HYBRID ORCHESTRATOR ==================== - -// 1. Initialize -const loopId = args['--loop-id'] || generateLoopId() -const mode = args['--mode'] || 'interactive' -let state = readOrCreateState(loopId, taskDescription) - -// 2. Mode selection -switch (mode) { - case 'interactive': - await runInteractiveMode(loopId, state) - break - - case 'auto': - await runAutoMode(loopId, state) - break - - case 'parallel': - await runParallelMode(loopId, state) - break -} -``` - -### Interactive Mode (单 agent 交互或按需 spawn worker) - -```javascript -async function runInteractiveMode(loopId, state) { - while (state.status === 'running') { - // Show menu, get user choice - const action = await showMenuAndGetChoice(state) - - if (action === 'exit') break - - // Spawn specialized worker for the action - const workerId = spawn_agent({ - message: buildWorkerPrompt(action, loopId, state) - }) - - // Wait for worker completion - const result = wait({ ids: [workerId], timeout_ms: 600000 }) - const output = result.status[workerId].completed - - // Update state and display result - state = updateState(loopId, action, output) - displayResult(output) - - // Cleanup worker - close_agent({ id: workerId }) - } -} -``` - -### Auto Mode (顺序执行 worker 链) - -```javascript -async function runAutoMode(loopId, state) { - const actionSequence = ['init', 'develop', 'debug', 'validate', 'complete'] - let currentIndex = state.skill_state?.action_index || 0 - - while (currentIndex < actionSequence.length && state.status === 'running') { - const action = actionSequence[currentIndex] - - // Spawn worker - const workerId = spawn_agent({ - message: buildWorkerPrompt(action, loopId, state) - }) - - const result = wait({ ids: [workerId], timeout_ms: 600000 }) - const output = result.status[workerId].completed - - // Parse worker result to determine next step - const workerResult = parseWorkerResult(output) - - // Update state - state = updateState(loopId, action, output) - - close_agent({ id: workerId }) - - // Determine next action - if (workerResult.needs_loop_back) { - // Loop back to develop or debug - currentIndex = actionSequence.indexOf(workerResult.loop_back_to) - } else if (workerResult.status === 'failed') { - // Stop on failure - break - } else { - currentIndex++ - } - } -} -``` - -### Parallel Mode (批量 spawn + wait) - -```javascript -async function runParallelMode(loopId, state) { - // Spawn multiple workers in parallel - const workers = { - develop: spawn_agent({ message: buildWorkerPrompt('develop', loopId, state) }), - debug: spawn_agent({ message: buildWorkerPrompt('debug', loopId, state) }), - validate: spawn_agent({ message: buildWorkerPrompt('validate', loopId, state) }) - } - - // Batch wait for all workers - const results = wait({ - ids: Object.values(workers), - timeout_ms: 900000 // 15 minutes for all - }) - - // Collect outputs - const outputs = {} - for (const [role, workerId] of Object.entries(workers)) { - outputs[role] = results.status[workerId].completed - close_agent({ id: workerId }) - } - - // Merge and analyze results - const mergedAnalysis = mergeWorkerOutputs(outputs) - - // Update state with merged results - updateState(loopId, 'parallel-analysis', mergedAnalysis) - - // Coordinator decides next action based on merged results - const decision = decideNextAction(mergedAnalysis) - return decision -} -``` - -### Worker Prompt Builder - -```javascript -function buildWorkerPrompt(action, loopId, state) { - const workerRoles = { - develop: '~/.codex/agents/ccw-loop-b-develop.md', - debug: '~/.codex/agents/ccw-loop-b-debug.md', - validate: '~/.codex/agents/ccw-loop-b-validate.md', - init: '~/.codex/agents/ccw-loop-b-init.md', - complete: '~/.codex/agents/ccw-loop-b-complete.md' - } - - return ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ${workerRoles[action]} (MUST read first) -2. Read: .workflow/project-tech.json -3. Read: .workflow/project-guidelines.json - ---- - -## LOOP CONTEXT - -- **Loop ID**: ${loopId} -- **Action**: ${action} -- **State File**: .workflow/.loop/${loopId}.json -- **Output File**: .workflow/.loop/${loopId}.workers/${action}.output.json -- **Progress File**: .workflow/.loop/${loopId}.progress/${action}.md - -## CURRENT STATE - -${JSON.stringify(state, null, 2)} - -## TASK DESCRIPTION - -${state.description} - -## EXPECTED OUTPUT - -\`\`\` -WORKER_RESULT: -- action: ${action} -- status: success | failed | needs_input -- summary: -- files_changed: [list] -- next_suggestion: -- loop_back_to: - -DETAILED_OUTPUT: - -\`\`\` - -Execute the ${action} action now. -` -} -``` - -## Worker Roles - -| Worker | Role File | 专注领域 | -|--------|-----------|----------| -| init | ccw-loop-b-init.md | 会话初始化、任务解析 | -| develop | ccw-loop-b-develop.md | 代码实现、重构 | -| debug | ccw-loop-b-debug.md | 问题诊断、假设验证 | -| validate | ccw-loop-b-validate.md | 测试执行、覆盖率 | -| complete | ccw-loop-b-complete.md | 总结收尾 | - -## State Schema - -See [phases/state-schema.md](phases/state-schema.md) - -## Usage - -```bash -# Interactive mode (default) -/ccw-loop-b TASK="Implement user authentication" - -# Auto mode -/ccw-loop-b --mode=auto TASK="Fix login bug" - -# Parallel analysis mode -/ccw-loop-b --mode=parallel TASK="Analyze and improve payment module" - -# Resume existing loop -/ccw-loop-b --loop-id=loop-b-20260122-abc123 -``` - -## Error Handling - -| Situation | Action | -|-----------|--------| -| Worker timeout | send_input 请求收敛 | -| Worker failed | Log error, 协调器决策是否重试 | -| Batch wait partial timeout | 使用已完成结果继续 | -| State corrupted | 从 progress 文件重建 | - -## Best Practices - -1. **协调器保持轻量**: 只做调度和状态管理，具体工作交给 worker -2. **Worker 职责单一**: 每个 worker 专注一个领域 -3. **结果标准化**: Worker 输出遵循统一 WORKER_RESULT 格式 -4. **灵活模式切换**: 根据任务复杂度选择合适模式 -5. **及时清理**: Worker 完成后 close_agent 释放资源 diff --git a/.codex/skills/ccw-loop-b/phases/orchestrator.md b/.codex/skills/ccw-loop-b/phases/orchestrator.md deleted file mode 100644 index 3cc29752..00000000 --- a/.codex/skills/ccw-loop-b/phases/orchestrator.md +++ /dev/null @@ -1,257 +0,0 @@ -# Orchestrator (Hybrid Pattern) - -协调器负责状态管理、worker 调度、结果汇聚。 - -## Role - -``` -Read state -> Select mode -> Spawn workers -> Wait results -> Merge -> Update state -> Loop/Exit -``` - -## State Management - -### Read State - -```javascript -function readState(loopId) { - const stateFile = `.workflow/.loop/${loopId}.json` - return fs.existsSync(stateFile) - ? JSON.parse(Read(stateFile)) - : null -} -``` - -### Create State - -```javascript -function createState(loopId, taskDescription, mode) { - const now = new Date().toISOString() - - return { - loop_id: loopId, - title: taskDescription.substring(0, 100), - description: taskDescription, - mode: mode, - status: 'running', - current_iteration: 0, - max_iterations: 10, - created_at: now, - updated_at: now, - skill_state: { - phase: 'init', - action_index: 0, - workers_completed: [], - parallel_results: null - } - } -} -``` - -## Mode Handlers - -### Interactive Mode - -```javascript -async function runInteractiveMode(loopId, state) { - while (state.status === 'running') { - // 1. Show menu - const action = await showMenu(state) - if (action === 'exit') break - - // 2. Spawn worker - const worker = spawn_agent({ - message: buildWorkerPrompt(action, loopId, state) - }) - - // 3. Wait for result - const result = wait({ ids: [worker], timeout_ms: 600000 }) - - // 4. Handle timeout - if (result.timed_out) { - send_input({ id: worker, message: 'Please converge and output WORKER_RESULT' }) - const retryResult = wait({ ids: [worker], timeout_ms: 300000 }) - if (retryResult.timed_out) { - console.log('Worker timeout, skipping') - close_agent({ id: worker }) - continue - } - } - - // 5. Process output - const output = result.status[worker].completed - state = processWorkerOutput(loopId, action, output, state) - - // 6. Cleanup - close_agent({ id: worker }) - - // 7. Display result - displayResult(output) - } -} -``` - -### Auto Mode - -```javascript -async function runAutoMode(loopId, state) { - const sequence = ['init', 'develop', 'debug', 'validate', 'complete'] - let idx = state.skill_state?.action_index || 0 - - while (idx < sequence.length && state.status === 'running') { - const action = sequence[idx] - - // Spawn and wait - const worker = spawn_agent({ message: buildWorkerPrompt(action, loopId, state) }) - const result = wait({ ids: [worker], timeout_ms: 600000 }) - const output = result.status[worker].completed - close_agent({ id: worker }) - - // Parse result - const workerResult = parseWorkerResult(output) - state = processWorkerOutput(loopId, action, output, state) - - // Determine next - if (workerResult.loop_back_to) { - idx = sequence.indexOf(workerResult.loop_back_to) - } else if (workerResult.status === 'failed') { - break - } else { - idx++ - } - - // Update action index - state.skill_state.action_index = idx - saveState(loopId, state) - } -} -``` - -### Parallel Mode - -```javascript -async function runParallelMode(loopId, state) { - // Spawn all workers - const workers = { - develop: spawn_agent({ message: buildWorkerPrompt('develop', loopId, state) }), - debug: spawn_agent({ message: buildWorkerPrompt('debug', loopId, state) }), - validate: spawn_agent({ message: buildWorkerPrompt('validate', loopId, state) }) - } - - // Batch wait - const results = wait({ - ids: Object.values(workers), - timeout_ms: 900000 - }) - - // Collect outputs - const outputs = {} - for (const [role, id] of Object.entries(workers)) { - if (results.status[id].completed) { - outputs[role] = results.status[id].completed - } - close_agent({ id }) - } - - // Merge analysis - state.skill_state.parallel_results = outputs - saveState(loopId, state) - - // Coordinator analyzes merged results - return analyzeAndDecide(outputs) -} -``` - -## Worker Prompt Template - -```javascript -function buildWorkerPrompt(action, loopId, state) { - const roleFiles = { - init: '~/.codex/agents/ccw-loop-b-init.md', - develop: '~/.codex/agents/ccw-loop-b-develop.md', - debug: '~/.codex/agents/ccw-loop-b-debug.md', - validate: '~/.codex/agents/ccw-loop-b-validate.md', - complete: '~/.codex/agents/ccw-loop-b-complete.md' - } - - return ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS -1. **Read role definition**: ${roleFiles[action]} -2. Read: .workflow/project-tech.json -3. Read: .workflow/project-guidelines.json - ---- - -## CONTEXT -- Loop ID: ${loopId} -- Action: ${action} -- State: ${JSON.stringify(state, null, 2)} - -## TASK -${state.description} - -## OUTPUT FORMAT -\`\`\` -WORKER_RESULT: -- action: ${action} -- status: success | failed | needs_input -- summary: -- files_changed: [] -- next_suggestion: -- loop_back_to: - -DETAILED_OUTPUT: - -\`\`\` -` -} -``` - -## Result Processing - -```javascript -function parseWorkerResult(output) { - const result = { - action: 'unknown', - status: 'unknown', - summary: '', - files_changed: [], - next_suggestion: null, - loop_back_to: null - } - - const match = output.match(/WORKER_RESULT:\s*([\s\S]*?)(?:DETAILED_OUTPUT:|$)/) - if (match) { - const lines = match[1].split('\n') - for (const line of lines) { - const m = line.match(/^-\s*(\w+):\s*(.+)$/) - if (m) { - const [, key, value] = m - if (key === 'files_changed') { - try { result.files_changed = JSON.parse(value) } catch {} - } else { - result[key] = value.trim() - } - } - } - } - - return result -} -``` - -## Termination Conditions - -1. User exits (interactive) -2. Sequence complete (auto) -3. Worker failed with no recovery -4. Max iterations reached -5. API paused/stopped - -## Best Practices - -1. **Worker 生命周期**: spawn → wait → close，不保留 worker -2. **结果持久化**: Worker 输出写入 `.workflow/.loop/{loopId}.workers/` -3. **状态同步**: 每次 worker 完成后更新 state -4. **超时处理**: send_input 请求收敛，再超时则跳过 diff --git a/.codex/skills/ccw-loop-b/phases/state-schema.md b/.codex/skills/ccw-loop-b/phases/state-schema.md deleted file mode 100644 index 17dbf966..00000000 --- a/.codex/skills/ccw-loop-b/phases/state-schema.md +++ /dev/null @@ -1,181 +0,0 @@ -# State Schema (CCW Loop-B) - -## Master State Structure - -```json -{ - "loop_id": "loop-b-20260122-abc123", - "title": "Implement user authentication", - "description": "Full task description here", - "mode": "interactive | auto | parallel", - "status": "running | paused | completed | failed", - "current_iteration": 3, - "max_iterations": 10, - "created_at": "2026-01-22T10:00:00.000Z", - "updated_at": "2026-01-22T10:30:00.000Z", - - "skill_state": { - "phase": "develop | debug | validate | complete", - "action_index": 2, - "workers_completed": ["init", "develop"], - "parallel_results": null, - "pending_tasks": [], - "completed_tasks": [], - "findings": [] - } -} -``` - -## Field Descriptions - -### Core Fields (API Compatible) - -| Field | Type | Description | -|-------|------|-------------| -| `loop_id` | string | Unique identifier | -| `title` | string | Short title (max 100 chars) | -| `description` | string | Full task description | -| `mode` | enum | Execution mode | -| `status` | enum | Current status | -| `current_iteration` | number | Iteration counter | -| `max_iterations` | number | Safety limit | -| `created_at` | ISO string | Creation timestamp | -| `updated_at` | ISO string | Last update timestamp | - -### Skill State Fields - -| Field | Type | Description | -|-------|------|-------------| -| `phase` | enum | Current execution phase | -| `action_index` | number | Position in action sequence (auto mode) | -| `workers_completed` | array | List of completed worker actions | -| `parallel_results` | object | Merged results from parallel mode | -| `pending_tasks` | array | Tasks waiting to be executed | -| `completed_tasks` | array | Tasks already done | -| `findings` | array | Discoveries during execution | - -## Worker Output Structure - -Each worker writes to `.workflow/.loop/{loopId}.workers/{action}.output.json`: - -```json -{ - "action": "develop", - "status": "success", - "summary": "Implemented 3 functions", - "files_changed": ["src/auth.ts", "src/utils.ts"], - "next_suggestion": "validate", - "loop_back_to": null, - "timestamp": "2026-01-22T10:15:00.000Z", - "detailed_output": { - "tasks_completed": [ - { "id": "T1", "description": "Create auth module" } - ], - "metrics": { - "lines_added": 150, - "lines_removed": 20 - } - } -} -``` - -## Progress File Structure - -Human-readable progress in `.workflow/.loop/{loopId}.progress/{action}.md`: - -```markdown -# Develop Progress - -## Session: loop-b-20260122-abc123 - -### Iteration 1 (2026-01-22 10:15) - -**Task**: Implement auth module - -**Changes**: -- Created `src/auth.ts` with login/logout functions -- Added JWT token handling in `src/utils.ts` - -**Status**: Success - ---- - -### Iteration 2 (2026-01-22 10:30) - -... -``` - -## Status Transitions - -``` - +--------+ - | init | - +--------+ - | - v -+------> +---------+ -| | develop | -| +---------+ -| | -| +--------+--------+ -| | | -| v v -| +-------+ +---------+ -| | debug |<------| validate| -| +-------+ +---------+ -| | | -| +--------+--------+ -| | -| v -| [needs fix?] -| yes | | no -| v v -+------------+ +----------+ - | complete | - +----------+ -``` - -## Parallel Results Schema - -When `mode === 'parallel'`: - -```json -{ - "parallel_results": { - "develop": { - "status": "success", - "summary": "...", - "suggestions": [] - }, - "debug": { - "status": "success", - "issues_found": [], - "suggestions": [] - }, - "validate": { - "status": "success", - "test_results": {}, - "coverage": {} - }, - "merged_at": "2026-01-22T10:45:00.000Z" - } -} -``` - -## Directory Structure - -``` -.workflow/.loop/ -+-- loop-b-20260122-abc123.json # Master state -+-- loop-b-20260122-abc123.workers/ -| +-- init.output.json -| +-- develop.output.json -| +-- debug.output.json -| +-- validate.output.json -| +-- complete.output.json -+-- loop-b-20260122-abc123.progress/ - +-- develop.md - +-- debug.md - +-- validate.md - +-- summary.md -``` diff --git a/.codex/skills/ccw-loop-b/specs/action-catalog.md b/.codex/skills/ccw-loop-b/specs/action-catalog.md deleted file mode 100644 index 1d628d91..00000000 --- a/.codex/skills/ccw-loop-b/specs/action-catalog.md +++ /dev/null @@ -1,383 +0,0 @@ -# Action Catalog (CCW Loop-B) - -Complete reference of worker actions and their capabilities. - -## Action Matrix - -| Action | Worker Agent | Purpose | Input Requirements | Output | -|--------|--------------|---------|-------------------|--------| -| init | ccw-loop-b-init.md | Session initialization | Task description | Task breakdown + execution plan | -| develop | ccw-loop-b-develop.md | Code implementation | Task list | Code changes + progress update | -| debug | ccw-loop-b-debug.md | Problem diagnosis | Issue description | Root cause analysis + fix suggestions | -| validate | ccw-loop-b-validate.md | Testing and verification | Files to test | Test results + coverage report | -| complete | ccw-loop-b-complete.md | Session finalization | All worker outputs | Summary + commit message | - -## Detailed Action Specifications - -### INIT - -**Purpose**: Parse requirements, create execution plan - -**Preconditions**: -- `status === 'running'` -- `skill_state === null` (first time) - -**Input**: -``` -- Task description (text) -- Project context files -``` - -**Execution**: -1. Read `.workflow/project-tech.json` -2. Read `.workflow/project-guidelines.json` -3. Parse task into phases -4. Create task breakdown -5. Generate execution plan - -**Output**: -``` -WORKER_RESULT: -- action: init -- status: success -- summary: "Initialized with 5 tasks" -- next_suggestion: develop - -TASK_BREAKDOWN: -- T1: Create auth module -- T2: Implement JWT utils -- T3: Write tests -- T4: Validate implementation -- T5: Documentation - -EXECUTION_PLAN: -1. Develop (T1-T2) -2. Validate (T3-T4) -3. Complete (T5) -``` - -**Effects**: -- `skill_state.pending_tasks` populated -- Progress structure created -- Ready for develop phase - ---- - -### DEVELOP - -**Purpose**: Implement code, create/modify files - -**Preconditions**: -- `skill_state.pending_tasks.length > 0` -- `status === 'running'` - -**Input**: -``` -- Task list from state -- Project conventions -- Existing code patterns -``` - -**Execution**: -1. Load pending tasks -2. Find existing patterns -3. Implement tasks one by one -4. Update progress file -5. Mark tasks completed - -**Output**: -``` -WORKER_RESULT: -- action: develop -- status: success -- summary: "Implemented 3 tasks" -- files_changed: ["src/auth.ts", "src/utils.ts"] -- next_suggestion: validate - -DETAILED_OUTPUT: - tasks_completed: [T1, T2] - metrics: - lines_added: 180 - lines_removed: 15 -``` - -**Effects**: -- Files created/modified -- `skill_state.completed_tasks` updated -- Progress documented - -**Failure Modes**: -- Pattern unclear → suggest debug -- Task blocked → mark blocked, continue -- Partial completion → set `loop_back_to: "develop"` - ---- - -### DEBUG - -**Purpose**: Diagnose issues, root cause analysis - -**Preconditions**: -- Issue exists (test failure, bug report, etc.) -- `status === 'running'` - -**Input**: -``` -- Issue description -- Error messages -- Stack traces -- Reproduction steps -``` - -**Execution**: -1. Understand problem symptoms -2. Gather evidence from code -3. Form hypothesis -4. Test hypothesis -5. Document root cause -6. Suggest fixes - -**Output**: -``` -WORKER_RESULT: -- action: debug -- status: success -- summary: "Root cause: memory leak in event listeners" -- next_suggestion: develop (apply fixes) - -ROOT_CAUSE_ANALYSIS: - hypothesis: "Listener accumulation" - confidence: high - evidence: [...] - mechanism: "Detailed explanation" - -FIX_RECOMMENDATIONS: - 1. Add removeAllListeners() on disconnect - 2. Verification: Monitor memory usage -``` - -**Effects**: -- `skill_state.findings` updated -- Fix recommendations documented -- Ready for develop to apply fixes - -**Failure Modes**: -- Insufficient info → request more data -- Multiple hypotheses → rank by likelihood -- Inconclusive → suggest investigation areas - ---- - -### VALIDATE - -**Purpose**: Run tests, check coverage, quality gates - -**Preconditions**: -- Code exists to validate -- `status === 'running'` - -**Input**: -``` -- Files to test -- Test configuration -- Coverage requirements -``` - -**Execution**: -1. Identify test framework -2. Run unit tests -3. Run integration tests -4. Measure coverage -5. Check quality (lint, types, security) -6. Generate report - -**Output**: -``` -WORKER_RESULT: -- action: validate -- status: success -- summary: "113 tests pass, coverage 95%" -- next_suggestion: complete (all pass) | develop (fix failures) - -TEST_RESULTS: - unit_tests: { passed: 98, failed: 0 } - integration_tests: { passed: 15, failed: 0 } - coverage: "95%" - -QUALITY_CHECKS: - lint: ✓ Pass - types: ✓ Pass - security: ✓ Pass -``` - -**Effects**: -- Test results documented -- Coverage measured -- Quality gates verified - -**Failure Modes**: -- Tests fail → document failures, suggest fixes -- Coverage low → identify gaps -- Quality issues → flag problems - ---- - -### COMPLETE - -**Purpose**: Finalize session, generate summary, commit - -**Preconditions**: -- All tasks completed -- Tests passing -- `status === 'running'` - -**Input**: -``` -- All worker outputs -- Progress files -- Current state -``` - -**Execution**: -1. Read all worker outputs -2. Consolidate achievements -3. Verify completeness -4. Generate summary -5. Prepare commit message -6. Cleanup and archive - -**Output**: -``` -WORKER_RESULT: -- action: complete -- status: success -- summary: "Session completed successfully" -- next_suggestion: null - -SESSION_SUMMARY: - achievements: [...] - files_changed: [...] - test_results: { ... } - quality_checks: { ... } - -COMMIT_SUGGESTION: - message: "feat: ..." - files: [...] - ready_for_pr: true -``` - -**Effects**: -- `status` → 'completed' -- Summary file created -- Progress archived -- Commit message ready - -**Failure Modes**: -- Pending tasks remain → mark partial -- Quality gates fail → list failures - ---- - -## Action Flow Diagrams - -### Interactive Mode Flow - -``` -+------+ -| INIT | -+------+ - | - v -+------+ user selects -| MENU |-------------+ -+------+ | - ^ v - | +--------------+ - | | spawn worker | - | +--------------+ - | | - | v - | +------+-------+ - +---------| wait result | - +------+-------+ - | - v - +------+-------+ - | update state | - +--------------+ - | - v - [completed?] --no--> [back to MENU] - | - yes - v - +----------+ - | COMPLETE | - +----------+ -``` - -### Auto Mode Flow - -``` -+------+ +---------+ +-------+ +----------+ +----------+ -| INIT | ---> | DEVELOP | ---> | DEBUG | ---> | VALIDATE | ---> | COMPLETE | -+------+ +---------+ +-------+ +----------+ +----------+ - ^ | | - | +--- [issues] | - +--------------------------------+ - [tests fail] -``` - -### Parallel Mode Flow - -``` -+------+ -| INIT | -+------+ - | - v -+---------------------+ -| spawn all workers | -| [develop, debug, | -| validate] | -+---------------------+ - | - v -+---------------------+ -| wait({ ids: all }) | -+---------------------+ - | - v -+---------------------+ -| merge results | -+---------------------+ - | - v -+---------------------+ -| coordinator decides | -+---------------------+ - | - v -+----------+ -| COMPLETE | -+----------+ -``` - -## Worker Coordination - -| Scenario | Worker Sequence | Mode | -|----------|-----------------|------| -| Simple task | init → develop → validate → complete | Auto | -| Complex task | init → develop → debug → develop → validate → complete | Auto | -| Bug fix | init → debug → develop → validate → complete | Auto | -| Analysis | init → [develop \|\| debug \|\| validate] → complete | Parallel | -| Interactive | init → menu → user selects → worker → menu → ... | Interactive | - -## Best Practices - -1. **Init always first**: Parse requirements before execution -2. **Validate often**: After each develop phase -3. **Debug when needed**: Don't skip diagnosis -4. **Complete always last**: Ensure proper cleanup -5. **Use parallel wisely**: For independent analysis tasks -6. **Follow sequence**: In auto mode, respect dependencies diff --git a/.codex/skills/ccw-loop/README.md b/.codex/skills/ccw-loop/README.md deleted file mode 100644 index b3b18863..00000000 --- a/.codex/skills/ccw-loop/README.md +++ /dev/null @@ -1,171 +0,0 @@ -# CCW Loop Skill (Codex Version) - -Stateless iterative development loop workflow using Codex subagent pattern. - -## Overview - -CCW Loop is an autonomous development workflow that supports: -- **Develop**: Task decomposition -> Code implementation -> Progress tracking -- **Debug**: Hypothesis generation -> Evidence collection -> Root cause analysis -- **Validate**: Test execution -> Coverage check -> Quality assessment - -## Subagent 机制 - -核心 API: `spawn_agent` / `wait` / `send_input` / `close_agent` - -可用模式: 单 agent 深度交互 / 多 agent 并行 / 混合模式 - -## Installation - -Files are in `.codex/skills/ccw-loop/`: - -``` -.codex/skills/ccw-loop/ -+-- SKILL.md # Main skill definition -+-- README.md # This file -+-- phases/ -| +-- orchestrator.md # Orchestration logic -| +-- state-schema.md # State structure -| +-- actions/ -| +-- action-init.md # Initialize session -| +-- action-develop.md # Development task -| +-- action-debug.md # Hypothesis debugging -| +-- action-validate.md # Test validation -| +-- action-complete.md # Complete loop -| +-- action-menu.md # Interactive menu -+-- specs/ -| +-- action-catalog.md # Action catalog -+-- templates/ - +-- (templates) - -.codex/agents/ -+-- ccw-loop-executor.md # Executor agent role -``` - -## Usage - -### Start New Loop - -```bash -# Direct call with task description -/ccw-loop TASK="Implement user authentication" - -# Auto-cycle mode -/ccw-loop --auto TASK="Fix login bug and add tests" -``` - -### Continue Existing Loop - -```bash -# Resume from loop ID -/ccw-loop --loop-id=loop-v2-20260122-abc123 - -# API triggered (from Dashboard) -/ccw-loop --loop-id=loop-v2-20260122-abc123 --auto -``` - -## Execution Flow - -``` -1. Parse arguments (task or --loop-id) -2. Create/read state from .workflow/.loop/{loopId}.json -3. spawn_agent with ccw-loop-executor role -4. Main loop: - a. wait() for agent output - b. Parse ACTION_RESULT - c. Handle outcome: - - COMPLETED/PAUSED/STOPPED: exit loop - - WAITING_INPUT: collect user input, send_input - - Next action: send_input to continue - d. Update state file -5. close_agent when done -``` - -## Session Files - -``` -.workflow/.loop/ -+-- {loopId}.json # Master state (API + Skill) -+-- {loopId}.progress/ - +-- develop.md # Development timeline - +-- debug.md # Understanding evolution - +-- validate.md # Validation report - +-- changes.log # Code changes (NDJSON) - +-- debug.log # Debug log (NDJSON) - +-- summary.md # Completion summary -``` - -## Codex Pattern Highlights - -### Single Agent Deep Interaction - -Instead of creating multiple agents, use `send_input` for multi-phase: - -```javascript -const agent = spawn_agent({ message: role + task }) - -// Phase 1: INIT -const initResult = wait({ ids: [agent] }) - -// Phase 2: DEVELOP (via send_input, same agent) -send_input({ id: agent, message: 'Execute DEVELOP' }) -const devResult = wait({ ids: [agent] }) - -// Phase 3: VALIDATE (via send_input, same agent) -send_input({ id: agent, message: 'Execute VALIDATE' }) -const valResult = wait({ ids: [agent] }) - -// Only close when all done -close_agent({ id: agent }) -``` - -### Role Path Passing - -Agent reads role file itself (no content embedding): - -```javascript -spawn_agent({ - message: ` -### MANDATORY FIRST STEPS -1. **Read role definition**: ~/.codex/agents/ccw-loop-executor.md -2. Read: .workflow/project-tech.json -... -` -}) -``` - -### Explicit Lifecycle Management - -- Always use `wait({ ids })` to get results -- Never assume `close_agent` returns results -- Only `close_agent` when confirming no more interaction needed - -## Error Handling - -| Situation | Action | -|-----------|--------| -| Agent timeout | `send_input` requesting convergence | -| Session not found | Create new session | -| State corrupted | Rebuild from progress files | -| Tests fail | Loop back to DEBUG | -| >10 iterations | Warn and suggest break | - -## Integration - -### Dashboard Integration - -Works with CCW Dashboard Loop Monitor: -- Dashboard creates loop via API -- API triggers this skill with `--loop-id` -- Skill reads/writes `.workflow/.loop/{loopId}.json` -- Dashboard polls state for real-time updates - -### Control Signals - -- `paused`: Skill exits gracefully, waits for resume -- `failed`: Skill terminates -- `running`: Skill continues execution - -## License - -MIT diff --git a/.codex/skills/ccw-loop/SKILL.md b/.codex/skills/ccw-loop/SKILL.md index de81d505..04e89b08 100644 --- a/.codex/skills/ccw-loop/SKILL.md +++ b/.codex/skills/ccw-loop/SKILL.md @@ -1,309 +1,436 @@ --- -name: CCW Loop -description: Stateless iterative development loop workflow with documented progress. Supports develop, debug, and validate phases with file-based state tracking. Triggers on "ccw-loop", "dev loop", "development loop", "开发循环", "迭代开发". -argument-hint: TASK="" [--loop-id=] [--auto] +name: ccw-loop +description: Stateless iterative development loop with single-agent deep interaction. Supports develop, debug, validate phases with file-based state tracking. Triggers on "ccw-loop", "dev loop", "development loop", "开发循环", "迭代开发". +allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep --- -# CCW Loop - Codex Stateless Iterative Development Workflow +# CCW Loop - Stateless Iterative Development Workflow -Stateless iterative development loop using Codex subagent pattern. Supports develop, debug, and validate phases with file-based state tracking. +Stateless iterative development loop using Codex single-agent deep interaction pattern. One agent handles all phases (develop → debug → validate → complete) via `send_input`, with file-based state tracking and Dashboard integration. -## Arguments - -| Arg | Required | Description | -|-----|----------|-------------| -| TASK | No | Task description (for new loop, mutually exclusive with --loop-id) | -| --loop-id | No | Existing loop ID to continue (from API or previous session) | -| --auto | No | Auto-cycle mode (develop -> debug -> validate -> complete) | - -## Unified Architecture (Codex Subagent Pattern) +## Architecture Overview ``` +-------------------------------------------------------------+ | Dashboard (UI) | -| [Create] [Start] [Pause] [Resume] [Stop] [View Progress] | +| [Create] [Start] [Pause] [Resume] [Stop] [View Progress] | +-------------------------------------------------------------+ | v +-------------------------------------------------------------+ | loop-v2-routes.ts (Control Plane) | | | -| State: .workflow/.loop/{loopId}.json (MASTER) | -| Tasks: .workflow/.loop/{loopId}.tasks.jsonl | +| State: .workflow/.loop/{loopId}.json (MASTER) | +| Tasks: .workflow/.loop/{loopId}.tasks.jsonl | | | -| /start -> Trigger ccw-loop skill with --loop-id | -| /pause -> Set status='paused' (skill checks before action) | -| /stop -> Set status='failed' (skill terminates) | -| /resume -> Set status='running' (skill continues) | +| /start -> Trigger ccw-loop skill with --loop-id | +| /pause -> Set status='paused' (skill checks before action) | +| /stop -> Set status='failed' (skill terminates) | +| /resume -> Set status='running' (skill continues) | +-------------------------------------------------------------+ | v +-------------------------------------------------------------+ | ccw-loop Skill (Execution Plane) | | | -| Codex Pattern: spawn_agent -> wait -> send_input -> close | +| Single Agent Deep Interaction: | +| spawn_agent -> wait -> send_input -> ... -> close_agent | | | -| Reads/Writes: .workflow/.loop/{loopId}.json (unified state) | -| Writes: .workflow/.loop/{loopId}.progress/* (progress files) | -| | -| BEFORE each action: | -| -> Check status: paused/stopped -> exit gracefully | -| -> running -> continue with action | -| | -| Actions: init -> develop -> debug -> validate -> complete | +| Actions: INIT -> DEVELOP -> DEBUG -> VALIDATE -> COMPLETE | +-------------------------------------------------------------+ ``` -## Key Design Principles (Codex Adaptation) +## Key Design Principles -1. **Unified State**: API and Skill share `.workflow/.loop/{loopId}.json` state file -2. **Control Signals**: Skill checks status field before each action (paused/stopped) -3. **File-Driven**: All progress documented in `.workflow/.loop/{loopId}.progress/` -4. **Resumable**: Continue any loop with `--loop-id` -5. **Dual Trigger**: Supports API trigger (`--loop-id`) and direct call (task description) -6. **Single Agent Deep Interaction**: Use send_input for multi-phase execution instead of multiple agents +1. **Single Agent Deep Interaction**: One agent handles entire loop lifecycle via `send_input` (no multi-agent overhead) +2. **Unified State**: API and Skill share `.workflow/.loop/{loopId}.json` state file +3. **Control Signals**: Skill checks `status` field before each action (paused/stopped → graceful exit) +4. **File-Driven Progress**: All progress documented in `.workflow/.loop/{loopId}.progress/` +5. **Resumable**: Continue any loop with `--loop-id` +6. **Dual Trigger**: Supports API trigger (`--loop-id`) and direct call (task description) -## Subagent 机制 +## Arguments -### 核心 API - -| API | 作用 | -|-----|------| -| `spawn_agent({ message })` | 创建 subagent，返回 `agent_id` | -| `wait({ ids, timeout_ms })` | 等待结果（唯一取结果入口） | -| `send_input({ id, message })` | 继续交互/追问 | -| `close_agent({ id })` | 关闭回收（不可逆） | - -### 可用模式 - -- **单 Agent 深度交互**: 一个 agent 多阶段，`send_input` 继续 -- **多 Agent 并行**: 主协调器 + 多 worker，`wait({ ids: [...] })` 批量等待 -- **混合模式**: 按需组合 +| Arg | Required | Description | +|-----|----------|-------------| +| TASK | One of TASK or --loop-id | Task description (for new loop) | +| --loop-id | One of TASK or --loop-id | Existing loop ID to continue | +| --auto | No | Auto-cycle mode (develop → debug → validate → complete) | ## Execution Modes ### Mode 1: Interactive -User manually selects each action, suitable for complex tasks. +User manually selects each action via menu. ``` -User -> Select action -> Execute -> View results -> Select next action +User -> MENU -> Select action -> Execute -> View results -> MENU -> ... ``` ### Mode 2: Auto-Loop -Automatic execution in preset order, suitable for standard development flow. +Automatic execution using `selectNextAction` logic. ``` -Develop -> Debug -> Validate -> (if issues) -> Develop -> ... +INIT -> DEVELOP -> ... -> VALIDATE -> (if fail) -> DEBUG -> VALIDATE -> COMPLETE ``` -## Session Structure (Unified Location) +## Execution Flow + +``` +Input Parsing: + └─ Parse arguments (TASK | --loop-id + --auto) + └─ Convert to structured context (loopId, state, progressDir) + +Phase 1: Session Initialization + └─ Ref: phases/01-session-init.md + ├─ Create new loop OR resume existing loop + ├─ Initialize state file and directory structure + └─ Output: loopId, state, progressDir + +Phase 2: Orchestration Loop + └─ Ref: phases/02-orchestration-loop.md + ├─ Spawn single executor agent + ├─ Main while loop: wait → parse → dispatch → send_input + ├─ Handle: COMPLETED / PAUSED / STOPPED / WAITING_INPUT / next action + ├─ Update iteration count per cycle + └─ close_agent on exit +``` + +**Phase Reference Documents** (read on-demand when phase executes): + +| Phase | Document | Purpose | +|-------|----------|---------| +| 1 | [phases/01-session-init.md](phases/01-session-init.md) | Argument parsing, state creation/resume, directory init | +| 2 | [phases/02-orchestration-loop.md](phases/02-orchestration-loop.md) | Agent spawn, main loop, result parsing, send_input dispatch | + +## Data Flow + +``` +User Input (TASK | --loop-id + --auto) + ↓ +[Parse Arguments] + ↓ loopId, state, progressDir + +Phase 1: Session Initialization + ↓ loopId, state (initialized/resumed), progressDir + +Phase 2: Orchestration Loop + ↓ spawn agent → [INIT] → wait → parse + ↓ + ┌─── Main Loop (while iteration < max) ──────────┐ + │ wait() → parseActionResult(output) │ + │ ├─ COMPLETED → close_agent, return │ + │ ├─ PAUSED → close_agent, return │ + │ ├─ STOPPED → close_agent, return │ + │ ├─ WAITING_INPUT → collect input → send_input │ + │ └─ next_action → send_input(continue) │ + │ Update iteration in state file │ + └──────────────────────────────────────────────────┘ + ↓ +close_agent → return finalState +``` + +## Session Structure ``` .workflow/.loop/ -+-- {loopId}.json # Master state file (API + Skill shared) -+-- {loopId}.tasks.jsonl # Task list (API managed) -+-- {loopId}.progress/ # Skill progress files - +-- develop.md # Development progress timeline - +-- debug.md # Understanding evolution document - +-- validate.md # Validation report - +-- changes.log # Code changes log (NDJSON) - +-- debug.log # Debug log (NDJSON) +├── {loopId}.json # Master state file (API + Skill shared) +├── {loopId}.tasks.jsonl # Task list (API managed) +└── {loopId}.progress/ # Skill progress files + ├── develop.md # Development progress timeline + ├── debug.md # Understanding evolution document + ├── validate.md # Validation report + ├── changes.log # Code changes log (NDJSON) + ├── debug.log # Debug log (NDJSON) + ├── hypotheses.json # Debug hypotheses tracking + ├── test-results.json # Test execution results + ├── coverage.json # Coverage data + └── summary.md # Completion summary ``` -## Implementation (Codex Subagent Pattern) +## State Management -### Session Setup +Master state file: `.workflow/.loop/{loopId}.json` -```javascript -// Helper: Get UTC+8 (China Standard Time) ISO string -const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() +```json +{ + "loop_id": "loop-v2-20260122T100000-abc123", + "title": "Task title", + "description": "Full task description", + "max_iterations": 10, + "status": "created | running | paused | completed | failed | user_exit", + "current_iteration": 0, + "created_at": "ISO8601", + "updated_at": "ISO8601", + "completed_at": "ISO8601 (optional)", + "failure_reason": "string (optional)", -// loopId source: -// 1. API trigger: from --loop-id parameter -// 2. Direct call: generate new loop-v2-{timestamp}-{random} + "skill_state": { + "current_action": "init | develop | debug | validate | complete | null", + "last_action": "string | null", + "completed_actions": [], + "mode": "interactive | auto", -const loopId = args['--loop-id'] || (() => { - const timestamp = getUtc8ISOString().replace(/[-:]/g, '').split('.')[0] - const random = Math.random().toString(36).substring(2, 10) - return `loop-v2-${timestamp}-${random}` -})() + "develop": { + "total": 0, "completed": 0, "current_task": null, + "tasks": [{ "id": "task-001", "description": "...", "tool": "gemini", "mode": "write", "status": "pending", "files_changed": [], "created_at": "ISO8601", "completed_at": null }], + "last_progress_at": null + }, -const loopFile = `.workflow/.loop/${loopId}.json` -const progressDir = `.workflow/.loop/${loopId}.progress` + "debug": { + "active_bug": null, "hypotheses_count": 0, + "hypotheses": [{ "id": "H1", "description": "...", "testable_condition": "...", "logging_point": "file:func:line", "evidence_criteria": { "confirm": "...", "reject": "..." }, "likelihood": 1, "status": "pending", "evidence": null, "verdict_reason": null }], + "confirmed_hypothesis": null, "iteration": 0, "last_analysis_at": null + }, -// Create progress directory -mkdir -p "${progressDir}" -``` + "validate": { + "pass_rate": 0, "coverage": 0, + "test_results": [{ "test_name": "...", "suite": "...", "status": "passed | failed | skipped", "duration_ms": 0, "error_message": null, "stack_trace": null }], + "passed": false, "failed_tests": [], "last_run_at": null + }, -### Main Execution Flow (Single Agent Deep Interaction) + "errors": [{ "action": "...", "message": "...", "timestamp": "ISO8601" }], -```javascript -// ==================== CODEX CCW-LOOP: SINGLE AGENT ORCHESTRATOR ==================== - -// Step 1: Read or create initial state -let state = null -if (existingLoopId) { - state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`)) - if (!state) { - console.error(`Loop not found: ${loopId}`) - return + "summary": { "duration": 0, "iterations": 0, "develop": {}, "debug": {}, "validate": {} } } -} else { - state = createInitialState(loopId, taskDescription) - Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2)) } - -// Step 2: Create orchestrator agent (single agent handles all phases) -const agent = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/ccw-loop-executor.md (MUST read first) -2. Read: .workflow/project-tech.json -3. Read: .workflow/project-guidelines.json - ---- - -## LOOP CONTEXT - -- **Loop ID**: ${loopId} -- **State File**: .workflow/.loop/${loopId}.json -- **Progress Dir**: ${progressDir} -- **Mode**: ${mode} // 'interactive' or 'auto' - -## CURRENT STATE - -${JSON.stringify(state, null, 2)} - -## TASK DESCRIPTION - -${taskDescription} - -## EXECUTION INSTRUCTIONS - -You are executing CCW Loop orchestrator. Your job: - -1. **Check Control Signals** - - Read .workflow/.loop/${loopId}.json - - If status === 'paused' -> Output "PAUSED" and stop - - If status === 'failed' -> Output "STOPPED" and stop - - If status === 'running' -> Continue - -2. **Select Next Action** - Based on skill_state: - - If not initialized -> Execute INIT - - If mode === 'interactive' -> Output MENU and wait for input - - If mode === 'auto' -> Auto-select based on state - -3. **Execute Action** - - Follow action instructions from ~/.codex/skills/ccw-loop/phases/actions/ - - Update progress files in ${progressDir}/ - - Update state in .workflow/.loop/${loopId}.json - -4. **Output Format** - \`\`\` - ACTION_RESULT: - - action: {action_name} - - status: success | failed | needs_input - - message: {user message} - - state_updates: {JSON of skill_state updates} - - NEXT_ACTION_NEEDED: {action_name} | WAITING_INPUT | COMPLETED | PAUSED - \`\`\` - -## FIRST ACTION - -${!state.skill_state ? 'Execute: INIT' : mode === 'auto' ? 'Auto-select next action' : 'Show MENU'} -` -}) - -// Step 3: Main orchestration loop -let iteration = 0 -const maxIterations = state.max_iterations || 10 - -while (iteration < maxIterations) { - iteration++ - - // Wait for agent output - const result = wait({ ids: [agent], timeout_ms: 600000 }) - const output = result.status[agent].completed - - // Parse action result - const actionResult = parseActionResult(output) - - // Handle different outcomes - switch (actionResult.next_action) { - case 'COMPLETED': - case 'PAUSED': - case 'STOPPED': - close_agent({ id: agent }) - return actionResult - - case 'WAITING_INPUT': - // Interactive mode: display menu, get user choice - const userChoice = await displayMenuAndGetChoice(actionResult) - - // Send user choice back to agent - send_input({ - id: agent, - message: ` -## USER INPUT RECEIVED - -Action selected: ${userChoice.action} -${userChoice.data ? `Additional data: ${JSON.stringify(userChoice.data)}` : ''} - -## EXECUTE SELECTED ACTION - -Follow instructions for: ${userChoice.action} -Update state and progress files accordingly. -` - }) - break - - default: - // Auto mode: agent continues to next action - // Check if we need to prompt for continuation - if (actionResult.next_action && actionResult.next_action !== 'NONE') { - send_input({ - id: agent, - message: ` -## CONTINUE EXECUTION - -Previous action completed: ${actionResult.action} -Result: ${actionResult.status} - -## EXECUTE NEXT ACTION - -Continue with: ${actionResult.next_action} -` - }) - } - } - - // Update iteration count in state - const currentState = JSON.parse(Read(`.workflow/.loop/${loopId}.json`)) - currentState.current_iteration = iteration - currentState.updated_at = getUtc8ISOString() - Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(currentState, null, 2)) -} - -// Step 4: Cleanup -close_agent({ id: agent }) ``` +**Control Signal Checking**: Agent checks `state.status` before every action: +- `running` → continue +- `paused` → exit gracefully, wait for resume +- `failed` → terminate +- Other → stop + +**Recovery**: If state corrupted, rebuild `skill_state` from `.progress/` markdown files and logs. + ## Action Catalog -| Action | Purpose | Output Files | Trigger | -|--------|---------|--------------|---------| -| [action-init](phases/actions/action-init.md) | Initialize loop session | meta.json, state.json | First run | -| [action-develop](phases/actions/action-develop.md) | Execute development task | progress.md, tasks.json | Has pending tasks | -| [action-debug](phases/actions/action-debug.md) | Hypothesis-driven debug | understanding.md, hypotheses.json | Needs debugging | -| [action-validate](phases/actions/action-validate.md) | Test and validate | validation.md, test-results.json | Needs validation | -| [action-complete](phases/actions/action-complete.md) | Complete loop | summary.md | All done | -| [action-menu](phases/actions/action-menu.md) | Display action menu | - | Interactive mode | +| Action | Purpose | Preconditions | Output Files | Trigger | +|--------|---------|---------------|--------------|---------| +| [INIT](actions/action-init.md) | Initialize session | status=running, skill_state=null | develop.md, state.json | First run | +| [DEVELOP](actions/action-develop.md) | Execute dev task | pending tasks > 0 | develop.md, changes.log | Has pending tasks | +| [DEBUG](actions/action-debug.md) | Hypothesis debug | needs debugging | debug.md, debug.log | Test failures | +| [VALIDATE](actions/action-validate.md) | Run tests | needs validation | validate.md, test-results.json | After develop/debug | +| [COMPLETE](actions/action-complete.md) | Finish loop | all done | summary.md | All tasks done | +| [MENU](actions/action-menu.md) | Display menu | interactive mode | - | Interactive mode | + +### Action Flow + +``` +spawn_agent (ccw-loop-executor) + | + v + +-------+ + | INIT | (if skill_state is null) + +-------+ + | + v + +-------+ send_input + | MENU | <------------- (user selection in interactive mode) + +-------+ + | + +---+---+---+---+ + | | | | | + v v v v v + DEV DBG VAL CMP EXIT + | + v + wait() -> get result + | + v + [Loop continues via send_input] + | + v + close_agent() +``` + +### Action Dependencies + +| Action | Depends On | Leads To | +|--------|------------|----------| +| INIT | - | MENU or DEVELOP | +| MENU | INIT | User selection | +| DEVELOP | INIT | DEVELOP, DEBUG, VALIDATE | +| DEBUG | INIT | DEVELOP, VALIDATE | +| VALIDATE | DEVELOP or DEBUG | COMPLETE, DEBUG, DEVELOP | +| COMPLETE | - | Terminal | + +### Action Sequences + +``` +Happy Path (Auto): INIT → DEVELOP → DEVELOP → VALIDATE (pass) → COMPLETE +Debug Iteration: INIT → DEVELOP → VALIDATE (fail) → DEBUG → VALIDATE (pass) → COMPLETE +Interactive Path: INIT → MENU → DEVELOP → MENU → VALIDATE → MENU → COMPLETE +``` + +## Auto Mode Selection Logic + +```javascript +function selectNextAction(state) { + const skillState = state.skill_state + + // 1. Terminal conditions + if (state.status === 'completed') return null + if (state.status === 'failed') return null + if (state.current_iteration >= state.max_iterations) return 'COMPLETE' + + // 2. Initialization check + if (!skillState) return 'INIT' + + // 3. Auto selection based on state + const hasPendingDevelop = skillState.develop.tasks.some(t => t.status === 'pending') + + if (hasPendingDevelop) return 'DEVELOP' + + if (skillState.last_action === 'DEVELOP') { + if (skillState.develop.completed < skillState.develop.total) return 'DEBUG' + } + + if (skillState.last_action === 'DEBUG' || skillState.debug.confirmed_hypothesis) { + return 'VALIDATE' + } + + if (skillState.last_action === 'VALIDATE') { + if (!skillState.validate.passed) return 'DEVELOP' + } + + if (skillState.validate.passed && !hasPendingDevelop) return 'COMPLETE' + + return 'DEVELOP' +} +``` + +## Coordination Protocol + +### Agent → Orchestrator (ACTION_RESULT) + +Every action MUST output: + +``` +ACTION_RESULT: +- action: {ACTION_NAME} +- status: success | failed | needs_input +- message: {user-facing message} +- state_updates: { ... } + +FILES_UPDATED: +- {file_path}: {description} + +NEXT_ACTION_NEEDED: {ACTION_NAME} | WAITING_INPUT | COMPLETED | PAUSED +``` + +### Orchestrator → Agent (send_input) + +Auto mode continuation: + +``` +## CONTINUE EXECUTION + +Previous action completed: {action} +Result: {status} + +## EXECUTE NEXT ACTION + +Continue with: {next_action} +Read action instructions and execute. +Output ACTION_RESULT when complete. +``` + +Interactive mode user input: + +``` +## USER INPUT RECEIVED + +Action selected: {action} + +## EXECUTE SELECTED ACTION + +Read action instructions and execute: {action} +Update state and progress files accordingly. +Output ACTION_RESULT when complete. +``` + +### Codex Subagent API + +| API | Purpose | +|-----|---------| +| `spawn_agent({ message })` | Create subagent, returns `agent_id` | +| `wait({ ids, timeout_ms })` | Wait for results (only way to get output) | +| `send_input({ id, message })` | Continue interaction / follow-up | +| `close_agent({ id })` | Close and reclaim (irreversible) | + +**Rules**: Single agent for entire loop. `send_input` for multi-phase. `close_agent` only after confirming no more interaction needed. + +## TodoWrite Pattern + +### Phase-Level Tracking (Attached) + +```json +[ + {"content": "Phase 1: Session Initialization", "status": "completed"}, + {"content": "Phase 2: Orchestration Loop", "status": "in_progress"}, + {"content": " → Action: INIT", "status": "completed"}, + {"content": " → Action: DEVELOP (task 1/3)", "status": "in_progress"}, + {"content": " → Action: VALIDATE", "status": "pending"}, + {"content": " → Action: COMPLETE", "status": "pending"} +] +``` + +### Iteration Tracking (Collapsed) + +```json +[ + {"content": "Phase 1: Session Initialization", "status": "completed"}, + {"content": "Iteration 1: DEVELOP x3 + VALIDATE (pass)", "status": "completed"}, + {"content": "Phase 2: COMPLETE", "status": "in_progress"} +] +``` + +## Core Rules + +1. **Start Immediately**: First action is TodoWrite initialization, then Phase 1 execution +2. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute +3. **Parse Every Output**: Extract ACTION_RESULT from agent output for next decision +4. **Auto-Continue**: After each action, execute next pending action automatically (auto mode) +5. **Track Progress**: Update TodoWrite dynamically with attachment/collapse pattern +6. **Single Writer**: Orchestrator updates master state file; agent writes to progress files +7. **File References**: Pass file paths between orchestrator and agent, not content +8. **DO NOT STOP**: Continuous execution until COMPLETED, PAUSED, STOPPED, or max iterations + +## Error Handling + +| Error Type | Recovery | +|------------|----------| +| Agent timeout | send_input requesting convergence, then retry | +| State corrupted | Rebuild from progress markdown files and logs | +| Agent closed unexpectedly | Re-spawn with previous output in message | +| Action failed | Log error, continue or prompt user | +| Tests fail | Loop back to DEVELOP or DEBUG | +| Max iterations reached | Generate summary with remaining issues documented | +| Session not found | Create new session | + +## Coordinator Checklist + +### Before Each Phase + +- [ ] Read phase reference document +- [ ] Check current state for dependencies +- [ ] Update TodoWrite with phase tasks + +### After Each Phase + +- [ ] Parse agent outputs (ACTION_RESULT) +- [ ] Update master state file (iteration count, updated_at) +- [ ] Collapse TodoWrite sub-tasks +- [ ] Determine next action (continue / iterate / complete) + +## Reference Documents + +| Document | Purpose | +|----------|---------| +| [actions/](actions/) | Action definitions (INIT, DEVELOP, DEBUG, VALIDATE, COMPLETE, MENU) | ## Usage @@ -311,40 +438,12 @@ close_agent({ id: agent }) # Start new loop (direct call) /ccw-loop TASK="Implement user authentication" -# Continue existing loop (API trigger or manual resume) -/ccw-loop --loop-id=loop-v2-20260122-abc123 - # Auto-cycle mode /ccw-loop --auto TASK="Fix login bug and add tests" +# Continue existing loop +/ccw-loop --loop-id=loop-v2-20260122-abc123 + # API triggered auto-cycle /ccw-loop --loop-id=loop-v2-20260122-abc123 --auto ``` - -## Reference Documents - -| Document | Purpose | -|----------|---------| -| [phases/orchestrator.md](phases/orchestrator.md) | Orchestrator: state reading + action selection | -| [phases/state-schema.md](phases/state-schema.md) | State structure definition | -| [specs/loop-requirements.md](specs/loop-requirements.md) | Loop requirements specification | -| [specs/action-catalog.md](specs/action-catalog.md) | Action catalog | - -## Error Handling - -| Situation | Action | -|-----------|--------| -| Session not found | Create new session | -| State file corrupted | Rebuild from file contents | -| Agent timeout | send_input to request convergence | -| Agent unexpectedly closed | Re-spawn, paste previous output | -| Tests fail | Loop back to develop/debug | -| >10 iterations | Warn user, suggest break | - -## Codex Best Practices Applied - -1. **Role Path Passing**: Agent reads role file itself (no content embedding) -2. **Single Agent Deep Interaction**: Use send_input for multi-phase instead of multiple agents -3. **Delayed close_agent**: Only close after confirming no more interaction needed -4. **Context Reuse**: Same agent maintains all exploration context automatically -5. **Explicit wait()**: Always use wait({ ids }) to get results, not close_agent diff --git a/.codex/skills/ccw-loop/phases/actions/action-complete.md b/.codex/skills/ccw-loop/actions/action-complete.md similarity index 100% rename from .codex/skills/ccw-loop/phases/actions/action-complete.md rename to .codex/skills/ccw-loop/actions/action-complete.md diff --git a/.codex/skills/ccw-loop/phases/actions/action-debug.md b/.codex/skills/ccw-loop/actions/action-debug.md similarity index 100% rename from .codex/skills/ccw-loop/phases/actions/action-debug.md rename to .codex/skills/ccw-loop/actions/action-debug.md diff --git a/.codex/skills/ccw-loop/phases/actions/action-develop.md b/.codex/skills/ccw-loop/actions/action-develop.md similarity index 100% rename from .codex/skills/ccw-loop/phases/actions/action-develop.md rename to .codex/skills/ccw-loop/actions/action-develop.md diff --git a/.codex/skills/ccw-loop/phases/actions/action-init.md b/.codex/skills/ccw-loop/actions/action-init.md similarity index 100% rename from .codex/skills/ccw-loop/phases/actions/action-init.md rename to .codex/skills/ccw-loop/actions/action-init.md diff --git a/.codex/skills/ccw-loop/phases/actions/action-menu.md b/.codex/skills/ccw-loop/actions/action-menu.md similarity index 100% rename from .codex/skills/ccw-loop/phases/actions/action-menu.md rename to .codex/skills/ccw-loop/actions/action-menu.md diff --git a/.codex/skills/ccw-loop/phases/actions/action-validate.md b/.codex/skills/ccw-loop/actions/action-validate.md similarity index 100% rename from .codex/skills/ccw-loop/phases/actions/action-validate.md rename to .codex/skills/ccw-loop/actions/action-validate.md diff --git a/.codex/skills/ccw-loop/phases/01-session-init.md b/.codex/skills/ccw-loop/phases/01-session-init.md new file mode 100644 index 00000000..adc3b6ad --- /dev/null +++ b/.codex/skills/ccw-loop/phases/01-session-init.md @@ -0,0 +1,138 @@ +# Phase 1: Session Initialization + +Create or resume a development loop, initialize state file and directory structure. + +## Objective + +- Parse user arguments (TASK, --loop-id, --auto) +- Create new loop with unique ID OR resume existing loop +- Initialize directory structure for progress files +- Create master state file +- Output: loopId, state, progressDir + +## Execution + +### Step 1.1: Parse Arguments + +```javascript +const { loopId: existingLoopId, task, mode = 'interactive' } = options + +// Validate mutual exclusivity +if (!existingLoopId && !task) { + console.error('Either --loop-id or task description is required') + return { status: 'error', message: 'Missing loopId or task' } +} + +// Determine mode +const executionMode = options['--auto'] ? 'auto' : 'interactive' +``` + +### Step 1.2: Utility Functions + +```javascript +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +function readLoopState(loopId) { + const stateFile = `.workflow/.loop/${loopId}.json` + if (!fs.existsSync(stateFile)) { + return null + } + return JSON.parse(Read(stateFile)) +} +``` + +### Step 1.3: New Loop Creation + +When `TASK` is provided (no `--loop-id`): + +```javascript +// Generate unique loop ID +const timestamp = getUtc8ISOString().replace(/[-:]/g, '').split('.')[0] +const random = Math.random().toString(36).substring(2, 10) +const loopId = `loop-v2-${timestamp}-${random}` + +console.log(`Creating new loop: ${loopId}`) +``` + +#### Create Directory Structure + +```bash +mkdir -p .workflow/.loop/${loopId}.progress +``` + +#### Initialize State File + +```javascript +function createLoopState(loopId, taskDescription) { + const stateFile = `.workflow/.loop/${loopId}.json` + const now = getUtc8ISOString() + + const state = { + // API compatible fields + loop_id: loopId, + title: taskDescription.substring(0, 100), + description: taskDescription, + max_iterations: 10, + status: 'running', + current_iteration: 0, + created_at: now, + updated_at: now, + + // Skill extension fields (initialized by INIT action) + skill_state: null + } + + Write(stateFile, JSON.stringify(state, null, 2)) + return state +} +``` + +### Step 1.4: Resume Existing Loop + +When `--loop-id` is provided: + +```javascript +const loopId = existingLoopId +const state = readLoopState(loopId) + +if (!state) { + console.error(`Loop not found: ${loopId}`) + return { status: 'error', message: 'Loop not found' } +} + +console.log(`Resuming loop: ${loopId}`) +console.log(`Status: ${state.status}`) +``` + +### Step 1.5: Control Signal Check + +Before proceeding, verify loop status allows continuation: + +```javascript +function checkControlSignals(loopId) { + const state = readLoopState(loopId) + + switch (state?.status) { + case 'paused': + return { continue: false, action: 'pause_exit' } + case 'failed': + return { continue: false, action: 'stop_exit' } + case 'running': + return { continue: true, action: 'continue' } + default: + return { continue: false, action: 'stop_exit' } + } +} +``` + +## Output + +- **Variable**: `loopId` - Unique loop identifier +- **Variable**: `state` - Initialized or resumed loop state object +- **Variable**: `progressDir` - `.workflow/.loop/${loopId}.progress` +- **Variable**: `mode` - `'interactive'` or `'auto'` +- **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress + +## Next Phase + +Return to orchestrator, then auto-continue to [Phase 2: Orchestration Loop](02-orchestration-loop.md). diff --git a/.codex/skills/ccw-loop/phases/02-orchestration-loop.md b/.codex/skills/ccw-loop/phases/02-orchestration-loop.md new file mode 100644 index 00000000..e0b0cbe4 --- /dev/null +++ b/.codex/skills/ccw-loop/phases/02-orchestration-loop.md @@ -0,0 +1,312 @@ +# Phase 2: Orchestration Loop + +Spawn single executor agent and run main orchestration loop until completion, pause, or max iterations. + +## Objective + +- Spawn single executor agent with loop context +- Run main while loop: wait → parse → dispatch → send_input +- Handle terminal conditions (COMPLETED, PAUSED, STOPPED) +- Handle interactive mode (WAITING_INPUT → user choice → send_input) +- Handle auto mode (next action → send_input) +- Update iteration count per cycle +- Close agent on exit + +## Execution + +### Step 2.1: Spawn Executor Agent + +```javascript +const agent = spawn_agent({ + message: ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/ccw-loop-executor.md (MUST read first) +2. Read: .workflow/project-tech.json (if exists) +3. Read: .workflow/project-guidelines.json (if exists) + +--- + +## LOOP CONTEXT + +- **Loop ID**: ${loopId} +- **State File**: .workflow/.loop/${loopId}.json +- **Progress Dir**: ${progressDir} +- **Mode**: ${mode} + +## CURRENT STATE + +${JSON.stringify(state, null, 2)} + +## TASK DESCRIPTION + +${state.description || task} + +## EXECUTION INSTRUCTIONS + +You are executing CCW Loop orchestrator. Your job: + +1. **Check Control Signals** + - Read .workflow/.loop/${loopId}.json + - If status === 'paused' -> Output "PAUSED" and stop + - If status === 'failed' -> Output "STOPPED" and stop + - If status === 'running' -> Continue + +2. **Select Next Action** + Based on skill_state: + - If not initialized -> Execute INIT + - If mode === 'interactive' -> Output MENU and wait for input + - If mode === 'auto' -> Auto-select based on state + +3. **Execute Action** + - Follow action instructions from ~/.codex/skills/ccw-loop/actions/ + - Update progress files in ${progressDir}/ + - Update state in .workflow/.loop/${loopId}.json + +4. **Output Format** + \`\`\` + ACTION_RESULT: + - action: {action_name} + - status: success | failed | needs_input + - message: {user message} + - state_updates: {JSON of skill_state updates} + + NEXT_ACTION_NEEDED: {action_name} | WAITING_INPUT | COMPLETED | PAUSED + \`\`\` + +## FIRST ACTION + +${!state.skill_state ? 'Execute: INIT' : mode === 'auto' ? 'Auto-select next action' : 'Show MENU'} +` +}) +``` + +### Step 2.2: Main Orchestration Loop + +```javascript +let iteration = state.current_iteration || 0 +const maxIterations = state.max_iterations || 10 +let continueLoop = true + +while (continueLoop && iteration < maxIterations) { + iteration++ + + // Wait for agent output + const result = wait({ ids: [agent], timeout_ms: 600000 }) + + // Handle timeout + if (result.timed_out) { + console.log('Agent timeout, requesting convergence...') + send_input({ + id: agent, + message: ` +## TIMEOUT NOTIFICATION + +Execution timeout reached. Please: +1. Output current progress +2. Save any pending state updates +3. Return ACTION_RESULT with current status +` + }) + continue + } + + const output = result.status[agent].completed + + // Parse action result + const actionResult = parseActionResult(output) + + console.log(`\n[Iteration ${iteration}] Action: ${actionResult.action}, Status: ${actionResult.status}`) + + // Update iteration in state + state = readLoopState(loopId) + state.current_iteration = iteration + state.updated_at = getUtc8ISOString() + Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2)) + + // Handle different outcomes + switch (actionResult.next_action) { + case 'COMPLETED': + console.log('Loop completed successfully') + continueLoop = false + break + + case 'PAUSED': + console.log('Loop paused by API, exiting gracefully') + continueLoop = false + break + + case 'STOPPED': + console.log('Loop stopped by API') + continueLoop = false + break + + case 'WAITING_INPUT': + // Interactive mode: display menu, get user choice + if (mode === 'interactive') { + const userChoice = await displayMenuAndGetChoice(actionResult) + + send_input({ + id: agent, + message: ` +## USER INPUT RECEIVED + +Action selected: ${userChoice.action} +${userChoice.data ? `Additional data: ${JSON.stringify(userChoice.data)}` : ''} + +## EXECUTE SELECTED ACTION + +Read action instructions and execute: ${userChoice.action} +Update state and progress files accordingly. +Output ACTION_RESULT when complete. +` + }) + } + break + + default: + // Continue with next action + if (actionResult.next_action && actionResult.next_action !== 'NONE') { + send_input({ + id: agent, + message: ` +## CONTINUE EXECUTION + +Previous action completed: ${actionResult.action} +Result: ${actionResult.status} +${actionResult.message ? `Message: ${actionResult.message}` : ''} + +## EXECUTE NEXT ACTION + +Continue with: ${actionResult.next_action} +Read action instructions and execute. +Output ACTION_RESULT when complete. +` + }) + } else { + if (actionResult.status === 'failed') { + console.log(`Action failed: ${actionResult.message}`) + } + continueLoop = false + } + } +} +``` + +### Step 2.3: Iteration Limit Check + +```javascript +if (iteration >= maxIterations) { + console.log(`\nReached maximum iterations (${maxIterations})`) + console.log('Consider breaking down the task or taking a break.') +} +``` + +### Step 2.4: Cleanup + +```javascript +close_agent({ id: agent }) + +console.log('\n=== CCW Loop Orchestrator Finished ===') + +const finalState = readLoopState(loopId) +return { + status: finalState.status, + loop_id: loopId, + iterations: iteration, + final_state: finalState +} +``` + +## Helper Functions + +### parseActionResult + +```javascript +function parseActionResult(output) { + const result = { + action: 'unknown', + status: 'unknown', + message: '', + state_updates: {}, + next_action: 'NONE' + } + + // Parse ACTION_RESULT block + const actionMatch = output.match(/ACTION_RESULT:\s*([\s\S]*?)(?:FILES_UPDATED:|NEXT_ACTION_NEEDED:|$)/) + if (actionMatch) { + const lines = actionMatch[1].split('\n') + for (const line of lines) { + const match = line.match(/^-\s*(\w+):\s*(.+)$/) + if (match) { + const [, key, value] = match + if (key === 'state_updates') { + try { + result.state_updates = JSON.parse(value) + } catch (e) { + // Try parsing multi-line JSON + } + } else { + result[key] = value.trim() + } + } + } + } + + // Parse NEXT_ACTION_NEEDED + const nextMatch = output.match(/NEXT_ACTION_NEEDED:\s*(\S+)/) + if (nextMatch) { + result.next_action = nextMatch[1] + } + + return result +} +``` + +### displayMenuAndGetChoice + +```javascript +async function displayMenuAndGetChoice(actionResult) { + const menuMatch = actionResult.message.match(/MENU_OPTIONS:\s*([\s\S]*?)(?:WAITING_INPUT:|$)/) + + if (menuMatch) { + console.log('\n' + menuMatch[1]) + } + + const response = await AskUserQuestion({ + questions: [{ + question: "Select next action:", + header: "Action", + multiSelect: false, + options: [ + { label: "develop", description: "Continue development" }, + { label: "debug", description: "Start debugging" }, + { label: "validate", description: "Run validation" }, + { label: "complete", description: "Complete loop" }, + { label: "exit", description: "Exit and save" } + ] + }] + }) + + return { action: response["Action"] } +} +``` + +## Termination Conditions + +1. **API Paused**: `state.status === 'paused'` (Skill exits, wait for resume) +2. **API Stopped**: `state.status === 'failed'` (Skill terminates) +3. **Task Complete**: `NEXT_ACTION_NEEDED === 'COMPLETED'` +4. **Iteration Limit**: `current_iteration >= max_iterations` +5. **User Exit**: User selects 'exit' in interactive mode + +## Output + +- **Variable**: `finalState` - Final loop state after all iterations +- **Return**: `{ status, loop_id, iterations, final_state }` +- **TodoWrite**: Mark Phase 2 completed + +## Next Phase + +None. Phase 2 is the terminal phase of the orchestrator. diff --git a/.codex/skills/ccw-loop/phases/orchestrator.md b/.codex/skills/ccw-loop/phases/orchestrator.md deleted file mode 100644 index e5a8d2cf..00000000 --- a/.codex/skills/ccw-loop/phases/orchestrator.md +++ /dev/null @@ -1,416 +0,0 @@ -# Orchestrator (Codex Pattern) - -Orchestrate CCW Loop using Codex subagent pattern: `spawn_agent -> wait -> send_input -> close_agent`. - -## Role - -Check control signals -> Read file state -> Select action -> Execute via agent -> Update files -> Loop until complete or paused/stopped. - -## Codex Pattern Overview - -``` -+-- spawn_agent (ccw-loop-executor role) --+ -| | -| Phase 1: INIT or first action | -| | | -| v | -| wait() -> get result | -| | | -| v | -| [If needs input] Collect user input | -| | | -| v | -| send_input(user choice + next action) | -| | | -| v | -| wait() -> get result | -| | | -| v | -| [Loop until COMPLETED/PAUSED/STOPPED] | -| | | -+----------v-------------------------------+ - | - close_agent() -``` - -## State Management (Unified Location) - -### Read State - -```javascript -const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() - -/** - * Read loop state (unified location) - * @param loopId - Loop ID (e.g., "loop-v2-20260122-abc123") - */ -function readLoopState(loopId) { - const stateFile = `.workflow/.loop/${loopId}.json` - - if (!fs.existsSync(stateFile)) { - return null - } - - const state = JSON.parse(Read(stateFile)) - return state -} -``` - -### Create New Loop State (Direct Call) - -```javascript -/** - * Create new loop state (only for direct calls, API triggers have existing state) - */ -function createLoopState(loopId, taskDescription) { - const stateFile = `.workflow/.loop/${loopId}.json` - const now = getUtc8ISOString() - - const state = { - // API compatible fields - loop_id: loopId, - title: taskDescription.substring(0, 100), - description: taskDescription, - max_iterations: 10, - status: 'running', // Direct call sets to running - current_iteration: 0, - created_at: now, - updated_at: now, - - // Skill extension fields - skill_state: null // Initialized by INIT action - } - - // Ensure directories exist - mkdir -p ".loop" - mkdir -p ".workflow/.loop/${loopId}.progress" - - Write(stateFile, JSON.stringify(state, null, 2)) - return state -} -``` - -## Main Execution Flow (Codex Subagent) - -```javascript -/** - * Run CCW Loop orchestrator using Codex subagent pattern - * @param options.loopId - Existing Loop ID (API trigger) - * @param options.task - Task description (direct call) - * @param options.mode - 'interactive' | 'auto' - */ -async function runOrchestrator(options = {}) { - const { loopId: existingLoopId, task, mode = 'interactive' } = options - - console.log('=== CCW Loop Orchestrator (Codex) Started ===') - - // 1. Determine loopId and initial state - let loopId - let state - - if (existingLoopId) { - // API trigger: use existing loopId - loopId = existingLoopId - state = readLoopState(loopId) - - if (!state) { - console.error(`Loop not found: ${loopId}`) - return { status: 'error', message: 'Loop not found' } - } - - console.log(`Resuming loop: ${loopId}`) - console.log(`Status: ${state.status}`) - - } else if (task) { - // Direct call: create new loopId - const timestamp = getUtc8ISOString().replace(/[-:]/g, '').split('.')[0] - const random = Math.random().toString(36).substring(2, 10) - loopId = `loop-v2-${timestamp}-${random}` - - console.log(`Creating new loop: ${loopId}`) - console.log(`Task: ${task}`) - - state = createLoopState(loopId, task) - - } else { - console.error('Either --loop-id or task description is required') - return { status: 'error', message: 'Missing loopId or task' } - } - - const progressDir = `.workflow/.loop/${loopId}.progress` - - // 2. Create executor agent (single agent for entire loop) - const agent = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/ccw-loop-executor.md (MUST read first) -2. Read: .workflow/project-tech.json (if exists) -3. Read: .workflow/project-guidelines.json (if exists) - ---- - -## LOOP CONTEXT - -- **Loop ID**: ${loopId} -- **State File**: .workflow/.loop/${loopId}.json -- **Progress Dir**: ${progressDir} -- **Mode**: ${mode} - -## CURRENT STATE - -${JSON.stringify(state, null, 2)} - -## TASK DESCRIPTION - -${state.description || task} - -## FIRST ACTION - -${!state.skill_state ? 'Execute: INIT' : mode === 'auto' ? 'Auto-select next action' : 'Show MENU'} - -Read the role definition first, then execute the appropriate action. -` - }) - - // 3. Main orchestration loop - let iteration = state.current_iteration || 0 - const maxIterations = state.max_iterations || 10 - let continueLoop = true - - while (continueLoop && iteration < maxIterations) { - iteration++ - - // Wait for agent output - const result = wait({ ids: [agent], timeout_ms: 600000 }) - - // Check for timeout - if (result.timed_out) { - console.log('Agent timeout, requesting convergence...') - send_input({ - id: agent, - message: ` -## TIMEOUT NOTIFICATION - -Execution timeout reached. Please: -1. Output current progress -2. Save any pending state updates -3. Return ACTION_RESULT with current status -` - }) - continue - } - - const output = result.status[agent].completed - - // Parse action result - const actionResult = parseActionResult(output) - - console.log(`\n[Iteration ${iteration}] Action: ${actionResult.action}, Status: ${actionResult.status}`) - - // Update iteration in state - state = readLoopState(loopId) - state.current_iteration = iteration - state.updated_at = getUtc8ISOString() - Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2)) - - // Handle different outcomes - switch (actionResult.next_action) { - case 'COMPLETED': - console.log('Loop completed successfully') - continueLoop = false - break - - case 'PAUSED': - console.log('Loop paused by API, exiting gracefully') - continueLoop = false - break - - case 'STOPPED': - console.log('Loop stopped by API') - continueLoop = false - break - - case 'WAITING_INPUT': - // Interactive mode: display menu, get user choice - if (mode === 'interactive') { - const userChoice = await displayMenuAndGetChoice(actionResult) - - // Send user choice back to agent - send_input({ - id: agent, - message: ` -## USER INPUT RECEIVED - -Action selected: ${userChoice.action} -${userChoice.data ? `Additional data: ${JSON.stringify(userChoice.data)}` : ''} - -## EXECUTE SELECTED ACTION - -Read action instructions and execute: ${userChoice.action} -Update state and progress files accordingly. -Output ACTION_RESULT when complete. -` - }) - } - break - - default: - // Continue with next action - if (actionResult.next_action && actionResult.next_action !== 'NONE') { - send_input({ - id: agent, - message: ` -## CONTINUE EXECUTION - -Previous action completed: ${actionResult.action} -Result: ${actionResult.status} -${actionResult.message ? `Message: ${actionResult.message}` : ''} - -## EXECUTE NEXT ACTION - -Continue with: ${actionResult.next_action} -Read action instructions and execute. -Output ACTION_RESULT when complete. -` - }) - } else { - // No next action specified, check if should continue - if (actionResult.status === 'failed') { - console.log(`Action failed: ${actionResult.message}`) - } - continueLoop = false - } - } - } - - // 4. Check iteration limit - if (iteration >= maxIterations) { - console.log(`\nReached maximum iterations (${maxIterations})`) - console.log('Consider breaking down the task or taking a break.') - } - - // 5. Cleanup - close_agent({ id: agent }) - - console.log('\n=== CCW Loop Orchestrator (Codex) Finished ===') - - // Return final state - const finalState = readLoopState(loopId) - return { - status: finalState.status, - loop_id: loopId, - iterations: iteration, - final_state: finalState - } -} - -/** - * Parse action result from agent output - */ -function parseActionResult(output) { - const result = { - action: 'unknown', - status: 'unknown', - message: '', - state_updates: {}, - next_action: 'NONE' - } - - // Parse ACTION_RESULT block - const actionMatch = output.match(/ACTION_RESULT:\s*([\s\S]*?)(?:FILES_UPDATED:|NEXT_ACTION_NEEDED:|$)/) - if (actionMatch) { - const lines = actionMatch[1].split('\n') - for (const line of lines) { - const match = line.match(/^-\s*(\w+):\s*(.+)$/) - if (match) { - const [, key, value] = match - if (key === 'state_updates') { - try { - result.state_updates = JSON.parse(value) - } catch (e) { - // Try parsing multi-line JSON - } - } else { - result[key] = value.trim() - } - } - } - } - - // Parse NEXT_ACTION_NEEDED - const nextMatch = output.match(/NEXT_ACTION_NEEDED:\s*(\S+)/) - if (nextMatch) { - result.next_action = nextMatch[1] - } - - return result -} - -/** - * Display menu and get user choice (interactive mode) - */ -async function displayMenuAndGetChoice(actionResult) { - // Parse MENU_OPTIONS from output - const menuMatch = actionResult.message.match(/MENU_OPTIONS:\s*([\s\S]*?)(?:WAITING_INPUT:|$)/) - - if (menuMatch) { - console.log('\n' + menuMatch[1]) - } - - // Use AskUserQuestion to get choice - const response = await AskUserQuestion({ - questions: [{ - question: "Select next action:", - header: "Action", - multiSelect: false, - options: [ - { label: "develop", description: "Continue development" }, - { label: "debug", description: "Start debugging" }, - { label: "validate", description: "Run validation" }, - { label: "complete", description: "Complete loop" }, - { label: "exit", description: "Exit and save" } - ] - }] - }) - - return { action: response["Action"] } -} -``` - -## Action Catalog - -| Action | Purpose | Preconditions | Effects | -|--------|---------|---------------|---------| -| INIT | Initialize session | status=running, skill_state=null | skill_state initialized | -| MENU | Display menu | skill_state != null, mode=interactive | Wait for user input | -| DEVELOP | Execute dev task | pending tasks > 0 | Update progress.md | -| DEBUG | Hypothesis debug | needs debugging | Update understanding.md | -| VALIDATE | Run tests | needs validation | Update validation.md | -| COMPLETE | Finish loop | all done | status=completed | - -## Termination Conditions - -1. **API Paused**: `state.status === 'paused'` (Skill exits, wait for resume) -2. **API Stopped**: `state.status === 'failed'` (Skill terminates) -3. **Task Complete**: `NEXT_ACTION_NEEDED === 'COMPLETED'` -4. **Iteration Limit**: `current_iteration >= max_iterations` -5. **User Exit**: User selects 'exit' in interactive mode - -## Error Recovery - -| Error Type | Recovery Strategy | -|------------|-------------------| -| Agent timeout | send_input requesting convergence | -| Action failed | Log error, continue or prompt user | -| State corrupted | Rebuild from progress files | -| Agent closed unexpectedly | Re-spawn with previous output in message | - -## Codex Best Practices Applied - -1. **Single Agent Pattern**: One agent handles entire loop lifecycle -2. **Deep Interaction via send_input**: Multi-phase without context loss -3. **Delayed close_agent**: Only after confirming no more interaction -4. **Explicit wait()**: Always get results before proceeding -5. **Role Path Passing**: Agent reads role file, no content embedding diff --git a/.codex/skills/ccw-loop/phases/state-schema.md b/.codex/skills/ccw-loop/phases/state-schema.md deleted file mode 100644 index 6fc12d9f..00000000 --- a/.codex/skills/ccw-loop/phases/state-schema.md +++ /dev/null @@ -1,388 +0,0 @@ -# State Schema (Codex Version) - -CCW Loop state structure definition for Codex subagent pattern. - -## State File - -**Location**: `.workflow/.loop/{loopId}.json` (unified location, API + Skill shared) - -## Structure Definition - -### Unified Loop State Interface - -```typescript -/** - * Unified Loop State - API and Skill shared state structure - * API (loop-v2-routes.ts) owns state control - * Skill (ccw-loop) reads and updates this state via subagent - */ -interface LoopState { - // ===================================================== - // API FIELDS (from loop-v2-routes.ts) - // These fields are managed by API, Skill read-only - // ===================================================== - - loop_id: string // Loop ID, e.g., "loop-v2-20260122-abc123" - title: string // Loop title - description: string // Loop description - max_iterations: number // Maximum iteration count - status: 'created' | 'running' | 'paused' | 'completed' | 'failed' | 'user_exit' - current_iteration: number // Current iteration count - created_at: string // Creation time (ISO8601) - updated_at: string // Last update time (ISO8601) - completed_at?: string // Completion time (ISO8601) - failure_reason?: string // Failure reason - - // ===================================================== - // SKILL EXTENSION FIELDS - // These fields are managed by Skill executor agent - // ===================================================== - - skill_state?: { - // Current execution action - current_action: 'init' | 'develop' | 'debug' | 'validate' | 'complete' | null - last_action: string | null - completed_actions: string[] - mode: 'interactive' | 'auto' - - // === Development Phase === - develop: { - total: number - completed: number - current_task?: string - tasks: DevelopTask[] - last_progress_at: string | null - } - - // === Debug Phase === - debug: { - active_bug?: string - hypotheses_count: number - hypotheses: Hypothesis[] - confirmed_hypothesis: string | null - iteration: number - last_analysis_at: string | null - } - - // === Validation Phase === - validate: { - pass_rate: number // Test pass rate (0-100) - coverage: number // Coverage (0-100) - test_results: TestResult[] - passed: boolean - failed_tests: string[] - last_run_at: string | null - } - - // === Error Tracking === - errors: Array<{ - action: string - message: string - timestamp: string - }> - - // === Summary (after completion) === - summary?: { - duration: number - iterations: number - develop: object - debug: object - validate: object - } - } -} - -interface DevelopTask { - id: string - description: string - tool: 'gemini' | 'qwen' | 'codex' | 'bash' - mode: 'analysis' | 'write' - status: 'pending' | 'in_progress' | 'completed' | 'failed' - files_changed: string[] - created_at: string - completed_at: string | null -} - -interface Hypothesis { - id: string // H1, H2, ... - description: string - testable_condition: string - logging_point: string - evidence_criteria: { - confirm: string - reject: string - } - likelihood: number // 1 = most likely - status: 'pending' | 'confirmed' | 'rejected' | 'inconclusive' - evidence: Record | null - verdict_reason: string | null -} - -interface TestResult { - test_name: string - suite: string - status: 'passed' | 'failed' | 'skipped' - duration_ms: number - error_message: string | null - stack_trace: string | null -} -``` - -## Initial State - -### Created by API (Dashboard Trigger) - -```json -{ - "loop_id": "loop-v2-20260122-abc123", - "title": "Implement user authentication", - "description": "Add login/logout functionality", - "max_iterations": 10, - "status": "created", - "current_iteration": 0, - "created_at": "2026-01-22T10:00:00+08:00", - "updated_at": "2026-01-22T10:00:00+08:00" -} -``` - -### After Skill Initialization (INIT action) - -```json -{ - "loop_id": "loop-v2-20260122-abc123", - "title": "Implement user authentication", - "description": "Add login/logout functionality", - "max_iterations": 10, - "status": "running", - "current_iteration": 0, - "created_at": "2026-01-22T10:00:00+08:00", - "updated_at": "2026-01-22T10:00:05+08:00", - - "skill_state": { - "current_action": "init", - "last_action": null, - "completed_actions": [], - "mode": "auto", - - "develop": { - "total": 3, - "completed": 0, - "current_task": null, - "tasks": [ - { "id": "task-001", "description": "Create auth component", "status": "pending" } - ], - "last_progress_at": null - }, - - "debug": { - "active_bug": null, - "hypotheses_count": 0, - "hypotheses": [], - "confirmed_hypothesis": null, - "iteration": 0, - "last_analysis_at": null - }, - - "validate": { - "pass_rate": 0, - "coverage": 0, - "test_results": [], - "passed": false, - "failed_tests": [], - "last_run_at": null - }, - - "errors": [] - } -} -``` - -## Control Signal Checking (Codex Pattern) - -Agent checks control signals at start of every action: - -```javascript -/** - * Check API control signals - * MUST be called at start of every action - * @returns { continue: boolean, action: 'pause_exit' | 'stop_exit' | 'continue' } - */ -function checkControlSignals(loopId) { - const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`)) - - switch (state.status) { - case 'paused': - // API paused the loop, Skill should exit and wait for resume - return { continue: false, action: 'pause_exit' } - - case 'failed': - // API stopped the loop (user manual stop) - return { continue: false, action: 'stop_exit' } - - case 'running': - // Normal continue - return { continue: true, action: 'continue' } - - default: - // Abnormal status - return { continue: false, action: 'stop_exit' } - } -} -``` - -## State Transitions - -### 1. Initialization (INIT action) - -```javascript -{ - status: 'created' -> 'running', // Or keep 'running' if API already set - updated_at: timestamp, - - skill_state: { - current_action: 'init', - mode: 'auto', - develop: { - tasks: [...parsed_tasks], - total: N, - completed: 0 - } - } -} -``` - -### 2. Development (DEVELOP action) - -```javascript -{ - updated_at: timestamp, - current_iteration: state.current_iteration + 1, - - skill_state: { - current_action: 'develop', - last_action: 'DEVELOP', - completed_actions: [..., 'DEVELOP'], - develop: { - current_task: 'task-xxx', - completed: N+1, - last_progress_at: timestamp - } - } -} -``` - -### 3. Debugging (DEBUG action) - -```javascript -{ - updated_at: timestamp, - current_iteration: state.current_iteration + 1, - - skill_state: { - current_action: 'debug', - last_action: 'DEBUG', - debug: { - active_bug: '...', - hypotheses_count: N, - hypotheses: [...new_hypotheses], - iteration: N+1, - last_analysis_at: timestamp - } - } -} -``` - -### 4. Validation (VALIDATE action) - -```javascript -{ - updated_at: timestamp, - current_iteration: state.current_iteration + 1, - - skill_state: { - current_action: 'validate', - last_action: 'VALIDATE', - validate: { - test_results: [...results], - pass_rate: 95.5, - coverage: 85.0, - passed: true | false, - failed_tests: ['test1', 'test2'], - last_run_at: timestamp - } - } -} -``` - -### 5. Completion (COMPLETE action) - -```javascript -{ - status: 'running' -> 'completed', - completed_at: timestamp, - updated_at: timestamp, - - skill_state: { - current_action: 'complete', - last_action: 'COMPLETE', - summary: { ... } - } -} -``` - -## File Sync - -### Unified Location - -State-to-file mapping: - -| State Field | Sync File | Sync Timing | -|-------------|-----------|-------------| -| Entire LoopState | `.workflow/.loop/{loopId}.json` | Every state change (master) | -| `skill_state.develop` | `.workflow/.loop/{loopId}.progress/develop.md` | After each dev operation | -| `skill_state.debug` | `.workflow/.loop/{loopId}.progress/debug.md` | After each debug operation | -| `skill_state.validate` | `.workflow/.loop/{loopId}.progress/validate.md` | After each validation | -| Code changes log | `.workflow/.loop/{loopId}.progress/changes.log` | Each file modification (NDJSON) | -| Debug log | `.workflow/.loop/{loopId}.progress/debug.log` | Each debug log (NDJSON) | - -### File Structure - -``` -.workflow/.loop/ -+-- loop-v2-20260122-abc123.json # Master state file (API + Skill) -+-- loop-v2-20260122-abc123.tasks.jsonl # Task list (API managed) -+-- loop-v2-20260122-abc123.progress/ # Skill progress files - +-- develop.md # Development progress - +-- debug.md # Debug understanding - +-- validate.md # Validation report - +-- changes.log # Code changes (NDJSON) - +-- debug.log # Debug log (NDJSON) - +-- summary.md # Completion summary -``` - -## State Recovery - -If master state file corrupted, rebuild skill_state from progress files: - -```javascript -function rebuildSkillStateFromProgress(loopId) { - const progressDir = `.workflow/.loop/${loopId}.progress` - - // Parse progress files to rebuild state - const skill_state = { - develop: parseProgressFile(`${progressDir}/develop.md`), - debug: parseProgressFile(`${progressDir}/debug.md`), - validate: parseProgressFile(`${progressDir}/validate.md`) - } - - return skill_state -} -``` - -## Codex Pattern Notes - -1. **Agent reads state**: Agent reads `.workflow/.loop/{loopId}.json` at action start -2. **Agent writes state**: Agent updates state after action completion -3. **Orchestrator tracks iterations**: Main loop tracks `current_iteration` -4. **Single agent context**: All state updates in same agent conversation via send_input -5. **No context serialization loss**: State transitions happen in-memory within agent diff --git a/.codex/skills/ccw-loop/specs/action-catalog.md b/.codex/skills/ccw-loop/specs/action-catalog.md deleted file mode 100644 index 8d325dbe..00000000 --- a/.codex/skills/ccw-loop/specs/action-catalog.md +++ /dev/null @@ -1,182 +0,0 @@ -# Action Catalog (Codex Version) - -CCW Loop available actions and their specifications. - -## Available Actions - -| Action | Purpose | Preconditions | Effects | Output | -|--------|---------|---------------|---------|--------| -| INIT | Initialize session | status=running, skill_state=null | skill_state initialized | progress/*.md created | -| MENU | Display action menu | skill_state!=null, mode=interactive | Wait for user input | WAITING_INPUT | -| DEVELOP | Execute dev task | pending tasks > 0 | Update progress.md | develop.md updated | -| DEBUG | Hypothesis debug | needs debugging | Update understanding.md | debug.md updated | -| VALIDATE | Run tests | needs validation | Update validation.md | validate.md updated | -| COMPLETE | Finish loop | all done | status=completed | summary.md created | - -## Action Flow (Codex Pattern) - -``` -spawn_agent (ccw-loop-executor) - | - v - +-------+ - | INIT | (if skill_state is null) - +-------+ - | - v - +-------+ send_input - | MENU | <------------- (user selection in interactive mode) - +-------+ - | - +---+---+---+---+ - | | | | | - v v v v v - DEV DBG VAL CMP EXIT - | - v - wait() -> get result - | - v - [Loop continues via send_input] - | - v - close_agent() -``` - -## Action Execution Pattern - -### Single Agent Deep Interaction - -All actions executed within same agent via `send_input`: - -```javascript -// Initial spawn -const agent = spawn_agent({ message: role + initial_task }) - -// Execute INIT -const initResult = wait({ ids: [agent] }) - -// Continue with DEVELOP via send_input -send_input({ id: agent, message: 'Execute DEVELOP' }) -const devResult = wait({ ids: [agent] }) - -// Continue with VALIDATE via send_input -send_input({ id: agent, message: 'Execute VALIDATE' }) -const valResult = wait({ ids: [agent] }) - -// Only close when done -close_agent({ id: agent }) -``` - -### Action Output Format (Standardized) - -Every action MUST output: - -``` -ACTION_RESULT: -- action: {ACTION_NAME} -- status: success | failed | needs_input -- message: {user-facing message} -- state_updates: { ... } - -FILES_UPDATED: -- {file_path}: {description} - -NEXT_ACTION_NEEDED: {NEXT_ACTION} | WAITING_INPUT | COMPLETED | PAUSED -``` - -## Action Selection Logic - -### Auto Mode - -```javascript -function selectNextAction(state) { - const skillState = state.skill_state - - // 1. Terminal conditions - if (state.status === 'completed') return null - if (state.status === 'failed') return null - if (state.current_iteration >= state.max_iterations) return 'COMPLETE' - - // 2. Initialization check - if (!skillState) return 'INIT' - - // 3. Auto selection based on state - const hasPendingDevelop = skillState.develop.tasks.some(t => t.status === 'pending') - - if (hasPendingDevelop) { - return 'DEVELOP' - } - - if (skillState.last_action === 'DEVELOP') { - const needsDebug = skillState.develop.completed < skillState.develop.total - if (needsDebug) return 'DEBUG' - } - - if (skillState.last_action === 'DEBUG' || skillState.debug.confirmed_hypothesis) { - return 'VALIDATE' - } - - if (skillState.last_action === 'VALIDATE') { - if (!skillState.validate.passed) return 'DEVELOP' - } - - if (skillState.validate.passed && !hasPendingDevelop) { - return 'COMPLETE' - } - - return 'DEVELOP' -} -``` - -### Interactive Mode - -Returns `MENU` action, which displays options and waits for user input. - -## Action Dependencies - -| Action | Depends On | Leads To | -|--------|------------|----------| -| INIT | - | MENU or DEVELOP | -| MENU | INIT | User selection | -| DEVELOP | INIT | DEVELOP, DEBUG, VALIDATE | -| DEBUG | INIT | DEVELOP, VALIDATE | -| VALIDATE | DEVELOP or DEBUG | COMPLETE, DEBUG, DEVELOP | -| COMPLETE | - | Terminal | - -## Action Sequences - -### Happy Path (Auto Mode) - -``` -INIT -> DEVELOP -> DEVELOP -> DEVELOP -> VALIDATE (pass) -> COMPLETE -``` - -### Debug Iteration Path - -``` -INIT -> DEVELOP -> VALIDATE (fail) -> DEBUG -> DEBUG -> VALIDATE (pass) -> COMPLETE -``` - -### Interactive Path - -``` -INIT -> MENU -> (user: develop) -> DEVELOP -> MENU -> (user: validate) -> VALIDATE -> MENU -> (user: complete) -> COMPLETE -``` - -## Error Recovery - -| Error | Recovery | -|-------|----------| -| Action timeout | send_input requesting convergence | -| Action failed | Log error, continue or retry | -| Agent closed unexpectedly | Re-spawn with previous output | -| State corrupted | Rebuild from progress files | - -## Codex Best Practices - -1. **Single agent for all actions**: No need to spawn new agent for each action -2. **Deep interaction via send_input**: Continue conversation in same context -3. **Delayed close_agent**: Only close after all actions complete -4. **Structured output**: Always use ACTION_RESULT format for parsing -5. **Control signal checking**: Check state.status before every action diff --git a/.codex/skills/workflow-execute/SKILL.md b/.codex/skills/workflow-execute/SKILL.md new file mode 100644 index 00000000..39516786 --- /dev/null +++ b/.codex/skills/workflow-execute/SKILL.md @@ -0,0 +1,810 @@ +--- +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. + +**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 → AskUserQuestion (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 + └─ AskUserQuestion: 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: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json + +## TASK CONTEXT +${taskContext} + +## DELIVERABLES +${deliverables} +` +}) +``` + +### wait +Get results from subagent (only way to retrieve results). + +```javascript +const result = wait({ + ids: [agentId], + timeout_ms: 600000 // 10 minutes +}) + +if (result.timed_out) { + // Handle timeout - can continue waiting or send_input to prompt completion +} +``` + +### send_input +Continue interaction with active subagent (for clarification or follow-up). + +```javascript +send_input({ + id: agentId, + message: ` +## CLARIFICATION ANSWERS +${answers} + +## NEXT STEP +Continue with 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 .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 .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 .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 AskUserQuestion 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) + + AskUserQuestion({ + questions: [{ + question: "Multiple active sessions detected. Select one:", + header: "Session", + multiSelect: false, + options: displaySessions.map(s => ({ + label: s.id, + description: `${s.project} | ${s.progress}` + })) + // Note: User can select "Other" to manually enter session ID + }] + }) +} +``` + +**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 .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)' \ + .workflow/active/${sessionId}/workflow-session.json > tmp.json && \ + mv tmp.json .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 `.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(.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 + AskUserQuestion({ + questions: [{ + question: "All tasks completed. What would you like to do next?", + header: "Next Step", + multiSelect: false, + options: [ + { + label: "Enter Review", + description: "Run specialized review (security/architecture/quality/action-items)" + }, + { + label: "Complete Session", + description: "Archive session and update manifest" + } + ] + }] + }) +} +``` + +**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: .workflow/project-tech.json +3. Read: .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: .workflow/project-tech.json +3. Read: .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 +``` +.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 `.workflow/active/` | Create or resume session: `workflow:plan "project"` | N/A | +| Multiple sessions | Multiple sessions in `.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