CCW - Claude Code Workflow Orchestrator

CCW - Claude Code Workflow Orchestrator

无状态工作流协调器，根据任务意图自动选择最优工作流。

Workflow System Overview

CCW 提供两个工作流系统：Main Workflow 和 Issue Workflow，协同覆盖完整的软件开发生命周期。

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Main Workflow                                  │
│                                                                             │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐     │
│  │   Level 1   │ → │   Level 2   │ → │   Level 3   │ → │   Level 4   │     │
│  │   Rapid     │   │ Lightweight │   │  Standard   │   │ Brainstorm  │     │
│  │             │   │             │   │             │   │             │     │
│  │ lite-lite-  │   │ lite-plan   │   │    plan     │   │ brainstorm  │     │
│  │    lite     │   │ lite-fix    │   │  tdd-plan   │   │  :auto-     │     │
│  │             │   │ multi-cli-  │   │ test-fix-   │   │  parallel   │     │
│  │             │   │    plan     │   │    gen      │   │     ↓       │     │
│  │             │   │             │   │             │   │   plan      │     │
│  └─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘     │
│                                                                             │
│  Complexity: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▶  │
│              Low                                                    High    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ After development
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              Issue Workflow                                 │
│                                                                             │
│     ┌──────────────┐         ┌──────────────┐         ┌──────────────┐     │
│     │  Accumulate  │    →    │    Plan      │    →    │   Execute    │     │
│     │  Discover &  │         │    Batch     │         │   Parallel   │     │
│     │   Collect    │         │   Planning   │         │  Execution   │     │
│     └──────────────┘         └──────────────┘         └──────────────┘     │
│                                                                             │
│     Supplementary role: Maintain main branch stability, worktree isolation  │
└─────────────────────────────────────────────────────────────────────────────┘

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  CCW Orchestrator (CLI-Enhanced + Requirement Analysis)         │
├─────────────────────────────────────────────────────────────────┤
│  Phase 1    │ Input Analysis (rule-based, fast path)            │
│  Phase 1.5  │ CLI Classification (semantic, smart path)         │
│  Phase 1.75 │ Requirement Clarification (clarity < 2)           │
│  Phase 2    │ Level Selection (intent → level → workflow)       │
│  Phase 2.5  │ CLI Action Planning (high complexity)             │
│  Phase 3    │ User Confirmation (optional)                      │
│  Phase 4    │ TODO Tracking Setup                               │
│  Phase 5    │ Execution Loop                                    │
└─────────────────────────────────────────────────────────────────┘

Level Quick Reference

Workflow Selection Decision Tree

Start
  │
  ├─ Is it post-development maintenance?
  │     ├─ Yes → Issue Workflow
  │     └─ No ↓
  │
  ├─ Are requirements clear?
  │     ├─ Uncertain → Level 4 (brainstorm:auto-parallel)
  │     └─ Clear ↓
  │
  ├─ Need persistent Session?
  │     ├─ Yes → Level 3 (plan / tdd-plan / test-fix-gen)
  │     └─ No ↓
  │
  ├─ Need multi-perspective / solution comparison?
  │     ├─ Yes → Level 2 (multi-cli-plan)
  │     └─ No ↓
  │
  ├─ Is it a bug fix?
  │     ├─ Yes → Level 2 (lite-fix)
  │     └─ No ↓
  │
  ├─ Need planning?
  │     ├─ Yes → Level 2 (lite-plan)
  │     └─ No → Level 1 (lite-lite-lite)

Intent Classification

Priority Order (with Level Mapping)

Quick Selection Guide

Complexity Assessment

function assessComplexity(text) {
  let score = 0
  if (/​refactor|重构|migrate|迁移|architect|架构|system|系统/​.test(text)) score += 2
  if (/​multiple|多个|across|跨|all|所有|entire|整个/​.test(text)) score += 2
  if (/​integrate|集成|api|database|数据库/​.test(text)) score += 1
  if (/​security|安全|performance|性能|scale|扩展/​.test(text)) score += 1
  return score >= 4 ? 'high' : score >= 2 ? 'medium' : 'low'
}

Dimension Extraction (WHAT/​WHERE/​WHY/​HOW)

