@rpamis/comet 0.2.3 → 0.2.5

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

@@ -11,17 +11,21 @@ description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas throug
 
 ## Steps
 
-### 0. Entry State Verification (Entry Check)
+### 0. Locate Comet Scripts
 
-Execute entry verification:
+Locate scripts before creating state:
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
-bash "$COMET_STATE" check <name> open
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
+
+if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
+  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
 ```
 
-Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
-
 ### 1. Explore Idea
 
 **Immediately execute:** Use the Skill tool to load the `openspec-explore` skill. Skipping this step is prohibited.
@@ -61,7 +65,15 @@ Confirm the three documents have complete content:
 ## 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
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> open --apply`; after all PASS, state automatically advances to the next phase
+
+You must use `--apply` before exiting. Otherwise `.comet.yaml` stays at `phase: open`, and the next phase entry check will fail.
+
+```bash
+bash "$COMET_GUARD" <change-name> open --apply
+```
+
+Full workflow advances to `phase: design`; hotfix/tweak presets advance to `phase: build`.
 
 ## Automatic Transition
 

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

@@ -13,7 +13,7 @@ Applicable for small-scale non-bug changes, such as copy adjustments, configurat
 1. No new capability
 2. No architecture changes
 3. No interface changes involved
-4. Usually not exceeding 3 tasks, 5 files
+4. Usually not exceeding 3 tasks, 4 files
 
 **Not applicable**: If change process discovers need for capability, architecture, or interface adjustments, should upgrade to full `/comet` workflow.
 
@@ -21,19 +21,17 @@ Applicable for small-scale non-bug changes, such as copy adjustments, configurat
 
 ## Process (preset workflow, 4 phases)
 
-### 0. Entry State Verification (Entry Check)
+Execution chain: open → lightweight build → light verify → archive. Tweak provides default decisions for each phase: streamlined open, lightweight build, lightweight verification, archive after verification passes.
 
-Execute entry verification:
+Locate Comet scripts before starting:
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
-bash "$COMET_STATE" check <name> open
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"
 ```
 
-Proceed to process steps after verification passes. The script outputs specific failure reasons when verification fails.
-
-Execution chain: open → lightweight build → light verify → archive. Tweak provides default decisions for each phase: streamlined open, lightweight build, lightweight verification, archive after verification passes.
-
 ### 1. Quick Open (preset open)
 
 Reuse Comet open capability to create change, but use tweak defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.
@@ -52,6 +50,12 @@ Initialize Comet state file:
 bash "$COMET_STATE" init <name> tweak
 ```
 
+Run phase guard to transition open → build:
+
+```bash
+bash "$COMET_GUARD" <change-name> open --apply
+```
+
 ### 2. Lightweight Build (preset build)
 
 Use tweak defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans`.
@@ -65,11 +69,18 @@ Use tweak defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `
    - Run related tests to confirm pass
    - Check corresponding `- [ ]` to `- [x]` in tasks.md
    - Commit code, commit message format: `tweak: <brief change description>`
-3. After all tasks complete, enter verification
+3. After all tasks complete, explicitly run relevant project tests and build commands
+4. Run phase guard to transition build → verify:
+
+```bash
+bash "$COMET_GUARD" <change-name> build --apply
+```
+
+State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
 
 ### 3. Lightweight Verification (preset verify)
 
-Reuse `/comet-verify`. Tweak must maintain lightweight verification conditions: ≤ 3 tasks, ≤ 5 files, no delta spec, no new capability.
+Reuse `/comet-verify`. Tweak must maintain lightweight verification conditions: ≤ 3 tasks, ≤ 4 files, no delta spec, no new capability.
 
 **Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
 
