CCW Loop - Stateless Iterative Development Workflow

无状态迭代开发循环工作流，支持开发 (develop)、调试 (debug)、验证 (validate) 三个阶段，每个阶段都有独立的文件记录进展。

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

统一状态: API 和 Skill 共享 .loop/{loopId}.json 状态文件
控制信号: Skill 每个 Action 前检查 status 字段 (paused/stopped)
文件驱动: 所有进度、理解、结果都记录在 .loop/{loopId}.progress/
可恢复: 任何时候可以继续之前的循环 (--loop-id )
双触发: 支持 API 触发 (--loop-id ) 和直接调用 (task description)
Gemini 辅助: 使用 CLI 工具进行深度分析和假设验证

Execution Modes

Mode 1: Interactive (交互式)

用户手动选择每个动作，适合复杂任务。

用户 → 选择动作 → 执行 → 查看结果 → 选择下一动作

Mode 2: Auto-Loop (自动循环)

按预设顺序自动执行，适合标准开发流程。

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 初始化循环会话 meta.json, state.json

action-develop-with-file 开发任务执行 progress.md, tasks.json gemini --mode write

action-debug-with-file 假设驱动调试 understanding.md, hypotheses.json gemini --mode analysis

action-validate-with-file 测试与验证 validation.md, test-results.json gemini --mode analysis

action-complete 完成循环 summary.md

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 编排器：状态读取 + 动作选择

phases/state-schema.md 状态结构定义

specs/loop-requirements.md 循环需求规范

specs/action-catalog.md 动作目录

templates/progress-template.md 进度文档模板

templates/understanding-template.md 理解文档模板

Integration with Loop Monitor (Dashboard)

此 Skill 与 CCW Dashboard 的 Loop Monitor 实现控制平面 + 执行平面分离架构：

Control Plane (Dashboard/API → loop-v2-routes.ts)

创建循环: POST /api/loops/v2 → 创建 .loop/{loopId}.json
启动执行: POST /api/loops/v2/:loopId/start → 触发 /ccw-loop --loop-id {loopId} --auto
暂停执行: POST /api/loops/v2/:loopId/pause → 设置 status='paused' (Skill 下次检查时退出)
恢复执行: POST /api/loops/v2/:loopId/resume → 设置 status='running' → 重新触发 Skill
停止执行: POST /api/loops/v2/:loopId/stop → 设置 status='failed'

Execution Plane (ccw-loop Skill)

读取状态: 从 .loop/{loopId}.json 读取 API 设置的状态
检查控制: 每个 Action 前检查 status 字段
执行动作: develop → debug → validate → complete
更新进度: 写入 .loop/{loopId}.progress/*.md 和更新 skill_state
状态同步: Dashboard 通过读取 .loop/{loopId}.json 获取进度

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

完成后询问用户是否扩展为 issue (test/enhance/refactor/doc)，选中项调用 /issue:new "{summary} - {dimension}"

ccw-loop

Safety Notice

Copy this and send it to your AI assistant to learn

action-init 初始化循环会话 meta.json, state.json

action-complete 完成循环 summary.md

action-menu 显示操作菜单

启动新循环 (直接调用)

继续现有循环 (API 触发或手动恢复)

自动循环模式

API 触发自动循环

Source Transparency

Related Skills

project-management-specialist

frontend-specialist

design-specialist

marketing-specialist