Stateless iterative development loop workflow, supporting three phases: develop, debug, and validate. Each phase has an independent file to record progress.
Arguments
| Arg | Required | Description |
|---|---|---|
| task | No | Task description (for new loop, mutually exclusive with --loop-id) |
| --loop-id | No | Existing loop ID to continue (from API or previous session) |
| --auto | No | Auto-cycle mode (develop → debug → validate → complete) |
Unified Architecture (API + Skill Integration)
┌─────────────────────────────────────────────────────────────────┐
│ Dashboard (UI) │
│ [Create] [Start] [Pause] [Resume] [Stop] [View Progress] │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ loop-v2-routes.ts (Control Plane) │
│ │
│ State: .loop/{loopId}.json (MASTER) │
│ Tasks: .loop/{loopId}.tasks.jsonl │
│ │
│ /start → Trigger ccw-loop skill with --loop-id │
│ /pause → Set status='paused' (skill checks before action) │
│ /stop → Set status='failed' (skill terminates) │
│ /resume → Set status='running' (skill continues) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ ccw-loop Skill (Execution Plane) │
│ │
│ Reads/Writes: .loop/{loopId}.json (unified state) │
│ Writes: .loop/{loopId}.progress/* (progress files) │
│ │
│ BEFORE each action: │
│ → Check status: paused/stopped → exit gracefully │
│ → running → continue with action │
│ │
│ Actions: init → develop → debug → validate → complete │
└─────────────────────────────────────────────────────────────────┘
Key Design Principles
- Unified State: API and Skill share
.loop/{loopId}.jsonstate file - Control Signal: Skill checks the status field (paused/stopped) before each Action
- File-Driven: All progress, understanding, and results are recorded in
.loop/{loopId}.progress/ - Resumable: At any time, you can continue the previous loop (
--loop-id) - Dual Trigger: Supports API trigger (
--loop-id) and direct invocation (task description) - Gemini-Assisted: Uses CLI tools for in-depth analysis and hypothesis verification
Execution Modes
Mode 1: Interactive
The user manually selects each action, suitable for complex tasks.
用户 → 选择动作 → 执行 → 查看结果 → 选择下一动作
Mode 2: Auto-Loop
Automatically executes in a preset order, suitable for standard development processes.
Develop → Debug → Validate → (如有问题) → Develop → ...
Session Structure (Unified Location)
.loop/
├── {loopId}.json # 主状态文件 (API + Skill 共享)
├── {loopId}.tasks.jsonl # 任务列表 (API 管理)
└── {loopId}.progress/ # Skill 进度文件
├── develop.md # 开发进度记录
├── debug.md # 理解演变文档
├── validate.md # 验证报告
├── changes.log # 代码变更日志 (NDJSON)
└── debug.log # 调试日志 (NDJSON)
Directory Setup
// loopId 来源:
// 1. API 触发时: 从 --loop-id 参数获取
// 2. 直接调用时: 生成新的 loop-v2-{timestamp}-{random}
const loopId = args['--loop-id'] || generateLoopId()
const loopFile = `.loop/${loopId}.json`
const progressDir = `.loop/${loopId}.progress`
// 创建进度目录
Bash(`mkdir -p "${progressDir}"`)
Action Catalog
| Action | Purpose | Output Files | CLI Integration |
|---|---|---|---|
| action-init | Initialize Loop Session | meta.json, state.json | - |
| action-develop-with-file | Development Task Execution | progress.md, tasks.json | gemini --mode write |
| action-debug-with-file | Hypothesis-Driven Debugging | understanding.md, hypotheses.json | gemini --mode analysis |
| action-validate-with-file | Testing and Verification | validation.md, test-results.json | gemini --mode analysis |
| action-complete | Complete Loop | summary.md | - |
| action-menu | Display Action Menu | - | - |
Usage
# 启动新循环 (直接调用)
/ccw-loop "实现用户认证功能"
# 继续现有循环 (API 触发或手动恢复)
/ccw-loop --loop-id loop-v2-20260122-abc123
# 自动循环模式
/ccw-loop --auto "修复登录bug并添加测试"
# API 触发自动循环
/ccw-loop --loop-id loop-v2-20260122-abc123 --auto
Execution Flow
┌─────────────────────────────────────────────────────────────────┐
│ /ccw-loop [<task> | --loop-id <id>] [--auto] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. Parameter Detection: │
│ ├─ IF --loop-id provided: │
│ │ ├─ Read .loop/{loopId}.json │
│ │ ├─ Validate status === 'running' │
│ │ └─ Continue from skill_state.current_action │
│ └─ ELSE (task description): │
│ ├─ Generate new loopId │
│ ├─ Create .loop/{loopId}.json │
│ └─ Initialize with action-init │
│ │
│ 2. Orchestrator Loop: │
│ ├─ Read state from .loop/{loopId}.json │
│ ├─ Check control signals: │
│ │ ├─ status === 'paused' → Exit (wait for resume) │
│ │ ├─ status === 'failed' → Exit with error │
│ │ └─ status === 'running' → Continue │
│ ├─ Show menu / auto-select next action │
│ ├─ Execute action │
│ ├─ Update .loop/{loopId}.progress/{action}.md │
│ ├─ Update .loop/{loopId}.json (skill_state) │
│ └─ Loop or exit based on user choice / completion │
│ │
│ 3. Action Execution: │
│ ├─ BEFORE: checkControlSignals() → exit if paused/stopped │
│ ├─ Develop: Plan → Implement → Document progress │
│ ├─ Debug: Hypothesize → Instrument → Analyze → Fix │
│ ├─ Validate: Test → Check → Report │
│ └─ AFTER: Update skill_state in .loop/{loopId}.json │
│ │
│ 4. Termination: │
│ ├─ Control signal: paused (graceful exit, wait resume) │
│ ├─ Control signal: stopped (failed state) │
│ ├─ User exits (interactive mode) │
│ ├─ All tasks completed (status → completed) │
│ └─ Max iterations reached │
│ │
└─────────────────────────────────────────────────────────────────┘
Reference Documents
| Document | Purpose |
|---|---|
| phases/orchestrator.md | Orchestrator: State Reading + Action Selection |
| phases/state-schema.md | State Structure Definition |
| specs/loop-requirements.md | Loop Requirements Specification |
| specs/action-catalog.md | Action Catalog |
| templates/progress-template.md | Progress Document Template |
| templates/understanding-template.md | Understanding Document Template |
Integration with Loop Monitor (Dashboard)
This Skill and CCW Dashboard's Loop Monitor implement Control Plane + Execution Plane separated architecture:
Control Plane (Dashboard/API → loop-v2-routes.ts)
- Create Loop:
POST /api/loops/v2→ Create.loop/{loopId}.json - Start Execution:
POST /api/loops/v2/:loopId/start→ Trigger/ccw-loop --loop-id {loopId} --auto - Pause Execution:
POST /api/loops/v2/:loopId/pause→ Setstatus='paused'(Skill exits on the next check) - Resume Execution:
POST /api/loops/v2/:loopId/resume→ Setstatus='running'→ Re-trigger Skill - Stop Execution:
POST /api/loops/v2/:loopId/stop→ Setstatus='failed'
Execution Plane (ccw-loop Skill)
- Read State: From
.loop/{loopId}.jsonread the state set by the API - Check Control: Check before each Action
statusfield - Execute Action: develop → debug → validate → complete
- Update Progress: Write
.loop/{loopId}.progress/*.mdand updateskill_state - State Sync: Dashboard reads
.loop/{loopId}.jsonto get progress
CLI Integration Points
Develop Phase
ccw cli -p "PURPOSE: Implement {task}...
TASK: • Analyze requirements • Write code • Update progress
MODE: write
CONTEXT: @progress.md @tasks.json
EXPECTED: Implementation + updated progress.md
" --tool gemini --mode write --rule development-implement-feature
Debug Phase
ccw cli -p "PURPOSE: Generate debugging hypotheses...
TASK: • Analyze error • Generate hypotheses • Add instrumentation
MODE: analysis
CONTEXT: @understanding.md @debug.log
EXPECTED: Hypotheses + instrumentation plan
" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause
Validate Phase
ccw cli -p "PURPOSE: Validate implementation...
TASK: • Run tests • Check coverage • Verify requirements
MODE: analysis
CONTEXT: @validation.md @test-results.json
EXPECTED: Validation report
" --tool gemini --mode analysis --rule analysis-review-code-quality
Error Handling
| Situation | Action |
|---|---|
| Session not found | Create new session |
| State file corrupted | Rebuild from file contents |
| CLI tool fails | Fallback to manual analysis |
| Tests fail | Loop back to develop/debug |
| >10 iterations | Warn user, suggest break |
Post-Completion Expansion
After completion, ask the user whether to extend into an issue (test/enhance/refactor/doc); the selected item invokes /issue:new "{summary} - {dimension}"