@rpamis/comet 0.3.0 → 0.3.2

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

@@ -1,14 +1,14 @@
 ---
 name: comet-verify
-description: "Comet Phase 4: Verify and Complete. Invoke with /comet-verify. Verify implementation matches design, handle development branch."
+description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify implementation matches design, handle development branch."
 ---
 
-# Comet Phase 4: Verify and Complete (Verify)
+# Comet Phase 4: Verify and Close (Verify)
 
 ## Prerequisites
 
-- Code has been committed (Phase 3 complete)
-- All tasks in tasks.md are complete
+- Code committed (Phase 3 complete)
+- All tasks.md tasks completed
 
 ## Steps
 
@@ -17,15 +17,18 @@ description: "Comet Phase 4: Verify and Complete. Invoke with /comet-verify. Ver
 Execute entry verification:
 
 ```bash
-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_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
 bash "$COMET_STATE" check <change-name> verify
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
-### 1. Change Scale Assessment
+### 1. Scale Assessment
 
 Execute scale assessment:
 
@@ -33,21 +36,22 @@ Execute scale assessment:
 bash "$COMET_STATE" scale <change-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.
+The script automatically counts tasks, delta spec count, changed file count, determines light or full verification mode, and sets the verify_mode field.
 
-Before verification starts, inspect and handle uncommitted changes through `comet/reference/dirty-worktree.md`. Verify-specific handling:
+Before verification begins, handle uncommitted changes through `comet/reference/dirty-worktree.md` protocol. Verify phase special handling:
 
-1. If dirty diff belongs to the current change and involves implementation, tests, tasks, delta spec, or design doc changes, do not fix or commit directly in verify; record failure and return to build
-2. If dirty diff is only a verify-phase artifact, such as a verification report draft or branch-handling record, continue in verify and record state
-3. If dirty diff has implemented work but tasks.md is unchecked, treat it as stale build state; record failure and return to build so `/comet-build` verifies the implementation, checks off tasks, and commits
+1. If dirty diff belongs to current change and involves implementation, tests, tasks, delta spec, or design doc changes, do not fix or commit directly in verify phase; report failures and enter Step 1b verification failure decision blocking point
+2. If dirty diff is only verify phase artifacts (e.g., verification report draft, branch handling records), may continue and record state in verify phase
+3. If dirty diff shows implementation but tasks.md not checked, treat as build state lag; report failures and enter Step 1b, let user decide to roll back for fix or accept deviation
 
-Return to build:
+Only after user chooses fix, allow rollback to build phase:
 
 ```bash
+# Execute only after user confirms fix
 bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
-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:
+Note: If every task in build phase was committed, the script's file count based on working tree diff may underestimate change scale. In this case, must read plan file header `base-ref` and verify with commit range:
 
 ```bash
 PLAN=$(bash "$COMET_STATE" get <change-name> plan)
@@ -55,27 +59,41 @@ 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:
+If commit range shows changes exceed lightweight threshold (> 4 files, cross-module coordination, or delta spec spans more than 1 capability), manually set to full verification:
 
 ```bash
 bash "$COMET_STATE" set <change-name> verify_mode full
 ```
 
+### 1b. Verification Failure Decision (Blocking Point)
+
+When verification does not pass, must pause and wait for the user to decide fix or accept deviation. Must not automatically run `bash "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`.
+
+When pausing, must list:
+- Failed items
+- Whether CRITICAL (build failure, test failure, security issues, core acceptance scenario failure)
+- Recommended handling approach
+
+After user selection, continue as follows:
+- **Fix all**: Run `bash "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
+- **Handle item by item**: CRITICAL failures must be fixed; non-CRITICAL failures may choose to accept deviation, but must record acceptance reason and impact scope in verification report. If any CRITICAL failure exists, skipping fix to accept all is not allowed
+
 ### 2a. Lightweight Verification (Small Changes)
 
-When scale assessment result is "small", skip `openspec-verify-change`, directly execute the following checks:
+When scale assessment result is "small", skip `openspec-verify-change` and directly execute these checks:
 
-1. All tasks in tasks.md completed `[x]`
-2. Changed files consistent with tasks.md description (compare `git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` against task content)
-3. Build passes (run project-appropriate build command, e.g., `npm run build`, `mvn compile`, `cargo build`)
+1. All tasks.md tasks completed `[x]`
+2. Changed files match tasks.md descriptions (`git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` compared against tasks content)
+3. Build passes (run project-specific build command, e.g., `npm run build`, `mvn compile`, `cargo build`, etc.)
 4. Related tests pass
-5. No obvious security issues (no hardcoded secrets, no new unsafe operations)
+5. No obvious security issues (no hardcoded keys, no new unsafe operations)
 
-**Pass standard**: All 5 items OK, no CRITICAL issues.
+**Pass criteria**: All 5 items OK, no CRITICAL issues.
 
-**When failing**: report failed items, record failure, move back to build, then invoke `/comet-build`.
+**When not passing**: Report failures, enter Step 1b verification failure decision blocking point. Only after user confirms fix, execute the following command to record failure and roll back to build phase, then invoke `/comet-build` to fix:
 
 ```bash
