ccw loop-b

CCW Loop-B - Hybrid Orchestrator Pattern

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "ccw loop-b" with this command: npx skills add catlog22/claude-code-workflow/catlog22-claude-code-workflow-ccw-loop-b

CCW Loop-B - Hybrid Orchestrator Pattern

协调器 + 专用 worker 的迭代开发工作流。支持三种执行模式（Interactive / Auto / Parallel），每个 action 由独立 worker agent 执行，协调器负责调度、状态管理和结果汇聚。

Architecture Overview

+------------------------------------------------------------+ | Main Coordinator | | 职责: 状态管理 + worker 调度 + 结果汇聚 + 用户交互 | +------------------------------------------------------------+ | | | v v v +----------------+ +----------------+ +----------------+ | Worker-Develop | | Worker-Debug | | Worker-Validate| | 专注: 代码实现 | | 专注: 问题诊断 | | 专注: 测试验证 | +----------------+ +----------------+ +----------------+ | | | v v v .workers/ .workers/ .workers/ develop.output.json debug.output.json validate.output.json

Subagent API

API 作用 注意事项

spawn_agent({ message })

创建 worker，返回 agent_id

首条 message 加载角色

wait({ ids, timeout_ms })

等待结果 唯一取结果入口，非 close

send_input({ id, message })

继续交互/追问 interrupt=true 慎用

close_agent({ id })

关闭回收 不可逆，确认不再交互后才关闭

Key Design Principles

  • 协调器保持轻量: 只做调度和状态管理，具体工作交给 worker

  • Worker 职责单一: 每个 worker 专注一个领域（develop/debug/validate）

  • 角色路径传递: Worker 自己读取角色文件，主流程不传递内容

  • 延迟 close_agent: 确认不再需要交互后才关闭 worker

  • 两阶段工作流: 复杂任务先澄清后执行，减少返工

  • 批量等待优化: 并行模式用 wait({ ids: [...] }) 批量等待

  • 结果标准化: Worker 输出遵循统一 WORKER_RESULT 格式

  • 灵活模式切换: 根据任务复杂度选择 interactive/auto/parallel

Arguments

Arg Required Description

TASK One of TASK or --loop-id Task description (for new loop)

--loop-id One of TASK or --loop-id Existing loop ID to continue

--mode No interactive (default) / auto / parallel

Execution Modes

Mode: Interactive (default)

协调器展示菜单，用户选择 action，spawn 对应 worker 执行。

Coordinator -> Show menu -> User selects -> spawn worker -> wait -> Display result -> Loop

Mode: Auto

自动按预设顺序执行，worker 完成后协调器决定下一步。

Init -> Develop -> [if issues] Debug -> Validate -> [if fail] Loop back -> Complete

Mode: Parallel

并行 spawn 多个 worker，batch wait 汇聚结果，协调器综合决策。

Coordinator -> spawn [develop, debug, validate] in parallel -> wait({ ids: all }) -> Merge -> Decide

Execution Flow

Input Parsing: └─ Parse arguments (TASK | --loop-id + --mode) └─ Convert to structured context (loopId, state, mode)

Phase 1: Session Initialization └─ Ref: phases/01-session-init.md ├─ Create new loop OR resume existing loop ├─ Initialize state file and directory structure └─ Output: loopId, state, progressDir, mode

Phase 2: Orchestration Loop └─ Ref: phases/02-orchestration-loop.md ├─ Mode dispatch: interactive / auto / parallel ├─ Worker spawn with structured prompt (Goal/Scope/Context/Deliverables) ├─ Wait + timeout handling + result parsing ├─ State update per iteration └─ close_agent on loop exit

Phase Reference Documents (read on-demand when phase executes):

Phase Document Purpose

1 phases/01-session-init.md Argument parsing, state creation/resume, directory init

2 phases/02-orchestration-loop.md 3-mode orchestration, worker spawn, batch wait, result merge

Data Flow

User Input (TASK | --loop-id + --mode) ↓ [Parse Arguments] ↓ loopId, state, mode

Phase 1: Session Initialization ↓ loopId, state (initialized/resumed), progressDir

Phase 2: Orchestration Loop ↓ ┌─── Interactive Mode ──────────────────────────────────┐ │ showMenu → user selects → spawn worker → wait → │ │ parseResult → updateState → close worker → loop │ └───────────────────────────────────────────────────────┘ ┌─── Auto Mode ─────────────────────────────────────────┐ │ selectNext → spawn worker → wait → parseResult → │ │ updateState → close worker → [loop_back?] → next │ └───────────────────────────────────────────────────────┘ ┌─── Parallel Mode ─────────────────────────────────────┐ │ spawn [develop, debug, validate] → batch wait → │ │ mergeOutputs → coordinator decides → close all │ └───────────────────────────────────────────────────────┘ ↓ return finalState

