workflow-execute

工作流执行

通过系统化的任务发现、Agent 协调和进度跟踪来编排自主工作流执行。执行整个工作流时不会中断用户（如果存在多个活动会话，初始会话选择除外），为 Agent 提供完整上下文，并确保正确执行流程控制，同时通过全面的 TodoWrite 跟踪进度。

恢复模式：使用 --resume-session 标志调用时，跳过发现阶段，直接进入 TodoWrite 生成和 Agent 执行，针对指定会话继续操作。

用法

# Interactive mode (with confirmations)
/workflow-execute
/workflow-execute --resume-session="WFS-auth"

# Auto mode (skip confirmations, use defaults)
/workflow-execute --yes
/workflow-execute -y
/workflow-execute -y --resume-session="WFS-auth"

# With auto-commit (commit after each task completion)
/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 标志时：

• 自动提交：每个 Agent 任务完成后，根据摘要文档提交更改
• 提交原则：最小化提交——仅提交已完成任务修改的文件
• 提交消息：根据任务摘要生成，格式为："feat/fix/refactor: {task-title} - {summary}"

标志解析：

// ★ 统一 auto mode 检测：-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 解析执行策略
• 任务 JSON：延迟加载——仅在任务即将执行时读取（阶段 4B）

核心规则

自主完成整个工作流，不中断用户，并使用 TodoWrite 全面跟踪进度。 执行所有已发现的待处理任务，直至工作流完成或遇到阻塞依赖项。 由用户选择完成方式：所有任务完成后，询问用户选择审查或完成。 一个 Agent 对应一个任务 JSON：每个 Agent 实例只执行一个任务 JSON 文件——绝不在单次 Agent 执行中批量处理多个任务。

核心职责

• 会话发现：识别并选择活动工作流会话
• 执行策略解析：从 IMPL_PLAN.md 中提取执行模型
• TodoWrite 进度跟踪：在整个工作流中实时维护执行状态
• Agent 编排：为专用 Agent 协调提供完整上下文
• 状态同步：更新任务 JSON 文件和工作流状态
• 自主完成：持续执行，直至所有任务完成或进入阻塞状态
• 会话完成方式选择：所有任务完成后，询问用户选择审查或完成

执行理念

• 进度跟踪：在整个工作流执行过程中持续更新 TodoWrite
• 自主完成：持续执行所有任务，不中断用户，直至工作流完成

执行流程

Normal Mode:
Phase 1: Discovery
   ├─ Count active sessions
   └─ Decision:
      ├─ count=0 → ERROR: No active sessions
      ├─ count=1 → Auto-select session → Phase 2
      └─ count>1 → AskUserQuestion (max 4 options) → Phase 2

Phase 2: Planning Document Validation
   ├─ Check IMPL_PLAN.md exists
   ├─ Check TODO_LIST.md exists
   └─ Validate .task/ contains IMPL-*.json files

Phase 3: TodoWrite Generation
   ├─ Update session status to "active" (Step 0)
   ├─ Parse TODO_LIST.md for task statuses
   ├─ Generate TodoWrite for entire workflow
   └─ Prepare session context paths

Phase 4: Execution Strategy & Task Execution
   ├─ Step 4A: Parse execution strategy from IMPL_PLAN.md
   └─ Step 4B: Execute tasks with lazy loading
      └─ Loop:
         ├─ Get next in_progress task from TodoWrite
         ├─ Lazy load task JSON
         ├─ Launch agent with task context
         ├─ Mark task completed (update IMPL-*.json status)
         │  # Quick fix: Update task status for ccw dashboard
         │  # 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] Commit changes based on summary (minimal principle)
         │  # Read summary from .summaries/IMPL-X-summary.md
         │  # Extract changed files from summary's "Files Modified" section
         │  # Generate commit message: "feat/fix/refactor: {task-title} - {summary}"
         │  # git add <changed-files> && git commit -m "<commit-message>"
         └─ Advance to next task

Phase 5: Completion
   ├─ Update task statuses in JSON files
   ├─ Generate summaries
   └─ AskUserQuestion: Choose next step
      ├─ "Enter Review" → Phase 6
      └─ "Complete Session" → /workflow:session:complete

Phase 6: Post-Implementation Review (Optional)
   └─ Ref: phases/06-review.md
      ├─ Select review type (quality/security/architecture/action-items)
      ├─ CLI-assisted analysis (Gemini/Qwen)
      ├─ Generate REVIEW-{type}.md report
      └─ Post-review: another review or complete session