@@ -119,4 +130,4 @@ Upgrade method: On current change basis, supplement Design Doc (execute `/comet-
 - Small change completed, tests pass
 - Change archived
 - No new capability, architecture adjustments, or interface changes
-- **Phase guard**: Before build → verify run `bash $COMET_GUARD <change-name> build`, before verify → archive run `bash $COMET_GUARD <change-name> verify`
+- **Phase guard**: Before build → verify run `bash "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `bash "$COMET_GUARD" <change-name> verify --apply`

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

@@ -17,7 +17,9 @@ description: "Comet Phase 4: Verify and Complete. Invoke with /comet-verify. Ver
 Execute entry verification:
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
 bash "$COMET_STATE" check <name> verify
 ```
 
@@ -33,18 +35,38 @@ bash "$COMET_STATE" scale <name>
 
 Script automatically counts tasks, delta specs, and changed files to determine whether to use light or full verification mode, and sets the verify_mode field.
 
+Note: if the build phase committed after each task, worktree diff can underestimate change size. In that case, read the plan header `base-ref` and re-check the full commit range:
+
+```bash
+PLAN=$(bash "$COMET_STATE" get <name> plan)
+BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
+git diff --stat "$BASE_REF"...HEAD
+```
+
+If the commit range exceeds lightweight thresholds (> 5 files, cross-module coordination, or more than 1 delta spec capability), manually switch to full verification:
+
+```bash
+bash "$COMET_STATE" set <name> verify_mode full
+```
+
 ### 2a. Lightweight Verification (Small Changes)
 
 When scale assessment result is "small", skip `openspec-verify-change`, directly execute the following checks:
 
 1. All tasks in tasks.md completed `[x]`
-2. Changed files consistent with tasks.md description (`git diff --stat`对照 tasks content)
+2. Changed files consistent with tasks.md description (compare `git diff --stat` against task content)
 3. Build passes (run project-appropriate build command, e.g., `npm run build`, `mvn compile`, `cargo build`)
 4. Related tests pass
 5. No obvious security issues (no hardcoded secrets, no new unsafe operations)
 
 **Pass standard**: All 5 items OK, no CRITICAL issues.
 
+**When failing**: report failed items, record failure, move back to build, then invoke `/comet-build`.
+
+```bash
+bash "$COMET_STATE" transition <name> verify-fail
+```
+
 **Report format**: Brief table listing 5 check results + PASS/FAIL.
 
 **Skipped items** (not checked in lightweight verification):
@@ -68,7 +90,11 @@ After the skill loads, follow its guidance to verify. Check items:
 6. No contradiction between delta spec and design doc (if Build phase had incremental spec modifications, check if design doc has corresponding records)
 7. `docs/superpowers/specs/` associated design document can be located (file exists and relates to current change)
 
-When verification fails: report missing items, return to Phase 3 to supplement (invoke `/comet-build`).
+When verification fails: report missing items, record failure, move back to build, then invoke `/comet-build`.
+
+```bash
+bash "$COMET_STATE" transition <name> verify-fail
+```
 
 **Spec drift handling**:
 - If check item 6 finds contradiction (delta spec has content but design doc doesn't reflect it), prompt user:
@@ -96,13 +122,12 @@ After the skill loads, follow its guidance to complete. Branch handling options:
 
 - Verification report passed
 - Branch handled
-- `.comet.yaml` `verify_result` recorded as `pass`
-- **Phase guard**: Run `bash $COMET_GUARD <change-name> verify`, allow transition only after all PASS
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> verify --apply`; after all PASS, it uses `comet-state transition verify-pass` to advance to `phase: archive`
 
-Before exit, run guard to auto-transition:
+After verification and branch handling are complete, run guard to auto-transition:
 
 ```bash
-bash $COMET_GUARD <change-name> verify --apply
+bash "$COMET_GUARD" <change-name> verify --apply
 ```
 
 State file is automatically updated to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.

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

@@ -22,33 +22,51 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 ### 阶段自动检测
 
-**Step 0: 活跃 Change 发现**
+**Step 0: 活跃 Change 发现与意图判定**
 
-1. 运行 `openspec list --json` 获取所有活跃 change
-2. 对每个 change，检查 `docs/superpowers/specs/` 和 `docs/superpowers/plans/` 匹配关联文件，判断阶段和进度
+1. 先做 Preset 检测；命中 hotfix/tweak 时直接调用对应 preset skill，不进入普通 open 分支
+2. 未命中 preset 时，运行 `openspec list --json` 获取所有活跃 change
 
-| 情况 | 行为 |
-|------|------|
-| 无活跃 change | → 调用 `/comet-open` |
-| 恰好 1 个活跃 change | → 自动选中，进入 Step 1 |
-| 多个活跃 change | → 列出清单让用户选择 |
-
-**Preset 检测**：
+**Preset 检测优先级最高**：
 - 用户明确描述为 bug fix / 热修复 + 满足 hotfix 条件 → 直接 `/comet-hotfix`
 - 用户明确描述为文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接 `/comet-tweak`
+- 未命中 preset → 按下表处理
+
+| 活跃 change | 用户输入 | 行为 |
+|-------------|---------|------|
+| 无 | 非 preset 输入 | → 调用 `/comet-open` |
+| 恰好 1 个 | `/comet <描述>` | → **询问**：继续该变更 or 创建新变更 |
+| 多个 | `/comet <描述>` | → **询问**：继续现有变更 or 创建新变更；若选继续 → 列出清单让用户选择 |
+| 恰好 1 个 | `/comet`（无描述） | → 自动选中，进入 Step 1 |
+| 多个 | `/comet`（无描述） | → 列出清单让用户选择 |
+
+<IMPORTANT>
+当用户选择「创建新变更」时，**必须调用 `/comet-open`**（禁止直接调用 `/opsx:new`）。
+`/comet-open` 负责完整双初始化：OpenSpec artifacts（由内部 `/opsx:new` 创建）+ `.comet.yaml` 状态文件。
+直接调用 `/opsx:new` 会缺失 `.comet.yaml`，导致后续阶段判定失败。
+</IMPORTANT>
 
 **Step 1: 读取 `.comet.yaml` 状态元数据**
 
 优先读取 `openspec/changes/<name>/.comet.yaml`。不存在时回退到 `openspec status --change "<name>" --json`、`tasks.md` 和 `docs/superpowers/` 文件检查。
 
+**断点恢复规则**：
+- 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
+- 若 `phase: build`，读取 tasks.md 的下一个未勾选任务继续
+- 若 `phase: verify` 且 `verify_result: fail`，先运行 `bash "$COMET_STATE" transition <name> verify-fail`，再调用 `/comet-build`
+- 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `bash "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定
+- 若 `phase: archive`，只允许调用 `/comet-archive`；归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard
+
 **Step 2: 阶段判定**（按顺序，命中即停）
 
 1. `archived: true` 或 change 已移入 archive → 流程已完成
 2. `verify_result: pass` 且 `archived` 不是 `true` → `/comet-archive`
-3. `phase: verify` 或 tasks.md 全部勾选 → `/comet-verify`
-4. `phase: build` 或已有 Design Doc 但计划/执行未完成 → `/comet-build`
-5. `phase: design` 或有 change 但无 Design Doc → `/comet-design`
-6. 无活跃 change 或状态无法判定 → `/comet-open`
+3. `verify_result: fail` → `bash "$COMET_STATE" transition <name> verify-fail` 后 `/comet-build`
+4. `phase: verify` 或 tasks.md 全部勾选 → `/comet-verify`
+5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → `/comet-build`
+6. `phase: design` 或有 change 但无 Design Doc → `/comet-design`
+7. `phase: open` 或有活跃 change 但 `.comet.yaml` 缺失 → `/comet-open`
+8. 无活跃 change → `/comet-open`
 
 如果元数据与文件状态冲突，以文件状态为准，修正 `.comet.yaml` 后继续。
 
@@ -74,7 +92,7 @@ agent 做决策只需读本节，参考附录按需查阅。
 | `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
 | 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
 | `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `bash $COMET_STATE set` 修正后继续 |
-| Maven 编译/测试失败 | 返回 build 阶段修复，不进入 verify |
+| 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
 | change 目录结构不完整 | 按 `comet-open` 产物要求补齐 |
 
 ### 阶段衔接
@@ -84,14 +102,16 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 流转链：open → design → build → verify → archive
 
-需要用户参与的节点：
+**连续执行要求**：从检测到的阶段开始，agent 必须自动走完后续所有阶段，中间不停顿等待用户输入（除非遇到需要用户决策的节点）。每个阶段完成后立即进入下一阶段，无需用户再次输入。
+
+需要用户参与的节点（仅在这些节点暂停）：
 1. brainstorming 确认设计方案
 2. build 阶段选择执行方式
 3. verify 不通过时决定修复或接受偏差
 4. finishing-branch 选择分支处理方式
 5. 遇到升级条件（hotfix/tweak → 完整流程）
 
-agent 不应跳过这些决策点；其他明确无歧义的阶段衔接可以继续推进。
+agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。
 </IMPORTANT>
 
 ---
@@ -138,6 +158,8 @@ build_mode: subagent-driven-development
 isolation: branch
 verify_mode: light
 verify_result: pending
+verification_report: null
+branch_status: pending
 verified_at: null
 archived: false
 ```
@@ -145,13 +167,15 @@ archived: false
 | 字段 | 含义 |
 |------|------|
 | `workflow` | `full`、`hotfix` 或 `tweak` |
-| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive` |
+| `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive`（init 统一设为 `open`，guard 负责过渡） |
 | `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
 | `plan` | 关联的 Superpowers Plan 路径，可为空 |
 | `build_mode` | 已选择的执行方式，可为空 |
 | `isolation` | `branch` 或 `worktree`，工作区隔离方式，默认 `branch` |
 | `verify_mode` | `light` 或 `full`，可为空 |
 | `verify_result` | `pending`、`pass` 或 `fail` |
+| `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
+| `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
 | `verified_at` | 验证通过时间，可为空 |
 | `archived` | change 是否已归档 |
 
@@ -160,9 +184,17 @@ archived: false
 Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量：
 
 ```bash
-COMET_GUARD="${COMET_GUARD:-$(find . -path '*/comet/scripts/comet-guard.sh' -type f -print -quit)}"
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
-COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)}"
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"
+
+# 脚本定位失败时停止流程
+if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_ARCHIVE" ]; then
+  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
+  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
+  return 1
+fi
 ```
 
 **自动状态更新**：guard 支持 `--apply` 参数，验证通过后自动更新 `.comet.yaml` 状态字段：
@@ -171,6 +203,17 @@ COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh
 bash "$COMET_GUARD" <change-name> <phase> --apply
 ```
 
+`--apply` 内部委托给 `comet-state transition`。需要直接表达状态事件时使用：
+
+```bash
+bash "$COMET_STATE" transition <change-name> open-complete
+bash "$COMET_STATE" transition <change-name> design-complete
+bash "$COMET_STATE" transition <change-name> build-complete
+bash "$COMET_STATE" transition <change-name> verify-pass
+bash "$COMET_STATE" transition <change-name> verify-fail
+bash "$COMET_STATE" transition <archive-name> archived
+```
+
 **归档脚本**：一键完成归档全部步骤：
 
 ```bash

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

@@ -18,7 +18,8 @@ description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta
 执行入口验证：
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
 bash "$COMET_STATE" check <name> archive
 ```
 
@@ -29,7 +30,6 @@ bash "$COMET_STATE" check <name> archive
 运行归档脚本，自动完成以下全部步骤：
 
 ```bash
-COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)}"
 bash "$COMET_ARCHIVE" "<change-name>"
 ```
 
@@ -39,7 +39,7 @@ bash "$COMET_ARCHIVE" "<change-name>"
 3. Design doc 前置元数据标注（archived-with, status）
 4. Plan 前置元数据标注（archived-with）
 5. 移动 change 到归档目录
-6. 更新 archived: true
+6. 通过 `comet-state transition <archive-name> archived` 更新 `archived: true`
 
 如脚本返回非零退出码，报告错误并停止。
 如脚本返回零退出码，归档完成。
@@ -56,7 +56,10 @@ brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → desig
 ## 退出条件
 
 - 归档脚本执行成功（退出码 0）
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> archive`，全部 PASS 后确认归档完整
+- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<change-name>/` 存在
+- 归档后的 `.comet.yaml` 中 `archived: true`
+
+归档脚本会把 `openspec/changes/<name>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。归档成功后**不要再对原 change 名运行** `bash "$COMET_GUARD" <change-name> archive`，因为原活跃目录已经不存在。归档完整性以脚本退出码和归档目录状态为准。
 
 ## 完成
 

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

