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

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

# 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

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

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

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):

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