# Spec Execute

> Use when 需要在 dlc-dev 的 Spec Pack 中执行 I2（实现执行），以 `{FEATURE_DIR}/implementation/plan.md` 为 Spec 级编排 SSOT；若存在 Task Pack（`implementation/tasks/*` 或 spec-context 的 TASK_PACK_DIR），将步骤与高频状态下沉到各包 `task.md`/`status.yaml`，任务完成时回写 plan 勾选；分批执行、最小验证、遇阻塞即停。

- Skill: `zixun-github/spec-execute` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zixun-github/spec-execute`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zixun-github/spec-execute/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zixun-github (https://skillmd.com/u/zixun-github)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zixun-github/spec-execute

---


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

## 概览

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

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

- **`plan.md`（必做）**：Spec 级编排 SSOT — 范围、依赖、子仓、NEEDS CLARIFICATION、任务清单与**任务级**完成勾选、Merge-back 待办等。
- **Task Pack 模式（可选）**：若 `spec-context` 给出 `TASK_WORK_BRANCH=true` 且 `TASK_PACK_DIR` 非空，或 `{FEATURE_DIR}/implementation/tasks/` 下存在带 `task.md`/`status.yaml` 的子目录，则：
  - **当前任务的可执行步骤**优先以对应 `{TASK_PACK_DIR}/task.md`（或 `implementation/tasks/<TASK_DIR>/task.md`）为准；
  - **高频状态**（活动阶段、路由状态、验证摘要、`updated_at` 等）回写到该目录的 **`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` 未将其声明为已批准的例外
- 执行中遇到阻塞：缺依赖/权限/环境/数据、测试反复失败、某条指令不理解

**寻求澄清，而非猜测。**

## 输入 / 输出（落盘约定）

- **读取（渐进式披露，最少必要）**
  - `{FEATURE_DIR}/implementation/plan.md`（必须；Spec 级 SSOT）
  - **Task Pack 模式**：`spec-context` 输出的 `TASK_PACK_DIR` 下 `task.md`、`status.yaml`（若当前在任务分支）；或对批次内每一任务读取 `implementation/tasks/<TASK_DIR>/task.md`（若存在）
  - `plan.md` 引用到的 `{FEATURE_DIR}/requirements/*`、`{FEATURE_DIR}/design/*`（按需读取，不要全量展开）
  - `{FEATURE_DIR}/requirements/solution.md#impact-analysis`（按需回查：受影响模块清单、需遵守的不变量、相关 ADR、跨模块影响）
  - 项目级索引（只读，按需）：`project/memory/*`、`project/contracts/`、`project/adr/`（若 `.aidlc/project/` 不存在或文件缺失，标注 `CONTEXT GAP` 但不阻断 I2）
  - `.gitmodules`（如存在；用于识别计划中声明的子仓路径是否真实存在）
  - `spec-context` 返回的 `SUBMODULE_SET_JSON`（如存在；用于校验分支一致性、detached HEAD、脏工作区）
- **写入**
  - **必写**：`{FEATURE_DIR}/implementation/plan.md` — 任务级 `- [x]`、摘要审计、阻塞与 Merge-back 待办
  - **Task Pack 模式另写**：对应 `implementation/tasks/<TASK_DIR>/status.yaml`（及按需 `review.md`）— 高频状态、验证字段、`activity_stage`/`routing_status`（词汇见 `spec-plan/assets/collaboration_stages_and_states.md`）
  - **仅 plan 模式**：全部状态与步骤回写仍在 `plan.md`
- **代码与配置变更**
  - 按 `plan.md` 每任务声明的路径实现（创建/修改/测试）
- **Spec 内决策/契约草案（如执行中产生）**
  - ADR 草案：优先写到 `{FEATURE_DIR}/design/design.md` 的“决策/权衡”段；必要时新增 `{FEATURE_DIR}/design/adr/*.md`
  - 契约草案：写到 `{FEATURE_DIR}/design/contracts/`
  - 同步要求：在 `plan.md` 追加/更新 “Merge-back 待办清单”（仅记录，不在 I2 直接改 `project/*`）

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

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

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

1. 打开并阅读 `{FEATURE_DIR}/implementation/plan.md`
2. 严格审查——识别任何会阻断执行的问题或疑虑，例如：
   - 任务未写清“改哪些文件/跑什么命令/期望看到什么信号”
   - 缺失最小验证方式或验证不可执行
   - 任务越界（与 plan.md 的范围 / 里程碑不一致）
   - 依赖/权限/环境未满足
   - `NEEDS CLARIFICATION` 未消除
   - `plan.md` 已声明受影响子仓，但未写清 `required`、同名分支要求或 `exception_reason`
   - `.gitmodules` / `SUBMODULE_SET_JSON` 表明某个 `required` 子仓未切到与根项目同名的 Spec 分支，或处于 detached HEAD / 脏工作区
3. 若有关键疑虑：**在开始前停止并汇报**（把问题写清、给出取证路径；必要时回到 I1 修订 plan.md）
4. 若无疑虑：进入批次执行

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

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

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

对每个任务：

1. 标记为 in_progress（`plan.md` 与/或 `status.yaml`）
2. **严格按任务步骤执行**（来源：`task.md` 与 `plan.md` 合并后的唯一解释；不要跳步；不要替换命令；不要暗改验收）
3. 按任务声明运行最小验证，并记录关键输出/信号（PASS/FAIL 的判据）
4. **频繁提交（受 AUTO_COMMIT 控制）**
   - `AUTO_COMMIT=true`（默认）：按计划要求的提交点执行 `git add` + `git commit`（如果计划要求更细提交点，优先按计划来）；Commit message **必须中文**
   - `AUTO_COMMIT=false`：跳过 `git add` + `git commit`，在 `plan.md` 审计信息中 commit 字段标记为"手动提交"，并输出"以下文件已变更，请手动提交："及变更文件清单
5. 回写状态：
   - **Task Pack 模式**：先更新 `status.yaml`（`verification`、`updated_at`、路由/活动阶段）；任务完成时 `plan.md` 该项 `- [ ]` → `- [x]` 并写**摘要**审计（`branch/commit/pr/changed_files` 可详列在 `task.md` 或 `status.yaml` 已有字段中，避免重复粘贴大段到 `plan.md`）
   - **仅 plan 模式**：仍在 `plan.md` 完成勾选与完整审计块
   - 若阻塞：在 `plan.md` 与/或 `status.yaml`/`task.md` 写清取证路径，并停止进入下一任务
6. 标记为 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` 获取上下文，拿到 `FEATURE_DIR=...`（及 `TASK_PACK_DIR`/`TASK_WORK_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），**必须**完成以下动作（按顺序，不可省略）：

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

**填写规则：**

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

```yaml
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: "示例：批次检查点已汇报，等待反馈后继续下一批"
```

2. **立即执行 `using-aidlc`**：将上述 `ROUTER_SUMMARY` 作为路由输入传递给 using-aidlc，由 Router 判定下一步并**自动推进**（无需等待用户说「继续」）。  
   - 若 Router 判定可自动续跑：在同一轮对话内继续执行下一步 worker skill（如下一批 I2、Finish 等）
   - 若 Router 触发硬中断：停下并输出阻断原因、需要的输入、候选下一步

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

## 集成

**上游 / 下游技能：**

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