@@ -17,7 +17,9 @@ description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制
 执行入口验证：
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
 bash "$COMET_STATE" check <name> build
 ```
 
@@ -36,9 +38,16 @@ bash "$COMET_STATE" check <name> build
 ---
 change: <openspec-change-name>
 design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
+base-ref: <git rev-parse HEAD before implementation>
 ---
 ```
 
+`base-ref` 用于验证阶段跨提交统计改动规模。创建计划时先记录当前提交：
+
+```bash
+git rev-parse HEAD
+```
+
 ### 2. 更新计划状态
 
 先记录 plan 路径：
@@ -127,21 +136,27 @@ bash "$COMET_STATE" set <name> build_mode <value>
 - delta spec 是活文档，本阶段期间随时可修改
 - 每次更新应提交，commit message 说明变更原因
 - 不提前同步到 main spec，归档时统一同步
-- 如增量任务超过原 tasks.md 初始任务总数 50%，考虑拆分为新 change
 - 小规模增量直接改 delta spec 时，应在 commit message 中注明，便于归档时判断 design doc 漂移
 
+### 6. 上下文管理
+
+Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：
+
+- **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.comet.yaml` 和文件状态持久化
+- **上下文压缩后恢复**：读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到下一个未勾选任务继续执行
+- **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交
+
 ## 退出条件
 
 - tasks.md 全部勾选
 - 代码已提交
-- 测试通过
-- `.comet.yaml` 中 `phase` 已更新为 `verify`
-- **阶段守卫**：运行 `bash $COMET_GUARD <change-name> build`，全部 PASS 后才允许流转
+- 已显式运行项目对应的构建/测试命令并通过（不要只依赖 guard 自动猜测）
+- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> build --apply`，全部 PASS 后自动流转到 `phase: verify`
 
 退出前运行 guard 自动流转：
 
 ```bash
-bash $COMET_GUARD <change-name> build --apply
+bash "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`。

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