Resume Mode (--resume-session):
   ├─ Skip Phase 1 & Phase 2
   └─ Entry Point: Phase 3 (TodoWrite Generation)
      ├─ Update session status to "active" (if not already)
      └─ Continue: Phase 4 → Phase 5 → [Phase 6]

执行生命周期

阶段 1：发现

适用于：仅普通模式（恢复模式下跳过）

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

流程：

步骤 1.1：统计活动会话数

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

步骤 1.2：处理会话选择

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

ERROR: No active workflow sessions found
Run /workflow-plan "task description" to create a session

情况 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 标志：

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

条件选择：

if (autoYes) {
  // Auto mode: Select first session (most recent)
  const firstSession = sessions[0]
  console.log(`[--yes] Auto-selecting session: ${firstSession.id}`)
  selectedSessionId = firstSession.id
  // Continue to Phase 2
} else {
  // Interactive mode: Use AskUserQuestion to present formatted options (max 4 options shown)
  // If more than 4 sessions, show most recent 4 with "Other" option for manual input
  const sessions = getActiveSessions()  // sorted by last modified
  const displaySessions = sessions.slice(0, 4)

  AskUserQuestion({
    questions: [{
      question: "Multiple active sessions detected. Select one:",
      header: "Session",
      multiSelect: false,
      options: displaySessions.map(s => ({
        label: s.id,
        description: `${s.project} | ${s.progress}`
      }))
      // Note: User can select "Other" to manually enter session ID
    }]
  })
}

输入验证：

• 如果用户从选项中进行选择：使用所选会话 ID
• 如果用户选择“其他”并提供输入：验证会话是否存在
• 如果验证失败：显示错误并重新提示，或建议可用会话

解析用户输入（支持：数字 "1"、完整 ID "WFS-auth-system" 或部分内容 "auth"），验证所选项，然后继续到阶段 2。

步骤 1.3：加载会话元数据

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

输出：将会话元数据存储在内存中 暂时不要读取任务 JSON——推迟到执行阶段再读取（延迟加载）

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

阶段 2：规划文档验证

适用范围：仅正常模式（恢复模式下跳过）

目的：在执行前验证规划产物是否存在

流程：

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

关键优化：此处仅检查文件是否存在。实际文件读取将在后续阶段进行。

恢复模式：提供 --resume-session 标志时，将跳过此阶段。恢复模式从阶段 3 开始。

阶段 3：TodoWrite 生成

适用范围：正常模式和恢复模式（恢复模式的入口点）

步骤 0：将会话状态更新为活动 生成 TodoWrite 前，将会话状态从“规划中”更新为“活动”：

# Update session status (idempotent - safe to run if already 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”。

流程：

1. 创建 TodoWrite 列表：根据 TODO_LIST.md 生成任务列表（而非根据任务 JSON）
   • 解析 TODO_LIST.md，提取所有任务及其当前状态
   • 找出依赖项已满足的第一个待处理任务
   • 生成覆盖整个工作流的完整 TodoWrite
2. 准备会话上下文：为 Agent 注入工作流路径（使用提供的 session-id）
3. 验证前置条件：确保 IMPL_PLAN.md 和 TODO_LIST.md 存在且有效

恢复模式行为：

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

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

适用范围：正常模式和恢复模式

步骤 4A：解析执行策略（优先使用 plan.json，回退到 IMPL_PLAN.md）

执行策略优先使用 plan.json（结构化），而非 IMPL_PLAN.md（人类可读）：

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

提取：

• 执行模型：顺序 | 并行 | 分阶段 | TDD 循环
• 并行化机会：哪些任务可以并行执行
• 串行化要求：哪些任务必须按顺序执行
• 关键路径：优先执行顺序

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

步骤 4B：通过延迟加载执行任务

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

执行循环模式：

while (TODO_LIST.md has pending tasks) {
  next_task_id = getTodoWriteInProgressTask()
  task_json = Read(.workflow/active/{session}/.task/{next_task_id}.json)  // Lazy load
  executeTaskWithAgent(task_json)
  updateTodoListMarkCompleted(next_task_id)
  advanceTodoWriteToNextTask()
}

每项任务的执行流程：

1. 识别下一个任务：从 TodoWrite 中获取下一个 in_progress 任务 ID
2. 按需加载任务 JSON：仅读取当前任务的 .task/{task-id}.json
3. 验证任务结构：确保必需字段存在（id、title、description、depends_on、convergence）
4. 启动 Agent：调用专用 Agent，并提供完整上下文，包括流程控制步骤
5. 监控进度：跟踪 Agent 执行情况并处理错误，无需中断用户
6. 收集结果：汇总实现结果和输出
7. [with-commit] 自动提交：如果启用了 --with-commit 标志，则根据摘要提交更改
   • 从 .summaries/{task-id}-summary.md 读取摘要
   • 从摘要的“已修改文件”部分提取更改的文件
   • 根据 meta.type 确定提交类型（feature→feat，bugfix→fix，refactor→refactor）
   • 生成提交消息："{type}: {task-title} - {summary-first-line}"
   • 仅提交已修改的文件（最小化原则）：git add <files> && git commit -m "<message>"
