@rpamis/comet 0.1.6 → 0.1.8

package/assets/skills-zh/comet-archive/SKILL.md

@@ -15,137 +15,49 @@ description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta
 
 ### 0. 入口状态验证（Entry Check）
 
-在执行任何操作之前，读取并验证当前状态：
+执行入口验证：
 
-**检查清单：**
-1. `openspec/changes/<name>/.comet.yaml` 存在
-2. `phase` 字段的值为 `"archive"`
-3. `verify_result` 字段的值为 `"pass"`
-4. `archived` 字段为 `"false"` 或 null（尚未归档）
-
-**验证方式：**
-- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
-- 如 `verify_result` 不是 `"pass"`，必须先完成验证
-
-**失败输出：**
-```
-[HARD STOP] Entry check failed for comet-archive
-  Expected: phase=archive, verify_result=pass, archived=false|null
-  Actual:   phase=<实际值>, verify_result=<实际值>, archived=<实际值>
-  Suggestion: Run comet-verify first, or this change was already archived.
+```bash
+COMET_STATE=$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)
+bash "$COMET_STATE" check <name> archive
 ```
 
-验证通过后才进入步骤 1。
+验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
 ### 1. 执行归档
 
-归档前如 `verify_result` 不是 `pass`，停止归档并返回 `/comet-verify`。
-
-**立即执行：** 使用 Skill 工具加载 `openspec-archive-change` 技能。禁止跳过此步骤。
-
-技能加载后，按其指引归档。自动检查：
-1. artifact 完成状态（proposal、design、specs、tasks）
-2. 所有任务已标记 `[x]`
-3. delta specs 同步状态
-
-### 1b. 移动 Comet 状态文件
-
-`openspec-archive-change` 不感知 `.comet.yaml`，因此 Comet 需要在 OpenSpec 归档完成后自行移动该文件：
+运行归档脚本，自动完成以下全部步骤：
 
 ```bash
-mv openspec/changes/<name>/.comet.yaml openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
-```
-
-【写入验证】移动完成后必须验证：
-  test -f openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
-  确认归档目录中 .comet.yaml 存在
-  如文件不在预期位置，检查 mv 命令是否成功执行。
-
-### 2. Delta Spec 同步
-
-归档时将 delta specs 同步到主 specs：
-
-```
-openspec/changes/<name>/specs/<capability>/spec.md
-       ↓ 同步
-openspec/specs/<capability>/spec.md  ← 主 spec（持久化）
+COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
+bash "$COMET_ARCHIVE" "<change-name>"
 ```
 
-### 3. Design Doc & Plan 处理
+脚本自动执行：
+1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+2. Delta spec 同步到主 spec
+3. Design doc 前置元数据标注（archived-with, status）
+4. Plan 前置元数据标注（archived-with）
+5. 移动 change 到归档目录
+6. 更新 archived: true
 
-归档时同步处理 `docs/superpowers/` 下的关联文件。若目标文件已有 YAML frontmatter，将归档字段合并到现有 frontmatter；若没有 frontmatter，才新建一组 frontmatter。
+如脚本返回非零退出码，报告错误并停止。
+如脚本返回零退出码，归档完成。
 
-**3a. Design Doc 一致性标注**
+如需预览而不实际执行，使用 `--dry-run` 参数。
 
-查找 `docs/superpowers/specs/` 中与当前 change 关联的设计文档：
-- 对比 delta spec 最终版与 design doc 内容
-- 如有偏差（实施过程中 spec 发生了增量修改），在 design doc 的 YAML frontmatter 中设置以下元数据：
-
-```yaml
----
-archived-with: YYYY-MM-DD-<name>
-status: superseded-by-main-spec
-implementation-notes: |
-  <简述实施过程中偏离原设计的关键变化>
----
-```
-
-- 如完全一致，仅设置：
-
-```yaml
----
-archived-with: YYYY-MM-DD-<name>
-status: final
----
-```
-
-**3b. Plan 关联标注**
-
-查找 `docs/superpowers/plans/` 中与当前 change 关联的实施计划，在 YAML frontmatter 中设置相同的 `archived-with` 元数据。
-
-### 4. 归档目录
-
-change 移入归档目录：
-
-```
-openspec/changes/archive/YYYY-MM-DD-<name>/
-├── .openspec.yaml
-├── .comet.yaml
-├── proposal.md
-├── design.md
-├── specs/<capability>/spec.md
-└── tasks.md
-```
-
-### 5. 生命周期闭环
+### 2. 生命周期闭环
 
 Spec 生命周期在此完成：
 ```
