claude-code-workflow 6.3.38 → 6.3.39

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

@@ -1,102 +1,301 @@
-# CCW Loop-B (Hybrid Orchestrator Pattern)
+# CCW Loop-B: Hybrid Orchestrator Pattern
 
-协调器 + 专用 worker 的迭代开发工作流。
+Iterative development workflow using coordinator + specialized workers architecture.
 
 ## Overview
 
-CCW Loop-B 采用混合模式设计：
-- **Coordinator**: 状态管理、worker 调度、结果汇聚
-- **Workers**: 专注各自领域（develop/debug/validate）
+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
 
-## Installation
+## Architecture
 
 ```
-.codex/skills/ccw-loop-b/
-+-- SKILL.md                    # Main skill definition
-+-- README.md                   # This file
-+-- phases/
-|   +-- orchestrator.md         # Coordinator logic
-|   +-- state-schema.md         # State structure
-+-- specs/
-    +-- action-catalog.md       # Action catalog
-
-.codex/agents/
-+-- ccw-loop-b-init.md          # Init worker
-+-- ccw-loop-b-develop.md       # Develop worker
-+-- ccw-loop-b-debug.md         # Debug worker
-+-- ccw-loop-b-validate.md      # Validate worker
-+-- ccw-loop-b-complete.md      # Complete worker
+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
 
-| Mode | Description | Use Case |
-|------|-------------|----------|
-| `interactive` | 用户选择 action | 复杂任务，需要人工决策 |
-| `auto` | 自动顺序执行 | 标准开发流程 |
-| `parallel` | 并行多维度分析 | 需要快速全面评估 |
+### Interactive Mode (default)
 
-## Usage
+Coordinator displays menu, user selects action, spawns corresponding worker.
 
 ```bash
-# Interactive (default)
 /ccw-loop-b TASK="Implement feature X"
+```
 
-# Auto mode
+**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.
 
-# Parallel analysis
+```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
 
-# Resume
-/ccw-loop-b --loop-id=loop-b-xxx
+## 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
 ```
 
-## Session Files
+## 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"
 ```
-.loop/
-+-- {loopId}.json              # Master state
-+-- {loopId}.workers/          # Worker outputs (JSON)
-+-- {loopId}.progress/         # Human-readable progress (MD)
+
+**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"
 ```
 
-## Core Pattern
+**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
 
-### Coordinator + Worker
+### Example 3: Comprehensive Analysis
 
-```javascript
-// Coordinator spawns specialized worker
-const worker = spawn_agent({ message: buildWorkerPrompt(action) })
+```bash
+/ccw-loop-b --mode=parallel TASK="Analyze payment module for improvements"
+```
 
-// Wait for completion
-const result = wait({ ids: [worker], timeout_ms: 600000 })
+**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
 
-// Process result
-const output = result.status[worker].completed
-updateState(output)
+### Example 4: Resume Existing Loop
 
-// Cleanup
-close_agent({ id: worker })
+```bash
+/ccw-loop-b --loop-id=loop-b-20260122-abc123
 ```
 
-### Batch Wait (Parallel Mode)
+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
-// Spawn multiple workers
-const workers = [
-  spawn_agent({ message: developPrompt }),
-  spawn_agent({ message: debugPrompt }),
-  spawn_agent({ message: validatePrompt })
-]
+const workers = {
+  develop: spawn_agent({ message: developPrompt }),
+  debug: spawn_agent({ message: debugPrompt }),
+  validate: spawn_agent({ message: validatePrompt })
+}
 
 // Batch wait
-const results = wait({ ids: workers, timeout_ms: 900000 })
+const results = wait({ ids: Object.values(workers), timeout_ms: 900000 })
 
-// Merge results
-const merged = mergeOutputs(results)
+// Process all results
+Object.values(workers).forEach(id => close_agent({ id }))
 ```
 
-## License
+### 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
 
-MIT
+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

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

@@ -61,7 +61,7 @@ Coordinator -> spawn [develop, debug, validate] in parallel -> wait({ ids: all }
 ## Session Structure
 
 ```
-.loop/
+.workflow/.loop/
 +-- {loopId}.json              # Master state
 +-- {loopId}.workers/          # Worker outputs
 |   +-- develop.output.json
@@ -242,9 +242,9 @@ function buildWorkerPrompt(action, loopId, state) {
 
 - **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
+- **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
 

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

@@ -14,7 +14,7 @@ Read state -> Select mode -> Spawn workers -> Wait results -> Merge -> Update st
 
 ```javascript
 function readState(loopId) {
-  const stateFile = `.loop/${loopId}.json`
+  const stateFile = `.workflow/.loop/${loopId}.json`
   return fs.existsSync(stateFile)
     ? JSON.parse(Read(stateFile))
     : null
@@ -252,6 +252,6 @@ function parseWorkerResult(output) {
 ## Best Practices
 
 1. **Worker 生命周期**: spawn → wait → close，不保留 worker
-2. **结果持久化**: Worker 输出写入 `.loop/{loopId}.workers/`
+2. **结果持久化**: Worker 输出写入 `.workflow/.loop/{loopId}.workers/`
 3. **状态同步**: 每次 worker 完成后更新 state
 4. **超时处理**: send_input 请求收敛，再超时则跳过

package/.codex/skills/ccw-loop-b/phases/state-schema.md

@@ -56,7 +56,7 @@
 
 ## Worker Output Structure
 
-Each worker writes to `.loop/{loopId}.workers/{action}.output.json`:
+Each worker writes to `.workflow/.loop/{loopId}.workers/{action}.output.json`:
 
 ```json
 {
@@ -81,7 +81,7 @@ Each worker writes to `.loop/{loopId}.workers/{action}.output.json`:
 
 ## Progress File Structure
 
-Human-readable progress in `.loop/{loopId}.progress/{action}.md`:
+Human-readable progress in `.workflow/.loop/{loopId}.progress/{action}.md`:
 
 ```markdown
 # Develop Progress
@@ -165,7 +165,7 @@ When `mode === 'parallel'`:
 ## Directory Structure
 
 ```
-.loop/
+.workflow/.loop/
 +-- loop-b-20260122-abc123.json          # Master state
 +-- loop-b-20260122-abc123.workers/
 |   +-- init.output.json