spec-execute

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

spec-execute（I2：执行 / plan.md SSOT）

spec-execute (I2: Execution / plan.md SSOT)

概览

Overview

I2 的目标是把

{FEATURE_DIR}/implementation/plan.md

中的任务按批次执行，并把执行状态与最小审计信息只回写到
plan.md
（作为唯一执行清单与状态 SSOT）。

本技能是

skills/executing-plans/SKILL.md

的 Spec 实现阶段版：重度复用其“五步执行 + 批次检查点 + 遇阻塞即停”骨架，但将“计划文件”的语义替换为实现阶段 SOP（见

design/aisdlc_spec_implementation.md

）的硬约束：

```
plan.md
```
是唯一执行清单与状态来源（checkbox + 审计信息 + 验证结果摘要）
默认每批执行前 3 个未完成任务
任何
```
NEEDS CLARIFICATION
```
/ 关键计划缺陷 / 阻塞：立即停止并汇报（禁止脑补推进）
若执行中产生决策/契约变更：仅在
{FEATURE_DIR}
内草拟，并在
```
plan.md
```
追加 Merge-back 待办清单（本阶段禁止直接更新
```
project/*
```
）

开始时宣布：「我正在使用 spec-execute 技能按 plan.md 分批执行并回写 SSOT。」

The goal of I2 is to execute tasks in
{FEATURE_DIR}/implementation/plan.md
in batches, and only write back execution status and minimal audit information to
plan.md
(as the only execution list and status SSOT).

This skill is the Spec implementation phase version of

skills/executing-plans/SKILL.md

