cx-exec

cx-exec: 自动执行与任务推进

默认像一个稳健主程一样持续推进；带 --all 时，再升级成高自治 agent teams。

强制规则

所有文件读写必须使用绝对路径。 禁止使用 ../ 相对路径操作文件。在 worktree 中工作时，先用 git rev-parse --show-toplevel 获取 worktree 根目录的绝对路径，所有 Read/Write/Edit 操作基于该绝对路径。

违反这条规则的行为：

• ❌ Edit("../../../../.worktrees/xxx/开发文档/CX工作流/状态.json", ...)
• ❌ 使用相对路径操作 worktree 外的文件

正确的行为：

• ✅ PROJECT_ROOT=$(git rev-parse --show-toplevel) 然后 Edit("$PROJECT_ROOT/开发文档/CX工作流/功能/{title}/状态.json", ...)

禁止跳过工作区选择。 执行前先调用 worktree 检测：

check_output=$(bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-worktree.sh check \
  --feature "{feature-slug}" \
  --project-root "$(git rev-parse --show-toplevel)" 2>&1) || true

如果返回 `on_main=true`，禁止在主分支上执行。必须先进入 feature worktree。

如果 in_worktree=false 且不在 main 上（可能在非 feature 分支），用 AskUserQuestion 列出可用 worktree 供选择。

违反这条规则的行为：

• ❌ --all 模式直接在当前分支开干
• ❌ 跳过询问默认选择 inline
• ❌ 在拉起子代理之前没有完成工作区选择

正确的行为：

• ✅ 读取状态 → AskUserQuestion 询问工作区 → 用户回答 → 记录选择 → 然后才开始执行/拉代理

反合理化

借口	现实
"这个改动很小不需要 worktree"	小改动也会污染 main 上下文
"我先在 main 上试试"	试完切 worktree 时上下文丢失更痛苦
"只有一个人用不需要隔离"	你可能同时开多个窗口
"创建 worktree 太慢了"	git worktree add 是毫秒级操作
"我等下再切 worktree"	等下就忘了，直到冲突发生
"这个 feature 很快就做完"	做完了 merge 回来也很快

先阅读：

• ${CLAUDE_PLUGIN_ROOT}/core/workflow/README.md
• ${CLAUDE_PLUGIN_ROOT}/core/workflow/protocols/exec.md

使用方法

/cx:cx-exec
/cx:cx-exec --all
/cx:cx-exec 任务-3

运行原则

• 项目级 开发文档/CX工作流/配置.json 和 feature 级 状态.json 是执行真相
• /cx:cx-exec 默认自动推进，直到完成、阻塞或关键决策点
• /cx:cx-exec --all 才进入高自治团队模式
• GitHub 不参与执行态主控，闭环同步交给 /cx:cx-summary
• Claude Code 在共享 core 中始终注册为 runner cc；如果 feature 当前由 codex 持有，必须先 handoff，不能静默抢占
• 允许在用户明确确认“进入执行阶段”或“继续执行”后，由工作流自动衔接到本 skill

核心步骤

Step 0: 读取当前功能和任务图

• 从 开发文档/CX工作流/配置.json 读取 current_feature 和 worktree_isolation
• 从项目级 开发文档/CX工作流/状态.json 找到对应中文目录
• 从 开发文档/CX工作流/功能/{功能标题}/状态.json 读取 tasks / phases / execution_order

Step 0.3: 工作区选择（每个 feature 首次执行时询问一次）

如果当前 feature 还没有绑定 worktree（状态.json 中 worktree.binding_status 不是 bound）， 必须（MUST） 使用 AskUserQuestion 工具询问用户，禁止用纯文字列选项：

{
  "questions": [
    {
      "question": "功能「{feature_title}」即将开始执行，选择工作区模式？",
      "header": "工作区",
      "multiSelect": false,
      "options": [
        {
          "label": "独立工作区 (Recommended)",
          "description": "在隔离 worktree 中开发，主分支不受影响，完成后合并回来"
        },
        {
          "label": "当前分支直接开始",
          "description": "在当前分支上直接开发，适合小改动或快速修复"
        }
      ]
    }
  ]
}

如果 worktree_isolation=true，"独立工作区" 放首位并标 (Recommended)。 如果 worktree_isolation=false，"当前分支直接开始" 放首位并标 (Recommended)。

用户选择 1（创建独立工作区）：

使用 Claude Code 内置的 EnterWorktree 工具创建隔离工作区：

EnterWorktree(name: "{feature-slug}")

这会：

• 在 <repo>/.claude/worktrees/{feature-slug}/ 创建独立目录
• 自动创建 worktree-{feature-slug} 分支
• 将当前会话切换到新工作区

创建成功后，把 worktree 信息记录到 feature 的 状态.json：

{
  "worktree": {
    "preferred_branch": "worktree-{feature-slug}",
    "preferred_worktree_path": ".claude/worktrees/{feature-slug}",
    "binding_status": "bound",
    "isolation_mode": "worktree"
  }
}

用户选择 2（当前分支直接开始）：

记录用户选择，后续不再询问：