@@ -17,7 +17,9 @@ description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过
 执行入口验证：
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
 bash "$COMET_STATE" check <name> design
 ```
 
@@ -57,32 +59,23 @@ Design 摘要: <design.md 架构决策>
 bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # 自动流转到下一阶段
-bash $COMET_GUARD <change-name> design --apply
+bash "$COMET_GUARD" <change-name> design --apply
 ```
 
 状态文件自动更新，无需手动编辑其他字段。
 
-### 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 后才允许流转
+- `design_doc` 已写入 `.comet.yaml`
+- **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
+
+退出前必须使用 `--apply`：
+
+```bash
+bash "$COMET_GUARD" <change-name> design --apply
+```
 
 ## 自动流转
 

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

@@ -5,14 +5,12 @@ description: "Comet 预设路径：Bug fix / 热修复。跳过 brainstorming，
 
 # Comet 预设路径：Hotfix
 
-Hotfix 是 Comet 五阶段能力的预设工作流，不是独立的平行流程。它复用 open、build、verify、archive 能力，仅跳过 brainstorming 和完整 plan。
-
-适用于 bug fix、热修复、小范围行为修正。不涉及新 capability 设计，不需要深度 brainstorming。
+快速 bug fix 工作流：open → build → verify → archive。跳过 brainstorming 和完整 plan，适用于行为修复、不涉及新 capability 设计的场景。
 
 **适用条件**（必须全部满足）：
 1. 修复已有功能的 bug，不新增 capability
 2. 不涉及接口变更或架构调整