+# Execute only after user confirms fix
 bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
@@ -84,7 +102,7 @@ bash "$COMET_STATE" transition <change-name> verify-fail
 **Skipped items** (not checked in lightweight verification):
 - spec scenario coverage
 - design doc consistency deep comparison
-- code pattern consistency recommendations
+- code pattern consistency suggestions
 - delta spec and design doc drift detection
 
 ### 2b. Full Verification (Large Changes)
@@ -94,49 +112,52 @@ When scale assessment result is "large":
 **Immediately execute:** Use the Skill tool to load the `openspec-verify-change` skill. Skipping this step is prohibited.
 
 After the skill loads, follow its guidance to verify. Check items:
-1. All tasks in tasks.md completed (`[x]`)
-2. Implementation matches design.md design decisions
-3. Implementation matches brainstorming design document
-4. All capability specification scenarios pass
-5. proposal.md goals satisfied
-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)
+1. All tasks.md tasks completed (`[x]`)
+2. Implementation matches `openspec/changes/<name>/design.md` high-level design decisions
+3. Implementation matches Design Doc (technical design documents under `docs/superpowers/specs/`)
+4. All capability spec scenarios pass
+5. proposal.md goals are satisfied
+6. No contradictions between delta spec and design doc (if Build phase had incremental spec modifications, check if design doc has corresponding records)
+7. Associated design documents under `docs/superpowers/specs/` are locatable (file exists and is related to current change)
 
-When verification fails: report missing items, record failure, move back to build, then invoke `/comet-build`.
+When verification does not pass: report missing items, enter Step 1b verification failure decision blocking point. Only after user confirms fix, execute the following command to record failure and roll back to build phase, then invoke `/comet-build` to supplement:
 
 ```bash
+# Execute only after user confirms fix
 bash "$COMET_STATE" transition <change-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:
-  - Option A: Append "Implementation Divergence" section to design doc recording deviation reason
-  - Option B: Roll back to Build phase, supplement brainstorming to update design doc
-  - Option C: Confirm deviation acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
+**Spec Drift Handling** (user decision point):
+- If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must pause and wait for user to choose handling method**; must not select automatically. Options:
+  - Option A: Append "Implementation Divergence" section to design doc recording deviation reason. Option A is a verify phase allowed artifact; after writing, must not re-trigger Step 1b dirty-worktree decision due to that design doc change
+  - Option B: After user selects B, run `bash "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load `superpowers:brainstorming` to update Design Doc + delta spec
+  - Option C: Confirm deviation is acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
 
-### 3. Completion (Superpowers)
+### 3. Finishing (Superpowers)
 
 **Immediately execute:** Use the Skill tool to load the `superpowers:finishing-a-development-branch` skill. Skipping this step is prohibited.
 
 If `superpowers:finishing-a-development-branch` is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.
 
-After the skill loads, follow its guidance to complete. Branch handling options:
-1. Local merge to main branch
+After the skill loads, follow its guidance to finish. Branch handling options:
+1. Merge to main branch locally
 2. Push and create PR
 3. Keep branch (handle later)
 4. Discard work
 
