名称: workflow-execute 描述: 通过自动会话发现、并行任务处理和状态跟踪来协调工作流任务的代理执行。触发条件为 “workflow:execute”。允许工具: Skill, Task, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Read, Write, Edit, Bash, Glob, Grep

工作流执行

通过系统性任务发现、代理协调和进度跟踪来编排自主工作流执行。无需用户中断即可执行整个工作流（除非存在多个活动会话时需要初始会话选择），为代理提供完整上下文，并确保通过全面的TodoWrite跟踪进行正确的流控制执行。

恢复模式: 当使用 --resume-session 标志调用时，跳过发现阶段，直接进入指定会话的TodoWrite生成和代理执行。

用法

# 交互模式（带确认）
/workflow:execute
/workflow:execute --resume-session="WFS-auth"

# 自动模式（跳过确认，使用默认值）
/workflow:execute --yes
/workflow:execute -y
/workflow:execute -y --resume-session="WFS-auth"

# 带自动提交（每个任务完成后提交）
/workflow:execute --with-commit
/workflow:execute -y --with-commit
/workflow:execute -y --with-commit --resume-session="WFS-auth"

自动模式默认值

当使用 --yes 或 -y 标志时：

会话选择: 自动选择第一个（最近）活动会话
完成选择: 自动完成会话（运行 /workflow:session:complete --yes）

当使用 --with-commit 标志时：

自动提交: 每个代理任务完成后，基于摘要文档提交更改
提交原则: 最小化提交 - 仅提交由完成任务修改的文件
提交消息: 从任务摘要生成，格式为：“feat/fix/refactor: {任务标题} - {摘要}”

标志解析:

// ★ 统一自动模式检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播
const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)
const withCommit = $ARGUMENTS.includes('--with-commit')

性能优化策略

懒加载: 任务JSON在执行期间按需读取，非预先读取。TODO_LIST.md + IMPL_PLAN.md 提供用于规划的元数据。

加载策略:

TODO_LIST.md: 在阶段3读取（任务元数据、状态、依赖关系用于TodoWrite生成）
IMPL_PLAN.md: 在阶段2检查存在性（正常模式），在阶段4A解析执行策略
任务JSONs: 懒加载 - 仅在任务即将执行时读取（阶段4B）

核心规则

无需用户中断即可自主完成整个工作流，使用TodoWrite进行全面的进度跟踪。 执行所有发现的待处理任务，直到工作流完成或遇到阻塞依赖。 用户选择完成：当所有任务完成时，询问用户选择审查或完成。 一个代理 = 一个任务JSON：每个代理实例执行恰好一个任务JSON文件 - 绝不将多个任务批量到单个代理执行中。

核心职责

会话发现: 识别和选择活动工作流会话
执行策略解析: 从IMPL_PLAN.md中提取执行模型
TodoWrite进度跟踪: 在整个工作流中维护实时执行状态
代理编排: 协调具有完整上下文的专业化代理
状态同步: 更新任务JSON文件和工作流状态
自主完成: 继续执行直到所有任务完成或达到阻塞状态
会话用户选择完成: 当所有任务完成时，询问用户选择审查或完成

执行理念

进度跟踪: 在整个工作流执行期间持续更新TodoWrite
自主完成: 无需用户中断执行所有任务，直到工作流完成

执行过程

正常模式：
阶段1：发现
   ├─ 统计活动会话
   └─ 决策：
      ├─ 数量=0 → 错误：无活动会话
      ├─ 数量=1 → 自动选择会话 → 阶段2
      └─ 数量>1 → 询问用户问题（最多4个选项） → 阶段2

阶段2：规划文档验证
   ├─ 检查IMPL_PLAN.md存在
   ├─ 检查TODO_LIST.md存在
   └─ 验证.task/包含IMPL-*.json文件

阶段3：TodoWrite生成
   ├─ 更新会话状态为"active"（步骤0）
   ├─ 解析TODO_LIST.md获取任务状态
   ├─ 生成整个工作流的TodoWrite
   └─ 准备会话上下文路径

