@rpamis/comet 0.1.0

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

@@ -0,0 +1,130 @@
+---
+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 阶段）
+
+执行链路：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>/.openspec.yaml` 中写入或合并 hotfix 状态：
+
+```yaml
+comet:
+  workflow: hotfix
+  phase: build
+  design_doc: null
+  plan: null
+  build_mode: direct
+  verify_mode: light
+  verify_result: pending
+  verified_at: null
+  archived: false
+```
+
+### 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.verify_result` 记录为 `pass`，归档前不得跳过该状态。
+
+### 4. 归档（preset archive）
+
+复用 `/comet-archive`。归档前必须满足 `comet.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

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

@@ -0,0 +1,86 @@
+---
+name: comet-open
+description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec 探索想法、创建 change 结构（proposal + design + tasks）。"
+---
+
+# Comet 阶段 1：开启（Open）
+
+## 前置条件
+
+- 无活跃 change，或用户希望创建新 change
+
+## 步骤
+
+### 1. 探索想法
+
+**立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引自由探索问题空间。
+
+### 2. 创建 Change 结构
+
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能（或 `openspec-propose` 如需先提建议）。
+
+确认以下产物已创建：
+
+```
+openspec/changes/<name>/
+├── .openspec.yaml
+├── proposal.md       # Why + What：问题、目标、范围
+├── design.md         # How（高层）：架构决策、方案选型
+└── tasks.md          # 任务清单（勾选框）
+```
+
+### 2b. 增量修改已有 Capability（可选）
+
+**触发条件**：proposal.md 中提到修改已有 capability，或用户明确要求增量修改。
+
+**适用场景**：对已归档功能做增量修改（而非全新 capability）。
+
+当 proposal.md 目标涉及修改已有 capability 时：
+1. 查找 `openspec/specs/<capability>/spec.md` 是否已存在主 spec
+2. 如已存在，将主 spec 复制为 delta spec 基线：
+
+```bash
+mkdir -p openspec/changes/<name>/specs/<capability>/
+cp openspec/specs/<capability>/spec.md openspec/changes/<name>/specs/<capability>/spec.md
+```
+
+3. 在复制的 delta spec 中，按 delta 格式组织变更（`## ADDED`、`## MODIFIED`、`## REMOVED`）
+4. 在 proposal.md 中注明 `基于已有 capability: <capability-name>` 
+
+**好处**：避免从零编写 delta spec，确保增量修改有完整上下文。
+
+### 3. 初始化 Comet 状态
+
+在 `openspec/changes/<name>/.openspec.yaml` 中写入或合并以下元数据：
+
+```yaml
+comet:
+  workflow: full
+  phase: design
+  design_doc: null
+  plan: null
+  build_mode: null
+  verify_mode: null
+  verify_result: pending
+  verified_at: null
+  archived: false
+```
+
+### 4. 内容完整性检查
+
+确认三个文档内容完整：
+- **proposal.md**：问题背景、目标、范围、非目标
+- **design.md**：高层架构决策、方案选型、数据流
+- **tasks.md**：任务列表，每个任务有明确描述
+
+## 退出条件
+
+- proposal.md、design.md、tasks.md 均已创建且内容完整
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `comet-design` skill 进入深度设计阶段。

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

