@rpamis/comet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rpamis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @rpamis/comet
+
+OpenSpec + Superpowers dual-star development workflow for Claude Code.
+
+## Installation
+
+```bash
+npm install -g @rpamis/comet
+```
+
+## Quick Start
+
+```bash
+cd your-project
+comet init
+```
+
+`comet init` will:
+1. Install Comet skills to `.claude/skills/`
+2. Set up OpenSpec (if not already installed)
+3. Set up Superpowers (if not already installed)
+4. Create `docs/superpowers/` working directories
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `comet init [path]` | Initialize Comet workflow |
+| `comet --help` | Show help |
+| `comet --version` | Show version |
+
+## Skills
+
+After `comet init`, these skills are available in Claude Code:
+
+| Skill | Description |
+|-------|-------------|
+| `/comet` | Main entry — auto-detects phase and dispatches |
+| `/comet-open` | Phase 1: Open change |
+| `/comet-design` | Phase 2: Deep design |
+| `/comet-build` | Phase 3: Plan and build |
+| `/comet-verify` | Phase 4: Verify and finish |
+| `/comet-archive` | Phase 5: Archive |
+| `/comet-hotfix` | Preset: Bug fix (skip brainstorming) |
+| `/comet-tweak` | Preset: Small change (skip brainstorming and plan) |
+
+## License
+
+MIT

package/assets/manifest.json

@@ -0,0 +1,13 @@
+{
+  "version": "0.1.0",
+  "skills": [
+    "comet/SKILL.md",
+    "comet-open/SKILL.md",
+    "comet-design/SKILL.md",
+    "comet-build/SKILL.md",
+    "comet-verify/SKILL.md",
+    "comet-archive/SKILL.md",
+    "comet-hotfix/SKILL.md",
+    "comet-tweak/SKILL.md"
+  ]
+}

package/assets/skills/comet/SKILL.md

@@ -0,0 +1,192 @@
+---
+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>/.openspec.yaml` 中的 `comet` 元数据。若该字段不存在，再回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
+
+推荐元数据结构：
+
+```yaml
+comet:
+  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. **`comet.archived: true` 或 change 已移入 archive** → 流程已完成
+2. **`comet.verify_result: pass` 且 `comet.archived` 不是 `true`** → 调用 `/comet-archive`
+3. **`comet.phase: verify` 或 tasks.md 全部勾选** → 调用 `/comet-verify`
+4. **`comet.phase: build` 或已有 Design Doc 但计划/执行未完成** → 调用 `/comet-build`
+5. **`comet.phase: design` 或有 change 但无 Design Doc** → 调用 `/comet-design`
+6. **无活跃 change 或状态无法判定** → 调用 `/comet-open`
+
+如果元数据与文件状态冲突，以可验证的文件状态为准，并在继续阶段前修正 `.openspec.yaml` 中的 `comet` 字段。
+
+---
+
+## 子命令
+
+| 命令 | 阶段 | 归属 | 产物 |
+|------|------|------|------|
+| `/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 |
+| `.openspec.yaml` 格式异常或缺失 | 以文件状态为准（tasks.md、docs/superpowers/），修正元数据后继续 |
+| Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
+| change 目录结构不完整 | 按 `comet-open` 的产物要求补齐缺失文件 |
+
+---
+
+## 快速参考
+
+### 文件结构
+
+```
+openspec/                              # OpenSpec — WHAT
+├── config.yaml
+├── changes/
+│   ├── <name>/                        # 活跃 change
+│   │   ├── .openspec.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 满足升级条件时及时切换到完整流程

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

@@ -0,0 +1,107 @@
+---
+name: comet-archive
+description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta spec 到主 spec，归档 change。"
+---
+
+# Comet 阶段 5：归档（Archive）
+
+## 前置条件
+
+- 验证已通过（阶段 4 完成）
+- 分支已处理
+- `openspec/changes/<name>/.openspec.yaml` 中 `comet.verify_result: pass`
+
+## 步骤
+
+### 1. 执行归档
+
+归档前如 `comet.verify_result` 不是 `pass`，停止归档并返回 `/comet-verify`。
+
+**立即执行：** 使用 Skill 工具加载 `openspec-archive-change` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引归档。自动检查：
+1. artifact 完成状态（proposal、design、specs、tasks）
+2. 所有任务已标记 `[x]`
+3. delta specs 同步状态
+
+### 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
+├── 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 已标注归档状态
+- `.openspec.yaml` 中 `comet.archived` 已记录为 `true`
+
+归档完成后，在归档目录的 `.openspec.yaml` 中合并更新：
+
+```yaml
+comet:
+  phase: archive
+  archived: true
+```
+
+## 完成
+
+Comet 流程全部完成。如需开始新工作，调用 `/comet` 或 `/comet-open`。

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

@@ -0,0 +1,122 @@
+---
+name: comet-build
+description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制定计划并通过 subagent-driven-development 执行实施。"
+---
+
+# Comet 阶段 3：计划与构建（Build）
+
+## 前置条件
+
+- Design Doc 已创建（阶段 2 完成）
+- 活跃 change 存在
+
+## 步骤
+
+### 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>/.openspec.yaml` 中合并更新：
+
+```yaml
+comet:
+  phase: build
+  plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+```
+
+### 3. 选择执行方式
+
+向用户展示计划摘要（任务数、涉及模块），然后询问执行方式：
+
+| 选项 | 技能 | 适用场景 |
+|------|------|---------|
+| A | `superpowers:subagent-driven-development` | 任务独立、复杂度高、需要双阶段审查 |
+| B | `superpowers:executing-plans` | 任务简单、无子agent环境、轻量快速 |
+
+**推荐规则**：
+- 任务数 ≥ 3 → 推荐 A
+- 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
+- 来自 hotfix 路径 → 推荐 B
+
+用户选择后，在 `openspec/changes/<name>/.openspec.yaml` 中记录实际执行方式。`build_mode` 只允许以下值之一：
+
+- `subagent-driven-development`
+- `executing-plans`
+- `direct`（仅 hotfix preset 使用）
+
+Few-shot 示例：
+
+```yaml
+# 用户选择稳健模式 / A
+comet:
+  build_mode: subagent-driven-development
+```
+
+```yaml
+# 用户选择快速模式 / B
+comet:
+  build_mode: executing-plans
+```
+
+然后，**立即执行：** 使用 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 全部勾选
+- 代码已提交
+- 测试通过
+- `.openspec.yaml` 中 `comet.phase` 已更新为 `verify`
+
+退出前合并更新：
+
+```yaml
+comet:
+  phase: verify
+  verify_result: pending
+```
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `comet-verify` skill 进入验证与收尾阶段。

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

@@ -0,0 +1,75 @@
+---
+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/` 下无对应文件）
+
+## 步骤
+
+### 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>/.openspec.yaml` 中合并更新：
+
+```yaml
+comet:
+  phase: build
+  design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+```
+
+### 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 已创建
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `comet-build` skill 进入计划与构建阶段。