8. 继续工作流：从 TODO_LIST.md 识别下一个待处理任务并重复以上步骤

注意：TODO_LIST.md 由 Agent（例如 code-developer.md）更新，而非由编排器更新。

阶段 5：完成

适用范围：正常模式和恢复模式

流程：

1. 更新任务状态：在 JSON 文件中将已完成任务标记为完成
2. 生成摘要：在 .summaries/ 中创建任务摘要
3. 更新 TodoWrite：将当前任务标记为完成，并转到下一项
4. 同步状态：更新会话状态和工作流状态
5. 检查工作流是否完成：确认所有任务均已完成
6. 用户选择：所有任务完成后，询问用户选择下一步：

// Parse --yes flag
// ★ 统一 auto mode 检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播
const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)

if (autoYes) {
  // Auto mode: Complete session automatically
  console.log(`[--yes] Auto-selecting: Complete Session`)
  Skill(skill="workflow:session:complete", args="--yes")
} else {
  // Interactive mode: Ask user
  AskUserQuestion({
    questions: [{
      question: "All tasks completed. What would you like to do next?",
      header: "Next Step",
      multiSelect: false,
      options: [
        {
          label: "Enter Review",
          description: "Run specialized review (security/architecture/quality/action-items)"
        },
        {
          label: "Complete Session",
          description: "Archive session and update manifest"
        }
      ]
    }]
  })
}

根据用户的选择：

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

完成后的扩展