-brainstorming → delta spec → 实施（增量修改）→ 验证 → 主 spec 同步 → design doc 标注 → 归档
+brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档
 ```
 
 ## 退出条件
 
-- change 已归档（从活跃列表移除）
-- 主 specs 已更新（delta → main 同步完成）
-- 关联 design doc 已标注归档状态
-- 关联 plan 已标注归档状态
-- `.comet.yaml` 中 `archived` 已记录为 `true`
+- 归档脚本执行成功（退出码 0）
 - **阶段守卫**：运行 `bash $COMET_GUARD <change-name> archive`，全部 PASS 后确认归档完整
 
-归档完成后，在归档目录的 `.comet.yaml` 中更新：
-
-```yaml
-phase: archive
-archived: true
-```
-
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
-  确认 phase 行的值为 "archive"
-  确认 archived 行的值为 "true"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
 ## 完成
 
 Comet 流程全部完成。如需开始新工作，调用 `/comet` 或 `/comet-open`。

package/assets/skills-zh/comet-build/SKILL.md

@@ -14,29 +14,14 @@ description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制
 
 ### 0. 入口状态验证（Entry Check）
 
-在执行任何操作之前，读取并验证当前状态：
+执行入口验证：
 
-**检查清单：**
-1. `openspec/changes/<name>/.comet.yaml` 存在
-2. `phase` 字段的值为 `"build"`
-3. `design_doc` 字段非 null 且非空
-4. `design_doc` 引用的文件存在（例如 `docs/superpowers/specs/YYYY-MM-DD-topic-design.md`）
-5. `openspec/changes/<name>/proposal.md` 存在且非空
-6. `openspec/changes/<name>/tasks.md` 存在且非空
-
-**验证方式：**
-- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
-- 用 `ls` 或 `test -f` 确认 design_doc 文件存在
-
-**失败输出：**
-```
-[HARD STOP] Entry check failed for comet-build
-  Expected: phase=build, design_doc=<path> exists
-  Actual:   phase=<实际值>, design_doc=<实际值或文件不存在>
-  Suggestion: Run comet-design first, or verify design_doc file exists.
+```bash
+COMET_STATE=$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)
+bash "$COMET_STATE" check <name> build
 ```
 
-验证通过后才进入步骤 1。
+验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
 ### 1. 制定计划
 
@@ -56,17 +41,13 @@ design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
 
 ### 2. 更新计划状态
 
-在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+先记录 plan 路径：
 
-```yaml
-phase: build
-plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+```bash
+bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 ```
 
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 plan 行的值为 "docs/superpowers/plans/YYYY-MM-DD-feature.md"
-  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+无需手动更新 phase，guard 会在退出条件满足后自动流转。
 
 ### 3. 工作区隔离
 
@@ -81,27 +62,14 @@ plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
 - 变更涉及 ≤ 3 个文件 → 推荐 A
 - 需要并行开发、当前分支有未提交工作 → 推荐 B
 
-用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中合并更新 `isolation`（保留其他字段不变）。`isolation` 只允许以下值之一：
-
-- `branch`
-- `worktree`
+用户选择后，更新 `isolation` 字段。`isolation` 只允许以下值之一：
 
-Few-shot 示例：
-
-```yaml
-# 用户选择创建分支 / A
-isolation: branch
-```
-
-```yaml
-# 用户选择创建 worktree / B
-isolation: worktree
+```bash
+bash "$COMET_STATE" set <name> isolation <value>
 ```
 
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 isolation 行的值为 "<branch 或 worktree>"
-  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+- `branch`
+- `worktree`
 
 **执行隔离**：
 
