@rpamis/comet 0.1.3 → 0.1.5

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

@@ -0,0 +1,151 @@
+---
+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）
+
+在执行任何操作之前，读取并验证当前状态：
+
+**检查清单：**
+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.
+```
+
+验证通过后才进入步骤 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（持久化）
+```
+
+### 3. Design Doc & Plan 处理
+
+归档时同步处理 `docs/superpowers/` 下的关联文件。若目标文件已有 YAML frontmatter，将归档字段合并到现有 frontmatter；若没有 frontmatter，才新建一组 frontmatter。
+
+**3a. Design Doc 一致性标注**
+
+查找 `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. 生命周期闭环
+
+Spec 生命周期在此完成：
+```
+brainstorming → delta spec → 实施（增量修改）→ 验证 → 主 spec 同步 → design doc 标注 → 归档
+```
+
+## 退出条件
+
+- change 已归档（从活跃列表移除）
+- 主 specs 已更新（delta → main 同步完成）
+- 关联 design doc 已标注归档状态
+- 关联 plan 已标注归档状态
+- `.comet.yaml` 中 `archived` 已记录为 `true`
+- **阶段守卫**：运行 `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

@@ -0,0 +1,161 @@
+---
+name: comet-build
+description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制定计划并通过 subagent-driven-development 执行实施。"
+---
+
+# Comet 阶段 3：计划与构建（Build）
+
+## 前置条件
+
+- Design Doc 已创建（阶段 2 完成）
+- 活跃 change 存在
+
+## 步骤
+
+### 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.
+```
+
+验证通过后才进入步骤 1。
+
+### 1. 制定计划
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:writing-plans` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引制定计划。计划要求：
+- 保存至 `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
+- 引用设计文档，拆分为可执行任务
+- **Plan 文件头必须包含关联元数据**：
+
+```yaml
+---
+change: <openspec-change-name>
+design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
+---
+```
+
+### 2. 更新计划状态
+
+在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+
+```yaml
+phase: build
+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 次，仍失败则报告错误并终止。
+
+### 3. 选择执行方式
+
+向用户展示计划摘要（任务数、涉及模块），然后询问执行方式：
+
+| 选项 | 技能 | 适用场景 |
+|------|------|---------|
+| A | `superpowers:subagent-driven-development` | 任务独立、复杂度高、需要双阶段审查 |
+| B | `superpowers:executing-plans` | 任务简单、无子agent环境、轻量快速 |
+
+**推荐规则**：
+- 任务数 ≥ 3 → 推荐 A
+- 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
+- 来自 hotfix 路径 → 推荐 B
+
+用户选择后，在 `openspec/changes/<name>/.comet.yaml` 中合并更新 `build_mode`（保留其他字段不变）。`build_mode` 只允许以下值之一：
+
+- `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 技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。
+
+技能加载后，按其指引执行：
+- 按计划执行任务
+- 完成 tasks.md 勾选（`- [ ]` → `- [x]`）
+- 每个任务完成后提交代码
+
+### 4. Spec 增量更新
+
+实施过程中发现初版 spec 不完整时，按变更规模分级处理：
+
+| 规模 | 触发条件 | 做法 |
+|------|---------|------|
+| 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md，追加 tasks.md 任务 |
+| 中 | 接口变更、新增组件、数据流变化 | 重新 `superpowers:brainstorming` 更新 Design Doc + delta spec |
+| 大 | 全新 capability 需求 | `/opsx:new` 创建独立 change |
+
+**50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，应考虑拆分为新 change。
+
+**原则**：
+- delta spec 是活文档，本阶段期间随时可修改
+- 每次更新应提交，commit message 说明变更原因
+- 不提前同步到 main spec，归档时统一同步
+- 如增量任务超过原 tasks.md 初始任务总数 50%，考虑拆分为新 change
+- 小规模增量直接改 delta spec 时，应在 commit message 中注明，便于归档时判断 design doc 漂移
+
+## 退出条件
+
+- tasks.md 全部勾选
+- 代码已提交
+- 测试通过
+- `.comet.yaml` 中 `phase` 已更新为 `verify`
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> build`，全部 PASS 后才允许流转
+
+退出前在 `.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+
+```yaml
+phase: verify
+verify_result: pending
+```
+
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 phase 行的值为 "verify"
+  确认 verify_result 行的值为 "pending"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `comet-verify` skill 进入验证与收尾阶段。

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

@@ -0,0 +1,108 @@
+---
+name: comet-design
+description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。"
+---
+
+# Comet 阶段 2：深度设计（Design）
+
+## 前置条件
+
+- 活跃 change 已存在（proposal.md、design.md、tasks.md）
+- 无 Design Doc（`docs/superpowers/specs/` 下无对应文件）
+
+## 步骤
+
+### 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.
+```
+
+验证通过后才进入步骤 1。
+
+### 1a. 读取已有上下文
+
+读取活跃 change 下的 `proposal.md` 和 `design.md`，将核心内容整理为摘要：
+- **proposal 摘要**：目标、动机、范围
+- **design 摘要**：架构决策、高层设计
+
+### 1b. 执行 Brainstorming（带上下文）
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:brainstorming` 技能，ARGUMENTS 包含：
+
+```
+Change: <change-name>
+Proposal 摘要: <proposal 核心内容>
+Design 摘要: <design.md 架构决策>
+跳过上下文探索，直接进入设计提问。
+```
+
+禁止跳过此步骤，禁止在未加载该技能的情况下继续。
+
+如 `superpowers:brainstorming` 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
+
+技能加载后，按其指引产出：
+- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — 设计文档（技术 RFC）
+- `openspec/changes/<name>/specs/<capability>/spec.md` — 能力规格（delta）
+
+### 2. 更新 Comet 状态
+
+在 `openspec/changes/<name>/.comet.yaml` 中合并更新以下字段（保留其他字段不变）：
+
+```yaml
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+```
+
+【写入验证】更新完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 phase 行的值为 "build"
+  确认 design_doc 行的值为 "docs/superpowers/specs/YYYY-MM-DD-topic-design.md"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
+### 3. 双 Spec 分工
+
+| Spec 类型 | 归属 | 存放位置 | 定义 |
+|-----------|------|---------|------|
+| 能力规格 | OpenSpec | `openspec/changes/<name>/specs/` | 系统应该做什么（需求 + 验收场景） |
+| 设计文档 | Superpowers | `docs/superpowers/specs/` | 怎么构建（技术架构 + 实现细节） |
+
+### 4. 文档层级确认
+
+```
+proposal.md（阶段 1）              → Why + What
+design.md（阶段 1，OpenSpec）      → 高层架构决策
+设计文档（阶段 2，Superpowers）     → 深度技术设计
+能力规格（阶段 2，delta）           → 需求 + 验收场景
+```
+
+## 退出条件
+
+- Design Doc 已创建并保存
+- 如有新能力则 delta spec 已创建
+- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> design`，全部 PASS 后才允许流转
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `comet-build` skill 进入计划与构建阶段。

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

