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

Level	Name	Workflows	Artifacts	Execution
1	Rapid	lite-lite-lite	None	Direct execute
2	Lightweight	lite-plan, lite-fix, multi-cli-plan	Memory/Lightweight files	→ lite-execute
3	Standard	plan, tdd-plan, test-fix-gen	Session persistence	→ execute / test-cycle-execute
4	Brainstorm	brainstorm:auto-parallel → plan	Multi-role analysis + Session	→ execute
-	Issue	discover → plan → queue → execute	Issue records	Worktree isolation (optional)

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)

Priority	Intent	Patterns	Level	Flow
1	bugfix/hotfix	urgent,production,critical + bug	L2	bugfix.hotfix
1	bugfix	fix,bug,error,crash,fail	L2	bugfix.standard
2	issue batch	issues,batch + fix,resolve	Issue	issue
3	exploration	不确定,explore,研究,what if	L4	full
3	multi-perspective	多视角,权衡,比较方案,cross-verify	L2	multi-cli-plan
4	quick-task	快速,简单,small,quick + feature	L1	lite-lite-lite
5	ui design	ui,design,component,style	L3/L4	ui
6	tdd	tdd,test-driven,先写测试	L3	tdd
7	test-fix	测试失败,test fail,fix test	L3	test-fix-gen
8	review	review,审查,code review	L3	review-fix
9	documentation	文档,docs,readme	L2	docs
99	feature	complexity-based	L2/L3	rapid/coupled

Quick Selection Guide

Scenario	Recommended Workflow	Level
Quick fixes, config adjustments	lite-lite-lite	1
Clear single-module features	lite-plan → lite-execute	2
Bug diagnosis and fix	lite-fix	2
Production emergencies	lite-fix --hotfix	2
Technology selection, solution comparison	multi-cli-plan → lite-execute	2
Multi-module changes, refactoring	plan → verify → execute	3
Test-driven development	tdd-plan → execute → tdd-verify	3
Test failure fixes	test-fix-gen → test-cycle-execute	3
New features, architecture design	brainstorm:auto-parallel → plan → execute	4
Post-development issue fixes	Issue Workflow	-

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'
}

Complexity	Flow
high	coupled (plan → verify → execute)
medium/low	rapid (lite-plan → lite-execute)

Dimension Extraction (WHAT/WHERE/WHY/HOW)

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

维度	提取内容	示例模式
WHAT	action + target	创建/修复/重构/优化/分析 + 目标对象
WHERE	scope + paths	file/module/system + 文件路径
WHY	goal + motivation	为了.../因为.../目的是...
HOW	constraints + preferences	必须.../不要.../应该...

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 调用：

Condition	CLI Inject
大量代码上下文 (≥50k chars)	gemini --mode analysis
高复杂度任务	gemini --mode analysis
Bug 诊断	gemini --mode analysis
多任务执行 (≥3 tasks)	codex --mode write

CLI Enhancement Phases

Phase 1.5: CLI-Assisted Classification

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

触发条件	说明
matchCount < 2	多个意图模式匹配
complexity = high	高复杂度任务
input > 100 chars	长输入需要语义理解

Phase 2.5: CLI-Assisted Action Planning

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

触发条件	说明
complexity = high	高复杂度任务
steps >= 3	多步骤工作流
input > 200 chars	复杂需求描述

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

Continuation Commands

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

命令	作用
continue	继续执行下一步
skip	跳过当前步骤
abort	终止工作流
/workflow:*	切换到指定命令
自然语言	重新分析意图

Workflow Flow Details

Issue Workflow (Main Workflow 补充机制)

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

设计理念

方面	Main Workflow	Issue Workflow
用途	主要开发周期	开发后维护
时机	功能开发阶段	主工作流完成后
范围	完整功能实现	针对性修复/增强
并行性	依赖分析 → Agent 并行	Worktree 隔离 (可选)
分支模型	当前分支工作	可使用隔离的 worktree

为什么 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
产物	无文件	IMPL_PLAN.md + plan.json + synthesis.json
状态	无状态	持久化 session
CLI选择	自动分析任务类型选择	配置驱动
迭代	通过 AskUser	多轮收敛
执行	直接执行	通过 lite-execute
适用	快速修复、简单功能	复杂多步骤实现

选择指南：

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

multi-cli-plan vs lite-plan

维度	multi-cli-plan	lite-plan
上下文	ACE 语义搜索	手动文件模式
分析	多 CLI 交叉验证	单次规划
迭代	多轮直到收敛	单轮
置信度	高 (共识驱动)	中 (单一视角)
适用	需要多视角的复杂任务	直接明确的实现

选择指南：

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

Artifact Flow Protocol

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

产出格式

命令	产出位置	格式	关键字段
/workflow:lite-plan	memory://plan	structured_plan	tasks, files, dependencies
/workflow:plan	.workflow/{session}/IMPL_PLAN.md	markdown_plan	phases, tasks, risks
/workflow:execute	execution_log.json	execution_report	completed_tasks, errors
/workflow:test-cycle-execute	test_results.json	test_report	pass_rate, failures, coverage
/workflow:review-session-cycle	review_report.md	review_report	findings, severity_counts

意图提取 (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