@rpamis/comet 0.1.4 → 0.1.6

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

@@ -1,165 +1,167 @@
----
-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`
+---
+name: comet-hotfix
+description: "Comet preset path: Bug fix / hotfix. Skip brainstorming, directly open → build → verify → archive. Applicable for behavior fixes, scenarios not involving new capability design."
+---
+
+# Comet Preset Path: Hotfix
+
+Hotfix is a preset workflow of Comet's five-phase capabilities, not a separate parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.
+
+Applicable for bug fixes, hotfixes, small-scale behavior corrections. Does not involve new capability design, does not require deep brainstorming.
+
+**Applicable conditions** (all must be met):
+1. Fix bugs in existing functionality, no new capability
+2. No interface changes or architecture adjustments
+3. Change scope is predictable (usually < 5 files)
+
+**Not applicable**: If fix process discovers need for architecture adjustments, should upgrade to full `/comet` workflow.
+
+---
+
+## Process (preset workflow, 4 phases)
+
+### 0. Entry State Verification (Entry Check)
+
+Before performing any operations, verify current state:
+
+**Checklist:**
+1. `openspec/changes/<name>/` directory does not exist, or directory exists but `.comet.yaml` does not exist (no conflict)
+
+**Verification method:**
+- `test -d openspec/changes/<name>` to check directory
+- If directory exists, `test -f openspec/changes/<name>/.comet.yaml` to check config file
+- If `.comet.yaml` exists, read `phase` to check if it's an incomplete hotfix
+
+**Failure output (has conflict):**
+```
+[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=<actual-value>
+  Suggestion: Pick a different change name, or check if an existing hotfix is in progress.
+```
+
+Proceed to process steps only after verification passes.
+
+Execution chain: open → build → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, scale-based verification, archive after verification passes.
+
+### 1. Quick Open (preset open)
+
+Reuse Comet open capability to create change, but use hotfix defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.
+
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
+
+After the skill loads, follow its guidance to create streamlined artifacts:
+  - `proposal.md` — problem description + root cause analysis + fix goal (no solution comparison needed)
+  - `design.md` — fix solution (one is enough, no multi-solution comparison needed)
+  - `tasks.md` — fix task list
+- **No delta spec needed** (unless fix changes existing spec acceptance scenarios)
+
+Create independent `.comet.yaml` file under `openspec/changes/<name>/`:
+
+```yaml
+workflow: hotfix
+phase: build
+design_doc: null
+plan: null
+build_mode: direct
+isolation: branch
+verify_mode: light
+verify_result: pending
+verified_at: null
+archived: false
+```
+
+【Write verification】After creation completion, must verify:
+  cat openspec/changes/<name>/.comet.yaml
+  Confirm workflow line value is "hotfix"
+  Confirm phase line value is "build"
+  Confirm design_doc line value is "null"
+  Confirm plan line value is "null"
+  Confirm build_mode line value is "direct"
+  Confirm isolation line value is "branch"
+  Confirm verify_mode line value is "light"
+  Confirm verify_result line value is "pending"
+  Confirm verified_at line value is "null"
+  Confirm archived line value is "false"
+  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+
+### 2. Direct Build (preset build)
+
+Use hotfix defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection).
+
+**Immediately execute:** Execute tasks one by one according to tasks.md:
+
+1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list
+2. For each incomplete task:
+   - Modify code according to task description
+   - Run `mvn spotless:apply` to format
+   - Run related tests to confirm pass
+   - Check corresponding `- [ ]` to `- [x]` in tasks.md
+   - Commit code, commit message format: `fix: <brief fix description>`
+3. After all tasks complete, enter verification
+
+**If fix affects existing spec acceptance scenarios**:
+- Create delta spec in `openspec/changes/<name>/specs/<capability>/spec.md`
+- Only include `## MODIFIED Requirements` section
+
+### 3. Verification (preset verify)
+
+Reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight or full verification.
+
+**Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
+
+Small-scale hotfixes without delta spec usually meet lightweight verification conditions (≤ 3 tasks, ≤ 5 files), comet-verify's scale assessment will select lightweight verification path (5 quick checks). If hotfix created delta spec, enter full verification path according to comet-verify's scale assessment rules.
+
+**Additional Hotfix-Exclusive Checks** (execute after comet-verify lightweight verification passes):
+
+1. **Root cause elimination**: Compare proposal.md's root cause analysis, confirm problem code eliminated
+   - Read bug description and root cause in proposal.md
+   - Search and verify problem code no longer exists
+   - If root cause not eliminated, return to Step 2 to continue fix
+
+**Verification phase upgrade conditions**:
+- Regression testing reveals deep architecture issues → Stop hotfix, upgrade to `/comet`
+- Fix requires additional interface changes → Stop hotfix, upgrade to `/comet`
+
+After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
+
+### 4. Archive (preset archive)
+
+Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving.
+
+**Immediately execute:** Use the Skill tool to load the `comet-archive` skill to archive. Skipping this step is prohibited.
+If there is delta spec, sync to main spec according to comet-archive rules, and handle associated Design Doc and Plan archiving annotations.
+
+---
+
+## Continuous Execution Mode
+
+<IMPORTANT>
+Hotfix workflow is **one-time continuous execution**. After invoking `/comet-hotfix`, agent must automatically complete all 4 phases, without pausing to wait for user input mid-way (unless encountering upgrade conditions requiring user confirmation).
+
+Execution order: quick open → direct build → verification → archive → complete
+
+After each phase completes, immediately enter next phase, no need for user input again. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements.
+</IMPORTANT>
+
+---
+
+## Upgrade Conditions
+
+When the following situations occur during fix process, stop hotfix workflow, upgrade to full `/comet`:
+
+1. Root cause discovered involves architecture defects
+2. Fix requires new interfaces or components
+3. Impact scope expands to > 10 files
+4. Needs new capability spec
+
+Upgrade method: On current change basis, supplement Design Doc (execute `/comet-design`), then proceed normally with full workflow.
+
+---
+
+## Exit Conditions
+
+- Bug fixed, tests pass
+- Change archived
+- If spec changes, synced to main spec
+- **Phase guard**: Before build → verify run `bash $COMET_GUARD <change-name> build`, before verify → archive run `bash $COMET_GUARD <change-name> verify`

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

@@ -1,123 +1,123 @@
----
-name: comet-open
-description: "Comet 阶段 1：开启。用 /comet-open 调用。通过 OpenSpec 探索想法、创建 change 结构（proposal + design + tasks）。"
----
-
-# Comet 阶段 1：开启（Open）
-
-## 前置条件
-
-- 无活跃 change，或用户希望创建新 change
-
-## 步骤
-
-### 0. 入口状态验证（Entry Check）
-
-在执行任何操作之前，读取并验证当前状态：
-
-**检查清单：**
-1. `openspec/changes/<name>/` 目录已存在（由 openspec-new-change 创建）
-2. `openspec/changes/<name>/.comet.yaml` 文件不存在（尚未初始化）
-3. `openspec/changes/<name>/proposal.md` 存在且非空
-4. `openspec/changes/<name>/design.md` 存在且非空
-5. `openspec/changes/<name>/tasks.md` 存在且非空
-
-**验证方式：**
-- 读取以上路径确认存在/不存在
-- 如 `.comet.yaml` 已存在，读取其 `phase` 字段：如 phase 不为空，输出 `[HARD STOP]` 并提示可能已有活跃 change
-
-**失败输出：**
-```
-[HARD STOP] Entry check failed for comet-open
-  Expected: .comet.yaml does not exist, proposal.md + design.md + tasks.md exist
-  Actual:   phase=<实际值>, design_doc=<实际值> (或文件不存在)
-  Suggestion: Check if another change with the same name is already active.
-```
-
-验证通过后才进入步骤 1。
-
-### 1. 探索想法
-
-**立即执行：** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
-
-技能加载后，按其指引自由探索问题空间。
-
-### 2. 创建 Change 结构
-
-**立即执行：** 使用 Skill 工具加载 `openspec-new-change` 技能。若用户意图未明确、需要先形成建议，改为加载 `openspec-propose`。禁止跳过此步骤。
-
-确认以下产物已创建：
-
-```
-openspec/changes/<name>/
-├── .openspec.yaml
-├── .comet.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>`
-
-### 3. 初始化 Comet 状态
-
-在 `openspec/changes/<name>/` 下创建独立的 `.comet.yaml` 文件：
-
-```yaml
-workflow: full
-phase: design
-design_doc: null
-plan: null
-build_mode: null
-verify_mode: null
-verify_result: pending
-verified_at: null
-archived: false
-```
-
-【写入验证】创建完成后必须验证：
-  cat openspec/changes/<name>/.comet.yaml
-  确认 workflow 行的值为 "full"
-  确认 phase 行的值为 "design"
-  确认 design_doc 行的值为 "null"
-  确认 plan 行的值为 "null"
-  确认 build_mode 行的值为 "null"
-  确认 verify_mode 行的值为 "null"
-  确认 verify_result 行的值为 "pending"
-  确认 verified_at 行的值为 "null"
-  确认 archived 行的值为 "false"
-  如任一字段不匹配，重试写入后再次验证。最多重试 2 次，仍失败则报告错误并终止。
-
-### 4. 内容完整性检查
-
-确认三个文档内容完整：
-- **proposal.md**：问题背景、目标、范围、非目标
-- **design.md**：高层架构决策、方案选型、数据流
-- **tasks.md**：任务列表，每个任务有明确描述
-
-## 退出条件
-
-- proposal.md、design.md、tasks.md 均已创建且内容完整
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> open`，全部 PASS 后才允许流转
-
-## 自动流转
-
-退出条件满足后，**无需等待用户再次输入**，直接执行下一阶段：
-
-> **REQUIRED NEXT SKILL:** 调用 `comet-design` skill 进入深度设计阶段。
+---
+name: comet-open
+description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas through OpenSpec and create change structure (proposal + design + tasks)."
+---
+
+# Comet Phase 1: Open
+
+## Prerequisites
+
+- No active change, or user wishes to create a new change
+
+## Steps
+
+### 0. Entry State Verification (Entry Check)
+
+Before performing any operations, read and verify the current state:
+
+**Checklist:**
+1. `openspec/changes/<name>/` directory exists (created by openspec-new-change)
+2. `openspec/changes/<name>/.comet.yaml` file does not exist (not yet initialized)
+3. `openspec/changes/<name>/proposal.md` exists and is non-empty
+4. `openspec/changes/<name>/design.md` exists and is non-empty
+5. `openspec/changes/<name>/tasks.md` exists and is non-empty
+
+**Verification method:**
+- Read the above paths to confirm existence/non-existence
+- If `.comet.yaml` already exists, read its `phase` field: if phase is not empty, output `[HARD STOP]` and prompt that there may already be an active change
+
+**Failure output:**
+```
+[HARD STOP] Entry check failed for comet-open
+  Expected: .comet.yaml does not exist, proposal.md + design.md + tasks.md exist
+  Actual:   phase=<actual-value>, design_doc=<actual-value> (or file does not exist)
+  Suggestion: Check if another change with the same name is already active.
+```
+
+Proceed to Step 1 only after verification passes.
+
+### 1. Explore Idea
+
+**Immediately execute:** Use the Skill tool to load the `openspec-explore` skill. Skipping this step is prohibited.
+
+After the skill loads, freely explore the problem space following its guidance.
+
+### 2. Create Change Structure
+
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. If user intent is unclear and needs to form a proposal first, load `openspec-propose` instead. Skipping this step is prohibited.
+
+Confirm the following artifacts have been created:
+
+```
+openspec/changes/<name>/
+├── .openspec.yaml
+├── .comet.yaml
+├── proposal.md       # Why + What: problem, goals, scope
+├── design.md         # How (high-level): architectural decisions, solution selection
+└── tasks.md          # Task checklist (checkboxes)
+```
+
+### 2b. Incrementally Modify Existing Capability (Optional)
+
+**Trigger condition:** proposal.md mentions modifying an existing capability, or user explicitly requests incremental modification.
+
+**Applicable scenario:** Incremental modification to archived functionality (not a brand-new capability).
+
+When proposal.md goals involve modifying an existing capability:
+1. Check if `openspec/specs/<capability>/spec.md` main spec already exists
+2. If it exists, copy the main spec as a delta spec baseline:
+
+```bash
+mkdir -p openspec/changes/<name>/specs/<capability>/
+cp openspec/specs/<capability>/spec.md openspec/changes/<name>/specs/<capability>/spec.md
+```
+
+3. In the copied delta spec, organize changes in delta format (`## ADDED`, `## MODIFIED`, `## REMOVED`)
+4. Note in proposal.md: `based on existing capability: <capability-name>`
+
+### 3. Initialize Comet State
+
+Create an independent `.comet.yaml` file under `openspec/changes/<name>/`:
+
+```yaml
+workflow: full
+phase: design
+design_doc: null
+plan: null
+build_mode: null
+verify_mode: null
+verify_result: pending
+verified_at: null
+archived: false
+```
+
+【Write verification】After creation, must verify:
+  cat openspec/changes/<name>/.comet.yaml
+  Confirm workflow line value is "full"
+  Confirm phase line value is "design"
+  Confirm design_doc line value is "null"
+  Confirm plan line value is "null"
+  Confirm build_mode line value is "null"
+  Confirm verify_mode line value is "null"
+  Confirm verify_result line value is "pending"
+  Confirm verified_at line value is "null"
+  Confirm archived line value is "false"
+  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+
+### 4. Content Completeness Check
+
+Confirm the three documents have complete content:
+- **proposal.md**: problem background, goals, scope, non-goals
+- **design.md**: high-level architectural decisions, solution selection, data flow
+- **tasks.md**: task list, each task has a clear description
+
+## Exit Conditions
+
+- proposal.md, design.md, and tasks.md are all created with complete content
+- **Phase guard**: Run `bash $COMET_GUARD <change-name> open`, allow transition only after all PASS
+
+## Automatic Transition
+
+After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
+
+> **REQUIRED NEXT SKILL:** Invoke `comet-design` skill to enter the deep design phase.