@@ -0,0 +1,117 @@
+---
+name: comet-tweak
+description: "Comet 预设路径：非 bug 的小改动（tweak）。跳过 brainstorming 和完整 plan，直接 open → lightweight build → light verify → archive。适用于文案、配置、文档或 prompt 的局部优化。"
+---
+
+# Comet 预设路径：Tweak
+
+Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程。它复用 open、build、verify、archive 能力，仅跳过 brainstorming 和完整 plan。
+
+适用于非 bug 的小范围变更，例如文案调整、配置调整、文档或 prompt 的局部优化。
+
+**适用条件**（必须全部满足）：
+1. 不新增 capability
+2. 不改变架构
+3. 不涉及接口变化
+4. 通常不超过 3 个 tasks、5 个文件
+
+**不适用**：如变更过程中发现需要 capability、架构或接口调整，应升级为完整 `/comet` 流程。
+
+---
+
+## 流程（preset workflow，4 阶段）
+
+执行链路：open → lightweight build → light verify → archive。Tweak 为每个阶段提供默认决策：精简开启、轻量构建、轻量验证、验证通过后归档。
+
+### 1. 快速开启（preset open）
+
+复用 Comet open 能力创建 change，但使用 tweak 默认值：不执行 `openspec-explore` 长探索，直接进入精简 change 创建。
+
+**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
+
+技能加载后，按其指引创建精简版产物：
+  - `proposal.md` — 变更动机 + 目标 + 范围
+  - `design.md` — 简短实现说明（无需方案对比）
+  - `tasks.md` — 不超过 3 个任务
+- **无需 delta spec**（除非变更改变了已有 spec 的验收场景；一旦需要 delta spec，升级为完整 `/comet`）
+
+在 `openspec/changes/<name>/.openspec.yaml` 中写入或合并 tweak 状态：
+
+```yaml
+comet:
+  workflow: tweak
+  phase: build
+  design_doc: null
+  plan: null
+  build_mode: direct
+  verify_mode: light
+  verify_result: pending
+  verified_at: null
+  archived: false
+```
+
+### 2. 轻量构建（preset build）
+
+使用 tweak 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`。
+
+**立即执行：** 按 tasks.md 逐个执行任务：
+
+1. 读取 `openspec/changes/<name>/tasks.md`，获取未完成任务列表
+2. 对每个未完成任务：
+   - 根据任务描述修改目标文件
+   - 运行 `mvn spotless:apply` 格式化
+   - 运行相关测试确认通过
+   - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
+   - 提交代码，commit message 格式：`tweak: <简述变更>`
+3. 全部任务完成后进入验证
+
+### 3. 轻量验证（preset verify）
+
+复用 `/comet-verify`。Tweak 必须保持轻量验证条件：≤ 3 tasks、≤ 5 files、无 delta spec、无新 capability。
+
+**立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
+
+如规模评估进入完整验证路径，停止 tweak，升级为完整 `/comet`。
+
+验证通过后，按 `/comet-verify` 的规则将 `comet.verify_result` 记录为 `pass`，归档前不得跳过该状态。
+
+### 4. 归档（preset archive）
+
+复用 `/comet-archive`。归档前必须满足 `comet.verify_result: pass`。
+
+**立即执行：** 使用 Skill 工具加载 `comet-archive` 技能进行归档。禁止跳过此步骤。
+
+---
+
+## 连续执行模式
+
+<IMPORTANT>
+Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 必须自动走完全部 4 个阶段，中间不停顿等待用户输入（除非遇到升级条件需要用户确认）。
+
+执行顺序：快速开启 → 轻量构建 → 轻量验证 → 归档 → 完成
+
+每个阶段完成后立即进入下一阶段，无需用户再次输入。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill。
+</IMPORTANT>
+
+---
+
+## 升级条件
+
+执行过程中出现以下情况时，停止 tweak 流程，升级为完整 `/comet`：
+
+1. 需要新增 capability
+2. 需要架构调整
+3. 需要接口变化
+4. 影响范围扩大到 > 5 个文件
+5. 任务数超过 3 个
+6. 需要 delta spec
+
+升级方式：在当前 change 基础上补充 Design Doc（执行 `/comet-design`），后续正常走完整流程。
+
+---
+
+## 退出条件
+
+- 小改动已完成，测试通过
+- change 已归档
+- 未新增 capability、架构调整或接口变化

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

@@ -0,0 +1,131 @@
+---
+name: comet-verify
+description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验证实现符合设计，处理开发分支。"
+---
+
+# Comet 阶段 4：验证与收尾（Verify）
+
+## 前置条件
+
+- 代码已提交（阶段 3 完成）
+- tasks.md 全部任务已完成
+
+## 步骤
+
+### 1. 改动规模评估
+
+根据以下指标判定改动规模：
+
+| 指标 | 小（轻量验证） | 大（完整验证） |
+|------|---------------|---------------|
+| tasks.md 任务数 | ≤ 3 | > 3 |
+| 变更文件数（git diff --stat） | ≤ 5 | > 5 |
+| 是否有 delta spec | 无 | 有 |
+| 是否新增 capability | 否 | 是 |
+
+**判定规则**：任一指标命中"大" → 完整验证。全部命中"小" → 轻量验证。
+
+判定完成后，在 `openspec/changes/<name>/.openspec.yaml` 中记录实际验证模式。`verify_mode` 只允许以下值之一：
+
+- `light`
+- `full`
+
+Few-shot 示例：
+
+```yaml
+# 全部指标命中“小”
+comet:
+  phase: verify
+  verify_mode: light
+  verify_result: pending
+```
+
+```yaml
+# 任一指标命中“大”
+comet:
+  phase: verify
+  verify_mode: full
+  verify_result: pending
+```
+
+### 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 格式问题
+- 无硬编码密钥或安全问题
+
+## 退出条件
+
+- 验证报告通过
+- 分支已处理
+- `.openspec.yaml` 中 `comet.verify_result` 已记录为 `pass`
+
+退出前合并更新：
+
+```yaml
+comet:
+  phase: archive
+  verify_result: pass
+  verified_at: YYYY-MM-DD
+```
+
+## 自动流转
+
+退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
+
+> **REQUIRED NEXT SKILL:** 调用 `comet-archive` skill 进入归档阶段。

package/bin/comet.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/cli/index.js';

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { initCommand } from '../core/init.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json');
+const program = new Command();
+program
+    .name('comet')
+    .description('OpenSpec + Superpowers dual-star development workflow')
+    .version(version);
+program
+    .command('init [path]')
+    .description('Initialize Comet workflow in your project')
+    .option('--yes', 'Auto-install missing components, skip existing')
+    .option('--skip-existing', 'Never overwrite existing components')
+    .option('--overwrite', 'Overwrite manifest-managed files')
+    .action(async (targetPath = '.', options) => {
+    await initCommand(targetPath, options);
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,uDAAuD,CAAC;KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,aAAa,CAAC;KACtB,WAAW,CAAC,2CAA2C,CAAC;KACxD,MAAM,CAAC,OAAO,EAAE,gDAAgD,CAAC;KACjE,MAAM,CAAC,iBAAiB,EAAE,qCAAqC,CAAC;KAChE,MAAM,CAAC,aAAa,EAAE,kCAAkC,CAAC;KACzD,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1C,MAAM,WAAW,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/core/init.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Init Command
+ *
+ * Interactive setup for Comet workflow: platform selection, scope (global/project),
+ * OpenSpec + Superpowers install, and Comet skill deployment.
+ */
+type InitOptions = {
+    yes?: boolean;
+    skipExisting?: boolean;
+    overwrite?: boolean;
+};
+export declare function initCommand(targetPath: string, options?: InitOptions): Promise<void>;
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/core/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/core/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,KAAK,WAAW,GAAG;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAuWF,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmH9F"}