阶段4：执行策略与任务执行
   ├─ 步骤4A：从IMPL_PLAN.md解析执行策略
   └─ 步骤4B：使用懒加载执行任务
      └─ 循环：
         ├─ 从TodoWrite获取下一个in_progress任务
         ├─ 懒加载任务JSON
         ├─ 使用任务上下文启动代理
         ├─ 标记任务完成（更新IMPL-*.json状态）
         │  # 快速修复：更新任务状态以用于ccw仪表板
         │  # TS=$(date -Iseconds) && jq --arg ts "$TS" '.status="completed" | .status_history=(.status_history // [])+[{"from":"in_progress","to":"completed","changed_at":$ts}]' IMPL-X.json > tmp.json && mv tmp.json IMPL-X.json
         ├─ [with-commit] 基于摘要提交更改（最小化原则）
         │  # 从.summaries/IMPL-X-summary.md读取摘要
         │  # 从摘要的"Files Modified"部分提取更改的文件
         │  # 生成提交消息："feat/fix/refactor: {任务标题} - {摘要}"
         │  # git add <更改的文件> && git commit -m "<提交消息>"
         └─ 前进到下一个任务

阶段5：完成
   ├─ 更新JSON文件中的任务状态
   ├─ 生成摘要
   └─ 询问用户问题：选择下一步
      ├─ "进入审查" → 阶段6
      └─ "完成会话" → /workflow:session:complete

阶段6：后实施审查（可选）
   └─ 参考：phases/06-review.md
      ├─ 选择审查类型（质量/安全/架构/行动项）
      ├─ CLI辅助分析（Gemini/Qwen）
      ├─ 生成REVIEW-{type}.md报告
      └─ 后审查：另一个审查或完成会话

恢复模式（--resume-session）：
   ├─ 跳过阶段1和阶段2
   └─ 入口点：阶段3（TodoWrite生成）
      ├─ 更新会话状态为"active"（如果尚未）
      └─ 继续：阶段4 → 阶段5 → [阶段6]

执行生命周期

阶段1：发现

适用于: 仅正常模式（恢复模式中跳过）

目的: 查找并选择活动工作流会话，当多个会话存在时使用用户确认

过程:

步骤1.1：统计活动会话

bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)

步骤1.2：处理会话选择

情况A：无会话（数量 = 0）

错误：未找到活动工作流会话
运行 /workflow:plan "任务描述" 以创建会话

情况B：单个会话（数量 = 1）

bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)

自动选择并继续到阶段2。

情况C：多个会话（数量 > 1）

列出带元数据的会话并提示用户选择：

bash(for dir in .workflow/active/WFS-*/; do [ -d "$dir" ] || continue; session=$(basename "$dir"); project=$(jq -r '.project // "Unknown"' "${dir}workflow-session.json" 2>/dev/null || echo "Unknown"); total=$(grep -c '^\- \[' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); completed=$(grep -c '^\- \[x\]' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); if [ "$total" -gt 0 ]; then progress=$((completed * 100 / total)); else progress=0; fi; echo "$session | $project | $completed/$total tasks ($progress%)"; done)

解析–yes标志:

// ★ 统一自动模式检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播
const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)

条件选择:

if (autoYes) {
  // 自动模式：选择第一个会话（最近）
  const firstSession = sessions[0]
  console.log(`[--yes] 自动选择会话：${firstSession.id}`)
  selectedSessionId = firstSession.id
  // 继续到阶段2
} else {
  // 交互模式：使用AskUserQuestion呈现格式化选项（最多显示4个选项）
  // 如果超过4个会话，显示最近4个并带"其他"选项用于手动输入
  const sessions = getActiveSessions()  // 按最后修改排序
  const displaySessions = sessions.slice(0, 4)

  AskUserQuestion({
    questions: [{
      question: "检测到多个活动会话。选择一个：",
      header: "会话",
      multiSelect: false,
      options: displaySessions.map(s => ({
        label: s.id,
        description: `${s.project} | ${s.progress}`
      }))
      // 注意：用户可以选择"其他"手动输入会话ID
    }]
  })
}