+This is a user decision point. **Must pause and wait for user to choose branch handling method**. Must not select based on recommendations, defaults, or current branch status. Only after the user completes selection and the corresponding operation finishes, may `branch_status: handled` be written.
+
 **Confirmation items**:
 - All tests pass
-- No hardcoded secrets or security issues
+- No hardcoded keys or security issues
 
 ### 4. Record Verification Evidence
 
-The verification report must be written to disk and recorded in `.comet.yaml`; branch handling must also be written to state after it completes. Do not manually set `verify_result: pass`; guard performs the transition.
+Verification report must be saved to disk and recorded in `.comet.yaml`; after branch handling completes, state fields must also be written. Do not manually set `verify_result: pass`; use guard for auto-transition.
 
 ```bash
 mkdir -p docs/superpowers/reports
-# Write this verification result to a report file, for example:
+# Write verification conclusions to report file, e.g.:
 # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
 
 bash "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
@@ -147,20 +168,20 @@ bash "$COMET_STATE" set <change-name> branch_status handled
 
 - Verification report passed
 - Branch handled
-- `.comet.yaml` `verification_report` points to an existing verification report file
-- `.comet.yaml` has `branch_status: handled`
-- **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`
+- `verification_report` in `.comet.yaml` points to an existing verification report file
+- `branch_status: handled` in `.comet.yaml`
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
 
-After verification and branch handling are complete, run guard to auto-transition:
+After both verification and branch handling are complete, run guard for auto-transition:
 
 ```bash
 bash "$COMET_GUARD" <change-name> verify --apply
 ```
 
-State file is automatically updated to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
+State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
 
 ## Automatic Transition
 
 After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
 
-> **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archiving phase.
+> **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archive phase.

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

@@ -53,8 +53,8 @@ agent 做决策只需读本节，参考附录按需查阅。
 **断点恢复规则**：
 - 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
 - 只要存在 active change 且工作区有未提交改动，必须按 `comet/reference/dirty-worktree.md` 协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复
-- 若 `phase: build`，读取 tasks.md 的下一个未勾选任务继续
-- 若 `phase: verify` 且 `verify_result: fail`，先运行 `bash "$COMET_STATE" transition <name> verify-fail`，再调用 `/comet-build`
+- 若 `phase: build`，先检查 `build_mode` 和 `isolation` 是否已设置；若有未设置的字段，回到 `/comet-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
 
@@ -62,9 +62,9 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 1. `archived: true` 或 change 已移入 archive → 流程已完成
 2. `verify_result: pass` 且 `archived` 不是 `true` → `/comet-archive`
-3. `verify_result: fail` → `bash "$COMET_STATE" transition <name> verify-fail` 后 `/comet-build`
+3. `verify_result: fail` → 进入验证失败决策阻塞点（暂停询问修复或接受偏差；用户选择修复后才 `verify-fail` 并 `/comet-build`）
 4. `phase: verify` 或 tasks.md 全部勾选 → `/comet-verify`
-5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → `/comet-build`
+5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → 优先按 workflow 路由：`hotfix` → `/comet-hotfix`，`tweak` → `/comet-tweak`，`full` → `/comet-build`
 6. `phase: design` 或有 change 但无 Design Doc → `/comet-design`
 7. `phase: open` 或有活跃 change 但 `.comet.yaml` 缺失 → `/comet-open`
 8. 无活跃 change → `/comet-open`
@@ -103,14 +103,17 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 流转链：open → design → build → verify → archive
 
-**连续执行要求**：从检测到的阶段开始，agent 必须自动走完后续所有阶段，中间不停顿等待用户输入（除非遇到需要用户决策的节点）。每个阶段完成后立即进入下一阶段，无需用户再次输入。
+**连续执行要求**：从检测到的阶段开始，agent 必须自动推进后续阶段；自动推进只适用于没有用户决策的衔接点。遇到用户决策点时必须暂停并等待用户明确回复，不得用推荐规则、默认值或历史偏好代替用户确认。
+
+**决策点是阻塞点**：只要到达下列任一节点，当前 `/comet` 调用必须停住。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
 
 需要用户参与的节点（仅在这些节点暂停）：
 1. brainstorming 确认设计方案
-2. build 阶段选择执行方式
-3. verify 不通过时决定修复或接受偏差
+2. build 阶段选择工作方式（隔离方式 + 执行方式，一次交互完成）
+3. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
 4. finishing-branch 选择分支处理方式
 5. 遇到升级条件（hotfix/tweak → 完整流程）
+6. build 阶段范围扩张需重新设计或拆分新 change
 
 agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。
 </IMPORTANT>
@@ -137,11 +140,11 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 
 /comet-hotfix（预设路径，跳过 brainstorming）
   open ──→ build ──→ verify ──→ archive
-    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
 
 /comet-tweak（预设路径，跳过 brainstorming 和完整 plan）
   open ──→ lightweight build ──→ light verify ──→ archive
-    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
 ```
 
 ---