从用户输入提取四个维度，用于需求澄清和工作流选择：

Clarity Score (0-3):

• +0.5: 有明确 action
• +0.5: 有具体 target
• +0.5: 有文件路径
• +0.5: scope 不是 unknown
• +0.5: 有明确 goal
• +0.5: 有约束条件
• -0.5: 包含不确定词 (不知道/​maybe/怎么)

Requirement Clarification

当 clarity_score < 2 时触发需求澄清：

if (dimensions.clarity_score < 2) {
  const questions = generateClarificationQuestions(dimensions)
  // 生成问题：目标是什么? 范围是什么? 有什么约束?
  AskUserQuestion({ questions })
}

澄清问题类型:

• 目标不明确 → "你想要对什么进行操作?"
• 范围不明确 → "操作的范围是什么?"
• 目的不明确 → "这个操作的主要目标是什么?"
• 复杂操作 → "有什么特殊要求或限制?"

TODO Tracking Protocol

CRITICAL: Append-Only Rule

CCW 创建的 Todo 必须附加到现有列表，不能覆盖用户的其他 Todo。

Implementation

// 1. 使用 CCW 前缀隔离工作流 todo
const prefix = `CCW:${flowName}`

// 2. 创建新 todo 时使用前缀格式
TodoWrite({
  todos: [
    ...existingNonCCWTodos,  // 保留用户的 todo
    { content: `${prefix}: [1/​N] /​command:step1`, status: "in_progress", activeForm: "..." },
    { content: `${prefix}: [2/​N] /​command:step2`, status: "pending", activeForm: "..." }
  ]
})

// 3. 更新状态时只修改匹配前缀的 todo

Todo Format

CCW:{flow}: [{N}/​{Total}] /​command:name

Visual Example

✓ CCW:rapid: [1/​2] /​workflow:lite-plan
→ CCW:rapid: [2/​2] /​workflow:lite-execute
  用户自己的 todo（保留不动）

Status Management

• 开始工作流：创建所有步骤 todo，第一步 in_progress
• 完成步骤：当前步骤 completed，下一步 in_progress
• 工作流结束：所有 CCW todo 标记 completed

Execution Flow

// 1. Check explicit command
if (input.startsWith('/​workflow:') || input.startsWith('/​issue:')) {
  SlashCommand(input)
  return
}

// 2. Classify intent
const intent = classifyIntent(input)  // See command.json intent_rules

// 3. Select flow
const flow = selectFlow(intent)  // See command.json flows

// 4. Create todos with CCW prefix
createWorkflowTodos(flow)

// 5. Dispatch first command
SlashCommand(flow.steps[0].command, args: input)

CLI Tool Integration

CCW 在特定条件下自动注入 CLI 调用：

CLI Enhancement Phases

Phase 1.5: CLI-Assisted Classification

当规则匹配不明确时，使用 CLI 辅助分类：

Phase 2.5: CLI-Assisted Action Planning

高复杂度任务的工作流优化：

CLI 可返回建议：use_default | modify (调整步骤) | upgrade (升级工作流)

Continuation Commands

工作流执行中的用户控制命令：

Workflow Flow Details

Issue Workflow (Main Workflow 补充机制)

Issue Workflow 是 Main Workflow 的补充机制，专注于开发后的持续维护。

设计理念

为什么 Main Workflow 不自动使用 Worktree？

依赖分析已解决并行性问题：

1. 规划阶段 (/​workflow:plan) 执行依赖分析
2. 自动识别任务依赖和关键路径
3. 划分为并行组（独立任务）和串行链（依赖任务）
4. Agent 并行执行独立任务，无需文件系统隔离

两阶段生命周期