输入验证:

如果用户从选项中选择：使用选定的会话ID
如果用户选择"其他"并提供输入：验证会话存在
如果验证失败：显示错误并重新提示或建议可用会话

解析用户输入（支持：数字 “1”、完整ID “WFS-auth-system”、或部分 “auth”），验证选择，并继续到阶段2。

步骤1.3：加载会话元数据

bash(cat .workflow/active/${sessionId}/workflow-session.json)

输出: 将会话元数据存储在内存中 不读取任务JSONs - 延迟到执行阶段（懒加载）

恢复模式: 当提供 --resume-session="session-id" 标志时，整个阶段被跳过。

阶段2：规划文档验证

适用于: 仅正常模式（恢复模式中跳过）

目的: 在执行前验证规划工件存在

过程:

检查IMPL_PLAN.md: 验证文件存在（详细解析延迟到阶段4A）
检查plan.json: 验证文件存在（结构化计划概述，用于阶段4A）
检查TODO_LIST.md: 验证文件存在（读取延迟到阶段3）
验证任务目录: 确保.task/至少包含一个IMPL-*.json文件

关键优化: 仅此处进行存在性检查。实际文件读取发生在后续阶段。

恢复模式: 当提供 --resume-session 标志时，此阶段被跳过。恢复模式入口点是阶段3。

阶段3：TodoWrite生成

适用于: 正常和恢复模式（恢复模式入口点）

步骤0：更新会话状态为Active 在生成TodoWrite前，更新会话状态从"planning"到"active"：

# 更新会话状态（幂等 - 如果已为active则可安全运行）
jq '.status = "active" | .execution_started_at = (.execution_started_at // now | todate)' \
  .workflow/active/${sessionId}/workflow-session.json > tmp.json && \
  mv tmp.json .workflow/active/${sessionId}/workflow-session.json

这确保仪表板在执行期间显示会话为"ACTIVE"。

过程:

创建TodoWrite列表: 从TODO_LIST.md生成任务列表（非从任务JSONs）
- 解析TODO_LIST.md提取所有任务及其当前状态
- 识别第一个具有满足依赖的待处理任务
- 生成覆盖整个工作流的全面TodoWrite
准备会话上下文: 注入工作流路径供代理使用（使用提供的会话ID）
验证先决条件: 确保IMPL_PLAN.md和TODO_LIST.md存在且有效

恢复模式行为:

直接从.workflow/active/{session-id}/加载现有TODO_LIST.md
从TODO_LIST.md提取当前进度
从TODO_LIST.md状态生成TodoWrite
立即进行代理执行（阶段4）

阶段4：执行策略选择与任务执行

适用于: 正常和恢复模式

步骤4A：解析执行策略（首选plan.json，IMPL_PLAN.md作为回退）

首选 plan.json（结构化）于 IMPL_PLAN.md（人类可读）用于执行策略：

如果plan.json存在: 读取 recommended_execution, complexity, task_ids[], shared_context
回退到IMPL_PLAN.md: 读取第4节提取执行模型

提取：

执行模型: 顺序 | 并行 | 分阶段 | TDD周期
并行化机会: 哪些任务可以并行运行
序列化要求: 哪些任务必须顺序运行
关键路径: 优先级执行顺序

如果两者都没有执行策略，使用智能回退（分析任务结构）。

步骤4B：使用懒加载执行任务

关键优化: 仅在执行需要时读取任务JSON

执行循环模式:

while (TODO_LIST.md有待处理任务) {
  next_task_id = getTodoWriteInProgressTask()
  task_json = Read(.workflow/active/{session}/.task/{next_task_id}.json)  // 懒加载
  executeTaskWithAgent(task_json)
  updateTodoListMarkCompleted(next_task_id)
  advanceTodoWriteToNextTask()
}

