@rpamis/comet 0.1.4 → 0.1.5

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

@@ -1,164 +1,164 @@
----
-name: comet-verify
-description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验证实现符合设计，处理开发分支。"
----
-
-# Comet 阶段 4：验证与收尾（Verify）
-
-## 前置条件
-
-- 代码已提交（阶段 3 完成）
-- tasks.md 全部任务已完成
-
-## 步骤
-
-### 0. 入口状态验证（Entry Check）
-
-在执行任何操作之前，读取并验证当前状态：
-
-**检查清单：**
-1. `openspec/changes/<name>/.comet.yaml` 存在
-2. `phase` 字段的值为 `"verify"`
-3. `verify_result` 字段为 `"pending"` 或 null（尚未验证通过）
-
-**验证方式：**
-- `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
-- 如 `verify_result` 已是 `"pass"`，说明此 change 已验证过
-
-**失败输出：**
-```
-[HARD STOP] Entry check failed for comet-verify
-  Expected: phase=verify, verify_result=pending|null
-  Actual:   phase=<实际值>, verify_result=<实际值>
-  Suggestion: Run comet-build first, or this change was already verified.
-```
-
-验证通过后才进入步骤 1。
-
-### 1. 改动规模评估
-
-根据以下指标判定改动规模：
-
-| 指标 | 小（轻量验证） | 大（完整验证） |
-|------|---------------|---------------|
-| tasks.md 任务数 | ≤ 3 | > 3 |
-| 变更文件数（git diff --stat） | ≤ 5 | > 5 |
-| 是否有 delta spec | 无 | 有 |
-| 是否新增 capability | 否 | 是 |
-
-**判定规则**：任一指标命中"大" → 完整验证。全部命中"小" → 轻量验证。
-
-判定完成后，在 `openspec/changes/<name>/.comet.yaml` 中记录实际验证模式。`verify_mode` 只允许以下值之一：
-
-- `light`
-- `full`
-
-Few-shot 示例：
-
-```yaml
-# 全部指标命中“小”
-phase: verify
-verify_mode: light
-verify_result: pending
-```
-
-```yaml
-# 任一指标命中”大”
-phase: verify
-verify_mode: full
-verify_result: pending
-```
-
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 verify_mode 行的值为 “<light 或 full>”
-  如不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
-### 2a. 轻量验证（小改动）
-
-当规模评估结果为"小"时，跳过 `openspec-verify-change`，直接执行以下检查：
-
-1. tasks.md 全部任务已完成 `[x]`
-2. 改动文件与 tasks.md 描述一致（`git diff --stat` 对照 tasks 内容）
-3. 编译通过（Maven 项目先执行 `mvn spotless:apply`，再执行 `mvn compile` 或等效命令）
-4. 相关测试通过
-5. 无明显安全问题（无硬编码密钥、无新增 unsafe 操作）
-
-**通过标准**：5 项全部 OK，无 CRITICAL 问题。
-
-**报告格式**：简表列出 5 项检查结果 + PASS/FAIL。
-
-**跳过项**（不在轻量验证中检查）：
-- spec scenario 覆盖率
-- design doc 一致性深度比对
-- code pattern consistency 建议
-- delta spec 与 design doc 漂移检测
-
-### 2b. 完整验证（大改动）
-
-当规模评估结果为"大"时：
-
-**立即执行：** 使用 Skill 工具加载 `openspec-verify-change` 技能。禁止跳过此步骤。
-
-技能加载后，按其指引验证。检查项：
-1. tasks.md 全部任务已完成（`[x]`）
-2. 实现符合 design.md 设计决策
-3. 实现符合 brainstorming 设计文档
-4. 能力规格场景全部通过
-5. proposal.md 目标已满足
-6. delta spec 与 design doc 无矛盾（若 Build 阶段有增量修改 spec，检查 design doc 是否有对应记录）
-7. `docs/superpowers/specs/` 关联的设计文档可定位（文件存在且与当前 change 相关）
-
-验证不通过时：报告缺失项，返回阶段 3 补充（调用 `/comet-build`）。
-
-**Spec 漂移处理**：
-- 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），提示用户：
-  - 选项 A：在 design doc 追加 "Implementation Divergence" 节记录偏差原因
-  - 选项 B：回退到 Build 阶段，补充 brainstorming 更新 design doc
-  - 选项 C：确认偏差可接受，继续验证（归档时 design doc 将标记为 `superseded-by-main-spec`）
-
-### 3. 收尾（Superpowers）
-
-**立即执行：** 使用 Skill 工具加载 `superpowers:finishing-a-development-branch` 技能。禁止跳过此步骤。
-
-如 `superpowers:finishing-a-development-branch` 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
-
-技能加载后，按其指引收尾。分支处理选项：
-1. 本地合并到主分支
-2. 推送并创建 PR
-3. 保持分支（稍后处理）
-4. 丢弃工作
-
-**确认项**：
-- Maven 测试或构建命令前已执行 `mvn spotless:apply`
-- 全部测试通过
-- 无遗留的 spotless 格式问题
-- 无硬编码密钥或安全问题
-
-## 退出条件
-
-- 验证报告通过
-- 分支已处理
-- `.comet.yaml` 中 `verify_result` 已记录为 `pass`
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> verify`，全部 PASS 后才允许流转
-
-退出前在 `.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
-
-```yaml
-phase: archive
-verify_result: pass
-verified_at: YYYY-MM-DD
-```
-
-【写入验证】更新完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 phase 行的值为 "archive"
-  确认 verify_result 行的值为 "pass"
-  确认 verified_at 行的值非空（格式为 YYYY-MM-DD）
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
-## 自动流转
-
-退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
-
-> **REQUIRED NEXT SKILL:** 调用 `comet-archive` skill 进入归档阶段。
+---
+name: comet-verify
+description: "Comet Phase 4: Verify and Complete. Invoke with /comet-verify. Verify implementation matches design, handle development branch."
+---
+
+# Comet Phase 4: Verify and Complete (Verify)
+
+## Prerequisites
+
+- Code has been committed (Phase 3 complete)
+- All tasks in tasks.md are complete
+
+## Steps
+
+### 0. Entry State Verification (Entry Check)
+
+Before performing any operations, read and verify the current state:
+
+**Checklist:**
+1. `openspec/changes/<name>/.comet.yaml` exists
+2. `phase` field value is `"verify"`
+3. `verify_result` field is `"pending"` or null (not yet verified)
+
+**Verification method:**
+- `cat openspec/changes/<name>/.comet.yaml` to read all fields
+- If `verify_result` is already `"pass"`, this change has already been verified
+
+**Failure output:**
+```
+[HARD STOP] Entry check failed for comet-verify
+  Expected: phase=verify, verify_result=pending|null
+  Actual:   phase=<actual-value>, verify_result=<actual-value>
+  Suggestion: Run comet-build first, or this change was already verified.
+```
+
+Proceed to Step 1 only after verification passes.
+
+### 1. Change Scale Assessment
+
+Determine change scale based on the following metrics:
+
+| Metric | Small (lightweight verification) | Large (full verification) |
+|------|-------------------------------|--------------------------|
+| tasks.md task count | ≤ 3 | > 3 |
+| Changed file count (git diff --stat) | ≤ 5 | > 5 |
+| Has delta spec | No | Yes |
+| New capability added | No | Yes |
+
+**Decision rule**: Any metric hitting "large" → full verification. All hitting "small" → lightweight verification.
+
+After determination, record actual verification mode in `openspec/changes/<name>/.comet.yaml`. `verify_mode` only allows one of the following values:
+
+- `light`
+- `full`
+
+Few-shot examples:
+
+```yaml
+# All metrics hit "small"
+phase: verify
+verify_mode: light
+verify_result: pending
+```
+
+```yaml
+# Any metric hits "large"
+phase: verify
+verify_mode: full
+verify_result: pending
+```
+
+【Write verification】After update completion, must verify:
+  cat openspec/changes/<name>/.comet.yaml
+  Confirm verify_mode line value is "<light or full>"
+  If not matching, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+
+### 2a. Lightweight Verification (Small Changes)
+
+When scale assessment result is "small", skip `openspec-verify-change`, directly execute the following checks:
+
+1. All tasks in tasks.md completed `[x]`
+2. Changed files consistent with tasks.md description (`git diff --stat`对照 tasks content)
+3. Build passes (for Maven projects, first execute `mvn spotless:apply`, then execute `mvn compile` or equivalent command)
+4. Related tests pass
+5. No obvious security issues (no hardcoded secrets, no new unsafe operations)
+
+**Pass standard**: All 5 items OK, no CRITICAL issues.
+
+**Report format**: Brief table listing 5 check results + PASS/FAIL.
+
+**Skipped items** (not checked in lightweight verification):
+- spec scenario coverage
+- design doc consistency deep comparison
+- code pattern consistency recommendations
+- delta spec and design doc drift detection
+
+### 2b. Full Verification (Large Changes)
+
+When scale assessment result is "large":
+
+**Immediately execute:** Use the Skill tool to load the `openspec-verify-change` skill. Skipping this step is prohibited.
+
+After the skill loads, follow its guidance to verify. Check items:
+1. All tasks in tasks.md completed (`[x]`)
+2. Implementation matches design.md design decisions
+3. Implementation matches brainstorming design document
+4. All capability specification scenarios pass
+5. proposal.md goals satisfied
+6. No contradiction between delta spec and design doc (if Build phase had incremental spec modifications, check if design doc has corresponding records)
+7. `docs/superpowers/specs/` associated design document can be located (file exists and relates to current change)
+
+When verification fails: report missing items, return to Phase 3 to supplement (invoke `/comet-build`).
+
+**Spec drift handling**:
+- If check item 6 finds contradiction (delta spec has content but design doc doesn't reflect it), prompt user:
+  - Option A: Append "Implementation Divergence" section to design doc recording deviation reason
+  - Option B: Roll back to Build phase, supplement brainstorming to update design doc
+  - Option C: Confirm deviation acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
+
+### 3. Completion (Superpowers)
+
+**Immediately execute:** Use the Skill tool to load the `superpowers:finishing-a-development-branch` skill. Skipping this step is prohibited.
+
+If `superpowers:finishing-a-development-branch` is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.
+
+After the skill loads, follow its guidance to complete. Branch handling options:
+1. Local merge to main branch
+2. Push and create PR
+3. Keep branch (handle later)
+4. Discard work
+
+**Confirmation items**:
+- Maven test or build commands have executed `mvn spotless:apply`
+- All tests pass
+- No remaining spotless formatting issues
+- No hardcoded secrets or security issues
+
+## Exit Conditions
+
+- Verification report passed
+- Branch handled
+- `.comet.yaml` `verify_result` recorded as `pass`
+- **Phase guard**: Run `bash $COMET_GUARD <change-name> verify`, allow transition only after all PASS
+
+Before exit, merge and update the following fields in `.comet.yaml` (keep other fields unchanged):
+
+```yaml
+phase: archive
+verify_result: pass
+verified_at: YYYY-MM-DD
+```
+
+【Write verification】After update completion, must verify:
+  cat openspec/changes/<name>/.comet.yaml
+  Confirm phase line value is "archive"
+  Confirm verify_result line value is "pass"
+  Confirm verified_at line value is non-empty (format YYYY-MM-DD)
+  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+
+## Automatic Transition
+
+After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
+
+> **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archiving phase.

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

@@ -0,0 +1,204 @@
+---
+name: comet
+description: "Comet — OpenSpec + Superpowers 双星开发流程。用 /comet 启动，自动检测阶段并分发到子命令。五阶段：开启 → 深度设计 → 计划与构建 → 验证与收尾 → 归档。"
+---
+
+# Comet — OpenSpec + Superpowers 双星开发流程
+
+OpenSpec 与 Superpowers 如双星系统围绕同一目标运转。OpenSpec 负责 WHAT，Superpowers 负责 HOW。
+
+```
+OpenSpec 负责 WHAT  — 大纲、提案、spec 生命周期、归档
+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 → 完整流程）
+
+agent 不应跳过这些决策点；其他明确无歧义的阶段衔接可以继续推进。
+</IMPORTANT>
+
+## 阶段自动检测
+
+### Step 0: 活跃 Change 发现
+
+**立即执行：**
+
+1. 运行 `openspec list --json` 获取所有活跃 change
+2. 对每个 change，检查 `docs/superpowers/specs/` 和 `docs/superpowers/plans/` 匹配关联文件，判断阶段和进度
+
+**分支逻辑：**
+
+| 情况 | 行为 |
+|------|------|
+| 无活跃 change | → 调用 `/comet-open` |
+| 恰好 1 个活跃 change | → 自动选中，进入阶段判定（Step 1） |
+| 多个活跃 change | → 列出清单让用户选择 |
+
+**多 change 选择**：使用 AskUserQuestion 展示，格式示例：
+
+```
+| # | Change 名称 | 当前阶段 | 任务进度 |
+|---|------------|---------|---------|
+| 1 | xxx-feature | Build | 3/5 tasks |
+| 2 | yyy-fix | Design | No design doc |
+```
+
+用户选择后，对选中的 change 进入阶段判定。
+
+**Preset 检测**：
+- 如用户明确描述为 bug fix / 热修复，且满足 hotfix 适用条件，直接调用 `/comet-hotfix`（跳过选择）。
+- 如用户明确描述为文案、配置、文档、prompt 或小范围非 bug 调整，且满足 tweak 适用条件，直接调用 `/comet-tweak`（跳过选择）。
+
+### Step 1: Comet 状态元数据读取
+
+优先读取 `openspec/changes/<name>/.comet.yaml`。若该文件不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+
+推荐元数据结构：
+
+```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
+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` | 已选择的执行方式，可为空 |
+| `verify_mode` | `light` 或 `full`，可为空 |
+| `verify_result` | `pending`、`pass` 或 `fail` |
+| `verified_at` | 验证通过时间，可为空 |
+| `archived` | change 是否已归档 |
+
+### Step 2: 阶段判定
+
+对选中的 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`
+
+如果元数据与文件状态冲突，以可验证的文件状态为准，并在继续阶段前修正 `.comet.yaml`。
+
+---
+
+## 子命令
+
+| 命令 | 阶段 | 归属 | 产物 |
+|------|------|------|------|
+| `/comet-open` | 1. 开启 | OpenSpec | proposal.md、design.md、tasks.md |
+| `/comet-design` | 2. 深度设计 | Superpowers | Design Doc、delta spec |
+| `/comet-build` | 3. 计划与构建 | Superpowers | 实施计划、代码提交 |
+| `/comet-verify` | 4. 验证与收尾 | Both | 验证报告、分支处理 |
+| `/comet-archive` | 5. 归档 | OpenSpec | delta→main spec 同步、design doc 标注、归档 |
+| `/comet-hotfix` | 预设路径 | Both | 快速修复（跳过 brainstorming） |
+| `/comet-tweak` | 预设路径 | Both | 小改动（跳过 brainstorming 和完整 plan） |
+
+---
+
+## 流程图
+
+```
+/comet
+  ↓ 自动检测
+/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
+  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
+
+/comet-hotfix（预设路径，跳过 brainstorming）
+  open ──→ build ──→ verify ──→ archive
+    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+
+/comet-tweak（预设路径，跳过 brainstorming 和完整 plan）
+  open ──→ lightweight build ──→ light verify ──→ archive
+    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+```
+
+---
+
+## 错误处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| `openspec list --json` 失败 | 检查 openspec 是否已安装，提示用户运行 `openspec init` |
+| 子 skill 不可用（如 `superpowers:brainstorming`） | 停止流程，提示安装或启用对应 skill |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），修正元数据后继续 |
+| Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
+| change 目录结构不完整 | 按 `comet-open` 的产物要求补齐缺失文件 |
+
+---
+
+## 快速参考
+
+### 脚本定位
+
+Comet 阶段守卫脚本 `comet-guard.sh` 随 skill 包分发，位于 `comet/scripts/` 目录。
+**不硬编码平台路径**，运行时通过以下命令自定位：
+
+```bash
+COMET_GUARD=$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)
+bash "$COMET_GUARD" <change-name> <phase>
+```
+
+后续文档中 `bash $COMET_GUARD <change> <phase>` 均指此命令。加载 comet 后，agent 应在 shell 环境中缓存 `COMET_GUARD` 路径，避免重复 `find`。
+
+### 文件结构
+
+```
+openspec/                              # OpenSpec — WHAT
+├── config.yaml
+├── changes/
+│   ├── <name>/                        # 活跃 change
+│   │   ├── .openspec.yaml
+│   │   ├── .comet.yaml
+│   │   ├── proposal.md                # Why + What
+│   │   ├── design.md                  # 高层架构决策
+│   │   ├── specs/<capability>/spec.md # Delta 能力规格
+│   │   └── tasks.md                   # 任务清单
+│   └── archive/YYYY-MM-DD-<name>/     # 已归档
+└── specs/<capability>/spec.md         # 主 specs（归档时从 delta 同步）
+
+docs/superpowers/                      # Superpowers — HOW
+├── specs/YYYY-MM-DD-<topic>-design.md # 设计文档（技术 RFC，归档时标注状态）
+└── plans/YYYY-MM-DD-<feature>.md      # 实施计划（文件头含 change 关联元数据）
+```
+
+### 最佳实践
+
+1. **brainstorming 不可跳过** — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
+2. **delta spec 是活文档** — 阶段 3 期间可自由修改，归档时同步
+3. **保持 tasks.md 同步** — 完成一个勾一个
+4. **频繁提交** — 每个任务一次提交，message 体现设计意图
+5. **先验证再归档** — `/comet-verify` 通过后才执行 `/comet-archive`
+6. **增量更新分级** — 小编辑、中重 brainstorming、大新 change
+7. **Plan 必须关联 change** — 文件头包含 `change:` 和 `design-doc:` 元数据
+8. **归档闭环** — design doc 和 plan 必须标注 `archived-with` 状态
+9. **增量修改已有功能** — 基于 main spec 创建 delta spec 基线，不从零编写
+10. **Preset 有上限** — hotfix/tweak 满足升级条件时及时切换到完整流程