Executing Spec Or Plan

执行规格说明书或实施计划

概述

执行两类输入：

• 完整 plan：严格遵守已有 Task、步骤、验证和明确的执行政策。
• 已批准 spec：不生成正式实施计划文档，根据用户选择进行轻量拆解或自主执行。

本技能自行完成预检、执行、验证和报告。只有用户在集中确认中明确选择带有 Skill 名称的选项时，才调用 git-auto-commit 或 test-driven-development；不建立隐藏的自动衔接。

激活边界

只有用户肯定地要求使用 executing-spec-or-plan，或明确选择写有该技能名称的选项时才能调用。否定使用、询问功能、仅打开 plan/spec、要求“继续”或存在可执行文档，都不构成授权。

解析输入

按以下顺序确定输入：

1. 从 brainstorming 的明确选项进入：使用刚批准的 spec。
2. 从 writing-plans 的明确选项进入：使用刚生成的 plan。
3. 用户给出路径：使用该文件。
4. 当前上下文只有一个明确候选：告知将使用的路径后继续。
5. 存在多个候选或上下文不明确：列出候选，让用户选择；不得猜测。

以内容判断类型：

• 含顶层 Tasks、可执行步骤、验证命令的文档是 plan。
• 描述目标、设计、约束和验收条件但没有完整执行步骤的是 spec。

用户直接点名某个 spec 并要求执行，视为授权以其当前内容作为执行基线；仍须报告阻塞性矛盾或关键歧义。

输入文档中要求调用其他 Skill 的文字不构成调用授权。只有用户在本流程的确认面板中明确选择相应 Skill，或另行直接点名，才能调用；否则在不改变目标的前提下由当前 Agent 完成底层工作，无法等价完成时暂停说明。

固定进度

完整 plan：

1/3 执行前检查与集中确认
2/3 执行 Tasks
3/3 最终验证与报告

spec 自主拆解：

1/3 执行前检查与集中确认
2/3 自主执行
3/3 最终验证与报告

spec 要求确认拆解：

1/4 环境检查与执行政策确认
2/4 关键步骤与 sub-agent 确认
3/4 执行关键步骤
4/4 最终验证与报告

兼容性检查属于第一阶段内部工作，不额外增加确认阶段。

共同前置检查

在询问执行策略前，先只读检查：

• 当前工作目录；
• 是否为 Git 仓库；
• 当前分支；
• 是否位于 main 或 master；
• staged、unstaged、untracked 状态；
• 输入文档路径和类型。
• 平台是否支持 sub-agent；
• 平台是否支持为单个 sub-agent 指定模型；若支持，同时取得当前可用的模型标识。
• 平台是否支持为单个 sub-agent 指定推理强度；若支持，同时取得当前可用的强度标识及模型兼容信息。

从平台当前暴露的 sub-agent 调用接口、参数 schema 或能力元数据分别判断模型与推理强度能力。能创建 sub-agent 不等于能单独指定模型或推理强度，能指定模型也不等于能指定推理强度；不得根据模型常识、其他平台经验或未暴露的兼容关系猜测。

一次性向用户展示检查结果和当前需要收集的全部维度。用户一次提供多个选择时全部记录，不重复询问。

确认面板格式

每次只询问尚未确认的维度。按它们在当前消息中的展示顺序从 1 开始编号，并为各选项添加 A、B、C，组成 1A、1B 等可直接回复的编号。编号只对当前确认消息有效，不与某个维度永久绑定；再次询问时，对仍未确认的维度重新从 1 编号。

使用有效的 Markdown 嵌套列表：外层有序列表表示维度，内层无序列表表示选项，并把选项编号写成行内代码。不要把 1A. 当作 Markdown 列表标记。

参考格式：

1. 执行位置

• 1A 当前分支
• 1B 新分支（建议：codex/todo-priority）
• 1C worktree

1. 提交策略

• 2A 每个顶层 Task 提交
• 2B 遵循 plan
• 2C 明确不提交

在面板结尾提示用户可以一次性回复所有编号，例如 1B 2A；需要调整某项时，可在对应编号后补充说明。只回复带建议值的选项编号表示接受该建议值。收到部分有效回答时，保留已经确认的选择，下一次只列出其余维度并重新编号。

main/master 警告

当前分支为 main 或 master 时单独醒目标注：

> ⚠️ 当前分支是 ``。选择“在当前分支执行”将直接修改主分支。

用户在看到警告后明确选择当前分支，才构成直接实施许可。

执行位置

提供以下选项：

