@rpamis/comet 0.1.8 → 0.2.1

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

@@ -5,7 +5,7 @@ description: "Comet — OpenSpec + Superpowers 双星开发流程。用 /comet
 
 # Comet — OpenSpec + Superpowers 双星开发流程
 
-OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。OpenSpec 负责 WHAT，Superpowers 负责 HOW。
+OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。
 
 ```
 OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
@@ -14,105 +14,89 @@ Superpowers 负责 HOW — 技术设计、计划、执行、收尾
 
 **核心原则：brainstorming 必不可跳过。每次变更都必须经过深度设计（hotfix 和 tweak preset 除外）。**
 
-<IMPORTANT>
-## 阶段衔接
-
-单次 `/comet` 调用会从检测到的阶段开始执行，并在每个阶段退出条件满足后提示或进入下一阶段。
-
-流转链：open → design → build → verify → archive
+---
 
-需要用户参与的节点：
-1. brainstorming 过程中确认设计方案
-2. build 阶段选择执行方式
-3. verify 不通过时决定修复或接受偏差
-4. finishing-branch 选择分支处理方式
-5. 遇到升级条件（hotfix/tweak → 完整流程）
+## 决策核心（Decision Core）
 
-agent 不应跳过这些决策点；其他明确无歧义的阶段衔接可以继续推进。
-</IMPORTANT>
+agent 做决策只需读本节，参考附录按需查阅。
 
-## 阶段自动检测
+### 阶段自动检测
 
-### Step 0: 活跃 Change 发现
-
-**立即执行：**
+**Step 0: 活跃 Change 发现**
 
 1. 运行 `openspec list --json` 获取所有活跃 change
 2. 对每个 change，检查 `docs/superpowers/specs/` 和 `docs/superpowers/plans/` 匹配关联文件，判断阶段和进度
 
-**分支逻辑：**
-
 | 情况 | 行为 |
 |------|------|
 | 无活跃 change | → 调用 `/comet-open` |
-| 恰好 1 个活跃 change | → 自动选中，进入阶段判定（Step 1） |
+| 恰好 1 个活跃 change | → 自动选中，进入 Step 1 |
 | 多个活跃 change | → 列出清单让用户选择 |
 
-**多 change 选择**：使用 AskUserQuestion 展示，格式示例：
+**Preset 检测**：
+- 用户明确描述为 bug fix / 热修复 + 满足 hotfix 条件 → 直接 `/comet-hotfix`
+- 用户明确描述为文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接 `/comet-tweak`
 
-```
-| # | Change 名称 | 当前阶段 | 任务进度 |
-|---|------------|---------|---------|
-| 1 | xxx-feature | Build | 3/5 tasks |
-| 2 | yyy-fix | Design | No design doc |
-```
+**Step 1: 读取 `.comet.yaml` 状态元数据**
 
-用户选择后，对选中的 change 进入阶段判定。
+优先读取 `openspec/changes/<name>/.comet.yaml`。不存在时回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
 
-**Preset 检测**：
-- 如用户明确描述为 bug fix / 热修复，且满足 hotfix 适用条件，直接调用 `/comet-hotfix`（跳过选择）。
-- 如用户明确描述为文案、配置、文档、prompt 或小范围非 bug 调整，且满足 tweak 适用条件，直接调用 `/comet-tweak`（跳过选择）。
+**Step 2: 阶段判定**（按顺序，命中即停）
 
-### Step 1: Comet 状态元数据读取
+1. `archived: true` 或 change 已移入 archive → 流程已完成
+2. `verify_result: pass` 且 `archived` 不是 `true` → `/comet-archive`
+3. `phase: verify` 或 tasks.md 全部勾选 → `/comet-verify`
+4. `phase: build` 或已有 Design Doc 但计划/执行未完成 → `/comet-build`
+5. `phase: design` 或有 change 但无 Design Doc → `/comet-design`
+6. 无活跃 change 或状态无法判定 → `/comet-open`
 
-优先读取 `openspec/changes/<name>/.comet.yaml`。若该文件不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+如果元数据与文件状态冲突，以文件状态为准，修正 `.comet.yaml` 后继续。
 
-推荐元数据结构：
+### 预设升级条件
 
-```yaml
-workflow: full
-phase: build
-design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
-plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
-build_mode: subagent-driven-development
-isolation: branch
-verify_mode: light
-verify_result: pending
-verified_at: null
-archived: false
-```
+**hotfix → full**（满足任一即升级）：
+- 改动涉及 **3+ 文件**
+- 涉及架构变更（新模块、新接口、新依赖）
+- 涉及数据库 schema 变更
+- 修复引入新的 public API
+- 修复范围超出单一函数/模块
 
-字段含义：
+**tweak → full**（满足任一即升级）：
+- 改动涉及 **5+ 文件**
+- 涉及多个模块的协调修改
+- 需要新增测试用例 **5+**
+- 涉及配置项的新增或删除（非值修改）
 
-| 字段 | 含义 |
-|------|------|
-| `workflow` | `full`、`hotfix` 或 `tweak` |
-| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive` |
-| `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
-| `plan` | 关联的 Superpowers Plan 路径，可为空 |
-| `build_mode` | 已选择的执行方式，可为空 |
-| `isolation` | `branch` 或 `worktree`，工作区隔离方式，默认 `branch` |
-| `verify_mode` | `light` 或 `full`，可为空 |
-| `verify_result` | `pending`、`pass` 或 `fail` |
-| `verified_at` | 验证通过时间，可为空 |
-| `archived` | change 是否已归档 |
+### 错误处理速查
 
-### Step 2: 阶段判定
+| 场景 | 处理方式 |
+|------|---------|
+| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
+| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `bash $COMET_STATE set` 修正后继续 |
+| Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
+| change 目录结构不完整 | 按 `comet-open` 产物要求补齐 |
 
-对选中的 change，按以下顺序判断当前状态：
+### 阶段衔接
 
-1. **`archived: true` 或 change 已移入 archive** → 流程已完成
-2. **`verify_result: pass` 且 `archived` 不是 `true`** → 调用 `/comet-archive`
-3. **`phase: verify` 或 tasks.md 全部勾选** → 调用 `/comet-verify`
-4. **`phase: build` 或已有 Design Doc 但计划/执行未完成** → 调用 `/comet-build`
-5. **`phase: design` 或有 change 但无 Design Doc** → 调用 `/comet-design`
-6. **无活跃 change 或状态无法判定** → 调用 `/comet-open`
+<IMPORTANT>
+单次 `/comet` 调用从检测到的阶段开始，退出条件满足后进入下一阶段。
 
-如果元数据与文件状态冲突，以可验证的文件状态为准，并在继续阶段前修正 `.comet.yaml`。
+流转链：open → design → build → verify → archive
+
+需要用户参与的节点：
+1. brainstorming 确认设计方案
+2. build 阶段选择执行方式
+3. verify 不通过时决定修复或接受偏差
+4. finishing-branch 选择分支处理方式
+5. 遇到升级条件（hotfix/tweak → 完整流程）
+
+agent 不应跳过这些决策点；其他明确无歧义的阶段衔接可以继续推进。
+</IMPORTANT>
 
 ---
 
-## 子命令
+## 子命令速查
 
 | 命令 | 阶段 | 归属 | 产物 |
 |------|------|------|------|
@@ -124,10 +108,6 @@ archived: false
 | `/comet-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
 | `/comet-tweak` | 预设路径 | Both | 小改动（跳过 brainstorming 和完整 plan） |
 