每个任务的执行过程:

识别下一个任务: 从TodoWrite，获取下一个 in_progress 任务ID
按需加载任务JSON: 读取.task/{task-id}.json 仅用于当前任务
验证任务结构: 确保必需字段存在（id, title, description, depends_on, convergence）
启动代理: 使用完整上下文调用专业化代理，包括流控制步骤
监控进度: 跟踪代理执行并无用户中断处理错误
收集结果: 收集实施结果和输出
[with-commit] 自动提交: 如果启用 --with-commit 标志，基于摘要提交更改
- 从.summaries/{task-id}-summary.md读取摘要
- 从摘要的"Files Modified"部分提取更改的文件
- 从 meta.type 确定提交类型（feature→feat, bugfix→fix, refactor→refactor）
- 生成提交消息：“{type}: {任务标题} - {摘要首行}”
- 仅提交修改的文件（最小化原则）：git add <文件> && git commit -m "<消息>"
继续工作流: 从TODO_LIST.md识别下一个待处理任务并重复

注意: TODO_LIST.md更新由代理（如code-developer.md）处理，非由编排器处理。

阶段5：完成

适用于: 正常和恢复模式

过程:

更新任务状态: 在JSON文件中标记完成的任务
生成摘要: 在.summaries/中创建任务摘要
更新TodoWrite: 标记当前任务完成，前进到下一个
同步状态: 更新会话状态和工作流状态
检查工作流完成: 验证所有任务已完成
用户选择: 当所有任务完成时，询问用户选择下一步：

// 解析--yes标志
// ★ 统一自动模式检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播
const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)

if (autoYes) {
  // 自动模式：自动完成会话
  console.log(`[--yes] 自动选择：完成会话`)
  Skill(skill="workflow:session:complete", args="--yes")
} else {
  // 交互模式：询问用户
  AskUserQuestion({
    questions: [{
      question: "所有任务已完成。您接下来想做什么？",
      header: "下一步",
      multiSelect: false,
      options: [
        {
          label: "进入审查",
          description: "运行专业化审查（安全/架构/质量/行动项）"
        },
        {
          label: "完成会话",
          description: "归档会话并更新清单"
        }
      ]
    }]
  })
}

基于用户选择:

“进入审查”: 执行阶段6 → 参考：phases/06-review.md
“完成会话”: 执行 /workflow:session:complete

后完成扩展

完成后询问用户是否扩展为issue（测试/增强/重构/文档），选中项调用 /issue:new "{摘要} - {维度}"

执行策略（IMPL_PLAN驱动）

策略优先级

IMPL_PLAN驱动执行（推荐）:

读取IMPL_PLAN.md执行策略（第4节：实施策略）
遵循明确指导:
- 执行模型（顺序/并行/分阶段/TDD）
- 并行化机会（哪些任务可以并行运行）
- 序列化要求（哪些任务必须顺序运行）
- 关键路径（优先级执行顺序）
使用TODO_LIST.md仅用于状态跟踪
IMPL_PLAN决定"如何"，workflow-execute实施它

智能回退（当IMPL_PLAN缺乏执行细节时）:

分析任务结构:
- 检查任务JSON中的 meta.execution_group
- 分析 depends_on 关系
- 理解任务复杂性和风险
应用智能默认值:
- 无依赖 + 相同execution_group → 并行
- 有依赖 → 顺序（等待依赖）
- 关键/高风险任务 → 顺序
保守方法: 当不确定时，偏好顺序执行

执行模型

1. 顺序执行

当: IMPL_PLAN指定"顺序"或没有明确并行化指导时模式: 按TODO_LIST顺序逐个执行任务 TodoWrite: 一次仅一个任务标记为 in_progress

2. 并行执行

当: IMPL_PLAN指定"并行"并带有明确并行化机会时模式: 通过启动多个代理实例并发执行独立任务组 TodoWrite: 多个任务（在同一批次中）同时标记为 in_progress 代理实例化: 为每个任务启动一个代理实例（遵守一个代理 = 一个任务JSON规则）