@@ -124,29 +92,16 @@ isolation: worktree
 - 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
 - 来自 hotfix 路径 → 推荐 B
 
-用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中合并更新 `build_mode`（保留其他字段不变）。`build_mode` 只允许以下值之一：
+用户选择后，更新 `build_mode` 字段。`build_mode` 只允许以下值之一：
+
+```bash
+bash "$COMET_STATE" set <name> build_mode <value>
+```
 
 - `subagent-driven-development`
 - `executing-plans`
 - `direct`（仅 hotfix preset 使用）
 
-Few-shot 示例：
-
-```yaml
-# 用户选择稳健模式 / A
-build_mode: subagent-driven-development
-```
-
-```yaml
-# 用户选择快速模式 / B
-build_mode: executing-plans
-```
-
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 build_mode 行的值为 "<subagent-driven-development 或 executing-plans 或 direct>"
-  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
 然后，**立即执行：** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
 
 如所选 Superpowers 技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。
@@ -183,18 +138,13 @@ build_mode: executing-plans
 - `.comet.yaml` 中 `phase` 已更新为 `verify`
 - **阶段守卫**：运行 `bash $COMET_GUARD <change-name> build`，全部 PASS 后才允许流转
 
-退出前在 `.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+退出前运行 guard 自动流转：
 
-```yaml
-phase: verify
-verify_result: pending
+```bash
+bash $COMET_GUARD <change-name> build --apply
 ```
 
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 phase 行的值为 "verify"
-  确认 verify_result 行的值为 "pending"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+状态文件自动更新为 `phase: verify`、`verify_result: pending`。
 
 ## 自动流转
 

package/assets/skills-zh/comet-design/SKILL.md

@@ -14,30 +14,14 @@ description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过
 
 ### 0. 入口状态验证（Entry Check）
 
-在执行任何操作之前，读取并验证当前状态：
-
-**检查清单：**
-1. `openspec/changes/<name>/.comet.yaml` 存在
-2. `phase` 字段的值为 `"design"`
-3. `workflow` 字段的值为 `"full"`
-4. `design_doc` 字段为 `null` 或空
-5. `openspec/changes/<name>/proposal.md` 存在且非空
-6. `openspec/changes/<name>/design.md` 存在且非空
-7. `openspec/changes/<name>/tasks.md` 存在且非空
-
-**验证方式：**
-- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
-- 逐条比对检查清单
-
-**失败输出：**
-```
-[HARD STOP] Entry check failed for comet-design
-  Expected: phase=design, design_doc=<empty/null>, workflow=full
-  Actual:   phase=<实际值>, design_doc=<实际值>, workflow=<实际值>
-  Suggestion: Run comet-open first, or check if .comet.yaml was modified out of sequence.
+执行入口验证：
+
+```bash
+COMET_STATE=$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)
+bash "$COMET_STATE" check <name> design
 ```
 
-验证通过后才进入步骤 1。
+验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
 ### 1a. 读取已有上下文
 
@@ -66,18 +50,17 @@ Design 摘要: <design.md 架构决策>
 
 ### 2. 更新 Comet 状态
 
-在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+先记录 design_doc 路径，再运行 guard 自动流转：
+
+```bash
+# 记录 design_doc 路径
+bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
-```yaml
-phase: build
-design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+# 自动流转到下一阶段
+bash $COMET_GUARD <change-name> design --apply
 ```
 
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 phase 行的值为 "build"
-  确认 design_doc 行的值为 "docs/superpowers/specs/YYYY-MM-DD-topic-design.md"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+状态文件自动更新，无需手动编辑其他字段。
 
 ### 3. 双 Spec 分工
 

package/assets/skills-zh/comet-hotfix/SKILL.md

@@ -22,25 +22,14 @@ Hotfix 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 
 ### 0. 入口状态验证（Entry Check）
 
-在执行任何操作之前，验证当前状态：
+执行入口验证：
 
