---
name: ccw-coordinator
description: Interactive command orchestration tool for building and executing Claude CLI command chains. Triggers on "coordinator", "ccw-coordinator", "命令编排", "command chain", "orchestrate commands", "编排CLI命令".
allowed-tools: Task, AskUserQuestion, Read, Write, Bash, Glob, Grep
---

# CCW Coordinator

交互式命令编排工具：允许用户依次选择命令，形成命令串，然后依次调用claude cli执行整个命令串。

支持灵活的工作流组合，提供交互式界面用于命令选择、编排和执行管理。

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│           Orchestrator (状态驱动决策)                             │
│     根据用户选择编排命令和执行流程                                  │
└───────────────┬─────────────────────────────────────────────────┘
                │
    ┌───────────┼───────────┬───────────────┐
    ↓           ↓           ↓               ↓
┌─────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────┐
│  Init   │ │   Command    │ │  Command   │ │ Execute  │
│         │ │  Selection   │ │   Build    │ │          │
│         │ │              │ │            │ │          │
│ 初始化  │ │ 选择命令     │ │ 编排调整   │ │ 执行链   │
└─────────┘ └──────────────┘ └────────────┘ └──────────┘
    │               │              │            │
    └───────────────┼──────────────┴────────────┘
                    │
                    ↓
            ┌──────────────┐
            │   Complete   │
            │   生成报告   │
            └──────────────┘
```

## Key Design Principles

1. **智能推荐**: Claude 根据用户任务描述，自动推荐最优命令链
2. **交互式编排**: 用户通过交互式界面选择和编排命令，实时反馈
3. **无状态动作**: 每个动作独立执行，通过共享状态进行通信
4. **灵活的命令库**: 支持ccw workflow命令和标准claude cli命令
5. **执行透明性**: 展示执行进度、结果和可能的错误
6. **会话持久化**: 保存编排会话，支持中途暂停和恢复
7. **智能提示词生成**: 根据任务上下文和前序产物自动生成 ccw cli 提示词
8. **自动确认**: 所有命令自动添加 `-y` 参数，跳过交互式确认，实现无人值守执行

## Intelligent Prompt Generation

执行命令时，系统根据以下信息智能生成 `ccw cli -p` 提示词：

### 提示词构成

```javascript
// 集成命令注册表 (~/.claude/tools/command-registry.js)
const registry = new CommandRegistry();
registry.buildRegistry();

function generatePrompt(cmd, state) {
  const cmdMeta = registry.getCommand(cmd.command);

  let prompt = `任务: ${state.task_description}\n`;

  if (state.execution_results.length > 0) {
    const previousOutputs = state.execution_results
      .filter(r => r.status === 'success')
      .map(r => {
        if (r.summary?.session) {
          return `- ${r.command}: ${r.summary.session} (${r.summary.files?.join(', ')})`;
        }
        return `- ${r.command}: 已完成`;
      })
      .join('\n');

    prompt += `\n前序完成:\n${previousOutputs}\n`;
  }

  // 从 YAML 头提取命令元数据
  if (cmdMeta) {
    prompt += `\n命令: ${cmd.command}`;
    if (cmdMeta.argumentHint) {
      prompt += ` ${cmdMeta.argumentHint}`;
    }
  }

  return prompt;
}
```

### 产物追踪

每个命令执行后自动提取关键产物：

```javascript
{
  command: "/workflow:lite-plan",
  status: "success",
  output: "...",
  summary: {
    session: "WFS-plan-20250123",      // 会话ID
    files: [".workflow/IMPL_PLAN.md"], // 产物文件
    timestamp: "2025-01-23T10:30:00Z"
  }
}
```

### 命令调用示例

```bash
# 自动生成的智能提示词
ccw cli -p "任务: 实现用户认证功能

前序完成:
- /workflow:lite-plan: WFS-plan-20250123 (.workflow/IMPL_PLAN.md)