Session Structure

{projectRoot}/.workflow/.loop/ ├── {loopId}.json # Master state (API + Skill shared) ├── {loopId}.workers/ # Worker structured outputs │ ├── init.output.json │ ├── develop.output.json │ ├── debug.output.json │ ├── validate.output.json │ └── complete.output.json └── {loopId}.progress/ # Human-readable progress ├── develop.md ├── debug.md ├── validate.md └── summary.md

State Management

Master state file: {projectRoot}/.workflow/.loop/{loopId}.json

{ "loop_id": "loop-b-20260122-abc123", "title": "Task title", "description": "Full task description", "mode": "interactive | auto | parallel", "status": "running | paused | completed | failed", "current_iteration": 0, "max_iterations": 10, "created_at": "ISO8601", "updated_at": "ISO8601",

"skill_state": { "phase": "init | develop | debug | validate | complete", "action_index": 0, "workers_completed": [], "parallel_results": null, "pending_tasks": [], "completed_tasks": [], "findings": [] } }

Control Signal Checking: 协调器在每次 spawn worker 前检查 state.status :

  • running → continue

  • paused → exit gracefully, wait for resume

  • failed → terminate

Recovery: If state corrupted, rebuild from .progress/ markdown files and .workers/*.output.json .

Worker Catalog

Worker Role File Purpose Output Files

init ccw-loop-b-init.md 会话初始化、任务解析 init.output.json

develop ccw-loop-b-develop.md 代码实现、重构 develop.output.json, develop.md

debug ccw-loop-b-debug.md 问题诊断、假设验证 debug.output.json, debug.md

validate ccw-loop-b-validate.md 测试执行、覆盖率 validate.output.json, validate.md

complete ccw-loop-b-complete.md 总结收尾 complete.output.json, summary.md

Worker Dependencies

Worker Depends On Leads To

init

develop (auto) / menu (interactive)

develop init validate / debug

debug init develop / validate

validate develop or debug complete / develop (if fail)

complete

Terminal

Worker Sequences

Simple Task (Auto): init → develop → validate → complete Complex Task (Auto): init → develop → validate (fail) → debug → develop → validate → complete Bug Fix (Auto): init → debug → develop → validate → complete Analysis (Parallel): init → [develop ‖ debug ‖ validate] → complete Interactive: init → menu → user selects → worker → menu → ...

Worker Prompt Protocol

Spawn Message Structure (§7.1)

function buildWorkerPrompt(action, loopId, state) { return `

TASK ASSIGNMENT

MANDATORY FIRST STEPS (Agent Execute)

  1. Read role definition: ~/.codex/agents/ccw-loop-b-${action}.md (MUST read first)
  2. Read: ${projectRoot}/.workflow/project-tech.json
  3. Read: ${projectRoot}/.workflow/project-guidelines.json

Goal: ${goalForAction(action, state)}

Scope:

  • 可做: ${allowedScope(action)}
  • 不可做: ${forbiddenScope(action)}
  • 目录限制: ${directoryScope(action, state)}

Context:

  • Loop ID: ${loopId}
  • State: ${projectRoot}/.workflow/.loop/${loopId}.json
  • Output: ${projectRoot}/.workflow/.loop/${loopId}.workers/${action}.output.json
  • Progress: ${projectRoot}/.workflow/.loop/${loopId}.progress/${action}.md

Deliverables:

  • 按 WORKER_RESULT 格式输出
  • 写入 output.json 和 progress.md

Quality bar:

  • ${qualityCriteria(action)} ` }

关键: 角色文件由 worker 自己读取，主流程只传递路径。不嵌入角色内容。

Worker Output Format (WORKER_RESULT)

WORKER_RESULT:

  • action: {action_name}
  • status: success | failed | needs_input
  • summary: <brief summary>
  • files_changed: [list]
  • next_suggestion: <suggested next action>
  • loop_back_to: <action name if needs loop back, or null>

DETAILED_OUTPUT: <action-specific structured output>

Two-Phase Clarification (§5.2)

Worker 遇到模糊需求时采用两阶段模式:

阶段 1: Worker 输出 CLARIFICATION_NEEDED + Open questions 阶段 2: 协调器收集用户回答 → send_input → Worker 继续执行

// 解析 worker 是否需要澄清 if (output.includes('CLARIFICATION_NEEDED')) { const userAnswers = await collectUserAnswers(output) send_input({ id: workerId, message: ## CLARIFICATION ANSWERS\n${userAnswers}\n\n## CONTINUE EXECUTION }) const finalResult = wait({ ids: [workerId], timeout_ms: 600000 }) }

Parallel Split Strategy (§6)

Strategy 1: 按职责域拆分（推荐）

Worker 职责 交付物 禁止事项

develop 定位入口、调用链、实现方案 变更点清单 不做测试

debug 问题诊断、风险评估 问题清单+修复建议 不写代码

validate 测试策略、覆盖分析 测试结果+质量报告 不改实现

Strategy 2: 按模块域拆分

Worker 1: src/auth/** → 认证模块变更 Worker 2: src/api/** → API 层变更 Worker 3: src/database/** → 数据层变更

拆分原则

  • 文件隔离: 避免多个 worker 同时修改同一文件

  • 职责单一: 每个 worker 只做一件事

  • 边界清晰: 超出范围用 CLARIFICATION_NEEDED 请求确认

  • 最小上下文: 只传递完成任务所需的最小信息

Result Merge (Parallel Mode)

function mergeWorkerOutputs(outputs) { return { develop: parseWorkerResult(outputs.develop), debug: parseWorkerResult(outputs.debug), validate: parseWorkerResult(outputs.validate), conflicts: detectConflicts(outputs), // 检查 worker 间建议冲突 merged_at: getUtc8ISOString() } }

冲突检测: 当多个 worker 建议修改同一文件时，协调器标记冲突，由用户决定。

TodoWrite Pattern

Phase-Level Tracking (Attached)

[ {"content": "Phase 1: Session Initialization", "status": "completed"}, {"content": "Phase 2: Orchestration Loop (auto mode)", "status": "in_progress"}, {"content": " → Worker: init", "status": "completed"}, {"content": " → Worker: develop (task 2/5)", "status": "in_progress"}, {"content": " → Worker: validate", "status": "pending"}, {"content": " → Worker: complete", "status": "pending"} ]

Parallel Mode Tracking

[ {"content": "Phase 1: Session Initialization", "status": "completed"}, {"content": "Phase 2: Parallel Analysis", "status": "in_progress"}, {"content": " → Worker: develop (parallel)", "status": "in_progress"}, {"content": " → Worker: debug (parallel)", "status": "in_progress"}, {"content": " → Worker: validate (parallel)", "status": "in_progress"}, {"content": " → Merge results", "status": "pending"} ]

Core Rules

  • Start Immediately: First action is TodoWrite initialization, then Phase 1 execution

  • Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute

  • Parse Every Output: Extract WORKER_RESULT from worker output for next decision

  • Worker 生命周期: spawn → wait → [send_input if needed] → close，不长期保留 worker

  • 结果持久化: Worker 输出写入 {projectRoot}/.workflow/.loop/{loopId}.workers/

  • 状态同步: 每次 worker 完成后更新 master state

  • 超时处理: send_input 请求收敛，再超时则使用已有结果继续

  • DO NOT STOP: Continuous execution until completed, paused, or max iterations

Error Handling

Error Type Recovery

Worker timeout send_input 请求收敛 → 再超时则跳过

Worker failed Log error, 协调器决策是否重试

Batch wait partial timeout 使用已完成结果继续

State corrupted 从 progress 文件和 worker output 重建

Conflicting worker results 标记冲突，由用户决定

Max iterations reached 生成总结，记录未完成项

Coordinator Checklist

Before Each Phase

  • Read phase reference document

  • Check current state and control signals

  • Update TodoWrite with phase tasks

After Each Worker

  • Parse WORKER_RESULT from output

  • Persist output to .workers/{action}.output.json

  • Update master state file

  • close_agent (确认不再需要交互)

  • Determine next action (continue / loop back / complete)

Reference Documents

Document Purpose

workers/ Worker 定义 (init, develop, debug, validate, complete)

Usage

Interactive mode (default)

/ccw-loop-b TASK="Implement user authentication"

Auto mode

/ccw-loop-b --mode=auto TASK="Fix login bug"

Parallel analysis mode

/ccw-loop-b --mode=parallel TASK="Analyze and improve payment module"

Resume existing loop

/ccw-loop-b --loop-id=loop-b-20260122-abc123

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Coding

skill-generator

No summary provided by upstream source.

Repository SourceNeeds Review
81-catlog22
Coding

review-code

No summary provided by upstream source.

Repository SourceNeeds Review
79-catlog22
Coding

ccw-help

No summary provided by upstream source.

Repository SourceNeeds Review
61-catlog22
Coding

skill-tuning

No summary provided by upstream source.

Repository SourceNeeds Review
60-catlog22