┌─────────────────────────────────────────────────────────────────────┐
│                    Phase 1: Accumulation (积累阶段)                  │
│                                                                     │
│   Triggers: 任务完成后的 review、代码审查发现、测试失败              │
│                                                                     │
│   ┌────────────┐     ┌────────────┐     ┌────────────┐             │
│   │ discover   │     │ discover-  │     │    new     │             │
│   │ Auto-find  │     │ by-prompt  │     │  Manual    │             │
│   └────────────┘     └────────────┘     └────────────┘             │
│                                                                     │
│   持续积累 issues 到待处理队列                                       │
└─────────────────────────────────────────────────────────────────────┘
                               │
                               │ 积累足够后
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  Phase 2: Batch Resolution (批量解决阶段)            │
│                                                                     │
│   ┌────────────┐     ┌────────────┐     ┌────────────┐             │
│   │   plan     │ ──→ │   queue    │ ──→ │  execute   │             │
│   │ --all-     │     │ Optimize   │     │  Parallel  │             │
│   │  pending   │     │  order     │     │ execution  │             │
│   └────────────┘     └────────────┘     └────────────┘             │
│                                                                     │
│   支持 worktree 隔离，保持主分支稳定                                 │
└─────────────────────────────────────────────────────────────────────┘

与 Main Workflow 的协作

开发迭代循环
┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   ┌─────────┐                              ┌─────────┐             │
│   │ Feature │ ──→ Main Workflow ──→ Done ──→│ Review  │             │
│   │ Request │     (Level 1-4)              └────┬────┘             │
│   └─────────┘                                   │                  │
│        ▲                                        │ 发现 Issues       │
│        │                                        ▼                  │
│        │                                  ┌─────────┐              │
│   继续 │                                  │  Issue  │              │
│   新功能│                                  │ Workflow│              │
│        │                                  └────┬────┘              │
│        │         ┌──────────────────────────────┘                   │
│        │         │ 修复完成                                          │
│        │         ▼                                                 │
│   ┌────┴────┐◀──────                                               │
│   │  Main   │    Merge                                             │
│   │ Branch  │    back                                              │
│   └─────────┘                                                      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

命令列表

积累阶段：

/​issue:discover            # 多视角自动发现
/​issue:discover-by-prompt  # 基于提示发现
/​issue:new                 # 手动创建

批量解决阶段：

/​issue:plan --all-pending  # 批量规划所有待处理
/​issue:queue               # 生成优化执行队列
/​issue:execute             # 并行执行

lite-lite-lite vs multi-cli-plan

选择指南：

• 任务清晰、改动范围小 → lite-lite-lite
• 需要多视角分析、复杂架构 → multi-cli-plan

multi-cli-plan vs lite-plan

选择指南：

• 需求明确、路径清晰 → lite-plan
• 需要权衡、多方案比较 → multi-cli-plan

Artifact Flow Protocol

工作流产出的自动流转机制，支持不同格式产出间的意图提取和完成度判断。

产出格式

意图提取 (Intent Extraction)

流转到下一步时，自动提取关键信息：

plan → execute:
  提取: tasks (未完成), priority_order, files_to_modify, context_summary

execute → test:
  提取: modified_files, test_scope (推断), pending_verification

test → fix:
  条件: pass_rate < 0.95
  提取: failures, error_messages, affected_files, suggested_fixes

review → fix:
  条件: critical > 0 OR high > 3
  提取: findings (critical/​high), fix_priority, affected_files

完成度判断

Test 完成度路由:

pass_rate >= 0.95 AND coverage >= 0.80  → complete
pass_rate >= 0.95 AND coverage < 0.80   → add_more_tests
pass_rate >= 0.80                        → fix_failures_then_continue
pass_rate < 0.80                         → major_fix_required

Review 完成度路由:

critical == 0 AND high <= 3  → complete_or_optional_fix
critical > 0                  → mandatory_fix
high > 3                      → recommended_fix

流转决策模式

plan_execute_test:

plan → execute → test
         ↓ (if test fail)
    extract_failures → fix → test (max 3 iterations)
         ↓ (if still fail)
    manual_intervention

iterative_improvement:

execute → test → fix → test → ...
    loop until: pass_rate >= 0.95 OR iterations >= 3

使用示例

// 执行完成后，根据产出决定下一步
const result = await execute(plan)

// 提取意图流转到测试
const testContext = extractIntent('execute_to_test', result)
// testContext = { modified_files, test_scope, pending_verification }

// 测试完成后，根据完成度决定路由
const testResult = await test(testContext)
const nextStep = evaluateCompletion('test', testResult)
// nextStep = 'fix_failures_then_continue' if pass_rate = 0.85

Reference

• command.json - 命令元数据、Flow 定义、意图规则、Artifact Flow