spec-writer

Spec Writer

捆绑运行时

执行下方的 CLI 命令前，先将开头的 SSF 替换为 node "<plugin-root>/scripts/spec-superflow.mjs"；<plugin-root> 是此文件上两级目录的绝对路径。切勿直接运行 SSF，也不要调用 PATH 中的 ssf。

当变更已超出探索阶段时，创建或完善规划文档。

新的计划变更

对于新请求（没有状态或工作流自动模式），或 workflow_variant 为 planned 的情况，应一并编写 proposal.md 和 tasks.md，中间不要因单个文档而暂停。Proposal 需说明目标、范围内外的内容、验收标准和风险；tasks 需列出有序的交付项和验证命令。仅当行为需要可长期沿用的场景时才添加 specs，仅当尚未解决的架构决策需要记录时才添加 design。不要创建 execution-contract.md，也不要在另一份计划中重复任务列表。

根据真实源代码核对一次共享接口，然后自行检查问题、范围、依赖项和验证方式。只有当这份具体计划尚未获批时，才提出一次审批请求。获批后，运行 SSF workflow start <dir> --path planned --confirm --reason "<user decision>" 并继续实施。不要进行中间规划／衔接状态转换，也不要安排独立的 reader Agent。语义性修订获批后使用同一命令；非语义性修正则使用执行同步，并保留未通过审核的历史记录。以下各节仅适用于现有的旧版变更。

必需输入

读取 .spec-superflow.yaml（尤其是 dp_0_decisions、dp_0_confirmed）以及任何现有的规划文档。如果 dp_0_confirmed 不是 true，则停止并返回 workflow-start，以完成 DP-0。

配置检查

运行：SSF runtime config --get artifacts.order — 按配置顺序生成（默认：proposal → specs → design → tasks）。使用 artifacts.skip 运行时，跳过其中列出的文档。

文档职责

• proposal.md：原因和范围
• specs/：必需行为（可测试）
• design.md：架构决策及权衡（不必逐行描述）
• tasks.md：考虑依赖关系的实施步骤

工作规则

遵循 DP-0：读取 dp_0_decisions，尊重已确认的约束，不得擅自扩大范围。遇到未确认的决策时暂停。

proposal.md

必须说明：已观察到的问题、变更内容、范围内外的内容、影响范围以及完成的验证方式。优先使用具体事实，避免使用“更好”“健壮”或“高效”等空泛形容词。

specs/

每项需求都必须可测试。使用 SHALL 或 MUST。每项需求都必须至少包含一个带有 WHEN/THEN 的 #### Scenario:。按 ADDED/MODIFIED/REMOVED Requirements 标题分组。

design.md

必须包含：相关事实和约束、目标与非目标、决策（Choice + Rationale + Alternatives + Consequences），以及附有验证证据的风险。若利益相关方、迁移步骤或未决问题与决策无关，则不要臆造。

tasks.md

必须包含交付／验证对应关系表，以及考虑依赖关系的任务。每项任务都要注明受影响的路径或明确界定的范围、可观察到的结果和验证命令。将 RED/GREEN 细节、审核记录和分派机制保留在执行约定／任务简报中；不要把面向读者的任务拆成五个形式化步骤。

工件生成

创建或编辑规划工件前，先进入 specifying：仅当尚未处于该状态时，运行 SSF state transition <change-dir> specifying。恢复时，继续完成未完成的工件；不要自行转换状态。完整规划只有在明确不变的行为可省略规格说明，且可按配置省略设计。完整规划不能跳过任务：生成工件包前先修正此配置。

当 DP-0 已明确范围后，按顺序生成配置的规划工件包（提案、基于 templates/spec.md 的差异规格、设计和任务），中途不要在单个工件之间暂停。验证工件包，然后请求一次 DP-2 审查。仅当缺失的决策可能改变用户可见行为、兼容性、安全性、交付范围或所选设计，或工件中的范围相互冲突时，才提前暂停。

验证清单

proposal.md

• ## Why > 50 个字符，包含 ## What Changes、## Scope（In/Out）、## Impact，且无 TBD/TODO；声明需指出观察到的问题和完成证明

specs/

• 必需行为使用 SHALL/MUST，每项要求均包含 #### Scenario:，并使用 WHEN/THEN，按差异标题分组，且不存在矛盾

design.md

• 事实/约束、目标/非目标、## Decisions（至少 1 项，包含 Choice+Rationale+Alternatives+Consequences）、风险和验证

tasks.md

• 交付/证明映射、编号任务、受影响路径或有界范围、可观察结果、无占位符、每项要求均有映射、明确的依赖关系
• 必须使用模板复选框格式（每项任务单独占一行，格式为 - [ ]）；进入执行阶段时，守卫会强制检查此格式

如果任一工件未通过验证，交接给 contract-builder 前必须修复。

DP-2：工件审查关卡

简要概述配置的工件。自行检查以下五个问题一次：问题、命令边界、失效边界、续接边界和文档流程。除非用户明确要求委派，否则不要派遣盲读子 Agent。复用已涵盖这些工件的批准；仅当出现新的重大决策或缺少工件批准时，才提出一个整合问题。不要另行询问是否继续。批准后：

SSF state set <change-dir> dp_2_result "approved: <summary>"
SSF state set <change-dir> dp_2_timestamp now

记录 DP-2 后，保持在 specifying 状态并继续交接给 contract-builder。

交接规则

编写规划工件后不要开始实施。工件稳定且通过验证，并记录 DP-2 后，交接给 contract-builder。

异常处理

• 解析失败：报告具体文件/错误；不要使用损坏的模板生成工件
• 缺少模板：使用此技能中定义的工件结构作为后备方案
• 用户中断：磁盘上的工件是恢复检查点；从第一个缺失/未完成的工件继续
• 验证失败：交接前修复——不要交接有问题的工件