@rpamis/comet 0.3.1 → 0.3.3

package/assets/manifest.json

@@ -1,8 +1,9 @@
 {
-  "version": "0.3.1",
+  "version": "0.3.2",
   "skills": [
     "comet/SKILL.md",
     "comet/reference/dirty-worktree.md",
+    "comet/scripts/comet-env.sh",
     "comet/scripts/comet-guard.sh",
     "comet/scripts/comet-state.sh",
     "comet/scripts/comet-handoff.sh",

package/assets/skills/comet/SKILL.md

@@ -206,11 +206,12 @@ State-machine hard constraints:
 Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars:
 
 ```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"
 
 # Stop workflow when script location fails
 if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then

package/assets/skills/comet/scripts/comet-env.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# Comet script locator — source this file to export paths to bundled scripts.
+#
+# Usage:
+#   . /path/to/comet/scripts/comet-env.sh
+#
+# This file is sourced by workflow snippets. Do not set global shell options here.
+
+_comet_env_source="${BASH_SOURCE[0]:-$0}"
+_comet_script_dir="$(cd "$(dirname "$_comet_env_source")" && pwd -P)"
+_comet_env_sourced=0
+(return 0 2>/dev/null) && _comet_env_sourced=1
+
+export COMET_GUARD="${COMET_GUARD:-${_comet_script_dir}/comet-guard.sh}"
+export COMET_STATE="${COMET_STATE:-${_comet_script_dir}/comet-state.sh}"
+export COMET_HANDOFF="${COMET_HANDOFF:-${_comet_script_dir}/comet-handoff.sh}"
+export COMET_ARCHIVE="${COMET_ARCHIVE:-${_comet_script_dir}/comet-archive.sh}"
+export COMET_YAML_VALIDATE="${COMET_YAML_VALIDATE:-${_comet_script_dir}/comet-yaml-validate.sh}"
+
+_comet_env_fail() {
+  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed completely." >&2
+  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
+}
+
+_comet_env_abort() {
+  local _comet_env_was_sourced="$_comet_env_sourced"
+  unset _comet_env_source _comet_script_dir _comet_script _comet_env_missing _comet_env_sourced
+  unset -f _comet_env_fail
+  if [ "$_comet_env_was_sourced" -eq 1 ]; then
+    unset -f _comet_env_abort
+    return 1
+  fi
+  exit 1
+}
+
+_comet_env_missing=0
+for _comet_script in \
+  "$COMET_GUARD" \
+  "$COMET_STATE" \
+  "$COMET_HANDOFF" \
+  "$COMET_ARCHIVE" \
+  "$COMET_YAML_VALIDATE"; do
+  if [ ! -f "$_comet_script" ]; then
+    _comet_env_fail
+    _comet_env_missing=1
+    break
+  fi
+done
+
+if [ "$_comet_env_missing" -ne 0 ]; then
+  _comet_env_abort
+else
+  unset _comet_env_source _comet_script_dir _comet_script _comet_env_missing _comet_env_sourced
+  unset -f _comet_env_fail _comet_env_abort
+fi

package/assets/skills/comet/scripts/comet-state.sh

@@ -271,8 +271,8 @@ cmd_set() {
       red "Valid fields:" >&2
       red "  workflow, phase, design_doc, plan, build_mode, isolation," >&2
       red "  verify_mode, verify_result, verification_report, branch_status," >&2
-      red "  verified_at, archived, direct_override, build_command," >&2
-      red "  verify_command, handoff_context, handoff_hash" >&2
+      red "  verified_at, created_at, archived, base_ref, direct_override," >&2
+      red "  build_command, verify_command, handoff_context, handoff_hash" >&2
       exit 1
       ;;
   esac

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

@@ -18,8 +18,12 @@ description: "Comet Phase 5: Archive. Invoke with /comet-archive. Sync delta spe
 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_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/comet-build/SKILL.md

@@ -17,9 +17,12 @@ description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create pl
 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 <name> build
 ```
 
@@ -85,7 +88,7 @@ Plan has been written to the current branch. Before starting execution, **ask th
 - Task count ≤ 2 and no cross-module dependencies → Recommend B
 - From hotfix path → Recommend B
 
-This is a user decision point. Must pause and wait for the user to explicitly choose both isolation method and execution method. **Must not select based on recommendation rules**. Recommendation rules are for suggestion only, not a substitute for user confirmation.
+This is a user decision point. Must pause and wait for the user to explicitly choose both isolation method and execution method. You **must not choose `branch` or `worktree` based on recommendation rules**, and **must not choose the execution method based on recommendation rules**. Recommendation rules are for suggestion only, not a substitute for user confirmation.
 
 After user selection, update `isolation` and `build_mode` fields:
 

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

@@ -17,10 +17,12 @@ description: "Comet Phase 2: Deep Design. Invoke with /comet-design. Produce Des
 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_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
 ```
 

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

@@ -23,10 +23,12 @@ Execution chain: open → build → root cause check → verify → archive. Hot
 Locate Comet scripts before starting:
 
 ```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_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"
 ```
 
 ### 1. Quick Open (preset open)
@@ -124,9 +126,9 @@ If there is delta spec, sync to main spec according to comet-archive rules, and
 <IMPORTANT>
 Hotfix workflow is **one-time continuous execution**. After invoking `/comet-hotfix`, agent must automatically advance through hotfix steps, without pausing to wait for user input mid-way. But the following situations must pause and wait for user confirmation:
 
-1. Encountering upgrade conditions (see "Upgrade Conditions" section)
-2. When tasks exceed 3 and transfer to `/comet-build` for workspace isolation and execution method selection
-3. Verification phase (comet-verify) verification failure decision and branch handling decision
+1. Encountering upgrade conditions (see "Upgrade Conditions" section). Handle through the upgrade-condition blocking confirmation
+2. workspace isolation and execution-method selection when tasks exceed 3 and transfer to `/comet-build`
+3. verify phase (comet-verify) verification-failure and branch-handling decisions
 
 Execution order: quick open → direct build → root cause check → verification → archive → complete
 
@@ -147,7 +149,7 @@ Upgrade to full `/comet` when **any** of the following conditions are met:
 | Introduces new public API | Fix creates new external interface |
 | Fix scope exceeds single function/module | Requires coordinated changes |
 
-When upgrade conditions are met, must pause and wait for user to explicitly confirm upgrade to full `/comet` workflow. Must not directly enter `/comet-design`, must not automatically supplement Design Doc.
+When upgrade conditions are met, must pause and wait for the user to explicitly confirm upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc.
 
 After user confirms upgrade, **must first update the workflow field** before entering full flow:
 
@@ -155,7 +157,7 @@ After user confirms upgrade, **must first update the workflow field** before ent
 bash "$COMET_STATE" set <name> workflow full
 ```
 
-Then on current change basis, supplement Design Doc: **immediately use Skill tool to load `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop hotfix and report that current change has exceeded hotfix scope.
+Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop hotfix and report that current change has exceeded hotfix scope.
 
 ---
 

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

@@ -35,9 +35,12 @@ openspec/changes/<name>/
 Create `.comet.yaml` state file:
 
 ```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"
 
 if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2

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

@@ -26,10 +26,12 @@ Execution chain: open → lightweight build → light verify → archive. Tweak
 Locate Comet scripts before starting:
 
 ```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_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"
 ```
 
 ### 1. Quick Open (preset open)
@@ -109,8 +111,8 @@ Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` befo
 <IMPORTANT>
 Tweak workflow is **one-time continuous execution**. After invoking `/comet-tweak`, agent must automatically advance through tweak steps, without pausing to wait for user input mid-way. But the following situations must pause and wait for user confirmation:
 
-1. Encountering upgrade conditions (see "Upgrade Conditions" section)
-2. Verification phase (comet-verify) verification failure decision and branch handling decision
+1. Encountering upgrade conditions (see "Upgrade Conditions" section). Handle through the upgrade-condition blocking confirmation
+2. verify phase (comet-verify) verification-failure and branch-handling decisions
 
 Execution order: quick open → lightweight build → lightweight verification → archive → complete
 
@@ -132,7 +134,7 @@ Upgrade to full `/comet` when **any** of the following conditions are met:
 | New capability needed | Exceeds local optimization |
 | Delta spec needed | Affects existing specs |
 
-When upgrade conditions are met, must pause and wait for user to explicitly confirm upgrade to full `/comet` workflow. Must not directly enter `/comet-design`, must not automatically supplement Design Doc.
+When upgrade conditions are met, must pause and wait for the user to explicitly confirm upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc.
 
 After user confirms upgrade, **must first update the workflow field** before entering full flow:
 
@@ -140,7 +142,7 @@ After user confirms upgrade, **must first update the workflow field** before ent
 bash "$COMET_STATE" set <name> workflow full
 ```
 
-Then on current change basis, supplement Design Doc: **immediately use Skill tool to load `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop tweak and report that current change has exceeded tweak scope.
+Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop tweak and report that current change has exceeded tweak scope.
 
 ---
 

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

@@ -17,9 +17,12 @@ description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify
 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
 ```
 

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

@@ -110,7 +110,7 @@ agent 做决策只需读本节，参考附录按需查阅。
 需要用户参与的节点（仅在这些节点暂停）：
 1. brainstorming 确认设计方案
 2. build 阶段选择工作方式（隔离方式 + 执行方式，一次交互完成）
-4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
+3. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
 4. finishing-branch 选择分支处理方式
 5. 遇到升级条件（hotfix/tweak → 完整流程）
 6. build 阶段范围扩张需重新设计或拆分新 change
@@ -206,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
 ```
 

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
 ```
 

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

@@ -16,17 +16,19 @@ description: "Comet 预设路径：Bug fix / 热修复。跳过 brainstorming，
 
 ---
 
-## 流程（preset workflow，4 阶段）
+## 流程（preset workflow，5 阶段）
 
 执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后归档。
 
 开始前先定位 Comet 脚本：
 
 ```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_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"
 ```
 
 ### 1. 快速开启（preset open）
@@ -110,7 +112,7 @@ bash "$COMET_GUARD" <change-name> build --apply
 
 验证通过后，按 `/comet-verify` 的规则将 `.comet.yaml` 的 `verify_result` 记录为 `pass`，归档前不得跳过该状态。
 
-### 4. 归档（preset archive）
+### 5. 归档（preset archive）
 
 复用 `/comet-archive`。归档前必须满足 `.comet.yaml` 中 `verify_result: pass`。
 
@@ -128,7 +130,7 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 2. 任务超过 3 个转入 `/comet-build` 时的工作区隔离和执行方式选择
 3. 验证阶段（comet-verify）的验证失败决策和分支处理决策
 
-执行顺序：快速开启 → 直接构建 → 验证 → 归档 → 完成
+执行顺序：快速开启 → 直接构建 → 根因消除检查 → 验证 → 归档 → 完成
 
 每个阶段完成后立即进入下一阶段。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill，被调用的 skill 如有自己的用户决策点，按该 skill 规则执行。
 </IMPORTANT>

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

@@ -35,9 +35,12 @@ openspec/changes/<name>/
 创建 `.comet.yaml` 状态文件：
 
 ```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"
 
 if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2

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

@@ -26,10 +26,12 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 开始前先定位 Comet 脚本：
 
 ```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_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"
 ```
 
 ### 1. 快速开启（preset open）

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

@@ -17,9 +17,12 @@ description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验
 执行入口验证：
 
 ```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
 ```
 

package/dist/core/command-error.d.ts

@@ -0,0 +1,4 @@
+declare function formatCommandErrorDetails(error: unknown): string[];
+declare function printCommandErrorDetails(error: unknown, indent?: string): void;
+export { printCommandErrorDetails, formatCommandErrorDetails };
+//# sourceMappingURL=command-error.d.ts.map

package/dist/core/command-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-error.d.ts","sourceRoot":"","sources":["../../src/core/command-error.ts"],"names":[],"mappings":"AA2BA,iBAAS,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CA+B3D;AAED,iBAAS,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,GAAG,IAAI,CAIvE;AAED,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,CAAC"}

package/dist/core/command-error.js

@@ -0,0 +1,53 @@
+const ESC = String.fromCharCode(27);
+const ANSI_ESCAPE_PATTERN = new RegExp(`${ESC}\\[[0-9;?]*[a-zA-Z]`, 'g');
+const LOOSE_ESCAPE_PATTERN = new RegExp(`${ESC}\\[[^a-zA-Z\\r\\n]*`, 'g');
+function streamToText(stream) {
+    if (!stream)
+        return '';
+    return Buffer.isBuffer(stream) ? stream.toString() : stream;
+}
+function cleanCommandOutput(output) {
+    return output
+        .replace(ANSI_ESCAPE_PATTERN, '')
+        .replace(LOOSE_ESCAPE_PATTERN, '')
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim() && !/^(│|├|╮|╯|●|◇|◒|◐|◓|◑|■)/.test(line.trim()))
+        .join('\n')
+        .trim();
+}
+function formatCommandErrorDetails(error) {
+    const details = [];
+    if (!error || typeof error !== 'object') {
+        details.push('Unknown error occurred');
+        return details;
+    }
+    const commandError = error;
+    for (const [label, stream] of [
+        ['stderr', commandError.stderr],
+        ['stdout', commandError.stdout],
+    ]) {
+        const cleaned = cleanCommandOutput(streamToText(stream));
+        if (cleaned) {
+            details.push(`${label}:\n${cleaned}`);
+        }
+    }
+    if (details.length === 0) {
+        const reason = commandError.killed
+            ? 'Process was killed (likely timed out)'
+            : commandError.code === 'ETIMEDOUT'
+                ? 'Process timed out'
+                : commandError.code === 'ENOENT'
+                    ? 'Command not found — check that the required CLI is installed and on PATH'
+                    : 'No error output captured';
+        details.push(reason);
+    }
+    return details;
+}
+function printCommandErrorDetails(error, indent = '    ') {
+    for (const detail of formatCommandErrorDetails(error)) {
+        console.error(`${indent}${detail.split('\n').join(`\n${indent}`)}`);
+    }
+}
+export { printCommandErrorDetails, formatCommandErrorDetails };
+//# sourceMappingURL=command-error.js.map

package/dist/core/command-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-error.js","sourceRoot":"","sources":["../../src/core/command-error.ts"],"names":[],"mappings":"AAAA,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;AACpC,MAAM,mBAAmB,GAAG,IAAI,MAAM,CAAC,GAAG,GAAG,qBAAqB,EAAE,GAAG,CAAC,CAAC;AACzE,MAAM,oBAAoB,GAAG,IAAI,MAAM,CAAC,GAAG,GAAG,qBAAqB,EAAE,GAAG,CAAC,CAAC;AAS1E,SAAS,YAAY,CAAC,MAAmC;IACvD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAC9D,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,OAAO,MAAM;SACV,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC;SAChC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC;SACjC,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;SAC7B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;SAC9E,IAAI,CAAC,IAAI,CAAC;SACV,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAc;IAC/C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QACvC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,YAAY,GAAG,KAAqB,CAAC;IAE3C,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI;QAC5B,CAAC,QAAQ,EAAE,YAAY,CAAC,MAAM,CAAC;QAC/B,CAAC,QAAQ,EAAE,YAAY,CAAC,MAAM,CAAC;KACvB,EAAE,CAAC;QACX,MAAM,OAAO,GAAG,kBAAkB,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QACzD,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,OAAO,EAAE,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM;YAChC,CAAC,CAAC,uCAAuC;YACzC,CAAC,CAAC,YAAY,CAAC,IAAI,KAAK,WAAW;gBACjC,CAAC,CAAC,mBAAmB;gBACrB,CAAC,CAAC,YAAY,CAAC,IAAI,KAAK,QAAQ;oBAC9B,CAAC,CAAC,0EAA0E;oBAC5E,CAAC,CAAC,0BAA0B,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,wBAAwB,CAAC,KAAc,EAAE,MAAM,GAAG,MAAM;IAC/D,KAAK,MAAM,MAAM,IAAI,yBAAyB,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AAED,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/core/detect.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoC,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAU/C,iBAAS,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;GAGG;AACH,iBAAe,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,CAmBtD;AAED,iBAAe,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAuBxE;AAED,iBAAe,SAAS,CACtB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,UAAU,GAAG,aAAa,GAAG,OAAO,EAC/C,kBAAkB,GAAE,QAAQ,EAAO,EACnC,KAAK,GAAE,YAAwB,GAC9B,OAAO,CAAC,OAAO,CAAC,CAiDlB;AAED,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,oBAAoB,EAAE,UAAU,EAAE,CAAC;AACxE,YAAY,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/core/detect.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoC,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAU/C,iBAAS,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;GAGG;AACH,iBAAe,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,CAmBtD;AAWD,iBAAe,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAuBxE;AAED,iBAAe,SAAS,CACtB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,UAAU,GAAG,aAAa,GAAG,OAAO,EAC/C,kBAAkB,GAAE,QAAQ,EAAO,EACnC,KAAK,GAAE,YAAwB,GAC9B,OAAO,CAAC,OAAO,CAAC,CAqElB;AAED,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,oBAAoB,EAAE,UAAU,EAAE,CAAC;AACxE,YAAY,EAAE,YAAY,EAAE,CAAC"}