----
-
-## 流程图
-
 ```
 /comet
   ↓ 自动检测
@@ -145,34 +125,44 @@ archived: false
 
 ---
 
-## 错误处理
+## 参考附录（Reference Appendix）
 
-| 场景 | 处理方式 |
-|------|---------|
-| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示用户运行 `openspec init` |
-| 子 skill 不可用（如 `superpowers:brainstorming`） | 停止流程，提示安装或启用对应 skill |
-| `.comet.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），使用 `bash $COMET_STATE set <name> <field> <value>` 修正元数据后继续 |
-| Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
-| change 目录结构不完整 | 按 `comet-open` 的产物要求补齐缺失文件 |
+### .comet.yaml 字段说明
 
----
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+isolation: branch
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
+```
 
-## 快速参考
+| 字段 | 含义 |
+|------|------|
+| `workflow` | `full`、`hotfix` 或 `tweak` |
+| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive` |
+| `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
+| `plan` | 关联的 Superpowers Plan 路径，可为空 |
+| `build_mode` | 已选择的执行方式，可为空 |
+| `isolation` | `branch` 或 `worktree`，工作区隔离方式，默认 `branch` |
+| `verify_mode` | `light` 或 `full`，可为空 |
+| `verify_result` | `pending`、`pass` 或 `fail` |
+| `verified_at` | 验证通过时间，可为空 |
+| `archived` | change 是否已归档 |
 
 ### 脚本定位
 
-Comet 阶段守卫脚本 `comet-guard.sh` 和归档脚本 `comet-archive.sh` 随 skill 包分发，位于 `comet/scripts/` 目录。
-**不硬编码平台路径**，运行时通过以下命令自定位：
-
-```bash
-COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)
-bash "$COMET_GUARD" <change-name> <phase>
-```
-
-**状态管理脚本**：`comet-state.sh` 提供 init/set/get/check/scale 五个子命令，统一管理状态文件字段：
+Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量：
 
 ```bash