@@ -0,0 +1,165 @@
+---
+name: comet-hotfix
+description: "Comet 预设路径：Bug fix / 热修复。跳过 brainstorming，直接 open → build → verify → archive。适用于行为修复、不涉及新 capability 设计的场景。"
+---
+
+# Comet 预设路径：Hotfix
+
+Hotfix 是 Comet 五阶段能力的预设工作流，不是独立的平行流程。它复用 open、build、verify、archive 能力，仅跳过 brainstorming 和完整 plan。
+
+适用于 bug fix、热修复、小范围行为修正。不涉及新 capability 设计，不需要深度 brainstorming。
+
+**适用条件**（必须全部满足）：
+1. 修复已有功能的 bug，不新增 capability
+2. 不涉及接口变更或架构调整
+3. 改动范围可预估（通常 < 5 个文件）
+
+**不适用**：如修复过程发现需要架构调整，应升级为完整 `/comet` 流程。
+
+---
+
+## 流程（preset workflow，4 阶段）
+
+### 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.
+```
+
+验证通过后才进入流程步骤。
+
+执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后归档。
+
+### 1. 快速开启（preset open）
+
+复用 Comet open 能力创建 change，但使用 hotfix 默认值：不执行 `openspec-explore` 长探索，直接进入精简 change 创建。
+
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引创建精简版产物：
+  - `proposal.md` — 问题描述 + 根因分析 + 修复目标（无需方案对比）
+  - `design.md` — 修复方案（1 个即可，无需多方案对比）
+  - `tasks.md` — 修复任务清单
+- **无需 delta spec**（除非修复改变了已有 spec 的验收场景）
+
+在 `openspec/changes/<name>/` 下创建独立的 `.comet.yaml` 文件：
+
+```yaml
+workflow: hotfix
+phase: build
+design_doc: null
+plan: null
+build_mode: direct
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
+```
+
+【写入验证】创建完成后必须验证：
+  cat openspec/changes/<name>/.comet.yaml
+  确认 workflow 行的值为 "hotfix"
+  确认 phase 行的值为 "build"
+  确认 design_doc 行的值为 "null"
+  确认 plan 行的值为 "null"
+  确认 build_mode 行的值为 "direct"
+  确认 verify_mode 行的值为 "light"
+  确认 verify_result 行的值为 "pending"
+  确认 verified_at 行的值为 "null"
+  确认 archived 行的值为 "false"
+  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
+
+### 2. 直接构建（preset build）
+
+使用 hotfix 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择）。
+
+**立即执行：** 按 tasks.md 逐个执行任务：
+
+1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表
+2. 对每个未完成任务：
+   - 根据任务描述修改代码
+   - 运行 `mvn spotless:apply` 格式化
+   - 运行相关测试确认通过
+   - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
+   - 提交代码，commit message 格式：`fix: <简述修复>`
+3. 全部任务完成后进入验证
+
+**如修复影响已有 spec 验收场景**：
+- 在 `openspec/changes/<name>/specs/<capability>/spec.md` 创建 delta spec
+- 仅包含 `## MODIFIED Requirements` 部分
+
+### 3. 验证（preset verify）
+
+复用 `/comet-verify`，由 comet-verify 的规模评估决定轻量或完整验证。
+
+**立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
+
+无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、≤ 5 files），comet-verify 的规模评估会选择轻量验证路径（5 项快速检查）。若 hotfix 创建了 delta spec，则根据 comet-verify 的规模评估规则进入完整验证路径。
+
+**额外 Hotfix 专属检查**（在 comet-verify 轻量验证通过后执行）：
+
+1. **根因消除**：对照 proposal.md 的根因分析，确认问题代码已消除
+   - 读取 proposal.md 中的 bug 描述和根因
+   - 搜索验证问题代码不再存在
+   - 如根因未消除，返回 Step 2 继续修复
+
+**验证阶段升级条件**：
+- 回归测试揭示深层架构问题 → 停止 hotfix，升级为 `/comet`
+- 修复需要额外接口变更 → 停止 hotfix，升级为 `/comet`
+
+验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。
+
+### 4. 归档（preset archive）
+
+复用 `/comet-archive`。归档前必须满足 `.comet.yaml` 中 `verify_result: pass`。
+
+**立即执行：** 使用 Skill 工具加载 `comet-archive` 技能进行归档。禁止跳过此步骤。
+如有 delta spec，按 comet-archive 规则同步到 main spec，并处理关联 Design Doc 与 Plan 的归档标注。
+
+---
+
+## 连续执行模式
+
+<IMPORTANT>
+Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 必须自动走完全部 4 个阶段，中间不停顿等待用户输入（除非遇到升级条件需要用户确认）。
+
+执行顺序：快速开启 → 直接构建 → 验证 → 归档 → 完成
+
+每个阶段完成后立即进入下一阶段，无需用户再次输入。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill。
+</IMPORTANT>
+
+---
+
+## 升级条件
+
+修复过程中出现以下情况时，停止 hotfix 流程，升级为完整 `/comet`：
+
+1. 发现根因涉及架构缺陷
+2. 修复需要新增接口或组件
+3. 影响范围扩大到 > 10 个文件
+4. 需要新 capability 的 spec
+
+升级方式：在当前 change 基础上补充 Design Doc（执行 `/comet-design`），后续正常走完整流程。
+
+---
+
+## 退出条件
+
+- Bug 已修复，测试通过
+- change 已归档
+- 如有 spec 变更，已同步到 main spec
+- **阶段守卫**：build → verify 前运行 `bash $COMET_GUARD <change-name> build`，verify → archive 前运行 `bash $COMET_GUARD <change-name> verify`