3. 分阶段执行

当: IMPL_PLAN指定"分阶段"并带有阶段细分时模式: 按阶段执行任务，尊重阶段边界 TodoWrite: 在每个阶段内，遵循顺序或并行规则

4. 智能回退

当: IMPL_PLAN缺乏执行策略细节时模式: 分析任务结构并应用智能默认值 TodoWrite: 基于分析遵循顺序或并行规则

任务状态逻辑

待处理 + 依赖满足 → 可执行
已完成 → 跳过
阻塞 → 跳过直到依赖清除

TodoWrite协调

TodoWrite规则（统一）

规则1：初始创建

正常模式: 从发现的待处理任务生成整个工作流的TodoWrite
恢复模式: 从现有会话状态和当前进度生成

规则2：进行中任务计数（执行模型依赖）

顺序执行: 一次仅标记一个任务为 in_progress
并行批次执行: 同时标记当前批次中的所有任务为 in_progress
执行组指示器: 为并行任务显示 [execution_group: group-id]

规则3：状态更新

立即更新: 每个任务/批次完成后无需用户中断更新状态
状态同步: 更新后与JSON任务文件同步
持续跟踪: 在整个工作流执行期间维护TodoWrite直到完成

规则4：工作流完成检查

当所有任务标记为 completed 时，提示用户选择审查或完成会话

TodoWrite工具用法

示例1：顺序执行

TodoWrite({
  todos: [
    {
      content: "执行IMPL-1.1：设计身份验证架构 [code-developer] [FLOW_CONTROL]",
      status: "in_progress",  // 一个任务进行中
      activeForm: "执行IMPL-1.1：设计身份验证架构"
    },
    {
      content: "执行IMPL-1.2：实施身份验证逻辑 [code-developer] [FLOW_CONTROL]",
      status: "pending",
      activeForm: "执行IMPL-1.2：实施身份验证逻辑"
    }
  ]
});

示例2：并行批次执行

TodoWrite({
  todos: [
    {
      content: "执行IMPL-1.1：构建身份验证API [code-developer] [execution_group: parallel-auth-api]",
      status: "in_progress",  // 批次任务1
      activeForm: "执行IMPL-1.1：构建身份验证API"
    },
    {
      content: "执行IMPL-1.2：构建用户UI [code-developer] [execution_group: parallel-ui-comp]",
      status: "in_progress",  // 批次任务2（并发运行）
      activeForm: "执行IMPL-1.2：构建用户UI"
    },
    {
      content: "执行IMPL-1.3：设置数据库 [code-developer] [execution_group: parallel-db-schema]",
      status: "in_progress",  // 批次任务3（并发运行）
      activeForm: "执行IMPL-1.3：设置数据库"
    },
    {
      content: "执行IMPL-2.1：集成测试 [test-fix-agent] [depends_on: IMPL-1.1, IMPL-1.2, IMPL-1.3]",
      status: "pending",  // 下一个批次（等待当前批次完成）
      activeForm: "执行IMPL-2.1：集成测试"
    }
  ]
});

代理执行模式

流控制执行

[FLOW_CONTROL] 标记表示任务JSON包含用于上下文准备的 pre_analysis 步骤。

注意: 编排器不执行流控制步骤 - 代理自主解释和执行它们。

代理提示模板

基于路径的调用: 传递路径和触发标记，让代理自主解析任务JSON。

Task(subagent_type="{meta.agent}",
     run_in_background=false,
     prompt="实施任务 {task.id}: {task.title}

     [FLOW_CONTROL]

     **输入**:
     - 任务JSON: {session.task_json_path}
     - 上下文包: {session.context_package_path}

     **输出位置**:
     - 工作流: {session.workflow_dir}
     - TODO列表: {session.todo_list_path}
     - 摘要: {session.summaries_dir}

     **执行**: 读取任务JSON → 执行pre_analysis → 检查execution_config.method → (CLI: 转交给CLI工具 | 代理: 直接实施) → 更新TODO_LIST.md → 生成摘要",
     description="实施: {task.id}")