@@ -155,12 +158,14 @@ workflow: full
 phase: build
 design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+base_ref: a1b2c3d4e5f6...
 build_mode: subagent-driven-development
 isolation: branch
 verify_mode: light
 verify_result: pending
 verification_report: null
 branch_status: pending
+created_at: 2026-05-26
 verified_at: null
 archived: false
 ```
@@ -171,12 +176,14 @@ archived: false
 | `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive`（init 统一设为 `open`，guard 负责过渡） |
 | `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
 | `plan` | 关联的 Superpowers Plan 路径，可为空 |
+| `base_ref` | init 时记录的 git commit SHA，用于 scale 评估。无 plan 时作为改动文件数统计基准 |
 | `build_mode` | 已选择的执行方式，可为空 |
 | `isolation` | `branch` 或 `worktree`，工作区隔离方式。full 初始化可为 `null`，但只允许持续到 `/comet-build` Step 3 前；hotfix/tweak 默认 `branch` |
 | `verify_mode` | `light` 或 `full`，可为空 |
 | `verify_result` | `pending`、`pass` 或 `fail` |
 | `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
 | `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
+| `created_at` | change 创建日期（init 时自动写入），格式 `YYYY-MM-DD` |
 | `verified_at` | 验证通过时间，可为空 |
 | `archived` | change 是否已归档 |
 
@@ -199,11 +206,12 @@ archived: false
 Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量：
 
 ```bash
-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_HANDOFF="${COMET_HANDOFF:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-handoff.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)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
 
 # 脚本定位失败时停止流程
 if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then

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

@@ -18,8 +18,12 @@ description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta
 执行入口验证：
 
 ```bash
-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_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
 bash "$COMET_STATE" check <name> archive
 ```
 

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

@@ -17,9 +17,12 @@ description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制
 执行入口验证：
 
 ```bash