-3. 改动范围可预估（通常 < 5 个文件）
+3. 改动范围可预估（通常 ≤ 2 个文件）
 
 **不适用**：如修复过程发现需要架构调整，应升级为完整 `/comet` 流程。
 
@@ -20,19 +18,17 @@ Hotfix 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 
 ## 流程（preset workflow，4 阶段）
 
-### 0. 入口状态验证（Entry Check）
+执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后归档。
 
-执行入口验证：
+开始前先定位 Comet 脚本：
 
 ```bash
-COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
-bash "$COMET_STATE" check <name> open
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"
 ```
 
-验证通过后继续流程步骤。验证失败时脚本会输出具体失败原因。
-
-执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后归档。
-
 ### 1. 快速开启（preset open）
 
 复用 Comet open 能力创建 change，但使用 hotfix 默认值：不执行 `openspec-explore` 长探索，直接进入精简 change 创建。
@@ -51,6 +47,18 @@ bash "$COMET_STATE" check <name> open
 bash "$COMET_STATE" init <name> hotfix
 ```
 
+初始化后验证状态：
+
+```bash
+bash "$COMET_STATE" check <name> open
+```
+
+阶段守卫完成 open → build 过渡：
+
+```bash
+bash "$COMET_GUARD" <change-name> open --apply
+```
+
 ### 2. 直接构建（preset build）
 
 使用 hotfix 默认值：`build_mode: direct`。跳过 `superpowers:brainstorming` 和 `superpowers:writing-plans`（除非任务 > 3 个；若超过 3 个任务，转入 `/comet-build` 的计划与执行方式选择）。
@@ -64,30 +72,38 @@ bash "$COMET_STATE" init <name> hotfix
    - 运行相关测试确认通过
    - 将 tasks.md 中对应 `- [ ]` 勾选为 `- [x]`
    - 提交代码，commit message 格式：`fix: <简述修复>`
-3. 全部任务完成后进入验证
+3. 全部任务完成后，显式运行项目相关测试和构建命令
+4. 运行阶段守卫完成 build → verify 过渡：
+
+```bash
+bash "$COMET_GUARD" <change-name> build --apply
+```
+
+状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
 
 **如修复影响已有 spec 验收场景**：
 - 在 `openspec/changes/<name>/specs/<capability>/spec.md` 创建 delta spec
 - 仅包含 `## MODIFIED Requirements` 部分
 
