Claude-Code-Workflow/.claude/skills/ccw-coordinator/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
ccw-coordinator	Interactive command orchestration tool for building and executing Claude CLI command chains. Triggers on "coordinator", "ccw-coordinator", "命令编排", "command chain", "orchestrate commands", "编排CLI命令".	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 提示词：

提示词构成

// 集成命令注册表 (~/.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;
}

产物追踪

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

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

命令调用示例

# 自动生成的智能提示词
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

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

{
  "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

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/state-schema.md	状态结构定义
phases/actions/action-init.md	初始化动作
phases/actions/action-command-selection.md	命令选择动作
phases/actions/action-command-build.md	命令编排动作
phases/actions/action-command-execute.md	命令执行动作
phases/actions/action-complete.md	完成动作
phases/actions/action-abort.md	中止动作
specs/specs.md	命令库、验证规则、注册表
tools/chain-validate.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 智能推荐基于任务分析，非查表静态推荐