comet-archive - SKILL.md Agent Skill

name: comet-archive description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta spec 到主 spec，归档 change。"

Comet 阶段 5：归档（Archive）

前置条件

验证已通过（阶段 4 完成）
分支已处理
openspec/changes/<name>/.comet.yaml 中 verify_result: pass

步骤

0. 入口状态验证（Entry Check）

执行入口验证：

COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
if [ -z "$COMET_ENV" ]; then
  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
  return 1
fi
. "$COMET_ENV"
bash "$COMET_STATE" check <name> archive

验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。

1. 执行归档

运行归档脚本，自动完成以下全部步骤：

bash "$COMET_ARCHIVE" "<change-name>"

脚本自动执行：

入口状态验证（phase=archive, verify_result=pass, archived=false）
Delta spec 同步到主 spec
Design doc 前置元数据标注（archived-with, status）
Plan 前置元数据标注（archived-with）
移动 change 到归档目录
通过 comet-state transition <archive-name> archived 更新 archived: true

如脚本返回非零退出码，报告错误并停止。如脚本返回零退出码，归档完成。脚本摘要中的 X/Y steps succeeded 以真实执行步骤计数，不会因 delta spec 同步或文档标注重复累计。

当待同步的 delta spec 与已有主 spec 不一致时，脚本会在覆盖前打印 unified diff 预览，帮助确认归档同步内容。

如需预览而不实际执行，使用 --dry-run 参数。

2. 生命周期闭环

Spec 生命周期在此完成：

brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档

退出条件

归档脚本执行成功（退出码 0）
归档目录 openspec/changes/archive/YYYY-MM-DD-<change-name>/ 存在
归档后的 .comet.yaml 中 archived: true

归档脚本会把 openspec/changes/<name>/ 移动到 openspec/changes/archive/YYYY-MM-DD-<name>/。归档成功后不要再对原 change 名运行 bash "$COMET_GUARD" <change-name> archive，因为原活跃目录已经不存在。归档完整性以脚本退出码和归档目录状态为准。

完成

Comet 流程全部完成。如需开始新工作，调用 /comet 或 /comet-open。