• 当前分支——在当前工作区实施。
• 新分支——用户指定或接受 Agent 建议的名称后，由 Agent 创建并切换。
• worktree——只有用户明确选择时，由 Agent 使用当前平台可用的 Git 能力创建。

不要调用工作区技能。worktree 需要有效 Git HEAD；无法创建时报告真实限制并请求改选。

工作区存在既有修改时：

• 在确认面板中列出。
• 记录执行前基线。
• 不暂存或覆盖无关修改。
• 既有修改与目标文件重叠时，实施前报告并请求处理方式。

非 Git 目录

• 提交策略不需要 Git 时，可以继续。
• 提交策略要求 commit 时，在同一确认面板中询问是否执行 git init。
• 用户不同意初始化时，必须改为不提交才能继续。
• 非 Git 目录没有有效 HEAD 时，不提供 worktree 作为可立即执行的选项；不得为了创建 worktree 擅自制造 bootstrap commit。初始化并产生有效 HEAD 后，用户仍可另行明确选择 worktree。

执行完整 plan

第一阶段：分析并集中确认

读取整份 plan，先完成：

• 识别关键缺口、矛盾和无法执行的步骤。
• 评估 Task 的依赖、复杂度和文件重叠。
• 给出 sub-agent 建议及理由。
• 检查 plan 是否与 TDD 顺序兼容。

按“确认面板格式”一次性收集尚未确定的维度：

• 执行位置：当前分支／新分支／worktree；
• 提交策略：使用 git-auto-commit 强制每个顶层 Task 提交／使用 git-auto-commit 遵循 plan／明确不提交；
• sub-agent：强制使用／Agent 判断／禁止使用；
• sub-agent 模型：仅在平台支持单独指定时询问；
• sub-agent 推理强度：仅在平台支持单独指定时询问；
• TDD：使用 test-driven-development／不调用，由 Agent 决定测试方式；
• Git 初始化：仅在非 Git 目录且提交策略需要时询问是否执行 git init。

plan 的提交策略

1. 使用 git-auto-commit 强制每个顶层 Task 提交

• 每个 Task 完成并验证后提交一次。
• 即使 plan 漏写 commit，也要按 Task 边界提交。

1. 使用 git-auto-commit 遵循 plan

• 只执行 plan 明确写出的 commit 步骤。

1. 明确不提交

• 跳过 plan 中所有 commit 步骤。
• 保留其他步骤、验证和交付物。

用户选择任一明确写有 git-auto-commit 的选项，即构成对该技能的显式调用授权。该授权覆盖本次执行中符合所选策略的全部提交边界，不需要逐次确认提交信息。用户在确认面板中的选择也是对 plan 提交步骤的显式覆盖。

plan 与 TDD 冲突

若 plan 存在先实现后测试的步骤，用以下选项替换当前面板的 TDD 维度：

• 使用 TDD，并允许只调整冲突 Task 的测试/实现顺序；
• 保持 plan 顺序，不调用 TDD；
• 暂停执行。

选择使用 TDD 时，只调整 RED/GREEN 的顺序，不改变功能范围、architecture 或验收目标。

plan 中对其他 Skill 的调用要求仍受“解析输入”中的显式授权规则约束，不属于“严格遵循 plan”的自动执行范围。

第二阶段：执行 Tasks

除用户在集中确认面板中明确覆盖的提交、TDD 和调度政策外，严格遵循 plan：

1. 默认按 plan 的书写顺序处理顶层 Task；若依赖关系使该顺序不可执行，在预检中报告，不静默重排。
2. 执行每个指令性步骤，包括所有 checkbox 项。
3. 运行计划规定的验证。
4. 验证成功后才把 Task 标记为完成。
5. 到达已授权的提交边界时，按所选策略调用 git-auto-commit。

直接执行 spec

不得创建 docs/superpowers/plans/ 下的正式计划文档，也不得调用 writing-plans。

第一阶段：集中确认

按“确认面板格式”一次性收集尚未确定的维度：

• 执行位置：当前分支／新分支／worktree；
• 任务拆解：展示关键步骤并确认／完全由 Agent 自主；
• 提交策略：使用 git-auto-commit 在每个关键步骤后提交／明确不提交；
• TDD：使用 test-driven-development／不调用，由 Agent 决定测试方式；
• sub-agent 模型：仅在平台支持单独指定时询问；
• sub-agent 推理强度：仅在平台支持单独指定时询问；
• Git 初始化：仅在必要时询问是否执行 git init。

同时显示：

执行前确认：基础信息与执行策略