-**检查清单：**
-1. `openspec/changes/<name>/` 目录不存在，或目录存在但 `.comet.yaml` 不存在（无冲突）
-
-**验证方式：**
-- `test -d openspec/changes/<name>` 检查目录
-- 如目录存在，`test -f openspec/changes/<name>/.comet.yaml` 检查配置文件
-- 如 `.comet.yaml` 已存在，读取 `phase` 检查是否为未完成的 hotfix
-
-**失败输出（有冲突）：**
-```
-[HARD STOP] Entry check failed for comet-hotfix
-  Expected: openspec/changes/<name>/.comet.yaml does not exist (new change)
-  Actual:   .comet.yaml exists with phase=<实际值>
-  Suggestion: Pick a different change name, or check if an existing hotfix is in progress.
+```bash
+COMET_STATE=$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)
+bash "$COMET_STATE" check <name> open
 ```
 
-验证通过后才进入流程步骤。
+验证通过后继续流程步骤。验证失败时脚本会输出具体失败原因。
 
 执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后归档。
 
@@ -56,34 +45,11 @@ Hotfix 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
   - `tasks.md` — 修复任务清单
 - **无需 delta spec**（除非修复改变了已有 spec 的验收场景）
 
-在 `openspec/changes/<name>/` 下创建独立的 `.comet.yaml` 文件：
-
-```yaml
-workflow: hotfix
-phase: build
-design_doc: null
-plan: null
-build_mode: direct
-isolation: branch
-verify_mode: light
-verify_result: pending
-verified_at: null
-archived: false
-```
+初始化 Comet 状态文件：
 
-【写入验证】创建完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 workflow 行的值为 "hotfix"
-  确认 phase 行的值为 "build"
-  确认 design_doc 行的值为 "null"
-  确认 plan 行的值为 "null"
-  确认 build_mode 行的值为 "direct"
-  确认 isolation 行的值为 "branch"
-  确认 verify_mode 行的值为 "light"
-  确认 verify_result 行的值为 "pending"
-  确认 verified_at 行的值为 "null"
-  确认 archived 行的值为 "false"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+```bash
+bash "$COMET_STATE" init <name> hotfix
+```
 
 ### 2. 直接构建（preset build）
 

package/assets/skills-zh/comet-open/SKILL.md

@@ -13,28 +13,14 @@ description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec
 
 ### 0. 入口状态验证（Entry Check）
 
-在执行任何操作之前，读取并验证当前状态：
+执行入口验证：
 
-**检查清单：**
-1. `openspec/changes/<name>/` 目录已存在（由 openspec-new-change 创建）
-2. `openspec/changes/<name>/.comet.yaml` 文件不存在（尚未初始化）
-3. `openspec/changes/<name>/proposal.md` 存在且非空
-4. `openspec/changes/<name>/design.md` 存在且非空
-5. `openspec/changes/<name>/tasks.md` 存在且非空
-
-**验证方式：**
-- 读取以上路径确认存在/不存在
-- 如 `.comet.yaml` 已存在，读取其 `phase` 字段：如 phase 不为空，输出 `[HARD STOP]` 并提示可能已有活跃 change
-
-**失败输出：**
-```
-[HARD STOP] Entry check failed for comet-open
-  Expected: .comet.yaml does not exist, proposal.md + design.md + tasks.md exist
-  Actual:   phase=<实际值>, design_doc=<实际值> (或文件不存在)
-  Suggestion: Check if another change with the same name is already active.
+```bash
+COMET_STATE=$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)
+bash "$COMET_STATE" check <name> open
 ```
 
-验证通过后才进入步骤 1。
+验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
 
 ### 1. 探索想法
 
@@ -57,53 +43,14 @@ openspec/changes/<name>/
 └── tasks.md          # 任务清单（勾选框）
 ```
 
-### 2b. 增量修改已有 Capability（可选）
-
-**触发条件**：proposal.md 中提到修改已有 capability，或用户明确要求增量修改。
-
-**适用场景**：对已归档功能做增量修改（而非全新 capability）。
+### 3. 初始化 Comet 状态
 
-当 proposal.md 目标涉及修改已有 capability 时：
-1. 查找 `openspec/specs/<capability>/spec.md` 是否已存在主 spec
-2. 如已存在，将主 spec 复制为 delta spec 基线：
+初始化 Comet 状态文件：
 
 ```bash
