mini-spec 是一个轻量 SDD 工作流 skill，用来把需求材料收敛成 mini-spec.md，再生成 plan.md，最后让 agent 按计划执行并维护 progress.md。

它的目标不是复刻完整 Spec Kit，也不是强制重型文档，而是用少量固定入口约束 agent：先明确需求，再规划，再执行。

/mini-spec init
/mini-spec plan
/mini-spec progress

核心产物默认写在当前目录：

• mini-spec.md
• plan.md
• progress.md

如果这些文件已存在，skill 会先读取并说明建议变更，不应静默覆盖。

初始化或修订 mini-spec.md。

适合场景：

• 用户有一个 prompt、需求描述或 story.md，希望先收敛成轻量 spec。
• 需求材料还比较散，需要暴露目标、范围、约束、验收和未知点。
• 用户希望 agent 不要直接编码，而是先停在需求验收点。

使用方式：

/mini-spec init

也可以附带材料：

/mini-spec init 基于 story.md 初始化 mini-spec.md

如果缺少关键材料，agent 应主动提示用户补充。重点缺口包括：

• 目标
• 范围和非目标
• 验收标准
• 技术或业务约束
• 相关上下文
• 下一检查点

基于 mini-spec.md 生成或修订 plan.md。

使用方式：

/mini-spec plan

重要规则：如果需求中没有明确说明使用 phase 格式，agent 必须先询问用户要使用普通 plan 还是 phase plan，然后加载对应模板。

普通 plan 使用：

references/plan.md

phase plan 使用：

references/phase/plan.md

明确指定 phase 的示例：

/mini-spec plan 使用 phase 格式规划这个需求

明确指定普通计划的示例：

/mini-spec plan 使用普通 plan，不要分 phase

如果当前目录没有 mini-spec.md，应先运行 /mini-spec init，或在用户确认后先生成 mini-spec.md 草案。

让 agent 根据 plan.md 执行操作，并维护 progress.md。

使用方式：

/mini-spec progress

执行规则：

• 先读取当前目录下的 plan.md。
• 如果 plan 是普通计划，使用 references/progress.md。
• 如果 plan 是 phase plan，使用 references/phase/progress.md。
• 如果 progress.md 不存在，按模板创建。
• 如果 progress.md 已存在，只追加或修改经过确认的内容。
• 实现偏离 plan.md 时，必须记录原因；如果偏离影响范围、架构、验收或风险，应先停止并询问用户。

phase 执行时，一次只推进一个 phase。当前 phase 的验证结果未记录前，不应开始下一个 phase。

本 skill 的模板位于：

• references/mini-spec.md
• references/plan.md
• references/progress.md
• references/phase/plan.md
• references/phase/progress.md

• 默认中文输出，除非用户或仓库约定要求其他语言。
• 未知点显式保留，不让 agent 自行脑补。
• 任务必须可验证。
• checkpoint 是执行停靠点，不是装饰。
• progress 用来承接长任务、偏离记录和验证结果。