| name | ccb-execute |
| description | Execute CCB implementation, explore, or consult tasks from Claude based on spec/docs, validate the result, and return a compact receipt. Use when Claude sends a CCB task with execute/explore/consult mode.
|
| metadata | {"short-description":"CCB 执行、协商与回执"} |
CCB 执行
触发条件
- Claude 通过 ask 派发了实施任务、勘探任务或协商请求。
- 当前任务已有 spec 或明确的文档路径。
- 需要按 CCB 回执合同或协商契约返回结果。
输入
- Claude 提供的 ask 指令（含 mode 标记）。
docs/.ccb/specs/active/*.md。- 按需读取的架构、需求、计划、模块与经验文档。
- 当前项目代码与配置。
同组对端路由
当 Codex 侧需要判断 CCB consult / dispatch 的默认对端，必须读取项目内同一份 kernel 约定：
references/kernel/agent-routing-contract.md
可调用本 skill 自带脚本解析当前项目拓扑：
node <ccb-execute-skill-dir>/scripts/resolve-same-group-peer.mjs \
--project-root "$PWD" \
--current-agent "$CCB_CALLER_ACTOR" \
--pretty
脚本读取 <project>/.ccb/ccb.config 的 [windows]，按“当前 agent → 同 window → 唯一互补 provider”返回 JSON：
{"kind":"peer","peer":"...","window":"..."}：可作为默认同组对端。{"kind":"ambiguous",...} / {"kind":"no_peer",...}：必须要求显式 target，不得猜 main_codex 或按 slot 字符串推断。
测试向量见 references/agent-routing-test-vectors.json，与 Claude plugin PR1 resolver 行为对齐。若项目缺少 agent-routing-contract.md，视为契约不可确认，要求显式 target。
per-需求 worktree 执行纪律
当 dev_task frontmatter 含 code_workspace 时，ccb-execute 只消费 plugin dispatch 已建好的 worktree，绝不执行 git worktree add/remove 或自行创建目录。实施前必须 fail-fast 校验：
node <ccb-execute-skill-dir>/scripts/ccb-execute-worktree.mjs validate-worktree \
--project-root "$PWD" \
--spec "<dev_task.md>" \
--pretty
校验读取 code_workspace.path / code_workspace.branch，计算主空间 codeRoot = resolve(canonicalRoot, path)，并确认 codeRoot 已存在且当前分支等于声明分支。字段缺失、path 不存在、branch 不匹配时，停止实施并回执拒绝原因；不要让 Codex 自己 ensure。
dispatch brief 若附运行态空间表，必须同时消费该表。canonicalRoot 是主仓，专用于读取人读 docs 和经 plugin lib 写 docs/.ccb；主空间的 codeRoot = resolve(canonicalRoot, code_workspace.path)，专用于代码改动、git、测试和构建。若该需求声明多个实施空间，按 brief 空间表分别使用各空间自己的 codeRoot；字段缺失、路径不存在或分支不匹配时拒绝实施。
路径纪律：
canonicalRoot 是 ccb 启动 cwd / 主仓，只用于读取 spec、人读 docs，以及以绝对路径读写 docs/.ccb 真相。codeRoot 是 worktree；所有代码编辑、构建、lint、test 命令都必须以对应空间的 cwd=codeRoot 执行。- git 命令必须写成
git -C "$codeRoot" ...，不得在主仓 cwd 下只传代码文件绝对路径。
- 多空间任务的路径纪律、验证和 auto-commit 按空间分别生效；跨空间改动不得混在同一个 git 工作区提交。
- 不得把 canonical
docs/.ccb 写入 worktree；commit 前必须运行 commit-guard。
- 不得手工 bump root 的 submodule gitlink；空间间版本关联由 worktree association executor 统一同步和 verify。
子任务级验证与 auto-commit：
node <ccb-execute-skill-dir>/scripts/ccb-execute-worktree.mjs commit \
--project-root "$PWD" \
--spec "<dev_task.md>" \
--pretty
该脚本会解析 spec 中 ## 验证（兼容 ### 验证）下第一个 fenced block 的逐行命令，并在 codeRoot 中运行。所有命令 exit 0 时 commit 标记为 verified；无验证块时仍可 commit，但标记为 unverified，回执必须显式说明“未独立验证”，review/archive 不得等价为已验证。验证失败时脚本返回 validation_failed 且不 commit。
commit-guard 也可单独运行：
node <ccb-execute-skill-dir>/scripts/ccb-execute-worktree.mjs guard-docs-ccb \
--code-root "$codeRoot" \
--pretty
guard 使用 git status --porcelain=v1 --untracked-files=all -- docs/.ccb 检查 staged、unstaged、untracked 三态；任一 docs/.ccb 改动都会拒绝 commit。执行回执必须带 auto-commit 结果：验证命令列表、每条 exit code、verified|unverified|validation_failed、commit sha 或拒绝原因。
三模式行为
mode: execute（执行模式，默认）
- 先读 spec，再读相关文档，再看现有实现，最后判断边界。
- 默认采用半开放实施模式，对实现负责，但不擅自更改高影响决策。
- 做最小充分改动，允许局部整理与有限重构。
- 验证是交付的一部分，明确跑了什么、结果如何、哪些未覆盖。
- 按
receipt-contract 生成精简回执。
mode: explore（勘探模式）
- 不写代码，返回现状、风险、建议切分与待拍板问题。
- 如遇高影响决策、任务模糊、范围扩大、设计冲突等情况，立即回抛给 Claude。
mode: consult（协商模式，v0.2 新增）
- 只读/分析/推理，不修改任何文件。
- 读取 Claude 指定的代码和文档，分析现状。
- 遵循 evidence-before-conclusion：先列 findings，再给 recommendation。
- 按
consult-contract 格式回复，包含 analysis_depth_hint / hint_reason / hint_confidence。
- 详见
references/consult-contract.md。
Superpowers 协调
不同模式下 Superpowers 的适用边界不同：
| Superpowers Skill | 执行模式 | 协商模式 |
|---|
executing-plans | ✅ 适用 | ❌ 不适用 |
systematic-debugging | ✅ 适用 | ⚠️ 仅故障分析咨询 |
verification-before-completion | ✅ 适用 | ❌ 不适用（替代为 evidence-before-conclusion） |
receiving-code-review | ✅ 返工时 | ❌ 不适用 |
详见 references/superpowers-integration.md。
输出格式
执行/勘探模式
- 结果摘要。
- 修改文件或勘探输出。
- 验证结果。
- 风险点。
- 建议补文档项。
协商模式
- mode / status / understanding / findings / options / recommendation / rationale / risks / assumptions / open_questions / analysis_depth_hint / hint_reason / hint_confidence
停止条件
- 执行/勘探：目标已完成 + 已验证 + 已输出回执。
- 协商：已按 consult-contract 格式回复。
升级条件（回抛给 Claude）
- 需求不清楚，无法确定正确做法。
- 现有设计与代码冲突，无法判断以哪个为准。
- 外部契约、数据结构、跨模块依赖、状态流或事务流需要变化。
- 改动范围明显扩大，或继续实施会引入更大风险。
- 协商模式下：
status=blocked 或 status=insufficient-context。