关键标记:

实施 关键词: 触发技术栈检测和指南加载
[FLOW_CONTROL]: 触发pre_analysis执行

为何基于路径: 代理（code-developer.md）自主地：

读取和解析任务JSON（描述、convergence、implementation、execution_config）
执行pre_analysis步骤（阶段1：上下文收集）
检查execution_config.method（阶段2：确定模式）
CLI模式: 构建转交提示并通过ccw cli执行，带恢复策略
代理模式: 直接使用modification_points和logic_flow实施
生成带集成点的结构化摘要

在提示中嵌入任务内容会导致重复，并与代理的解析逻辑冲突。

代理分配规则

指定了meta.agent → 使用指定代理
缺少meta.agent → 从meta.type推断：
  - "feature" → @code-developer
  - "test-gen" → @code-developer
  - "test-fix" → @test-fix-agent
  - "review" → @universal-executor
  - "docs" → @doc-generator

阶段参考文档

阶段	文档	目的
6	phases/06-review.md	后实施专业化审查（安全/架构/质量/行动项）

工作流文件结构参考

.workflow/active/WFS-[topic-slug]/
├── workflow-session.json     # 会话状态和元数据
├── plan.json                # 结构化计划概述（机器可读）
├── IMPL_PLAN.md             # 规划文档和需求（人类可读）
├── TODO_LIST.md             # 进度跟踪（由代理更新）
├── .task/                   # 任务定义（仅JSON）
│   ├── IMPL-1.json          # 主要任务定义
│   └── IMPL-1.1.json        # 子任务定义
├── .summaries/              # 任务完成摘要
│   ├── IMPL-1-summary.md    # 任务完成细节
│   └── IMPL-1.1-summary.md  # 子任务完成细节
└── .process/                # 规划工件
    ├── context-package.json # 智能上下文包
    └── ANALYSIS_RESULTS.md  # 规划分析结果

错误处理与恢复

常见错误与恢复

错误类型	原因	恢复策略	最大尝试次数
发现错误
无活动会话	`.workflow/active/` 中无会话	创建或恢复会话：`/workflow:plan "项目"`	N/A
多个会话	`.workflow/active/` 中多个会话	提示用户选择	N/A
损坏会话	无效JSON文件	重新创建会话结构或验证文件	N/A
执行错误
代理失败	代理崩溃/超时	使用简化上下文重试	2
流控制错误	命令失败	跳过可选，关键失败	每步1次
上下文加载错误	缺少依赖项	从JSON重新加载，使用默认值	3
JSON文件损坏	文件系统问题	从备份/重新创建恢复	1

错误预防

飞行前检查: 在执行前验证会话完整性
备份策略: 在主要操作前创建任务快照
原子更新: 原子更新JSON文件以防止损坏
依赖验证: 检查所有depends_on引用存在
上下文验证: 确保所有必需上下文可用

自动提交模式（–with-commit）

行为: 每个代理任务完成后，基于摘要文档自动提交更改。

最小化原则: 仅提交由完成任务修改的文件。

提交消息格式: {type}: {任务标题} - {摘要}

类型映射（从 meta.type）：

feature → feat | bugfix → fix | refactor → refactor
test-gen → test | docs → docs | review → chore

实施:

# 1. 从.summaries/{task-id}-summary.md读取摘要
# 2. 从"Files Modified"部分提取文件
# 3. 提交：git add <文件> && git commit -m "{type}: {标题} - {摘要}"

错误处理: 无更改/缺少摘要时跳过提交，记录错误，继续工作流。

名称: workflow-execute 描述: 通过自动会话发现、并行任务处理和状态跟踪来协调工作流任务的代理执行。触发条件为 “workflow:execute”。 允许工具: Skill, Task, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Read, Write, Edit, Bash, Glob, Grep