Agent-Skills.md

Agent Skills: 执行实施计划

>-

UncategorizedID: FlameMida/spec-dev/executing-plans

Repository

FlameMida/spec-dev
FlameMidaLicense: NOASSERTION
12

Install this agent skill to your local

pnpm dlx add-skill https://github.com/FlameMida/spec-dev/tree/HEAD/skills/executing-plans

Skill Files

Browse the full folder contents for executing-plans.

Download Skill

Loading file tree…

skills/executing-plans/SKILL.md

Skill Metadata

Name
executing-plans
Description
>-

Language Protocol / 语言协议: Respond in the user's conversation language — an explicit user instruction (including the platform language setting) takes precedence, then the language of the user's recent messages; default to English when neither indicates a language. All deliverables written to the repo (specs, plans, reports, notes) follow the conversation language at creation; incremental edits keep the artifact's existing language. Fixed-wording prompts in this skill are semantic templates — express their meaning in the conversation language, don't quote them verbatim. 语言协议：以对话语言输出——用户显式指定（含平台 language 设置）优先，其次跟随用户近期消息语言；均无法判定时默认英语。落盘产物以创建时对话语言为准，增量修改保持产物既有语言。本 skill 中的固定话术是语义模板，用对话语言表达其意，不逐字照搬。

执行实施计划

概述

载入计划 → 隔离工作区 → 主线程逐任务执行 → 收尾多维审查 → 合并与总结。

核心范式：主线程干活、子代理不写码——实现代码由主线程编写（保证上下文连续与契约一致），子代理只承担审查、探索与复跑验证等分析性任务，不产出实现代码。

开始时声明：「我正在使用 executing-plans skill 执行实施计划。」

Checklist

必须为以下每一项创建任务（Claude Code 用 TaskCreate，Codex 用 update_plan）：

  1. 载入并批判性审阅计划 — 有疑虑先提出；开工前过执行确认门
  2. 隔离工作区 — 执行计划的任务 0（纪律遵循 using-git-worktrees）
  3. 逐任务执行 — TDD + 每任务提交 + spec 自检，连续执行
  4. 收尾审查 — 多维 fan-out + 对抗复核 + completeness critic；按验收矩阵触发 acceptance-qa
  5. 审查处置与交付对账 — 例外驱动：零发现且全 DELIVERED 静默通过；否则一次性征询修复与裁决
  6. 合并与总结 — 执行计划的最终任务（合并与清理，含 sync_commit 锚定），回写 roadmap 状态（如属），输出总结

阶段 1：载入并批判性审阅计划

  1. 读取计划文件（.spec-dev/YYYY-MM-DD-<feature>/plan/<feature>-plan.md）与同特性目录的 spec/<feature>-design.md；产物仍在历史位置 docs/YYYY-MM-DD-<feature>/ 时，默认先自动迁移到 .spec-dev/ 再执行（有 scripts/spec-dev/migrate-to-spec-dev.mjs 则运行之，否则 git mv 等效迁移并重写文件内路径引用），迁移单独提交
  2. 批判性审阅：步骤有歧义？接口块互相矛盾？与代码库现状不符？——有疑虑先向用户提出，别带着疑虑开工
  3. 执行确认门：向用户呈现执行摘要（计划路径、任务数与分组、将创建的 worktree 分支名）并确认开始——用户本轮已显式指示执行（如"执行这份计划"）或经 writing-plans 交接确认的，视为已确认、不重复问
  4. 把计划任务注册进任务管理（每任务一条，T{n}: 任务名 命名），进入阶段 2

阶段 2：隔离工作区

执行计划的任务 0（建立隔离工作区）——完整纪律遵循 using-git-worktrees skill（已隔离检测、原生工具优先、git 降级、基线测试验证），分支名对齐计划（如 plan/2026-07-03-export-report）。计划缺任务 0（旧版计划）时，直接调用 using-git-worktrees 补齐同等效果。

降级：非 git 仓库、受保护分支未授权、沙箱无写权限 → 原地实施并向用户注明"未隔离"及原因。

阶段 3：逐任务执行

任务 0 已在阶段 2 完成，计划的验收任务（如有）留待阶段 4、最终任务（合并与清理）留待阶段 6——两者都不参与本阶段连续执行；对其余每个任务（任务 1 起），按序：

  1. 标记 in_progress，严格按计划步骤执行——计划已是 bite-sized 步骤，照做；TDD 循环遵循 test-driven-development skill（红→绿→重构，每步运行验证）

  2. commit：任务完成即提交（message 对齐编号：feat(T3): xxx）；非 git 仓库跳过并注明

  3. spec 自检（主线程，不派子代理）：对照本任务在计划中的验收标准重读本任务 diff，只查两件收尾审查不覆盖的事：

    • over/under-building——写了任务没要求的代码？漏了任务要求的产出？
    • 契约锚定——本任务确立的契约（函数签名/数据结构/API 形态）与计划接口块一致？会不会被后续任务隐式重新解释？

    发现即就地修正并补提交（或 amend）。禁止在此猎 bug、查风格、查规范——那是阶段 4 的活，重复只造噪音与虚假安全感

  4. 勾选计划复选框、标记任务 completed，进入下一任务

连续执行：任务之间不停下来向用户汇报或请示——用户已经确认过计划。仅三种情况停下：无法自行解除的 BLOCKED、真正阻断前进的歧义、全部任务完成。

