@rpamis/comet 0.1.4 → 0.1.5

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

@@ -1,151 +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`。
+---
+name: comet-archive
+description: "Comet Phase 5: Archive. Invoke with /comet-archive. Sync delta spec to main spec, archive change."
+---
+
+# Comet Phase 5: Archive (Archive)
+
+## Prerequisites
+
+- Verification passed (Phase 4 complete)
+- Branch handled
+- `verify_result: pass` in `openspec/changes/<name>/.comet.yaml`
+
+## 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 `"archive"`
+3. `verify_result` field value is `"pass"`
+4. `archived` field is `"false"` or null (not yet archived)
+
+**Verification method:**
+- `cat openspec/changes/<name>/.comet.yaml` to read all fields
+- If `verify_result` is not `"pass"`, must complete verification first
+
+**Failure output:**
+```
+[HARD STOP] Entry check failed for comet-archive
+  Expected: phase=archive, verify_result=pass, archived=false|null
+  Actual:   phase=<actual-value>, verify_result=<actual-value>, archived=<actual-value>
+  Suggestion: Run comet-verify first, or this change was already archived.
+```
+
+Proceed to Step 1 only after verification passes.
+
+### 1. Execute Archive
+
+Before archiving, if `verify_result` is not `pass`, stop archiving and return to `/comet-verify`.
+
+**Immediately execute:** Use the Skill tool to load the `openspec-archive-change` skill. Skipping this step is prohibited.
+
+After the skill loads, follow its guidance to archive. Automatic checks:
+1. Artifact completion status (proposal, design, specs, tasks)
+2. All tasks marked `[x]`
+3. Delta specs sync status
+
+### 1b. Move Comet State File
+
+`openspec-archive-change` is not aware of `.comet.yaml`, so Comet needs to move this file itself after OpenSpec archiving completes:
+
+```bash
+mv openspec/changes/<name>/.comet.yaml openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
+```
+
+【Write verification】After move completion, must verify:
+  test -f openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
+  Confirm .comet.yaml exists in archive directory
+  If file is not at expected location, check if mv command executed successfully.
+
+### 2. Delta Spec Sync
+
+Sync delta specs to main specs during archiving:
+
+```
+openspec/changes/<name>/specs/<capability>/spec.md
+       ↓ sync
+openspec/specs/<capability>/spec.md  ← main spec (persistent)
+```
+
+### 3. Design Doc & Plan Handling
+
+Handle associated files under `docs/superpowers/` during archiving. If target file already has YAML frontmatter, merge archive fields into existing frontmatter; if no frontmatter, create new frontmatter.
+
+**3a. Design Doc Consistency Annotation**
+
+Find design documents associated with current change in `docs/superpowers/specs/`:
+- Compare delta spec final version with design doc content
+- If there are discrepancies (incremental spec modifications during implementation), set the following metadata in design doc's YAML frontmatter:
+
+```yaml
+---
+archived-with: YYYY-MM-DD-<name>
+status: superseded-by-main-spec
+implementation-notes: |
+  <briefly describe key changes deviating from original design during implementation>
+---
+```
+
+- If completely consistent, only set:
+
+```yaml
+---
+archived-with: YYYY-MM-DD-<name>
+status: final
+---
+```
+
+**3b. Plan Association Annotation**
+
+Find implementation plans associated with current change in `docs/superpowers/plans/`, set the same `archived-with` metadata in YAML frontmatter.
+
+### 4. Archive Directory
+
+Change moves to archive directory:
+
+```
+openspec/changes/archive/YYYY-MM-DD-<name>/
+├── .openspec.yaml
+├── .comet.yaml
+├── proposal.md
+├── design.md
+├── specs/<capability>/spec.md
+└── tasks.md
+```
+
+### 5. Lifecycle Closed Loop
+
+Spec lifecycle completes here:
+```
+brainstorming → delta spec → implementation (incremental modifications) → verification → main spec sync → design doc annotation → archive
+```
+
+## Exit Conditions
+
+- Change archived (removed from active list)
+- Main specs updated (delta → main sync complete)
+- Associated design doc annotated with archive status
+- Associated plan annotated with archive status
+- `.comet.yaml` `archived` recorded as `true`
+- **Phase guard**: Run `bash $COMET_GUARD <change-name> archive`, confirm archive complete after all PASS
+
+After archiving completes, update `.comet.yaml` in archive directory:
+
+```yaml
+phase: archive
+archived: true
+```
+
+【Write verification】After update completion, must verify:
+  cat openspec/changes/archive/YYYY-MM-DD-<name>/.comet.yaml
+  Confirm phase line value is "archive"
+  Confirm archived line value is "true"
+  If any field does not match, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+
+## Complete
+
+Comet workflow complete. To start new work, invoke `/comet` or `/comet-open`.

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

@@ -1,161 +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 进入验证与收尾阶段。
+---
+name: comet-build
+description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create plans and execute implementation through subagent-driven-development."
+---
+
+# Comet Phase 3: Plan and Build (Build)
+
+## Prerequisites
+
+- Design Doc has been created (Phase 2 complete)
+- Active change exists
+
+## 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 `"build"`
+3. `design_doc` field is non-null and non-empty
+4. File referenced by `design_doc` exists (e.g., `docs/superpowers/specs/YYYY-MM-DD-topic-design.md`)
+5. `openspec/changes/<name>/proposal.md` exists and is non-empty
+6. `openspec/changes/<name>/tasks.md` exists and is non-empty
+
+**Verification method:**
+- `cat openspec/changes/<name>/.comet.yaml` to read all fields
+- Use `ls` or `test -f` to confirm design_doc file exists
+
+**Failure output:**
+```
+[HARD STOP] Entry check failed for comet-build
+  Expected: phase=build, design_doc=<path> exists
+  Actual:   phase=<actual-value>, design_doc=<actual-value or file does not exist>
+  Suggestion: Run comet-design first, or verify design_doc file exists.
+```
+
+Proceed to Step 1 only after verification passes.
+
+### 1. Create Plan
+
+**Immediately execute:** Use the Skill tool to load the `superpowers:writing-plans` skill. Skipping this step is prohibited.
+
+After the skill loads, follow its guidance to create a plan. Plan requirements:
+- Save to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
+- Reference design document, break down into executable tasks
+- **Plan file header must contain associated metadata**:
+
+```yaml
+---
+change: <openspec-change-name>
+design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
+---
+```
+
+### 2. Update Plan Status
+
+Merge and update the following fields in `openspec/changes/<name>/.comet.yaml` (keep other fields unchanged):
+
+```yaml
+phase: build
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+```
+
+【Write verification】After update completion, must verify:
+  cat openspec/changes/<name>/.comet.yaml
+  Confirm plan line value is "docs/superpowers/plans/YYYY-MM-DD-feature.md"
+  If not matching, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+
+### 3. Select Execution Method
+
+Present plan summary to user (task count, involved modules), then ask for execution method:
+
+| Option | Skill | Applicable Scenario |
+|------|------|-------------------|
+| A | `superpowers:subagent-driven-development` | Independent tasks, high complexity, requires two-phase review |
+| B | `superpowers:executing-plans` | Simple tasks, no subagent environment, lightweight and fast |
+
+**Recommendation rules**:
+- Task count ≥ 3 → Recommend A
+- Task count ≤ 2 and no cross-module dependencies → Recommend B
+- From hotfix path → Recommend B
+
+After user selection, merge and update `build_mode` in `openspec/changes/<name>/.comet.yaml` (keep other fields unchanged). `build_mode` only allows one of the following values:
+
+- `subagent-driven-development`
+- `executing-plans`
+- `direct` (only for hotfix preset use)
+
+Few-shot examples:
+
+```yaml
+# User selects robust mode / A
+build_mode: subagent-driven-development
+```
+
+```yaml
+# User selects fast mode / B
+build_mode: executing-plans
+```
+
+【Write verification】After update completion, must verify:
+  cat openspec/changes/<name>/.comet.yaml
+  Confirm build_mode line value is "<subagent-driven-development or executing-plans or direct>"
+  If not matching, retry write then verify again. Maximum 2 retries, report error and terminate if still fails.
+
+Then, **immediately execute:** Use the Skill tool to load the corresponding skill. Skipping this step is prohibited.
+
+If the selected Superpowers skill is unavailable, stop the process and prompt to install or enable the corresponding skill. Do not substitute this step with normal conversation.
+
+After the skill loads, follow its guidance to execute:
+- Execute tasks according to plan
+- Complete tasks.md check (`- [ ]` → `- [x]`)
+- Commit code after each task completion
+
+### 4. Spec Incremental Updates
+
+When the initial spec is found incomplete during implementation, handle by scale:
+
+| Scale | Trigger Conditions | Approach |
+|------|-------------------|----------|
+| Small | Missing acceptance scenarios, edge cases | Directly edit delta spec + design.md, append tasks.md tasks |
+| Medium | Interface changes, new components, data flow changes | Re-run `superpowers:brainstorming` to update Design Doc + delta spec |
+| Large | Brand-new capability requirements | `/opsx:new` to create independent change |
+
+**50% Threshold Determination**: Using initial task count in tasks.md as baseline, if new tasks exceed half of that total, it's considered outside original plan scope, should consider splitting into new change.
+
+**Principles**:
+- Delta spec is a living document, can be modified at any time during this phase
+- Each update should be committed with commit message explaining the change reason
+- Do not sync to main spec in advance, sync uniformly during archiving
+- If incremental tasks exceed 50% of initial tasks.md total task count, consider splitting into new change
+- For small-scale incremental direct delta spec edits, note in commit message to facilitate design doc drift assessment during archiving
+
+## Exit Conditions
+
+- All tasks.md checked
+- Code committed
+- Tests pass
+- `.comet.yaml` `phase` updated to `verify`
+- **Phase guard**: Run `bash $COMET_GUARD <change-name> build`, allow transition only after all PASS
+
+Before exit, merge and update the following fields in `.comet.yaml` (keep other fields unchanged):
+
+```yaml
+phase: verify
+verify_result: pending
+```
+
+【Write verification】After update completion, must verify:
+  cat openspec/changes/<name>/.comet.yaml
+  Confirm phase line value is "verify"
+  Confirm verify_result line value is "pending"
+  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-verify` skill to enter the verification and completion phase.