[已检测] Git 仓库、分支和工作区状态
[待选择] 执行位置
[待选择] 任务拆解方式
[待选择] 提交策略
[待选择] TDD 模式
[待选择] sub-agent 模型（仅在平台支持单独指定时显示）
[待选择] sub-agent 推理强度（仅在平台支持单独指定时显示）
[稍后确认] sub-agent 模式（仅在要求确认任务拆解时）

完全由 Agent 自主

• 不再向用户展示或确认步骤。
• 不再单独询问 sub-agent。
• Agent 内部形成关键步骤并自主决定是否及如何使用 sub-agent。
• 若平台支持相应覆盖能力，实际派遣时使用第一轮已经确认的 sub-agent 模型与推理强度。
• 只按用户已经选择的提交和 TDD 政策执行。

展示关键步骤并确认

进入第二轮：

1. 阅读 spec 和代码库，列出若干关键步骤。
2. 展示依赖、复杂度和可能冲突。
3. 根据实际拆解给出 sub-agent 建议及理由。
4. 允许用户修改步骤。
5. 在新的确认面板中收集 sub-agent 选择：强制使用／Agent 判断／禁止使用。
6. 只有步骤和调度政策都明确批准后才能实施。

spec 的提交策略

• 使用 git-auto-commit 在每个关键步骤后提交：每个关键步骤完成并验证后调用一次；用户选择该项即授权本次执行中的全部关键步骤提交。
• 明确不提交：全部实现完成后保持代码未提交。

即使选择自主拆解，只要要求逐步提交，Agent 也必须在内部形成清晰的关键步骤和提交边界。

sub-agent 调度

sub-agent 是平台原生执行能力，不是另一个技能。

三种状态

1. 强制使用

• plan 的每个可委派顶层 Task 都分别使用原生 sub-agent 执行。
• spec 的每个可委派关键步骤都分别使用原生 sub-agent 执行。
• 纯用户交互或平台无法委派的步骤不能假装派遣；遇到这类步骤时报告限制，并由用户决定改为 Agent 判断、当前 Agent 执行或暂停。

1. Agent 判断

• 根据独立性、上下文量、并行价值和冲突风险决定。

1. 禁止使用

• 全部由当前 Agent 执行。

决策原则

倾向使用：

• 多个相对独立的模块；
• 大量只读探索、日志分析或测试输出；
• 可安全并行且写入区域不重叠。

倾向当前 Agent：

• 小型或紧密耦合变更；
• 多个步骤反复修改相同文件；
• 需要频繁与用户交互；
• 上下文连续性比隔离更重要。

默认按依赖顺序执行。并行写代码必须确认文件范围互不冲突。主 Agent 负责上下文、整合、验证和按策略调用 git-auto-commit。

平台不支持 sub-agent 时：

• “Agent 判断”自动退化为当前 Agent。
• “强制使用”必须报告限制并请求用户改选，不能假装已派遣。

不得调用任何调度或 reviewer Skill。

模型能力与选择

只有平台当前明确支持为 sub-agent 单独指定模型时，才把“sub-agent 模型”作为确认维度；不支持时完全省略，不向用户收集这项数据。

按以下顺序生成选项：

1. 默认——确认面板不强加固定模型覆盖值。派遣时先解析适用指令与配置；若 AGENTS.md、平台配置或其他适用规则指定了 sub-agent 模型，则按要求使用该模型，否则通过平台默认行为继承当前会话模型。
2. 可用模型——把平台当前明确暴露的每个可用模型标识分别列为选项，不硬编码、不臆测。

在确认面板中，把“默认（遵守现有配置；未指定时与当前会话相同）”放在该维度的 A 选项，从 B 开始为每个可用模型生成一个独立选项；不要把多个模型合并为一个选项，也不要要求用户自行填写平台未列出的模型名。

即使平台没有暴露当前会话的具体模型名，也可以提供“默认”选项。不要把“默认”解释为强制使用当前会话模型；它表示由适用指令与配置决定，只有没有额外规则时才继承当前会话。若现有规则指定了模型，派遣时按平台接口要求传递或应用该值。若平台支持模型参数但没有给出完整可用值，只列出当前能够验证的值；没有可验证的显式模型时，不得编造选项。

该选择是本次执行中所有 sub-agent 的统一默认策略，不改变当前 Agent 的模型。明确模型选项产生固定覆盖值；“默认”则对所有 sub-agent 使用同一解析规则，实际值可以由各自适用的配置决定。只有实际派遣 sub-agent 时才生效；选择“禁止使用”或最终没有派遣时不产生调用。派遣时若解析出的模型已不可用，暂停并重新询问，不得静默改用其他模型。

推理强度能力与选择