{
  "worktree": {
    "preferred_branch": "{当前分支名}",
    "preferred_worktree_path": "{当前目录}",
    "binding_status": "bound",
    "isolation_mode": "inline"
  }
}

如果 feature 已经绑定了 worktree：

• isolation_mode = "worktree" 且当前不在该 worktree 中：提示用户切换或使用 EnterWorktree 进入
• isolation_mode = "inline"：直接继续
• 不再重复询问

Step 0.5: 校验 worktree 绑定

在 claim 之前做最终校验，确保 runner 当前 checkout 与 feature 绑定一致：

bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-core-worktree.sh \
  --feature {feature-slug} \
  --runner {runner} \
  --session-id {session-id} \
  --branch {branch} \
  --worktree-path {preferred-worktree-path}

• 如果脚本拒绝当前 checkout，先走 handoff 或切换到正确 worktree，不能直接 claim
• 同一 feature 只能在一个 worktree 中持有活跃执行权，除非已经发生 handoff
• claim helper 注册当前 session 时，runner 固定使用 cc

Step 1: 通过 shared dispatch helper 选择可执行任务

先调用共享调度 helper，而不是自己凭感觉决定“做到哪停”：

bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-workflow-exec-dispatch.sh \
  --feature {feature-slug} \
  --runner cc \
  --session-id {session-id} \
  --mode {auto|all}

dispatch helper 会返回统一决策：

• continue：继续当前 in_progress 或下一个 ready task
• ask_parallel：检测到同一 parallel_group 下有 2+ ready task，允许问用户一次是否切到团队模式
• parallel：--all 下直接推进多任务
• blocked：进入阻塞说明或关键决策
• completed：全部完成，进入 /cx:summary

如果没有显式参数：

• 优先继续当前 in_progress 任务
• 没有 in_progress 时，由 dispatch helper 选择下一个 ready 任务
• 完成一个 task 后，重新运行 dispatch helper，直到 blocked / completed / 关键决策点
• 不允许在普通 task 边界自然停下

Step 2: 实现、验证、更新状态

每个任务都走同一闭环：

1. 读取 任务/任务-{n}.md
2. 读取 契约.md，确认本任务引用的 API 路径、数据模型
3. 实现代码
4. 契约一致性校验（MUST）：
   • 后端任务：实际路由是否与契约中的路径一致
   • 前端任务：API 调用路径是否与契约中的路径一致
   • 数据模型：字段名、类型是否与契约一致
   • 如果不一致：先更新契约文件，再继续，不能静默忽略
5. 运行最相关验证
6. 更新 状态.json
7. 提交代码

如果执行失败，优先自救；确实无法继续时，把任务或 feature 标成 blocked。

Step 2.5: 完成后立即重新调度

一个 task 完成并更新共享状态后：

1. 重新运行 ${CLAUDE_PLUGIN_ROOT}/scripts/cx-workflow-exec-dispatch.sh
2. 如果返回 continue，直接接着做下一个 task
3. 如果返回 ask_parallel，可以问用户一次是否切到 --all
4. 如果返回 parallel，进入团队模式
5. 如果返回 blocked 或 completed，再停

Step 3: 结构化阻塞

所有阻塞都要落到状态里，不能只靠自然语言描述。

{
  "status": "blocked",
  "blocked": {
    "reason_type": "needs_decision",
    "message": "需要确认接口返回结构"
  }
}

任务级也允许记录 reason_type，便于 /cx:cx-status 和 hook 恢复。

Step 4: 默认执行模式

普通 /cx:cx-exec 的含义是：

• 自动连续推进可执行任务
• 自己处理普通测试失败和局部冲突
• 不在普通 task 边界或 wave 边界做建议性停顿
• 仅在下面 4 类关键决策点暂停：
  • 多条行为路径且结果差异明显
  • 会改架构、API 契约、数据库结构、状态模型
  • 高风险或不可逆操作
  • 需要用户提供外部信息
• 如果检测到明确的并行机会，可以问用户一次是否升级到 --all；若用户没有明确切换，默认继续串行推进

Step 5: /cx:cx-exec --all

/cx:cx-exec --all 的含义不是简单“全跑完”，而是：

• 进入高自治 agent teams 模式
• 按任务图自适应拆 wave
• 尽可能拉起 3+ 专业代理
• 主代理只负责调度、整合、契约校验和关键决策暂停

团队角色不写死，只按任务图临时组队，例如：

• backend-agent
• frontend-agent
• database-agent
• integration-agent
• review-agent

提交规范

默认每个 task 独立提交，并在 commit message 末尾追加标记：

[cx:<feature-slug>] [task:<n>]

完整示例：

feat(memory): add vector query service [cx:vector-memory] [task:4]
fix(liuyao): guard divine fallback path [cx:liuyao-divine] [task:2]

如果是 fix 路径，则使用：

fix(scope): description [cx-fix:<fix-slug>]

完成条件

当所有任务都完成后：

• feature 状态切到 completed
• 如果 code_review=true，先建议做闭环审查
• 最后再进入 /cx:cx-summary