spec-driven-archive

你正在帮助用户归档一项已完成的规格驱动变更。

此技能的命令

如果你不记得此技能使用的确切命令，请在运行任何命令前在此查找。 不要猜测。

modify: node {{SKILL_DIR}}/scripts/spec-driven.js modify
apply: node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
verify-spec-mappings: node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
archive: node {{SKILL_DIR}}/scripts/spec-driven.js archive <name>

职责划分

运行此技能时，请明确区分脚本工作和 AI 工作。

由 CLI 脚本处理

• node {{SKILL_DIR}}/scripts/spec-driven.js modify 列出活跃变更
• node {{SKILL_DIR}}/scripts/spec-driven.js apply <name> 报告任务完成状态
• node {{SKILL_DIR}}/scripts/spec-driven.js archive <name> 将变更目录移至 .spec-driven/changes/archive/YYYY-MM-DD-<name>/；如果 .spec-driven/roadmap/ 存在，还会协调任何受影响里程碑的声明状态，并更新 .spec-driven/roadmap/INDEX.md

由 AI 处理

• 必要时询问用户要归档哪项变更
• 解读 apply 的输出；若仍有未完成任务，则阻止归档
• 检查 .spec-driven/changes/<name>/specs/，将增量规格合并到 .spec-driven/specs/；如果 REMOVED 有要求，则删除已清空的主规格文件
• specs/ 为空时无需确认，直接继续——没有规格影响的变更也是有效的
• 更新 .spec-driven/specs/INDEX.md，反映新增或删除的主规格文件
• 在合并规格时保留或应用规格映射 frontmatter
• 总结合并后的规格影响、归档导致的路线图状态变更，以及最终归档位置

前提条件

.spec-driven/ 目录必须存在于项目根目录。继续之前，请验证：

ls .spec-driven/

如果验证失败，说明项目尚未初始化。请先运行 /spec-driven-init。

步骤

1. 选择变更 — 运行 node {{SKILL_DIR}}/scripts/spec-driven.js modify 列出活跃变更。询问用户要归档哪项变更。如果用户已指定，则使用该变更。

2. 检查是否有未完成任务 — 运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js apply <name>
   

   如果 remaining > 0，则停止——所有任务完成前不允许归档。列出未完成的任务，并建议运行 /spec-driven-apply <name> 或 /spec-driven-cancel <name>。

3. 合并增量规格 — 列出 .spec-driven/changes/<name>/specs/ 中的所有文件：

   • 如果 specs/ 为空：无需确认，直接继续——没有规格影响的变更也是有效的。
   • 对于每个增量文件（例如 specs/install/install-behavior.md），将其合并到对应的主规格文件（例如 .spec-driven/specs/install/install-behavior.md）：
   • ADDED：将 ### Requirement: 块追加到目标文件（如果文件不存在，则创建该文件）
   • MODIFIED：按名称定位现有的 ### Requirement: <name> 块，并在原位置替换
   • REMOVED：按名称定位 ### Requirement: <name> 块并删除；如果文件因此变为空文件，则删除该文件
   • 如果增量文件包含映射 frontmatter，请在将变更移至归档前，将该 frontmatter 应用到目标主规格文件
   • 合并后简要总结 specs/ 中的变更。

4. 更新 specs/INDEX.md — 合并后，更新 .spec-driven/specs/INDEX.md：

   • 为新创建的规格文件添加条目（附上一行描述）
   • 删除已删除规格文件的条目
   • 除非文件的范围发生变化，否则保留现有条目不变
   • 运行 node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings，并在归档收尾前修复映射 frontmatter 错误

5. 归档变更 — 运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js archive <name>
   

   这会将整个变更目录（包括 questions.md）移至归档目录。 如果 .spec-driven/roadmap/ 存在，该命令还会协调里程碑声明状态，并为受影响的里程碑重新生成 .spec-driven/roadmap/INDEX.md。

6. 确认 — 报告结果：

   • 变更移至何处（例如 .spec-driven/changes/archive/2024-01-15-<name>/）
   • 因归档而变更的里程碑声明状态或路线图索引条目
   • 如果有后续工作，建议运行 /spec-driven-propose

规则

• 归档前始终检查是否有未完成的任务
• 切勿归档存在未完成任务的变更
• 始终说明哪些步骤由脚本执行，哪些由 AI 执行
• 归档前始终合并增量规格——这是强制门槛，并非可选项
• 如果 changes/<name>/specs/ 为空，无需确认即可继续——不影响规格的变更也是有效的
• 应用 REMOVED 增量条目时，允许删除 .spec-driven/specs/ 中的需求或空规格文件
• 不要手动删除变更目录——应运行归档命令来归档变更
• 将实现和测试映射保留在 frontmatter 中，而不是需求正文中