spec-execute（I2：执行 / plan.md + 可选 Task Pack）

概览

I2 的目标是把 {FEATUREDIR}/implementation/plan.md 中的任务按批次执行，运行最小验证，并按模式回写状态（见 design/aidlcspecimplementation.md、design/aidlccollaboration.md §3、design/aidlctoolingtaskpack_skills.md）。

本技能是 skills/executing-plans/SKILL.md 的 Spec 实现阶段版：重度复用其“五步执行 + 批次检查点 + 遇阻塞即停”骨架，但将“计划文件”的语义对齐为：

plan.md（必做）：Spec 级编排 SSOT — 范围、依赖、子仓、NEEDS CLARIFICATION、任务清单与任务级完成勾选、Merge-back 待办等。
Task Pack 模式（可选）：若 spec-context 给出 TASKWORKBRANCH=true 且 TASKPACKDIR 非空，或 {FEATURE_DIR}/implementation/tasks/ 下存在带 task.md/status.yaml 的子目录，则：

- 当前任务的可执行步骤优先以对应 {TASKPACKDIR}/task.md（或 implementation/tasks/<TASKDIR>/task.md）为准； - 高频状态（活动阶段、路由状态、验证摘要、updatedat 等）回写到该目录的 status.yaml； - 任务完成时仍须在 plan.md 将对应 Task 标为 - [x] 并补摘要级审计（避免多人争改 plan.md 全文）。