-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_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
 bash "$COMET_STATE" check <name> build
 ```
 
@@ -58,9 +61,11 @@ bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 
 无需手动更新 phase，guard 会在退出条件满足后自动流转。
 
-### 3. 工作区隔离
+### 3. 选择工作方式
 
-计划已写入当前分支。在开始执行前，选择工作区隔离方式：
+计划已写入当前分支。在开始执行前，**一次性询问用户**选择工作区隔离方式和执行方式：
+
+**工作区隔离**：
 
 | 选项 | 方式 | 说明 |
 |------|------|------|
@@ -71,52 +76,30 @@ bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 - 变更涉及 ≤ 3 个文件 → 推荐 A
 - 需要并行开发、当前分支有未提交工作 → 推荐 B
 
-用户选择后，更新 `isolation` 字段。`isolation` 只允许以下值之一：
-
-```bash
-bash "$COMET_STATE" set <name> isolation <value>
-```
-
-- `branch`
-- `worktree`
-
-<IMPORTANT>
-这是脚本级硬约束，不是建议。full workflow 初始化时 `isolation` 可以暂时为 `null`，但只允许存在到本步骤之前。
-进入实现前必须停下来询问用户并写入 `branch` 或 `worktree`。若保持 `null`，`build → verify` 的 guard 和 `comet-state transition build-complete` 都会失败。
-</IMPORTANT>
-
-**执行隔离**：
-
-- **branch**：执行 `git checkout -b <change-name>`，后续工作在新分支上进行
-- **worktree**：调用 `superpowers:using-git-worktrees` 技能或使用原生 `EnterWorktree` 工具创建隔离工作区
-
-创建隔离后，确认计划文件可访问（分支方式天然可访问；worktree 方式需确认计划已提交）。
-
-### 4. 选择执行方式
-
-向用户展示计划摘要（任务数、涉及模块），然后询问执行方式：
+**执行方式**：
 
 | 选项 | 技能 | 适用场景 |
 |------|------|---------|
 | A | `superpowers:subagent-driven-development` | 任务独立、复杂度高、需要双阶段审查 |
 | B | `superpowers:executing-plans` | 任务简单、无子agent环境、轻量快速 |
 
-**推荐规则**：
+**执行方式推荐规则**：
 - 任务数 ≥ 3 → 推荐 A
 - 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
 - 来自 hotfix 路径 → 推荐 B
 
-用户选择后，更新 `build_mode` 字段。`build_mode` 只允许以下值之一：
+这是用户决策点。必须暂停并等待用户明确选择隔离方式和执行方式，**不得根据推荐规则自行选择 `branch` 或 `worktree`**，也**不得根据推荐规则自行选择执行方式**。推荐规则只能用于说明建议，不能替代用户确认。
+
+用户选择后，更新 `isolation` 和 `build_mode` 字段：
 
 ```bash
-bash "$COMET_STATE" set <name> build_mode <value>
+bash "$COMET_STATE" set <name> isolation <branch|worktree>
+bash "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
 ```
 
-- `subagent-driven-development`
-- `executing-plans`
-- `direct`（默认仅 hotfix/tweak preset 使用）
+`isolation` 是脚本级硬约束。full workflow 初始化时可以为 `null`，但只允许存在到本步骤之前。若保持 `null`，`build → verify` 的 guard 和 `comet-state transition build-complete` 都会失败。
 
-full workflow 不得默认使用 `direct`。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：
+`build_mode` 默认仅 hotfix/tweak preset 使用 `direct`。full workflow 不得默认使用 `direct`。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：
 
 ```bash
 bash "$COMET_STATE" set <name> direct_override true
@@ -125,7 +108,14 @@ bash "$COMET_STATE" set <name> build_mode direct
 
 没有 `direct_override: true` 时，full workflow 的 `build_mode=direct` 会被 guard 和状态转换同时拦截。
 
-然后，**立即执行：** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
+**执行隔离**：
+
+- **branch**：执行 `git checkout -b <change-name>`，后续工作在新分支上进行
+- **worktree**：必须使用 Skill 工具加载 `superpowers:using-git-worktrees` 技能创建隔离工作区。禁止用普通 shell 命令或原生工具绕过该技能；如该技能不可用，停止流程并提示安装或启用 Superpowers 技能。
+
+创建隔离后，确认计划文件可访问（分支方式天然可访问；worktree 方式需确认计划已提交）。
+
+**加载执行技能**：使用 Skill 工具加载对应技能。禁止跳过此步骤。
 
 如所选 Superpowers 技能不可用，停止流程并提示安装或启用对应技能，不要用普通对话替代该步骤。
 
@@ -134,17 +124,19 @@ bash "$COMET_STATE" set <name> build_mode direct
 - 完成 tasks.md 勾选（`- [ ]` → `- [x]`）
 - 每个任务完成后提交代码
 
-### 5. Spec 增量更新
+### 4. Spec 增量更新
 
 实施过程中发现初版 spec 不完整时，按变更规模分级处理：
 
 | 规模 | 触发条件 | 做法 |
 |------|---------|------|
 | 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md，追加 tasks.md 任务 |
-| 中 | 接口变更、新增组件、数据流变化 | 重新 `superpowers:brainstorming` 更新 Design Doc + delta spec |
-| 大 | 全新 capability 需求 | `/opsx:new` 创建独立 change |
+| 中 | 接口变更、新增组件、数据流变化 | 暂停并等待用户确认后，必须使用 Skill 工具加载 `superpowers:brainstorming` 更新 Design Doc + delta spec |
+| 大 | 全新 capability 需求 | 必须暂停并等待用户确认拆分；用户确认后，通过 `/comet-open` 创建独立 change |
+
+**50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，必须暂停并等待用户决定是否拆分为新 change。
 