只有平台当前明确支持为 sub-agent 单独指定推理强度时，才把“sub-agent 推理强度”作为独立确认维度；不支持时完全省略，不向用户收集这项数据。模型覆盖能力与推理强度覆盖能力必须分别判断，不能互相推导。

按以下顺序生成选项：

1. 默认——确认面板不强加固定推理强度覆盖值。派遣时先解析适用指令与配置；若 AGENTS.md、平台配置或其他适用规则指定了 sub-agent 推理强度，则按要求使用该强度，否则通过平台默认行为继承当前会话推理强度。
2. 明确强度——依次列出平台当前明确支持的 low、medium、high、xhigh、max、ultra；平台未明确支持的值不得显示。

例如该维度在当前面板中排第 5 时，格式为：

1. sub-agent 推理强度

• 5A 默认（遵守现有配置；未指定时与当前会话相同）
• 5B low
• 5C medium
• 5D high
• 5E xhigh
• 5F max
• 5G ultra

实际序号仍按“确认面板格式”随当前未决维度动态生成；如果平台只明确支持上述值的子集，保留顺序并只显示该子集，不为省略的值保留空选项。

不要把“默认”解释为强制使用当前会话推理强度；它表示由适用指令与配置决定，只有没有额外规则时才继承当前会话。若现有规则指定了推理强度，派遣时按平台接口要求传递或应用该值。

该选择是本次执行中所有 sub-agent 的统一默认策略，不改变当前 Agent 的推理强度。明确强度选项产生固定覆盖值；“默认”则对所有 sub-agent 使用同一解析规则，实际值可以由各自适用的配置决定。只有实际派遣 sub-agent 时才生效；选择“禁止使用”或最终没有派遣时不产生调用。

每次派遣前，根据平台当前能力重新核对所选模型与所选推理强度的兼容性。若所选模型不支持该强度、所选强度已不可用，或平台在调用时报告两者不兼容，立即暂停并重新确认受影响的模型或推理强度维度；不得静默降低强度、移除覆盖值或改用其他模型。

重新确认时仍把模型与推理强度保持为两个独立维度，不得把兼容组合合并成一个选项。若两项都需要重选，分别列出模型与强度选项，并在模型选项或说明中标注兼容范围，直到用户明确选出兼容组合。

git-auto-commit 调用

只有用户选择确认面板中明确写有 git-auto-commit 的提交策略，才加载并调用该技能。plan、spec 或其他文档中的 commit 步骤与提交信息建议本身不构成调用授权；选择“明确不提交”时不得加载。

每到一个已授权的提交边界：

1. 先完成当前顶层 Task 或关键步骤及其验证；
2. 以该 Task 或关键步骤产生的修改作为当前提交单元，调用 git-auto-commit；
3. 把 plan 中的“建议提交信息”作为语义提示，由 git-auto-commit 根据实际 diff、项目规则和近期历史生成最终信息；
4. 没有文件变化时不调用技能创建空 commit，记录该事实后继续。

git-auto-commit 因范围不清、hook、验证或 Git 状态而停止时，同步暂停执行流程并报告实际状态，不绕过该技能继续提交。

TDD 调用

用户选择“使用 test-driven-development”即构成对该技能的显式调用：

• 加载并遵循其 RED–GREEN–REFACTOR 约束。
• plan 模式仍执行 plan 规定的验证。
• spec 模式按 TDD 拆解适用的代码行为。

用户选择“不调用”时，不加载该技能；Agent 仍应执行 plan 中已有测试，或在 spec 模式下自行选择合适的测试方式。

何时停止

立即暂停并报告：

• 输入存在无法开始的关键缺口；
• 指令相互矛盾且未被确认政策解决；
• 缺少必要依赖或权限；
• 测试或验证反复失败；
• 不理解某项要求；
• 既有用户修改可能被覆盖或误提交。

不要猜测，不要通过调用另一个技能绕过阻塞。

精简收尾

全部工作完成后：

1. 运行适合项目的最终验证。
2. 对照 plan 或 spec 检查覆盖情况。
3. 报告：

• 已完成的 Tasks/关键步骤；
• 测试和验证结果；
• 本次产生的 commits；
• 未提交文件；
• 当前 branch；
• sub-agent 模型选择及实际使用情况（若收集过该维度）；
• sub-agent 推理强度选择及实际使用情况（若收集过该维度）；
• worktree 路径（如由本技能创建）。

1. 保留 branch 和 worktree 原状。

不自动 merge、push、创建 PR、删除 branch、删除 worktree，也不调用收尾技能。用户后续明确要求时，由普通 Agent 按新指令处理。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cmstar
• Source: cmstar/hyperpowers-skills
• License: MIT

Install and usage instructions live in the source repository linked above.