仅 plan 模式（无 Task Pack）：与历史一致 — 步骤与状态只在 plan.md。
默认每批执行前 3 个未完成任务
任何 NEEDS CLARIFICATION / 关键计划缺陷 / 阻塞：立即停止并汇报（禁止脑补推进）
若执行中产生决策/契约变更：仅在 {FEATURE_DIR} 内草拟，并在 plan.md 追加 Merge-back 待办清单（本阶段禁止直接更新 project/*）
若仓库存在 .gitmodules：执行前必须根据 plan.md 校验受影响且 required 的子仓是否已切到与根项目同名的 Spec 分支

开始时宣布：「我正在使用 spec-execute 技能按 plan.md（及 Task Pack，若存在）分批执行并回写 SSOT。」

何时使用 / 不使用

使用时机

- 已有 {FEATURE_DIR}/implementation/plan.md（I1 已完成），现在进入 I2 按任务实现。 - 你需要在执行中严格做“批次检查点汇报”，并把状态/审计回写到 plan.md 与/或 Task Pack status.yaml（按是否存在 Task Pack）。

不要用在

- spec-context 失败、拿不到 FEATURE_DIR（此时必须停止）。 - plan.md 不存在，或缺少可执行的任务清单（此时回到 I1：spec-plan）。 - plan.md 的 NEEDS CLARIFICATION 仍未消除、或存在关键缺陷导致无法开始（此时必须先停止并提出澄清/修计划）。

门禁 / 停止（严格执行）

REQUIRED SUB-SKILL：正在执行 spec-context 获取上下文，并在对话中回显 FEATURE_DIR=...（允许 (reuse)）。

立刻停止（满足其一即可）：

未得到 FEATURE_DIR
当前分支是 main/master（或你未得到用户明确同意在主分支实施）
{FEATURE_DIR}/implementation/plan.md 不存在或不可读
plan.md 中存在未消除的 NEEDS CLARIFICATION，且其会阻断继续执行
计划存在关键缺陷：缺失可执行命令/缺失最小验证/范围不清/依赖不明，导致无法安全开始
plan.md 标记为 required 的子仓未创建与根项目同名的 Spec 分支，或存在未声明的分支例外
子仓处于 detached HEAD，且 plan.md 未将其声明为已批准的例外
执行中遇到阻塞：缺依赖/权限/环境/数据、测试反复失败、某条指令不理解

寻求澄清，而非猜测。

输入 / 输出（落盘约定）

读取（渐进式披露，最少必要）

- {FEATUREDIR}/implementation/plan.md（必须；Spec 级 SSOT） - Task Pack 模式：spec-context 输出的 TASKPACKDIR 下 task.md、status.yaml（若当前在任务分支）；或对批次内每一任务读取 implementation/tasks/<TASKDIR>/task.md（若存在） - plan.md 引用到的 {FEATUREDIR}/requirements/、{FEATUREDIR}/design/（按需读取，不要全量展开） - {FEATUREDIR}/requirements/solution.md#impact-analysis（按需回查：受影响模块清单、需遵守的不变量、相关 ADR、跨模块影响） - 项目级索引（只读，按需）：project/memory/*、project/contracts/、project/adr/（若 .aidlc/project/ 不存在或文件缺失，标注 CONTEXT GAP 但不阻断 I2） - .gitmodules（如存在；用于识别计划中声明的子仓路径是否真实存在） - spec-context 返回的 SUBMODULESET_JSON（如存在；用于校验分支一致性、detached HEAD、脏工作区）

写入

- 必写：{FEATUREDIR}/implementation/plan.md — 任务级 - [x]、摘要审计、阻塞与 Merge-back 待办 - Task Pack 模式另写：对应 implementation/tasks/<TASKDIR>/status.yaml（及按需 review.md）— 高频状态、验证字段、activitystage/routingstatus（词汇见 spec-plan/assets/collaborationstagesand_states.md） - 仅 plan 模式：全部状态与步骤回写仍在 plan.md

代码与配置变更

- 按 plan.md 每任务声明的路径实现（创建/修改/测试）

Spec 内决策/契约草案（如执行中产生）

- ADR 草案：优先写到 {FEATUREDIR}/design/design.md 的“决策/权衡”段；必要时新增 {FEATUREDIR}/design/adr/.md - 契约草案：写到 {FEATURE_DIR}/design/contracts/ - 同步要求：在 plan.md 追加/更新 “Merge-back 待办清单”（仅记录，不在 I2 直接改 project/）

命令书写约定：默认面向 PowerShell；同一行多命令请用 ; 分隔（不要用 &&）。

流程（重用 executing-plans 的五步骨架）

步骤 1：加载并审查计划（Review）

打开并阅读 {FEATURE_DIR}/implementation/plan.md
严格审查——识别任何会阻断执行的问题或疑虑，例如：

- 任务未写清“改哪些文件/跑什么命令/期望看到什么信号” - 缺失最小验证方式或验证不可执行 - 任务越界（与 plan.md 的范围 / 里程碑不一致） - 依赖/权限/环境未满足 - NEEDS CLARIFICATION 未消除 - plan.md 已声明受影响子仓，但未写清 required、同名分支要求或 exceptionreason - .gitmodules / SUBMODULESET_JSON 表明某个 required 子仓未切到与根项目同名的 Spec 分支，或处于 detached HEAD / 脏工作区

若有关键疑虑：在开始前停止并汇报（把问题写清、给出取证路径；必要时回到 I1 修订 plan.md）
若无疑虑：进入批次执行

步骤 2：执行批次（Batch execute）

默认：前 3 个未完成任务（可根据风险与依赖调整，但必须解释原因）。

Task Pack 模式：执行某任务前，若存在其 Task Pack，先打开 task.md 对齐步骤；plan.md 中该任务块可仅为摘要。每步推进时更新 status.yaml（如 activitystage: task-execute / routingstatus: in_dev 等）。

对每个任务：

标记为 in_progress（plan.md 与/或 status.yaml）
严格按任务步骤执行（来源：task.md 与 plan.md 合并后的唯一解释；不要跳步；不要替换命令；不要暗改验收）
按任务声明运行最小验证，并记录关键输出/信号（PASS/FAIL 的判据）
频繁提交（受 AUTO_COMMIT 控制）

- AUTOCOMMIT=true（默认）：按计划要求的提交点执行 git add + git commit（如果计划要求更细提交点，优先按计划来）；Commit message 必须中文 - AUTOCOMMIT=false：跳过 git add + git commit，在 plan.md 审计信息中 commit 字段标记为"手动提交"，并输出"以下文件已变更，请手动提交："及变更文件清单

回写状态：

- Task Pack 模式：先更新 status.yaml（verification、updatedat、路由/活动阶段）；任务完成时 plan.md 该项 - [ ] → - [x] 并写摘要审计（branch/commit/pr/changedfiles 可详列在 task.md 或 status.yaml 已有字段中，避免重复粘贴大段到 plan.md） - 仅 plan 模式：仍在 plan.md 完成勾选与完整审计块 - 若阻塞：在 plan.md 与/或 status.yaml/task.md 写清取证路径，并停止进入下一任务

标记为 completed（或 blocked）

步骤 3：批次检查点报告（Report checkpoint）

批次完成时必须汇报：

已完成任务列表（对应 Task ID）
验证结果摘要（关键命令 + 关键输出/信号）
plan.md 与（若有）status.yaml 已回写的位置与审计/验证摘要
未完成任务概览
阻塞项清单（如有）

然后说：「准备好反馈。」并等待反馈后再继续下一批。

步骤 4：继续 / 回到审查（Continue / Re-review）

根据反馈：

如对计划做了更新或出现新的关键疑虑：返回 步骤 1 重新审查
否则：执行下一批并重复步骤 2–3，直至任务清单处理完毕

步骤 5：完成开发（Finish）

当 plan.md 中计划内任务全部完成且最小验证通过后：

本技能不直接决定“下一步”。请立即调用 using-aidlc 路由到 Finish：finishing-development（仅验证，确保测试/检查全绿）。
进入 Finish 前，确保 plan.md 的审计信息完整可追溯（至少包含 commit 与关键验证结果摘要；若有 PR 则补齐 pr）

何时停止并寻求帮助（Stop on block）

立即停止执行：

批次中遇到阻塞（缺失依赖/权限/环境/数据）
测试或验证反复失败（无法在当前证据下定位或修复）
不理解某条指令或验收口径
发现 plan.md 有关键缺陷（无法继续安全执行）
发现/新增 NEEDS CLARIFICATION 会影响正确性或范围

寻求澄清，而非猜测。

何时返回 earlier 步骤

返回审查（步骤 1）时：

协作方根据你的反馈更新了 plan.md
你需要对任务顺序/拆分做调整才能继续（必须先在 plan.md 明确化，再执行）
根本方案需要重新考虑（先停、再修计划/补证据）

牢记

始终先执行 spec-context 获取上下文，拿到 FEATUREDIR=...（及 TASKPACKDIR/TASKWORK_BRANCH 若存在），失败就停止
Spec 级编排以 plan.md 为准；Task Pack 模式下任务步骤与高频状态以各包 task.md/status.yaml 为准，禁止在无 Task Pack 时虚构 implementation/tasks/ 路径
严格按 plan.md 步骤执行；不要跳过验证
默认每批前 3 个未完成任务；批次之间只汇报并等待
遇到阻塞/澄清项立刻停止，不要猜测推进
执行中产生 ADR/契约：只在 {FEATURE_DIR} 内落盘草案，并在 plan.md 记录 Merge-back 待办（I2 不直接改 project/*）
涉及子仓时，进入 I2 前先校验同名分支；执行后按 repo 回写审计信息，不要把多个仓的结果压成单条 commit/pr/changed_files

完成后输出与自动路由（必须执行）

在以下任一时刻（批次检查点汇报结束 / 因阻塞停止 / 全部任务完成准备进入 Finish），必须完成以下动作（按顺序，不可省略）：

输出 ROUTER_SUMMARY（YAML 形态，供 Router 决策；按当前状态填写，不要总是写死为同一个值）：

填写规则：

批次检查点（等待反馈）：needshumanreview=true，blocked=false
阻塞停止：needshumanreview=true，blocked=true，并写清 block_reason
全部任务完成，准备进入 Finish：needshumanreview=false，blocked=false

ROUTER_SUMMARY:
  stage: I2
  artifacts:
    - "{FEATURE_DIR}/implementation/plan.md"
    # Task Pack 模式下追加，例如：
    # - "{FEATURE_DIR}/implementation/tasks/T1-foo/status.yaml"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "示例：批次检查点已汇报，等待反馈后继续下一批"

立即执行 using-aidlc：将上述 ROUTER_SUMMARY 作为路由输入传递给 using-aidlc，由 Router 判定下一步并自动推进（无需等待用户说「继续」）。

- 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill（如下一批 I2、Finish 等） - 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步

对话输出：在调用 using-aidlc 前，可简短说明「本阶段产物已落盘，正在调用 using-aidlc 路由下一步。」

集成

上游 / 下游技能：

spec-plan - 生成 {FEATURE_DIR}/implementation/plan.md（Spec 级 SSOT；可选 Task Pack 模板/脚本）
finishing-development - 所有任务完成后做开发收尾确认

spec-execute

Installation

Stronger alternatives

Similar popular skills

Also in this package

Agent compatibility

Repository health

Package contents

History

SKILL.md