-mkdir -p openspec/changes/<name>/specs/<capability>/
-cp openspec/specs/<capability>/spec.md openspec/changes/<name>/specs/<capability>/spec.md
+bash "$COMET_STATE" init <name> full
 ```
 
-3. 在复制的 delta spec 中，按 delta 格式组织变更（`## ADDED`、`## MODIFIED`、`## REMOVED`）
-4. 在 proposal.md 中注明 `基于已有 capability: <capability-name>`
-
-### 3. 初始化 Comet 状态
-
-在 `openspec/changes/<name>/` 下创建独立的 `.comet.yaml` 文件：
-
-```yaml
-workflow: full
-phase: design
-design_doc: null
-plan: null
-build_mode: null
-verify_mode: null
-verify_result: pending
-verified_at: null
-archived: false
-```
-
-【写入验证】创建完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 workflow 行的值为 "full"
-  确认 phase 行的值为 "design"
-  确认 design_doc 行的值为 "null"
-  确认 plan 行的值为 "null"
-  确认 build_mode 行的值为 "null"
-  确认 verify_mode 行的值为 "null"
-  确认 verify_result 行的值为 "pending"
-  确认 verified_at 行的值为 "null"
-  确认 archived 行的值为 "false"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
 ### 4. 内容完整性检查
 
 确认三个文档内容完整：

package/assets/skills-zh/comet-tweak/SKILL.md

@@ -23,25 +23,14 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 
 ### 0. 入口状态验证（Entry Check）
 
-在执行任何操作之前，验证当前状态：
+执行入口验证：
 
-**检查清单：**
-1. `openspec/changes/<name>/` 目录不存在，或目录存在但 `.comet.yaml` 不存在（无冲突）
-
-**验证方式：**
-- `test -d openspec/changes/<name>` 检查目录
-- 如目录存在，`test -f openspec/changes/<name>/.comet.yaml` 检查配置文件
-- 如 `.comet.yaml` 已存在，读取 `phase` 检查是否为未完成的 tweak
-
-**失败输出（有冲突）：**
-```
-[HARD STOP] Entry check failed for comet-tweak
-  Expected: openspec/changes/<name>/.comet.yaml does not exist (new change)
-  Actual:   .comet.yaml exists with phase=<实际值>
-  Suggestion: Pick a different change name, or check if an existing tweak is in progress.
+```bash
+COMET_STATE=$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)
+bash "$COMET_STATE" check <name> open
 ```
 
-验证通过后才进入流程步骤。
+验证通过后继续流程步骤。验证失败时脚本会输出具体失败原因。
 
 执行链路：open → lightweight build → light verify → archive。Tweak 为每个阶段提供默认决策：精简开启、轻量构建、轻量验证、验证通过后归档。
 
@@ -57,34 +46,11 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
   - `tasks.md` — 不超过 3 个任务
 - **无需 delta spec**（除非变更改变了已有 spec 的验收场景；一旦需要 delta spec，升级为完整 `/comet`）
 
-在 `openspec/changes/<name>/` 下创建独立的 `.comet.yaml` 文件：
-
-```yaml
-workflow: tweak
-phase: build
-design_doc: null
-plan: null
-build_mode: direct
-isolation: branch
-verify_mode: light
-verify_result: pending
-verified_at: null
-archived: false
-```
+初始化 Comet 状态文件：
 
-【写入验证】创建完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 workflow 行的值为 "tweak"
-  确认 phase 行的值为 "build"
-  确认 design_doc 行的值为 "null"
-  确认 plan 行的值为 "null"
-  确认 build_mode 行的值为 "direct"
-  确认 isolation 行的值为 "branch"
-  确认 verify_mode 行的值为 "light"
-  确认 verify_result 行的值为 "pending"
-  确认 verified_at 行的值为 "null"
-  确认 archived 行的值为 "false"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+```bash
+bash "$COMET_STATE" init <name> tweak
+```
 
 ### 2. 轻量构建（preset build）