-### 3. 验证（preset verify）
+### 3a. Hotfix 专属检查：根因消除
 
-复用 `/comet-verify`，由 comet-verify 的规模评估决定轻量或完整验证。
+**在加载 comet-verify 之前执行**，确保修复确实消除了问题根因：
 
-**立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
+1. 读取 proposal.md 中的 bug 描述和根因
+2. 搜索验证问题代码不再存在
+3. 如根因未消除，返回 Step 2 继续修复
+
+**升级条件**：
+- 根因消除检查发现深层架构问题 → 停止 hotfix，升级为 `/comet`
+- 修复需要额外接口变更 → 停止 hotfix，升级为 `/comet`
 
-无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、≤ 5 files），comet-verify 的规模评估会选择轻量验证路径（5 项快速检查）。若 hotfix 创建了 delta spec，则根据 comet-verify 的规模评估规则进入完整验证路径。
+### 3b. 验证（preset verify）
 
-**额外 Hotfix 专属检查**（在 comet-verify 轻量验证通过后执行）：
+根因消除检查通过后，复用 `/comet-verify`，由 comet-verify 的规模评估决定轻量或完整验证。
 
-1. **根因消除**：对照 proposal.md 的根因分析，确认问题代码已消除
-   - 读取 proposal.md 中的 bug 描述和根因
-   - 搜索验证问题代码不再存在
-   - 如根因未消除，返回 Step 2 继续修复
+**立即执行：** 使用 Skill 工具加载 `comet-verify` 技能。禁止跳过此步骤。
 
-**验证阶段升级条件**：
-- 回归测试揭示深层架构问题 → 停止 hotfix，升级为 `/comet`
-- 修复需要额外接口变更 → 停止 hotfix，升级为 `/comet`
+无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、≤ 2 files），comet-verify 的规模评估会选择轻量验证路径（5 项快速检查）。若 hotfix 创建了 delta spec，则根据 comet-verify 的规模评估规则进入完整验证路径。
 
 验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。
 
@@ -133,4 +149,4 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 - Bug 已修复，测试通过
 - change 已归档
 - 如有 spec 变更，已同步到 main spec
-- **阶段守卫**：build → verify 前运行 `bash $COMET_GUARD <change-name> build`，verify → archive 前运行 `bash $COMET_GUARD <change-name> verify`
+- **阶段守卫**：build → verify 前运行 `bash "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `bash "$COMET_GUARD" <change-name> verify --apply`