|
| 1 | +# CCW Loop-B: Hybrid Orchestrator Pattern |
| 2 | + |
| 3 | +Iterative development workflow using coordinator + specialized workers architecture. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +CCW Loop-B implements a flexible orchestration pattern: |
| 8 | +- **Coordinator**: Main agent managing state, user interaction, worker scheduling |
| 9 | +- **Workers**: Specialized agents (init, develop, debug, validate, complete) |
| 10 | +- **Modes**: Interactive / Auto / Parallel execution |
| 11 | + |
| 12 | +## Architecture |
| 13 | + |
| 14 | +``` |
| 15 | +Coordinator (Main Agent) |
| 16 | + | |
| 17 | + +-- Spawns Workers |
| 18 | + | - ccw-loop-b-init.md |
| 19 | + | - ccw-loop-b-develop.md |
| 20 | + | - ccw-loop-b-debug.md |
| 21 | + | - ccw-loop-b-validate.md |
| 22 | + | - ccw-loop-b-complete.md |
| 23 | + | |
| 24 | + +-- Batch Wait (parallel mode) |
| 25 | + +-- Sequential Wait (auto/interactive) |
| 26 | + +-- State Management |
| 27 | + +-- User Interaction |
| 28 | +``` |
| 29 | + |
| 30 | +## Subagent API |
| 31 | + |
| 32 | +Core APIs for worker orchestration: |
| 33 | + |
| 34 | +| API | 作用 | |
| 35 | +|-----|------| |
| 36 | +| `spawn_agent({ message })` | 创建 worker,返回 `agent_id` | |
| 37 | +| `wait({ ids, timeout_ms })` | 等待结果(唯一取结果入口) | |
| 38 | +| `send_input({ id, message })` | 继续交互 | |
| 39 | +| `close_agent({ id })` | 关闭回收 | |
| 40 | + |
| 41 | +**可用模式**: 单 agent 深度交互 / 多 agent 并行 / 混合模式 |
| 42 | + |
| 43 | +## Execution Modes |
| 44 | + |
| 45 | +### Interactive Mode (default) |
| 46 | + |
| 47 | +Coordinator displays menu, user selects action, spawns corresponding worker. |
| 48 | + |
| 49 | +```bash |
| 50 | +/ccw-loop-b TASK="Implement feature X" |
| 51 | +``` |
| 52 | + |
| 53 | +**Flow**: |
| 54 | +1. Init: Parse task, create breakdown |
| 55 | +2. Menu: Show options to user |
| 56 | +3. User selects action (develop/debug/validate) |
| 57 | +4. Spawn worker for selected action |
| 58 | +5. Wait for result |
| 59 | +6. Display result, back to menu |
| 60 | +7. Repeat until complete |
| 61 | + |
| 62 | +### Auto Mode |
| 63 | + |
| 64 | +Automated sequential execution following predefined workflow. |
| 65 | + |
| 66 | +```bash |
| 67 | +/ccw-loop-b --mode=auto TASK="Fix bug Y" |
| 68 | +``` |
| 69 | + |
| 70 | +**Flow**: |
| 71 | +1. Init → 2. Develop → 3. Validate → 4. Complete |
| 72 | + |
| 73 | +If issues found: loop back to Debug → Develop → Validate |
| 74 | + |
| 75 | +### Parallel Mode |
| 76 | + |
| 77 | +Spawn multiple workers simultaneously, batch wait for results. |
| 78 | + |
| 79 | +```bash |
| 80 | +/ccw-loop-b --mode=parallel TASK="Analyze module Z" |
| 81 | +``` |
| 82 | + |
| 83 | +**Flow**: |
| 84 | +1. Init: Create analysis plan |
| 85 | +2. Spawn workers in parallel: [develop, debug, validate] |
| 86 | +3. Batch wait: `wait({ ids: [w1, w2, w3] })` |
| 87 | +4. Merge results |
| 88 | +5. Coordinator decides next action |
| 89 | +6. Complete |
| 90 | + |
| 91 | +## Session Structure |
| 92 | + |
| 93 | +``` |
| 94 | +.workflow/.loop/ |
| 95 | ++-- {loopId}.json # Master state |
| 96 | ++-- {loopId}.workers/ # Worker outputs |
| 97 | +| +-- init.output.json |
| 98 | +| +-- develop.output.json |
| 99 | +| +-- debug.output.json |
| 100 | +| +-- validate.output.json |
| 101 | +| +-- complete.output.json |
| 102 | ++-- {loopId}.progress/ # Human-readable logs |
| 103 | + +-- develop.md |
| 104 | + +-- debug.md |
| 105 | + +-- validate.md |
| 106 | + +-- summary.md |
| 107 | +``` |
| 108 | + |
| 109 | +## Worker Responsibilities |
| 110 | + |
| 111 | +| Worker | Role | Specialization | |
| 112 | +|--------|------|----------------| |
| 113 | +| **init** | Session initialization | Task parsing, breakdown, planning | |
| 114 | +| **develop** | Code implementation | File operations, pattern matching, incremental development | |
| 115 | +| **debug** | Problem diagnosis | Root cause analysis, hypothesis testing, fix recommendations | |
| 116 | +| **validate** | Testing & verification | Test execution, coverage analysis, quality gates | |
| 117 | +| **complete** | Session finalization | Summary generation, commit preparation, cleanup | |
| 118 | + |
| 119 | +## Usage Examples |
| 120 | + |
| 121 | +### Example 1: Simple Feature Implementation |
| 122 | + |
| 123 | +```bash |
| 124 | +/ccw-loop-b TASK="Add user logout function" |
| 125 | +``` |
| 126 | + |
| 127 | +**Auto flow**: |
| 128 | +- Init: Parse requirements |
| 129 | +- Develop: Implement logout in `src/auth.ts` |
| 130 | +- Validate: Run tests |
| 131 | +- Complete: Generate commit message |
| 132 | + |
| 133 | +### Example 2: Bug Investigation |
| 134 | + |
| 135 | +```bash |
| 136 | +/ccw-loop-b TASK="Fix memory leak in WebSocket handler" |
| 137 | +``` |
| 138 | + |
| 139 | +**Interactive flow**: |
| 140 | +1. Init: Parse issue |
| 141 | +2. User selects "debug" → Spawn debug worker |
| 142 | +3. Debug: Root cause analysis → recommends fix |
| 143 | +4. User selects "develop" → Apply fix |
| 144 | +5. User selects "validate" → Verify fix works |
| 145 | +6. User selects "complete" → Generate summary |
| 146 | + |
| 147 | +### Example 3: Comprehensive Analysis |
| 148 | + |
| 149 | +```bash |
| 150 | +/ccw-loop-b --mode=parallel TASK="Analyze payment module for improvements" |
| 151 | +``` |
| 152 | + |
| 153 | +**Parallel flow**: |
| 154 | +- Spawn [develop, debug, validate] workers simultaneously |
| 155 | +- Develop: Analyze code quality and patterns |
| 156 | +- Debug: Identify potential issues |
| 157 | +- Validate: Check test coverage |
| 158 | +- Wait for all three to complete |
| 159 | +- Merge findings into comprehensive report |
| 160 | + |
| 161 | +### Example 4: Resume Existing Loop |
| 162 | + |
| 163 | +```bash |
| 164 | +/ccw-loop-b --loop-id=loop-b-20260122-abc123 |
| 165 | +``` |
| 166 | + |
| 167 | +Continues from previous state, respects status (running/paused). |
| 168 | + |
| 169 | +## Key Features |
| 170 | + |
| 171 | +### 1. Worker Specialization |
| 172 | + |
| 173 | +Each worker focuses on one domain: |
| 174 | +- **No overlap**: Clear boundaries between workers |
| 175 | +- **Reusable**: Same worker for different tasks |
| 176 | +- **Composable**: Combine workers for complex workflows |
| 177 | + |
| 178 | +### 2. Flexible Coordination |
| 179 | + |
| 180 | +Coordinator adapts to mode: |
| 181 | +- **Interactive**: Menu-driven, user controls flow |
| 182 | +- **Auto**: Predetermined sequence |
| 183 | +- **Parallel**: Concurrent execution with batch wait |
| 184 | + |
| 185 | +### 3. State Management |
| 186 | + |
| 187 | +Unified state at `.workflow/.loop/{loopId}.json`: |
| 188 | +- **API compatible**: Works with CCW API |
| 189 | +- **Extension fields**: Skill-specific data in `skill_state` |
| 190 | +- **Worker outputs**: Structured JSON for each action |
| 191 | + |
| 192 | +### 4. Progress Tracking |
| 193 | + |
| 194 | +Human-readable logs: |
| 195 | +- **Per-worker progress**: `{action}.md` files |
| 196 | +- **Summary**: Consolidated achievements |
| 197 | +- **Commit-ready**: Formatted commit messages |
| 198 | + |
| 199 | +## Best Practices |
| 200 | + |
| 201 | +1. **Start with Init**: Always initialize before execution |
| 202 | +2. **Use appropriate mode**: |
| 203 | + - Interactive: Complex tasks needing user decisions |
| 204 | + - Auto: Well-defined workflows |
| 205 | + - Parallel: Independent analysis tasks |
| 206 | +3. **Clean up workers**: `close_agent()` after each worker completes |
| 207 | +4. **Batch wait wisely**: Use in parallel mode for efficiency |
| 208 | +5. **Track progress**: Document in progress files |
| 209 | +6. **Validate often**: After each develop phase |
| 210 | + |
| 211 | +## Implementation Patterns |
| 212 | + |
| 213 | +### Pattern 1: Single Worker Deep Interaction |
| 214 | + |
| 215 | +```javascript |
| 216 | +const workerId = spawn_agent({ message: workerPrompt }) |
| 217 | +const result1 = wait({ ids: [workerId] }) |
| 218 | + |
| 219 | +// Continue with same worker |
| 220 | +send_input({ id: workerId, message: "Continue with next task" }) |
| 221 | +const result2 = wait({ ids: [workerId] }) |
| 222 | + |
| 223 | +close_agent({ id: workerId }) |
| 224 | +``` |
| 225 | + |
| 226 | +### Pattern 2: Multi-Worker Parallel |
| 227 | + |
| 228 | +```javascript |
| 229 | +const workers = { |
| 230 | + develop: spawn_agent({ message: developPrompt }), |
| 231 | + debug: spawn_agent({ message: debugPrompt }), |
| 232 | + validate: spawn_agent({ message: validatePrompt }) |
| 233 | +} |
| 234 | + |
| 235 | +// Batch wait |
| 236 | +const results = wait({ ids: Object.values(workers), timeout_ms: 900000 }) |
| 237 | + |
| 238 | +// Process all results |
| 239 | +Object.values(workers).forEach(id => close_agent({ id })) |
| 240 | +``` |
| 241 | + |
| 242 | +### Pattern 3: Sequential Worker Chain |
| 243 | + |
| 244 | +```javascript |
| 245 | +const actions = ['init', 'develop', 'validate', 'complete'] |
| 246 | + |
| 247 | +for (const action of actions) { |
| 248 | + const workerId = spawn_agent({ message: buildPrompt(action) }) |
| 249 | + const result = wait({ ids: [workerId] }) |
| 250 | + |
| 251 | + updateState(action, result) |
| 252 | + close_agent({ id: workerId }) |
| 253 | +} |
| 254 | +``` |
| 255 | + |
| 256 | +## Error Handling |
| 257 | + |
| 258 | +| Error | Recovery | |
| 259 | +|-------|----------| |
| 260 | +| Worker timeout | `send_input` request convergence | |
| 261 | +| Worker fails | Log error, coordinator decides retry strategy | |
| 262 | +| Partial results | Use completed workers, mark incomplete | |
| 263 | +| State corruption | Rebuild from progress files | |
| 264 | + |
| 265 | +## File Structure |
| 266 | + |
| 267 | +``` |
| 268 | +.codex/skills/ccw-loop-b/ |
| 269 | ++-- SKILL.md # Entry point |
| 270 | ++-- README.md # This file |
| 271 | ++-- phases/ |
| 272 | +| +-- state-schema.md # State structure definition |
| 273 | ++-- specs/ |
| 274 | + +-- action-catalog.md # Action reference |
| 275 | +
|
| 276 | +.codex/agents/ |
| 277 | ++-- ccw-loop-b-init.md # Worker: Init |
| 278 | ++-- ccw-loop-b-develop.md # Worker: Develop |
| 279 | ++-- ccw-loop-b-debug.md # Worker: Debug |
| 280 | ++-- ccw-loop-b-validate.md # Worker: Validate |
| 281 | ++-- ccw-loop-b-complete.md # Worker: Complete |
| 282 | +``` |
| 283 | + |
| 284 | +## Comparison: ccw-loop vs ccw-loop-b |
| 285 | + |
| 286 | +| Aspect | ccw-loop | ccw-loop-b | |
| 287 | +|--------|----------|------------| |
| 288 | +| Pattern | Single agent, multi-phase | Coordinator + workers | |
| 289 | +| Worker model | Single agent handles all | Specialized workers per action | |
| 290 | +| Parallelization | Sequential only | Supports parallel mode | |
| 291 | +| Flexibility | Fixed sequence | Mode-based (interactive/auto/parallel) | |
| 292 | +| Best for | Simple linear workflows | Complex tasks needing specialization | |
| 293 | + |
| 294 | +## Contributing |
| 295 | + |
| 296 | +To add new workers: |
| 297 | +1. Create worker role file in `.codex/agents/` |
| 298 | +2. Define clear responsibilities |
| 299 | +3. Update `action-catalog.md` |
| 300 | +4. Add worker to coordinator spawn logic |
| 301 | +5. Test integration with existing workers |
0 commit comments