SuperAPI AI Directory

ccw-loop

Coding & development

View repository

Updated 10-16 01:06

About this skill

CCW Loop - Stateless Iterative Development Workflow

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

  1. Unified State: API and Skill share .loop/{loopId}.json state file
  2. Control Signal: Skill checks the status field (paused/stopped) before each Action
  3. File-Driven: All progress, understanding, and results are recorded in .loop/{loopId}.progress/
  4. Resumable: At any time, you can continue the previous loop (--loop-id)
  5. Dual Trigger: Supports API trigger (--loop-id) and direct invocation (task description)
  6. 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)

  1. Create Loop: POST /api/loops/v2 → Create .loop/{loopId}.json
  2. Start Execution: POST /api/loops/v2/:loopId/start → Trigger /ccw-loop --loop-id {loopId} --auto
  3. Pause Execution: POST /api/loops/v2/:loopId/pause → Set status='paused' (Skill exits on the next check)
  4. Resume Execution: POST /api/loops/v2/:loopId/resume → Set status='running' → Re-trigger Skill
  5. Stop Execution: POST /api/loops/v2/:loopId/stop → Set status='failed'

Execution Plane (ccw-loop Skill)

  1. Read State: From .loop/{loopId}.json read the state set by the API
  2. Check Control: Check before each Action status field
  3. Execute Action: develop → debug → validate → complete
  4. Update Progress: Write .loop/{loopId}.progress/*.md and update skill_state
  5. State Sync: Dashboard reads .loop/{loopId}.json to 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}"