-**50% 阈值判定**：以 tasks.md 初始任务总数为基准，若新增任务数超过该总数的一半，视为超出原计划范围，应考虑拆分为新 change。
+创建独立 change 时必须调用 `/comet-open`，不得直接调用 `/opsx:new`。`/comet-open` 会同时创建 OpenSpec 产物和 `.comet.yaml`，避免新 change 脱离 Comet 状态机。
 
 **原则**：
 - delta spec 是活文档，本阶段期间随时可修改
@@ -152,14 +144,14 @@ bash "$COMET_STATE" set <name> build_mode direct
 - 不提前同步到 main spec，归档时统一同步
 - 小规模增量直接改 delta spec 时，应在 commit message 中注明，便于归档时判断 design doc 漂移
 
-### 6. 上下文管理
+### 5. 上下文管理
 
 Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：
 
 - **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.comet.yaml` 和文件状态持久化
 - **上下文压缩后恢复**：读取 `.comet.yaml` 的 `phase` 字段确认仍在 build 阶段，读取 plan 文件头的 `base-ref`，再读取 tasks.md 找到下一个未勾选任务继续执行
 - **用户手动修改恢复**：按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理：
-  1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 5「Spec 增量更新」分级处理
+  1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 4「Spec 增量更新」分级处理
 - **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交
 
 ## 退出条件

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

@@ -17,10 +17,12 @@ description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过
 执行入口验证：
 
 ```bash
-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_HANDOFF="${COMET_HANDOFF:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-handoff.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
 bash "$COMET_STATE" check <name> design
 ```
 
@@ -92,23 +94,41 @@ canonical_spec: openspec
 
 如 `superpowers:brainstorming` 不可用，停止流程并提示安装或启用 Superpowers 技能，不要用普通对话替代该步骤。
 
-技能加载后，按其指引产出：
-- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — 设计文档（技术 RFC）
-- 如需补充验收场景，回写 `openspec/changes/<name>/specs/<capability>/spec.md` — OpenSpec delta 能力规格
+技能加载后，按其指引产出设计方案（以对话形式呈现）：
+- 技术方案：架构、数据流、关键技术选型与风险
+- 测试策略
+- 如需补充验收场景，标明将回写的 delta spec 变更
+
+brainstorming 阶段不写入 Design Doc 文件，仅产出设计方案供 Step 1c 用户确认。确认后才创建 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` 并回写 delta spec。
+
+### 1c. 用户确认设计方案（阻塞点）
+
+brainstorming 产出设计方案后，**必须暂停并等待用户明确确认设计方案**。不得在用户确认前创建最终 Design Doc、写入 `design_doc`、运行 design guard，或进入 `/comet-build`。
+
+暂停时只展示必要摘要：
+- 采用的技术方案
+- 关键取舍与风险
+- 测试策略
+- 如有 Spec Patch，列出将回写的 delta spec 变更
+
+用户明确确认后，才继续 Step 2。若用户要求调整，继续 brainstorming 迭代，直到用户确认。
 
 ### 2. 更新 Comet 状态
 
-先记录 design_doc 路径，再运行 guard 自动流转：
+先记录 design_doc 路径。如果 Step 1c 回写了 delta spec（新增或修改了 `specs/*/spec.md`），必须重新生成 handoff 以更新 hash：
 
 ```bash
 # 记录 design_doc 路径
 bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
+# 如有 delta spec 变更，重新生成 handoff（更新 hash）
+bash "$COMET_HANDOFF" <change-name> design --write
+
 # 自动流转到下一阶段
 bash "$COMET_GUARD" <change-name> design --apply
 ```
 
-状态文件自动更新，无需手动编辑其他字段。
+如果没有 delta spec 变更，跳过 handoff 重新生成步骤。状态文件自动更新，无需手动编辑其他字段。
 
 ## 退出条件