偏差处理（三档）：

  • 小偏差（路径笔误、步骤缺失但意图明确）→ 就地修正，在最终总结中记录
  • 契约级偏差（接口/数据结构与计划不符且影响后续任务）→ 停下向用户确认修正方向，不猜着改；卡在子问题想不清时可切 exploring skill 想透再回来，洞见按其归位表回填（设计决策→修 spec 并请用户 review、新任务→补进 plan）
  • 意图级偏差（真正要做的已是另一件工作：意图变了、范围爆炸如"修登录 bug"变成"重写认证"、或原计划可独立标记完成而新工作自成一体）→ 停下建议收尾当前计划，新工作另起特性目录走 requirement-analysis——更新保留上下文，新起提供清晰

阶段 4：收尾审查

全部任务完成后，编排独立代码审查。完整编排（维度定义、伪代码、契约校验、Codex 降级）见 review-orchestration.md，要点：

  • 审查范围：worktree 分支上本计划的全部变更（git diff <base>...HEAD）
  • 维度派发（按变更规模）：小 diff（<100 行）1 路；常规 A/B/C 3 路；大变更/用户要求"彻底"时 5 路——单条消息一次性 fan-out code-reviewer 子代理
  • 契约校验：每份报告落盘后 node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-output.mjs review-findings <file>，失败退回补全一次，再失败主线程接管该维度
  • loop-until-dry：去重后无新发现即停（最多 2 轮）；高/中严重性发现逐条派独立子代理对抗复核（指令=试图反驳）
  • completeness critic：1 个子代理对照变更文件清单与 spec 的 Requirement/Scenario 查覆盖缺口，输出并入报告
  • acceptance-qa：计划含验收任务、或 spec 验收矩阵含「验收任务」行时，触发 acceptance-qa skill 按矩阵执行（输入=spec 路径+计划验收任务+本次变更文件清单+证据目录 acceptance/）；旧版计划无矩阵时，变更涉及 UI 即按其验收点触发。验收结论并入审查报告

阶段 5：审查处置与交付对账

交付对账初判（主线程）：依据 completeness critic 的覆盖缺口、任务完成记录与验收结果，逐条 Requirement 生成初判；实施中经用户确认补入的计划外行为记 ADDED-IN-FLIGHT（spec 已随偏差处理修订，此处只记账）。

例外驱动的停顿门（审查与对账共用一道门）：

  • 零 confirmed 发现且全部 DELIVERED（常态）→ 输出覆盖声明与对账计数，直接进入阶段 6——没有要用户决策的事，不停顿
  • 存在 confirmed 发现或非 DELIVERED 嫌疑项 → 一次性征询：按严重性分组展示发现 + 列出待裁决 Requirement（补做→回阶段 3 补任务 / DEFERRED 记一句原因 / DROPPED 记一句原因）——哪些值得修、什么没交付是用户的优先级决策，不自动修复、不擅自定稿

用户确认后在 worktree 内修复（修复本身同样走 TDD：先写复现测试），修复后受影响维度复审一次；裁决结果即对账定稿。

阶段 6：合并与总结

  1. 审查与对账定稿后，合并前在 worktree 内落盘并提交：对账结果写入特性目录 acceptance/acceptance-report.md 的「Requirement Reconciliation」节——全绿一行带过，有偏差才展开差量表；acceptance-qa 未触发的特性按模板新建仅含头部与该节的轻量报告（一次交付一份时点记录）。DEFERRED / DROPPED 同时在 spec 原位标注（形制见 spec 模板行为规范节），DELIVERED 不标
  2. 执行计划的最终任务（全量验证 → 合并回来源分支 → 清理 worktree 与分支 → sync_commit 锚定：合并后主工作区 HEAD 写入 spec frontmatter 并单独提交；原生工具建的隔离用原生方式退出）；计划缺最终任务或缺锚定步骤（旧版计划）时按同等步骤手工收尾；非 git 仓库跳过锚定并注明
  3. roadmap 状态回写（仅当 .spec-dev/roadmaps/ 下某 active roadmap 引用本特性目录）：把对应子项目行状态置 delivered 并提交；全部子项目已 delivered/dropped 时把该 roadmap frontmatter 的 status 翻 done。目录不存在或查无引用 → 跳过，零动作
  4. 输出总结：
    • 成果清单：完成的任务、创建/修改的文件、对账计数（X DELIVERED / Y DEFERRED / Z DROPPED / N ADDED-IN-FLIGHT）
    • 质量指标：测试数与结果、审查发现数与修复情况
    • 偏差记录：执行中对计划的就地修正
    • 后续建议：优化点、文档更新
    • roadmap 续接（仅当上一步命中 roadmap 且仍有 pending 子项目）：列出依赖已满足的下一个子项目，询问「roadmap <project> 还有 N 个子项目待做，下一个是 <子项目>，现在开始它的需求设计吗？」——用户同意后走 requirement-analysis（其 spec 已存在时直接 writing-plans）；不同意则保持 roadmap 现状，随时可续

Red Flags

  • "计划有点问题，我猜着改吧" → 契约级偏差停下问用户
  • "计划在手，直接开工" → 执行确认门：显式指示或交接确认之外，先获用户点头
  • "这个任务简单，跳过测试" → TDD 铁律无例外
  • "每完成一个任务都汇报一下" → 连续执行，别打断用户
  • "spec 自检时顺便找找 bug" → 自检只查 over/under-building 与契约锚定
  • "审查发现直接修了" → 先征询用户处理方式
  • "没做完的 Requirement 含糊带过" → 对账逐条裁决，DEFERRED/DROPPED 必须记原因并回写 spec
  • "零发现且全 DELIVERED 仍停下征询" → 例外驱动：没有要决策的事就静默进入合并，总结带一行计数
  • "改动不大，审查跳过吧" → 收尾审查是强制步骤，规模只影响维度数
  • "自己写的代码自己看一遍就行" → 审查必须由独立子代理承担
  • "子项目交付了，roadmap 回头再更新" → 交付即回写 delivered 并提示续接，否则剩余子项目无声搁浅