-COMET_STATE=$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)
+COMET_GUARD="${COMET_GUARD:-$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)}"
+COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)}"
 ```
 
 **自动状态更新**：guard 支持 `--apply` 参数，验证通过后自动更新 `.comet.yaml` 状态字段：
@@ -184,11 +174,10 @@ bash "$COMET_GUARD" <change-name> <phase> --apply
 **归档脚本**：一键完成归档全部步骤：
 
 ```bash
-COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
 bash "$COMET_ARCHIVE" <change-name>
 ```
 
-后续文档中 `bash $COMET_GUARD <change> <phase>` 均指此命令。加载 comet 后，agent 应在 shell 环境中缓存 `COMET_GUARD` 路径，避免重复 `find`。
+加载 comet 后，agent 应执行以上三条变量赋值一次，后续全程复用 `$COMET_GUARD`、`$COMET_STATE`、`$COMET_ARCHIVE`。
 
 ### 文件结构
 
@@ -221,5 +210,5 @@ docs/superpowers/                      # Superpowers — HOW
 6. **增量更新分级** — 小编辑、中重 brainstorming、大新 change
 7. **Plan 必须关联 change** — 文件头包含 `change:` 和 `design-doc:` 元数据
 8. **归档闭环** — design doc 和 plan 必须标注 `archived-with` 状态
-9. **增量修改已有功能** — 直接 open 新 change，brainstorming 会读取已有 main spec 作为上下文
+9. **修改已有功能** — 直接 open 新 change 即可
 10. **Preset 有上限** — hotfix/tweak 满足升级条件时及时切换到完整流程

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

@@ -1,63 +1,63 @@
----
-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）
-
-执行入口验证：
-
-```bash
-COMET_STATE=$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)
-bash "$COMET_STATE" check <name> archive
-```
-
-验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
-
-### 1. 执行归档
-
-运行归档脚本，自动完成以下全部步骤：
-
-```bash
-COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
-bash "$COMET_ARCHIVE" "<change-name>"
-```
-
-脚本自动执行：
-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
-
-如脚本返回非零退出码，报告错误并停止。
-如脚本返回零退出码，归档完成。
-
-如需预览而不实际执行，使用 `--dry-run` 参数。
-
-### 2. 生命周期闭环
-
-Spec 生命周期在此完成：
-```
-brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档
-```
-
-## 退出条件
-
-- 归档脚本执行成功（退出码 0）
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> archive`，全部 PASS 后确认归档完整
-
-## 完成
-
-Comet 流程全部完成。如需开始新工作，调用 `/comet` 或 `/comet-open`。
+---
+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）
+
+执行入口验证：
+
+```bash
+COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+bash "$COMET_STATE" check <name> archive
+```
+
+验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
+
+### 1. 执行归档
+
+运行归档脚本，自动完成以下全部步骤：
+
+```bash
+COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)}"
+bash "$COMET_ARCHIVE" "<change-name>"
+```
+
+脚本自动执行：
+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
+
+如脚本返回非零退出码，报告错误并停止。
+如脚本返回零退出码，归档完成。
+
+如需预览而不实际执行，使用 `--dry-run` 参数。
+
+### 2. 生命周期闭环
+
+Spec 生命周期在此完成：
+```
+brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档
+```
+
+## 退出条件
+
+- 归档脚本执行成功（退出码 0）
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> archive`，全部 PASS 后确认归档完整
+
+## 完成
+
+Comet 流程全部完成。如需开始新工作，调用 `/comet` 或 `/comet-open`。