Claude-Code-Workflow/.codex/skills/ccw-loop-b/README.md

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.

/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.

/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.

/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

/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

/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

/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

/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

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

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

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