命令: /workflow:lite-execute [--resume-session=\"session-id\"]" /workflow:lite-execute
```

### 命令注册表集成

- **位置**: `tools/command-registry.js` (skill 内置)
- **工作模式**: 按需提取（只提取用户任务链中的命令）
- **功能**: 自动查找全局 `.claude/commands/workflow` 目录，解析命令 YAML 头元数据
- **作用**: 确保提示词包含准确的命令参数和上下文

详见 `tools/README.md`

---

## Execution Flow

### Orchestrator Execution Loop

```javascript
1. 初始化会话
   ↓
2. 循环执行直到完成
   ├─ 读取当前状态
   ├─ 选择下一个动作（根据状态和用户意图）
   ├─ 执行动作，更新状态
   └─ 检查终止条件
   ↓
3. 生成最终报告
```

### Action Sequence (Typical)

```
action-init
    ↓ (status: pending → running)
action-command-selection (可重复)
    ↓ (添加命令到链)
action-command-build (可选)
    ↓ (调整命令顺序)
action-command-execute
    ↓ (依次执行所有命令)
action-complete
    ↓ (status: running → completed)
```

## State Management

### Initial State

```json
{
  "status": "pending",
  "task_description": "",
  "command_chain": [],
  "confirmed": false,
  "error_count": 0,
  "execution_results": [],
  "current_command_index": 0,
  "started_at": null
}
```

### State Transitions

```
pending → running (init) → running → completed (execute)
                          ↓
                       aborted (error or user exit)
```

## Directory Setup

```javascript
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const workDir = `.workflow/.ccw-coordinator/${timestamp}`;

Bash(`mkdir -p "${workDir}"`);
Bash(`mkdir -p "${workDir}/commands"`);
Bash(`mkdir -p "${workDir}/logs"`);
```

## Output Structure

```
.workflow/.ccw-coordinator/{timestamp}/
├── state.json                    # 当前会话状态
├── command-chain.json            # 编排的完整命令链
├── execution-log.md              # 执行日志
├── final-summary.md              # 最终报告
├── commands/                     # 各命令执行详情
│   ├── 01-command.log
│   ├── 02-command.log
│   └── ...
└── logs/                         # 错误和警告日志
    ├── errors.log
    └── warnings.log
```

## Reference Documents

| Document | Purpose |
|----------|---------|
| [phases/orchestrator.md](phases/orchestrator.md) | 编排器实现 |
| [phases/state-schema.md](phases/state-schema.md) | 状态结构定义 |
| [phases/actions/action-init.md](phases/actions/action-init.md) | 初始化动作 |
| [phases/actions/action-command-selection.md](phases/actions/action-command-selection.md) | 命令选择动作 |
| [phases/actions/action-command-build.md](phases/actions/action-command-build.md) | 命令编排动作 |
| [phases/actions/action-command-execute.md](phases/actions/action-command-execute.md) | 命令执行动作 |
| [phases/actions/action-complete.md](phases/actions/action-complete.md) | 完成动作 |
| [phases/actions/action-abort.md](phases/actions/action-abort.md) | 中止动作 |
| [specs/specs.md](specs/specs.md) | 命令库、验证规则、注册表 |
| [tools/chain-validate.cjs](tools/chain-validate.cjs) | 验证工具 |
| [tools/command-registry.cjs](tools/command-registry.cjs) | 命令注册表工具 |

---

## Usage Examples

### 快速命令链

用户想要执行：规划 → 执行 → 测试

```
1. 触发 /ccw-coordinator
2. 描述任务："实现用户注册功能"
3. Claude推荐: plan → execute → test-cycle-execute
4. 用户确认
5. 执行命令链
```

### 复杂工作流

用户想要执行：规划 → 执行 → 审查 → 修复

```
1. 触发 /ccw-coordinator
2. 描述任务："重构认证模块"
3. Claude推荐: plan → execute → review-session-cycle → review-fix
4. 用户可调整命令顺序
5. 确认执行
6. 实时查看执行进度
```

### 紧急修复

用户想要快速修复bug

```
1. 触发 /ccw-coordinator
2. 描述任务："修复生产环境登录bug"
3. Claude推荐: lite-fix --hotfix → test-cycle-execute
4. 用户确认
5. 快速执行修复
```

## Constraints and Rules

### 1. 命令推荐约束

- **智能推荐优先**: 必须先基于用户任务描述进行智能推荐，而非直接展示命令库
- **不使用静态映射**: 禁止使用查表或硬编码的推荐逻辑（如 `if task=bug则推荐lite-fix`）
- **推荐必须说明理由**: Claude 推荐命令链时必须解释为什么这样推荐
- **用户保留选择权**: 推荐后，用户可选择：使用推荐/调整/手动选择

### 2. 验证约束

- **执行前必须验证**: 使用 `chain-validate.js` 验证命令链合法性
- **不合法必须提示**: 如果验证失败，必须明确告知用户错误原因和修复方法
- **允许用户覆盖**: 验证失败时，询问用户是否仍要执行（警告模式）

### 3. 执行约束

- **顺序执行**: 命令必须严格按照 command_chain 中的 order 顺序执行
- **错误处理**: 单个命令失败时，询问用户：重试/跳过/中止
- **错误上限**: 连续 3 次错误自动中止会话
- **实时反馈**: 每个命令执行时显示进度（如 `[2/5] 执行: lite-execute`）

### 4. 状态管理约束

- **状态持久化**: 每次状态更新必须立即写入磁盘
- **单一数据源**: 状态只保存在 `state.json`，禁止多个状态文件
- **原子操作**: 状态更新必须使用 read-modify-write 模式，避免并发冲突

### 5. 用户体验约束

- **最小交互**: 默认使用智能推荐 + 一次确认，避免多次询问
- **清晰输出**: 每个步骤输出必须包含：当前状态、可用选项、建议操作
- **可恢复性**: 会话中断后，用户可从上次状态恢复

### 6. 禁止行为

- ❌ **禁止跳过推荐步骤**: 不能直接进入手动选择，必须先尝试推荐
- ❌ **禁止静态推荐**: 不能使用 recommended-chains.json 查表
- ❌ **禁止无验证执行**: 不能跳过链条验证直接执行
- ❌ **禁止静默失败**: 错误必须明确报告，不能静默跳过

## Notes

- 编排器使用状态机模式，确保执行流程的可靠性
- 所有命令链和执行结果都被持久化保存，支持后续查询和调试
- 支持用户中途修改命令链（在执行前）
- 执行错误会自动记录，支持重试机制
- Claude 智能推荐基于任务分析，非查表静态推荐