自动同步：执行 /workflow:session:sync -y "{summary}"，更新 specs/*.md + project-tech。

完成后询问用户是否要扩展为 issue（test/enhance/refactor/doc），对选中的项调用 /issue:new "{summary} - {dimension}"

执行策略（由 IMPL_PLAN 驱动）

策略优先级

由 IMPL_PLAN 驱动执行（推荐）：

1. 阅读 IMPL_PLAN.md 中的执行策略（第 4 节：实施策略）
2. 遵循明确的指导：
   • 执行模型（顺序／并行／分阶段／TDD）
   • 并行化机会（哪些任务可以并行执行）
   • 串行化要求（哪些任务必须按顺序执行）
   • 关键路径（优先执行顺序）
3. 仅使用 TODO_LIST.md 跟踪状态
4. IMPL_PLAN 决定“如何”执行，workflow-execute 负责实施

智能回退（当 IMPL_PLAN 缺少执行细节时）：

1. 分析任务结构：
   • 检查任务 JSON 中的 meta.execution_group
   • 分析 depends_on 关系
   • 了解任务的复杂度和风险
2. 应用智能默认规则：
   • 没有依赖项且属于同一 execution_group → 并行执行
   • 存在依赖项 → 顺序执行（等待依赖项完成）
   • 关键／高风险任务 → 顺序执行
3. 采取保守做法：不确定时，优先选择顺序执行

执行模型

1. 顺序执行

适用情况：IMPL_PLAN 指定“顺序执行”，或没有明确的并行化指导 模式：按照 TODO_LIST 中的顺序逐一执行任务 TodoWrite：每次仅将一个任务标记为 in_progress

2. 并行执行

适用情况：IMPL_PLAN 指定“并行执行”，并明确指出并行化机会 模式：通过启动多个 Agent 实例，并发执行相互独立的任务组 TodoWrite：同时将当前批次中的多个任务标记为 in_progress Agent 实例化：每个任务启动一个 Agent 实例（遵循“一个 Agent = 一个任务 JSON”的规则）

3. 分阶段执行

适用情况：IMPL_PLAN 指定“分阶段执行”，并提供阶段划分 模式：分阶段执行任务，遵守阶段边界 TodoWrite：在每个阶段内，遵循顺序执行或并行执行规则

4. 智能回退

适用情况：IMPL_PLAN 缺少执行策略细节 模式：分析任务结构并应用智能默认规则 TodoWrite：根据分析结果遵循顺序执行或并行执行规则

任务状态逻辑

pending + dependencies_met → executable
completed → skip
blocked → skip until dependencies clear

TodoWrite 协调

TodoWrite 规则（统一）

规则 1：初始创建

• 普通模式：根据发现的待处理任务，为整个工作流生成 TodoWrite
• 恢复模式：根据现有会话状态和当前进度生成 TodoWrite

规则 2：进行中任务数（取决于执行模型）

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

规则 3：状态更新

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

规则 4：工作流完成检查

• 所有任务均标记为 completed 后，提示用户选择进行审查或结束会话

TodoWrite 工具用法

示例 1：顺序执行

TodoWrite({
  todos: [
    {
      content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
      status: "in_progress",  // ONE task in progress
      activeForm: "Executing IMPL-1.1: Design auth schema"
    },
    {
      content: "Execute IMPL-1.2: Implement auth logic [code-developer] [FLOW_CONTROL]",
      status: "pending",
      activeForm: "Executing IMPL-1.2: Implement auth logic"
    }
  ]
});

示例 2：并行批次执行

TodoWrite({
  todos: [
    {
      content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
      status: "in_progress",  // Batch task 1
      activeForm: "Executing IMPL-1.1: Build Auth API"
    },
    {
      content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
      status: "in_progress",  // Batch task 2 (running concurrently)
      activeForm: "Executing IMPL-1.2: Build User UI"
    },
    {
      content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
      status: "in_progress",  // Batch task 3 (running concurrently)
      activeForm: "Executing IMPL-1.3: Setup Database"
    },
    {
      content: "Execute IMPL-2.1: Integration Tests [test-fix-agent] [depends_on: IMPL-1.1, IMPL-1.2, IMPL-1.3]",
      status: "pending",  // Next batch (waits for current batch completion)
      activeForm: "Executing IMPL-2.1: Integration Tests"
    }
  ]
});

Agent 执行模式

流程控制执行

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

注意：编排器不会执行流程控制步骤；Agent 会自行解读并执行这些步骤。

Agent 提示词模板

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

Agent(subagent_type="{meta.agent}",
     run_in_background=false,
     prompt="Implement task {task.id}: {task.title}

     [FLOW_CONTROL]

     **Input**:
     - Task JSON: {session.task_json_path}
     - Context Package: {session.context_package_path}

     **Output Location**:
     - Workflow: {session.workflow_dir}
     - TODO List: {session.todo_list_path}
     - Summaries: {session.summaries_dir}

     **Execution**: Read task JSON → Execute pre_analysis → Check execution_config.method → (CLI: handoff to CLI tool | Agent: direct implementation) → Update TODO_LIST.md → Generate summary",
     description="Implement: {task.id}")

关键标记：

• Implement 关键词：触发技术栈检测并加载指南
• [FLOW_CONTROL]：触发执行 pre_analysis

为何基于路径：Agent（code-developer.md）会自主：

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

在提示词中嵌入任务内容会造成重复，并与 Agent 的解析逻辑冲突。

Agent 分配规则

meta.agent specified → Use specified agent
meta.agent missing → Infer from 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     # Session state and metadata
├── plan.json                # Structured plan overview (machine-readable)
├── IMPL_PLAN.md             # Planning document and requirements (human-readable)
├── TODO_LIST.md             # Progress tracking (updated by agents)
├── .task/                   # Task definitions (JSON only)
│   ├── IMPL-1.json          # Main task definitions
│   └── IMPL-1.1.json        # Subtask definitions
├── .summaries/              # Task completion summaries
│   ├── IMPL-1-summary.md    # Task completion details
│   └── IMPL-1.1-summary.md  # Subtask completion details
└── .process/                # Planning artifacts
    ├── context-package.json # Smart context package
    └── ANALYSIS_RESULTS.md  # Planning analysis results

错误处理与恢复

常见错误与恢复

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

错误预防

• 预检查：执行前验证会话完整性
• 备份策略：在重大操作前创建任务快照
• 原子更新：原子化更新 JSON 文件以防止损坏
• 依赖项验证：检查所有 depends_on 引用是否存在
• 上下文验证：确保所有必需的上下文均可用

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

行为：每个 Agent 任务完成后，根据摘要文档自动提交更改。

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

提交消息格式：{type}: {task-title} - {summary}

类型映射（来自 meta.type）：

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

实现：

# 1. Read summary from .summaries/{task-id}-summary.md
# 2. Extract files from "Files Modified" section
# 3. Commit: git add <files> && git commit -m "{type}: {title} - {summary}"

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

相关技能

前置技能：

• workflow-plan 技能 - 生成实施计划和任务 JSON

执行期间调用：

• /workflow:session:complete - 所有任务完成后归档会话
• review-cycle 技能 - 实施后审查

后续技能：

• /issue:new - 创建后续问题（测试／增强／重构／文档）