: heavily reuse its "five-step execution + batch checkpoint + stop on block" framework, but replace the semantics of "plan file" with the hard constraints of the implementation phase SOP (see

design/aisdlc_spec_implementation.md

```
plan.md
```
is the only source of execution list and status (checkbox + audit information + verification result summary)
By default, execute the first 3 unfinished tasks per batch
Any
```
NEEDS CLARIFICATION
```
/ critical plan defect / block: stop and report immediately (no guesswork allowed to proceed)
If decision/contract changes occur during execution: draft only within
{FEATURE_DIR}
, and append a Merge-back to-do list to
```
plan.md
```
(direct update of
```
project/*
```
is prohibited in this phase)

Announce at startup: "I am using the spec-execute skill to execute in batches according to plan.md and write back to SSOT."

何时使用 / 不使用

When to use / not to use

使用时机
- 已有
```
{FEATURE_DIR}/implementation/plan.md
```
  （I1 已完成），现在进入 I2 按任务实现。
- 你需要在执行中严格做“批次检查点汇报”，并把状态/审计回写到
```
plan.md
```
  。
不要用在
- ```
spec-context
```
  失败、拿不到
```
FEATURE_DIR
```
  （此时必须停止）。
- ```
plan.md
```
  不存在，或缺少可执行的任务清单（此时回到 I1：
```
spec-plan
```
  ）。
- ```
plan.md
```
  的
```
NEEDS CLARIFICATION
```
  仍未消除、或存在关键缺陷导致无法开始（此时必须先停止并提出澄清/修计划）。

Use case
- ```
{FEATURE_DIR}/implementation/plan.md
```
  already exists (I1 is completed), now enter I2 to implement according to tasks.
- You need to strictly perform "batch checkpoint reporting" during execution, and write back status/audit information to
```
plan.md
```
  .
Do not use
- ```
spec-context
```
  failed,
```
FEATURE_DIR
```
  cannot be obtained (must stop at this time).
- ```
plan.md
```
  does not exist, or lacks an executable task list (return to I1:
```
spec-plan
```
  at this time).
- The
```
NEEDS CLARIFICATION
```
  in
```
plan.md
```
  has not been eliminated, or there are critical defects that prevent starting (must stop first and request clarification/revise the plan).

门禁 / 停止（严格执行）

Entrance Control / Stop Rules (strictly enforced)

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

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

未得到
```
FEATURE_DIR
```
当前分支是
```
main/master
```
（或你未得到用户明确同意在主分支实施）
```
{FEATURE_DIR}/implementation/plan.md
```
不存在或不可读
```
plan.md
```
中存在未消除的
```
NEEDS CLARIFICATION
```
，且其会阻断继续执行
计划存在关键缺陷：缺失可执行命令/缺失最小验证/范围不清/依赖不明，导致无法安全开始
执行中遇到阻塞：缺依赖/权限/环境/数据、测试反复失败、某条指令不理解

寻求澄清，而非猜测。

REQUIRED SUB-SKILL: You are executing
spec-context
to get context, and echo
FEATURE_DIR=...
in the conversation (allow
(reuse)
).

Stop immediately (if any of the following is met):

```
FEATURE_DIR
```
is not obtained
Current branch is
```
main/master
```
(or you have not obtained explicit consent from the user to implement on the main branch)
```
{FEATURE_DIR}/implementation/plan.md
```
does not exist or is unreadable
There is unresolved
```
NEEDS CLARIFICATION
```
in
```
plan.md
```
that will block further execution
The plan has critical defects: missing executable commands / missing minimal verification / unclear scope / unknown dependencies, making it impossible to start safely
Block encountered during execution: missing dependencies/permissions/environment/data, repeated test failures, incomprehensible instructions

Seek clarification instead of guessing.

输入 / 输出（落盘约定）

Input / Output (Persistence Convention)

读取（渐进式披露，最少必要）
- ```
{FEATURE_DIR}/implementation/plan.md
```
  （必须；SSOT）
- ```
plan.md
```
  引用到的
```
{FEATURE_DIR}/requirements/*
```
  、
```
{FEATURE_DIR}/design/*
```
  （按需读取，不要全量展开）
- ```
{FEATURE_DIR}/requirements/solution.md#impact-analysis
```
  （按需回查：受影响模块清单、需遵守的不变量、相关 ADR、跨模块影响）
- 项目级索引（只读，按需）：
```
project/memory/*
```
  、
```
project/contracts/
```
  、
```
project/adr/
```
写入（唯一状态来源）
- 只把状态/审计写回
```
{FEATURE_DIR}/implementation/plan.md
```
  ：勾选任务、补齐
```
commit/pr/changed_files
```
  、记录关键验证结果摘要与阻塞取证路径
代码与配置变更
- 按
```
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；同一行多命令请用
;
分隔（不要用
&&
）。

Read (progressive disclosure, minimum necessary)
- ```
{FEATURE_DIR}/implementation/plan.md
```
  (required; SSOT)
- ```
{FEATURE_DIR}/requirements/*
```
  ,
```
{FEATURE_DIR}/design/*
```
  referenced by
```
plan.md
```
  (read on demand, do not expand all)
- ```
{FEATURE_DIR}/requirements/solution.md#impact-analysis
```
  (check back on demand: list of affected modules, invariants to comply with, related ADR, cross-module impact)
- Project-level index (read-only, on demand):
```
project/memory/*
```
  ,
```
project/contracts/
```
  ,
```
project/adr/
```
Write (only status source)
- Only write status/audit information back to
```
{FEATURE_DIR}/implementation/plan.md
```
  : check tasks, fill in
```
commit/pr/changed_files
```
  , record key verification result summary and block evidence path
Code and configuration changes
- Implement according to the path declared for each task in
```
plan.md
```
  (create/modify/test)
Spec internal decision/contract draft (if generated during execution)
- ADR draft: prefer to write to the "Decision/Trade-off" section of
```
{FEATURE_DIR}/design/design.md
```
  ; add
```
{FEATURE_DIR}/design/adr/*.md
```
  if necessary
- Contract draft: write to
```
{FEATURE_DIR}/design/contracts/
```
- Synchronization requirement: append/update "Merge-back to-do list" in
```
plan.md
```
  (only record, do not directly modify
```
project/*
```
  in I2)

Command writing convention: default for PowerShell; separate multiple commands in the same line with
;
(do not use
&&
).

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

Process (reuse the 5-step framework of executing-plans)

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

Step 1: Load and review the plan (Review)

打开并阅读
```
{FEATURE_DIR}/implementation/plan.md
```
严格审查——识别任何会阻断执行的问题或疑虑，例如：
- 任务未写清“改哪些文件/跑什么命令/期望看到什么信号”
- 缺失最小验证方式或验证不可执行
- 任务越界（与 plan.md 的范围 / 里程碑不一致）
- 依赖/权限/环境未满足
- ```
NEEDS CLARIFICATION
```
  未消除
若有关键疑虑：在开始前停止并汇报（把问题写清、给出取证路径；必要时回到 I1 修订 plan.md）
若无疑虑：进入批次执行

Open and read
```
{FEATURE_DIR}/implementation/plan.md
```
Strictly review - identify any problems or doubts that will block execution, such as:
- The task does not clearly state "which files to modify/what commands to run/what signals to expect"
- Missing minimal verification method or verification is not executable
- Task is out of bounds (inconsistent with the scope/milestone of plan.md)
- Dependencies/permissions/environment are not met
- ```
NEEDS CLARIFICATION
```
  is not resolved
If there are critical doubts: stop and report before starting (clarify the problem, provide the evidence path; return to I1 to revise plan.md if necessary)
If there are no doubts: enter batch execution

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

Step 2: Execute batches (Batch execute)

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

对每个任务：

标记为 in_progress
严格按任务步骤执行（不要跳步；不要替换命令；不要暗改验收）
按任务声明运行最小验证，并记录关键输出/信号（PASS/FAIL 的判据）
频繁提交（如果计划要求更细提交点，优先按计划来）
- Commit message 必须中文
回写
```
plan.md
```
（唯一状态来源）：
- ```
- [ ]
```
  →
```
- [x]
```
- 补齐
```
commit/pr/changed_files
```
- 记录该任务的关键验证结果摘要（含命令与关键信号）
- 若阻塞：写清“缺什么、如何补齐、向谁/从哪取证”，并停止进入下一任务
标记为 completed（或 blocked）

Default: the first 3 unfinished tasks (can be adjusted according to risk and dependencies, but the reason must be explained).

For each task:

Mark as in_progress
Execute strictly according to task steps (do not skip steps; do not replace commands; do not secretly change acceptance criteria)
Run minimal verification as stated in the task, and record key output/signals (PASS/FAIL criteria)
Commit frequently (if the plan requires more granular commit points, follow the plan first)
- Commit message must be in Chinese
Write back to
```
plan.md
```
(only status source):
- ```
- [ ]
```
  →
```
- [x]
```
- Fill in
```
commit/pr/changed_files
```
- Record the key verification result summary of the task (including commands and key signals)
- If blocked: clearly write "what is missing, how to supplement, who to ask/where to get evidence", and stop entering the next task
Mark as completed (or blocked)

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

Step 3: Batch checkpoint report (Report checkpoint)

批次完成时必须汇报：

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

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

You must report when the batch is completed:

List of completed tasks (corresponding Task ID)
Verification result summary (key commands + key output/signals)
Location of written back content in
```
plan.md
```
and audit information (commit/pr/changed_files)
Overview of unfinished tasks
List of blocked items (if any)

Then say: "Ready for feedback." and wait for feedback before continuing to the next batch.

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

Step 4: Continue / Return to review (Continue / Re-review)

根据反馈：

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

According to feedback:

If the plan is updated or new critical doubts arise: return to Step 1 to re-review
Otherwise: execute the next batch and repeat steps 2–3 until the task list is processed

步骤 5：完成开发（Finish）

Step 5: Complete development (Finish)

当

plan.md

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

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

When all planned tasks in

plan.md

are completed and minimal verification passes:

This skill does not directly decide the "next step". Please immediately call
```
using-aisdlc
```
to route to Finish:
```
finishing-development
```
(only verify, ensure all tests/checks are green).
Before entering Finish, ensure that the audit information in
```
plan.md
```
is complete and traceable (at least include
```
commit
```
and key verification result summary; fill in
```
pr
```
if there is a PR)

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

When to stop and ask for help (Stop on block)

立即停止执行：

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

寻求澄清，而非猜测。

Stop execution immediately:

Block encountered in the batch (missing dependencies/permissions/environment/data)
Tests or verification fail repeatedly (cannot be located or fixed with current evidence)
Do not understand a certain instruction or acceptance standard
Found critical defects in
```
plan.md
```
(cannot continue to execute safely)
Found/added
```
NEEDS CLARIFICATION
```
that will affect correctness or scope

Seek clarification instead of guessing.

何时返回 earlier 步骤

When to return to earlier steps

返回审查（步骤 1）时：

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

When returning to review (Step 1):

The collaborator updated
```
plan.md
```
based on your feedback
You need to adjust the task order/split to continue (must first clarify in
```
plan.md
```
before executing)
The fundamental solution needs to be reconsidered (stop first, then revise the plan/supplement evidence)

牢记

Remember

始终先执行
```
spec-context
```
获取上下文，拿到
```
FEATURE_DIR=...
```
，失败就停止
```
plan.md
```
是唯一执行清单与状态 SSOT：不要另起“状态来源”
严格按
```
plan.md
```
步骤执行；不要跳过验证
默认每批前 3 个未完成任务；批次之间只汇报并等待
遇到阻塞/澄清项立刻停止，不要猜测推进
执行中产生 ADR/契约：只在
```
{FEATURE_DIR}
```
内落盘草案，并在
```
plan.md
```
记录 Merge-back 待办（I2 不直接改
```
project/*
```
）

Always execute
```
spec-context
```
first to get context, get
```
FEATURE_DIR=...
```
, stop if failed
```
plan.md
```
is the only execution list and status SSOT: do not create another "status source"
Execute strictly according to the steps in
```
plan.md
```
; do not skip verification
Default to the first 3 unfinished tasks per batch; only report and wait between batches
Stop immediately when encountering blocking/clarification items, do not proceed with guesswork
ADR/contract generated during execution: only persist drafts within
```
{FEATURE_DIR}
```
, and record Merge-back to-do items in
```
plan.md
```
(do not directly modify
```
project/*
```
in I2)

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

Output after completion and automatic routing (must be executed)

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

输出 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"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "示例：批次检查点已汇报，等待反馈后继续下一批"

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

At any of the following moments (batch checkpoint report completed / stopped due to block / all tasks completed and ready to enter Finish), must complete the following actions (in order, cannot be omitted):

Output ROUTER_SUMMARY (YAML format, for Router decision; fill in according to current status, do not always write the same fixed value):

Filling rules:

Batch checkpoint (waiting for feedback):
```
needs_human_review=true
```
,
```
blocked=false
```

Stopped due to block:

needs_human_review=true

blocked=true

, and clearly write

block_reason

All tasks completed, ready to enter Finish:
```
needs_human_review=false
```
,
```
blocked=false
```

yaml

ROUTER_SUMMARY:
  stage: I2
  artifacts:
    - "{FEATURE_DIR}/implementation/plan.md"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "Example: Batch checkpoint has been reported, wait for feedback before continuing to the next batch"

Immediately execute
using-aisdlc
: Pass the above
```
ROUTER_SUMMARY
```
as routing input to using-aisdlc, and the Router will determine the next step and automatically proceed (no need to wait for the user to say "continue").
- If the Router determines that it can automatically resume running: continue to execute the next worker skill in the same round of conversation (such as next batch of I2, Finish, etc.)
- If the Router triggers a hard interrupt: stop and output the blocking reason, required input, candidate next steps
Conversation output: Before calling using-aisdlc, you can briefly state "The products of this phase have been persisted, calling using-aisdlc to route the next step."

集成

Integration

上游 / 下游技能：

spec-plan

- 生成

{FEATURE_DIR}/implementation/plan.md

（SSOT）

```
finishing-development
```
- 所有任务完成后做开发收尾确认

Upstream / Downstream Skills:

spec-plan

- Generate

{FEATURE_DIR}/implementation/plan.md

(SSOT)

```
finishing-development
```
- Perform development final confirmation after all tasks are completed