claude-code-workflow 6.3.36 → 6.3.38

package/.codex/skills/ccw-loop-b/SKILL.md

@@ -0,0 +1,322 @@
+---
+description: Hybrid orchestrator pattern for iterative development. Coordinator + specialized workers with batch wait support. Triggers on "ccw-loop-b".
+argument-hint: TASK="<task description>" [--loop-id=<id>] [--mode=<interactive|auto|parallel>]
+---
+
+# 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
+
+```
+.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**: .loop/${loopId}.json
+- **Output File**: .loop/${loopId}.workers/${action}.output.json
+- **Progress File**: .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: <brief summary>
+- files_changed: [list]
+- next_suggestion: <suggested next action>
+- loop_back_to: <action name if needs loop back>
+
+DETAILED_OUTPUT:
+<structured output specific to action type>
+\`\`\`
+
+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 释放资源

package/.codex/skills/ccw-loop-b/phases/orchestrator.md

@@ -0,0 +1,257 @@
+# 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 = `.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: <brief>
+- files_changed: []
+- next_suggestion: <action>
+- loop_back_to: <action or null>
+
+DETAILED_OUTPUT:
+<action-specific 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 输出写入 `.loop/{loopId}.workers/`
+3. **状态同步**: 每次 worker 完成后更新 state
+4. **超时处理**: send_input 请求收敛，再超时则跳过