@rpamis/comet 0.3.3 → 0.3.5

package/README.md

@@ -28,13 +28,13 @@
 ```
 
 > 中文版：[README-zh.md](README-zh.md)
-> [B站视频介绍](https://www.bilibili.com/video/BV1y4Gi6CEo1/?spm_id_from=333.1387.homepage.video_card.click&vd_source=d22726fe6b108647dbebf1c5d8817377)
+> [Bilibili video](https://www.bilibili.com/video/BV1y4Gi6CEo1/?spm_id_from=333.1387.homepage.video_card.click&vd_source=d22726fe6b108647dbebf1c5d8817377)
 
 **OpenSpec + Superpowers dual-star development workflow** — one command from idea to archive.
 
-OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving). 
+OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving).
 
-Superpowers handles **HOW** (technical design, planning, execution, wrap-up). 
+Superpowers handles **HOW** (technical design, planning, execution, wrap-up).
 
 Comet chains both into a five-phase automated pipeline.
 
@@ -46,7 +46,7 @@ Superpowers generates Spec documents after brainstorming, but these documents ty
 
 **Comet combines the strengths of both**, integrating the core workflow into 5 phases
 
-The main entry `/comet` supports current Spec state detection, suitable for long tasks — after completing and closing CC midway, just `/comet continue` and Comet will automatically read the active Spec (lists multiple for selection), dynamically identify which phase is currently executing, and continue.
+The main entry `/comet` supports current Spec state detection, suitable for long tasks — after closing your AI coding session midway, just `/comet` and Comet will automatically read the active Spec (lists multiple for selection), dynamically identify which phase is currently executing, and continue.
 
 At the same time, Comet provides full Spec lifecycle management. During execution, it links OpenSpec change/spec artifacts with Superpowers design and planning documents, then automates handoff, state updates, validation, and archive sync so users do not have to repeatedly remind the Agent to keep documents synchronized and connected.
 
@@ -72,6 +72,13 @@ Long-term Skill users know these capabilities can be freely combined, but exactl
 
 ## Install
 
+Requirements:
+
+- Node.js 20+
+- npm/npx
+- Git
+- Bash-compatible shell for workflow scripts (Windows users should use Git Bash or an equivalent bash environment)
+
 ```bash
 npm install -g @rpamis/comet
 ```
@@ -100,6 +107,8 @@ comet init
 
 ## Support for OpenClaw and Hermes, and other AI platforms
 
+For platforms that use the generic `skills` CLI directly, you can install the Comet skill package with:
+
 ```bash
 npx skills add rpamis/comet
 ```
@@ -120,13 +129,13 @@ npx skills add rpamis/comet
 
 Initializes OpenSpec, Superpowers, and Comet skills for selected AI coding platforms.
 
-| Option | Description |
-|--------|-------------|
-| `--yes` | Non-interactive mode, auto-select detected platforms (or all if none detected) |
-| `--scope <scope>` | Install scope: `project` or `global` |
-| `--skip-existing` | Skip already installed components |
-| `--overwrite` | Overwrite already installed components |
-| `--json` | Output structured JSON |
+| Option            | Description                                                                    |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `--yes`           | Non-interactive mode, auto-select detected platforms (or all if none detected) |
+| `--scope <scope>` | Install scope: `project` or `global`                                           |
+| `--skip-existing` | Skip already installed components                                              |
+| `--overwrite`     | Overwrite already installed components                                         |
+| `--json`          | Output structured JSON                                                         |
 
 When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite all, skip all, or choose per component.
 
@@ -137,8 +146,8 @@ When multiple existing components are found on the same platform, interactive in
 
 Displays active changes, task progress, and the recommended next Comet workflow command.
 
-| Option | Description |
-|--------|-------------|
+| Option   | Description                              |
+| -------- | ---------------------------------------- |
 | `--json` | Output active changes with `nextCommand` |
 
 </details>
@@ -148,9 +157,9 @@ Displays active changes, task progress, and the recommended next Comet workflow
 
 Checks project/global installation health, working directories, installed skills, scripts, and Comet state files.
 
-| Option | Description |
-|--------|-------------|
-| `--json` | Output structured diagnostic results |
+| Option            | Description                                                     |
+| ----------------- | --------------------------------------------------------------- |
+| `--json`          | Output structured diagnostic results                            |
 | `--scope <scope>` | Diagnose `auto`, `project`, or `global` scope (default: `auto`) |
 
 </details>
@@ -160,17 +169,17 @@ Checks project/global installation health, working directories, installed skills
 
 Updates the npm package and refreshes installed Comet skills in detected project/global targets.
 
-| Option | Description |
-|--------|-------------|
-| `--json` | Output npm and skill update results as JSON |
+| Option              | Description                                   |
+| ------------------- | --------------------------------------------- |
+| `--json`            | Output npm and skill update results as JSON   |
 | `--language <lang>` | Override detected skill language (`en`, `zh`) |
-| `--scope <scope>` | Update only `global` or `project` scope |
+| `--scope <scope>`   | Update only `global` or `project` scope       |
 
 </details>
 
-| Command | Description |
-|---------|-------------|
-| `comet --help` | Show help |
+| Command           | Description  |
+| ----------------- | ------------ |
+| `comet --help`    | Show help    |
 | `comet --version` | Show version |
 
 ## Supported Platforms
@@ -180,25 +189,27 @@ Updates the npm package and refreshes installed Comet skills in detected project
 <details>
 <summary>View full platform list</summary>
 
-| Platform | Skills Dir | Platform | Skills Dir |
-|----------|-----------|----------|-----------|
-| Claude Code | `.claude/` | Cursor | `.cursor/` |
-| Codex | `.codex/` | OpenCode | `.opencode/` |
-| Windsurf | `.windsurf/` | Cline | `.cline/` |
-| RooCode | `.roo/` | Continue | `.continue/` |
-| GitHub Copilot | `.github/` | Gemini CLI | `.gemini/` |
-| Amazon Q Developer | `.amazonq/` | Qwen Code | `.qwen/` |
-| Kilo Code | `.kilocode/` | Auggie | `.augment/` |
-| Kiro | `.kiro/` | Lingma | `.lingma/` |
-| Junie | `.junie/` | CodeBuddy | `.codebuddy/` |
-| CoStrict | `.cospec/` | Crush | `.crush/` |
-| Factory Droid | `.factory/` | iFlow | `.iflow/` |
-| Pi | `.pi/` | Qoder | `.qoder/` |
-| Antigravity | `.agents/` | Bob Shell | `.bob/` |
-| ForgeCode | `.forge/` | Trae | `.trae/` |
+| Platform           | Skills Dir   | Platform   | Skills Dir    |
+| ------------------ | ------------ | ---------- | ------------- |
+| Claude Code        | `.claude/`   | Cursor     | `.cursor/`    |
+| Codex              | `.codex/`    | OpenCode   | `.opencode/`  |
+| Windsurf           | `.windsurf/` | Cline      | `.cline/`     |
+| RooCode            | `.roo/`      | Continue   | `.continue/`  |
+| GitHub Copilot     | `.github/`   | Gemini CLI | `.gemini/`    |
+| Amazon Q Developer | `.amazonq/`  | Qwen Code  | `.qwen/`      |
+| Kilo Code          | `.kilocode/` | Auggie     | `.augment/`   |
+| Kiro               | `.kiro/`     | Lingma     | `.lingma/`    |
+| Junie              | `.junie/`    | CodeBuddy  | `.codebuddy/` |
+| CoStrict           | `.cospec/`   | Crush      | `.crush/`     |
+| Factory Droid      | `.factory/`  | iFlow      | `.iflow/`     |
+| Pi                 | `.pi/`       | Qoder      | `.qoder/`     |
+| Antigravity        | `.agents/`   | Bob Shell  | `.bob/`       |
+| ForgeCode          | `.forge/`    | Trae       | `.trae/`      |
 
 </details>
 
+Some platforms use different project and global directories. For example, OpenCode global installs use `.config/opencode`, Lingma global installs use `.lingma`, and Antigravity global installs use `.gemini/antigravity`.
+
 ## Skills
 
 After `comet init`, three groups of skills are installed to the selected platform's `skills/` directory:
@@ -208,16 +219,16 @@ After `comet init`, three groups of skills are installed to the selected platfor
 <details>
 <summary>View Comet skills</summary>
 
-| Skill | Description |
-|-------|-------------|
-| `/comet` | Main entry — auto-detects phase and dispatches to sub-commands |
-| `/comet-open` | Phase 1: Open a change (proposal, design, task breakdown) |
-| `/comet-design` | Phase 2: Deep design (brainstorming, Design Doc) |
-| `/comet-build` | Phase 3: Plan and build (implementation plan, code commits) |
-| `/comet-verify` | Phase 4: Verify and finish (testing, verification report) |
-| `/comet-archive` | Phase 5: Archive (delta spec sync, status annotation) |
-| `/comet-hotfix` | Preset: Quick bug fix (skips brainstorming) |
-| `/comet-tweak` | Preset: Small change (skips brainstorming and full plan) |
+| Skill            | Description                                                    |
+| ---------------- | -------------------------------------------------------------- |
+| `/comet`         | Main entry — auto-detects phase and dispatches to sub-commands |
+| `/comet-open`    | Phase 1: Open a change (proposal, design, task breakdown)      |
+| `/comet-design`  | Phase 2: Deep design (brainstorming, Design Doc)               |
+| `/comet-build`   | Phase 3: Plan and build (implementation plan, code commits)    |
+| `/comet-verify`  | Phase 4: Verify and finish (testing, verification report)      |
+| `/comet-archive` | Phase 5: Archive (delta spec sync, status annotation)          |
+| `/comet-hotfix`  | Preset: Quick bug fix (skips brainstorming)                    |
+| `/comet-tweak`   | Preset: Small change (skips brainstorming and full plan)       |
 
 </details>
 
@@ -226,13 +237,14 @@ After `comet init`, three groups of skills are installed to the selected platfor
 <details>
 <summary>View script list</summary>
 
-| Script | Purpose |
-|--------|---------|
-| `comet-guard.sh` | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml` |
-| `comet-handoff.sh` | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing |
-| `comet-archive.sh` | One-command archive — validates state, syncs specs, moves to archive, updates status |
-| `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values |
-| `comet-state.sh` | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface |
+| Script                   | Purpose                                                                                               |
+| ------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `comet-env.sh`           | Script discovery helper — exports bundled script paths such as `COMET_GUARD`, `COMET_STATE`, `COMET_HANDOFF`, and `COMET_ARCHIVE` |
+| `comet-guard.sh`         | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml`              |
+| `comet-handoff.sh`       | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing |
+| `comet-archive.sh`       | One-command archive — validates state, syncs specs, moves to archive, updates status                  |
+| `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values                                 |
+| `comet-state.sh`         | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface                 |
 
 </details>
 
@@ -261,13 +273,13 @@ Development methodology: brainstorming, TDD, subagent-driven development, code r
 
 ### Five Phases
 
-| Phase | Command | Owner | Artifacts |
-|-------|---------|-------|-----------|
-| 1. Open | `/comet-open` | OpenSpec | proposal.md, design.md, tasks.md |
-| 2. Deep Design | `/comet-design` | Superpowers | Design Doc, delta spec |
-| 3. Plan & Build | `/comet-build` | Superpowers | Implementation plan, code commits |
-| 4. Verify & Finish | `/comet-verify` | Both | Verification report, branch handling |
-| 5. Archive | `/comet-archive` | OpenSpec | delta→main spec sync, archive |
+| Phase              | Command          | Owner       | Artifacts                            |
+| ------------------ | ---------------- | ----------- | ------------------------------------ |
+| 1. Open            | `/comet-open`    | OpenSpec    | proposal.md, design.md, tasks.md     |
+| 2. Deep Design     | `/comet-design`  | Superpowers | Design Doc, delta spec               |
+| 3. Plan & Build    | `/comet-build`   | Superpowers | Implementation plan, code commits    |
+| 4. Verify & Finish | `/comet-verify`  | Both        | Verification report, branch handling |
+| 5. Archive         | `/comet-archive` | OpenSpec    | delta→main spec sync, archive        |
 
 ### Core Principles
 
@@ -281,10 +293,10 @@ Development methodology: brainstorming, TDD, subagent-driven development, code r
 
 Comet uses a decoupled state architecture with separate YAML files:
 
-| File | Owner | Purpose |
-|------|-------|---------|
-| `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata |
-| `.comet.yaml` | Comet | Workflow phase, execution mode, verification status |
+| File             | Owner    | Purpose                                             |
+| ---------------- | -------- | --------------------------------------------------- |
+| `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata                     |
+| `.comet.yaml`    | Comet    | Workflow phase, execution mode, verification status |
 
 All states and execution phases are updated via scripts, and each phase verifies that tasks are truly complete before advancing. Compared to storing complex state rules only in Skill text, this script-backed state machine gives Comet more reliable phase transitions, correct YAML, and easier breakpoint recovery; agents can read the current Spec situation through Comet's built-in commands.
 
@@ -367,6 +379,7 @@ your-project/
 │   ├── comet/SKILL.md
 │   │   └── scripts/
 │   │       ├── comet-guard.sh       # Phase transition guard (--apply auto-updates state)
+│   │       ├── comet-env.sh         # Script discovery helper
 │   │       ├── comet-handoff.sh     # Design handoff (OpenSpec → Superpowers context tracing)
 │   │       ├── comet-archive.sh     # One-command archive automation
 │   │       ├── comet-yaml-validate.sh # Schema validator
@@ -403,9 +416,16 @@ Track our development progress and upcoming features on the [Comet Roadmap](http
 
 [![Star History Chart](https://api.star-history.com/svg?repos=rpamis/comet&type=Date)](https://star-history.com/#rpamis/comet&Date)
 
+## Contributors
+
+<a href="https://github.com/rpamis/comet/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=rpamis/comet&max=999&columns=12&anon=1" />
+</a>
+
 ## License
 
-[MIT](LICENSE.md)
+[MIT](LICENSE)
 
 ## Reference
+
 [LINUX DO - 新的理想型社区](https://linux.do/)

package/assets/skills/comet/SKILL.md

@@ -103,19 +103,30 @@ A single `/comet` invocation starts from the detected phase and advances to the
 
 Flow chain: open → design → build → verify → archive
 
-**Continuous execution requirement**: starting from the detected phase, the agent must automatically continue through all later phases. Auto-advancing only applies at transition points without user decisions. When encountering user decision points, must pause and wait for the user's explicit response. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation.
+**Continuous execution requirement**: starting from the detected phase, the agent automatically continues through all later phases. But **auto-advancing only applies at transition points without user decisions**. When encountering user decision points, **must use the AskUserQuestion tool to pause and wait for the user's explicit response**. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation, and must not just output a text prompt and then continue executing.
 
-**Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet` invocation must stop. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes.
+**Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet` invocation must stop, **using the AskUserQuestion tool to wait for the user's choice**. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes.
 
 Nodes requiring user participation (pause only at these nodes):
-1. Confirm design approach during brainstorming
-2. Select workflow configuration during build phase (isolation + execution method, single interaction)
-3. Decide to fix or accept deviation when verify fails (including Spec drift handling)
-4. Choose branch handling method for finishing-branch
-5. Encounter upgrade conditions (hotfix/tweak → full workflow)
-6. Build phase scope expansion requiring redesign or new change split
-
-Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway.
+1. Open phase proposal/design/tasks review and confirmation
+2. Confirm design approach during brainstorming
+3. Select workflow configuration during build phase (isolation + execution method, single interaction)
+4. Decide to fix or accept deviation when verify fails (including Spec drift handling)
+5. Choose branch handling method for finishing-branch
+6. Encounter upgrade conditions (hotfix/tweak → full workflow)
+7. Build phase scope expansion requiring redesign or new change split
+
+Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. At decision points, **text output must NOT substitute for tool-based waiting — must explicitly obtain the user's choice via AskUserQuestion before continuing**.
+
+**Red Flags** — when these thoughts appear, STOP and check:
+
+| Agent Thought | Actual Risk |
+|--------------|-------------|
+| "The user would probably agree with this approach" | Cannot decide for the user — use AskUserQuestion |
+| "This is a small change, confirmation isn't needed" | Decision points have no size exception — blocking points must wait |
+| "The user chose A last time, so A again" | Historical preference cannot substitute for current confirmation |
+| "I explained the plan and the user didn't object" | No objection ≠ consent — must use tool to get explicit choice |
+| "The flow has reached this point, should be fine" | Verification not passed ≠ passed — check verify_result |
 </IMPORTANT>
 
 ---

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

@@ -8,6 +8,7 @@
 #   set <change-name> <field> <val> — Update a field value
 #   transition <change-name> <event> — Apply a validated state transition
 #   check <change-name> <phase>    — Verify entry requirements for a phase
+#   check <change-name> <phase> --recover — Output structured recovery context for compaction resume
 #   scale <change-name>             — Assess and set verification mode based on metrics
 #
 # Workflows: full, hotfix, tweak
@@ -589,6 +590,169 @@ cmd_check() {
   fi
 }
 
+# --- Recovery context for compaction resume ---
+
+field_status() {
+  # Args: field_name value [file_path]
+  # Prints: "field_name: DONE (value)" or "field_name: PENDING"
+  local field="$1"
+  local value="$2"
+  local file_path="${3:-}"
+
+  if [ -z "$value" ] || [ "$value" = "null" ]; then
+    echo "  - ${field}: PENDING"
+  elif [ -n "$file_path" ] && [ ! -f "$file_path" ]; then
+    echo "  - ${field}: BROKEN (path ${value} does not exist)"
+  else
+    echo "  - ${field}: DONE (${value})"
+  fi
+}
+
+cmd_recover() {
+  local change_name="$1"
+
+  validate_change_name "$change_name"
+
+  local change_dir="openspec/changes/$change_name"
+  local yaml_file="$change_dir/.comet.yaml"
+
+  if [ ! -f "$yaml_file" ]; then
+    red "ERROR: .comet.yaml not found at $yaml_file"
+    exit 1
+  fi
+
+  local phase workflow
+  phase=$(cmd_get "$change_name" "phase")
+  workflow=$(cmd_get "$change_name" "workflow")
+
+  echo "=== Recovery Context: ${change_name} ==="
+  echo "Phase: ${phase}"
+  echo "Workflow: ${workflow}"
+  echo ""
+
+  # Read all relevant fields
+  local design_doc plan verify_result verify_mode verification_report
+  local branch_status handoff_context handoff_hash isolation build_mode direct_override
+  design_doc=$(cmd_get "$change_name" "design_doc")
+  plan=$(cmd_get "$change_name" "plan")
+  verify_result=$(cmd_get "$change_name" "verify_result")
+  verify_mode=$(cmd_get "$change_name" "verify_mode")
+  verification_report=$(cmd_get "$change_name" "verification_report")
+  branch_status=$(cmd_get "$change_name" "branch_status")
+  handoff_context=$(cmd_get "$change_name" "handoff_context")
+  handoff_hash=$(cmd_get "$change_name" "handoff_hash")
+  isolation=$(cmd_get "$change_name" "isolation")
+  build_mode=$(cmd_get "$change_name" "build_mode")
+  direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
+
+  echo "State fields:"
+
+  # Phase-specific field reporting
+  case "$phase" in
+    open)
+      echo "  Artifacts:"
+      for f in proposal.md design.md tasks.md; do
+        if file_nonempty "$change_dir/$f"; then
+          echo "  - ${f}: DONE"
+        else
+          echo "  - ${f}: PENDING"
+        fi
+      done
+      echo ""
+      echo "Recovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation."
+      ;;
+    design)
+      echo "  Artifacts:"
+      for f in proposal.md design.md tasks.md; do
+        if file_nonempty "$change_dir/$f"; then
+          echo "  - ${f}: DONE"
+        else
+          echo "  - ${f}: MISSING (unexpected in design phase)"
+        fi
+      done
+      echo ""
+      echo "  Design progress:"
+      field_status "handoff_context" "$handoff_context" "$handoff_context"
+      field_status "handoff_hash" "$handoff_hash"
+      field_status "design_doc" "$design_doc" "$design_doc"
+      echo ""
+      if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then
+        echo "Recovery action: Design Doc already created and linked. Run guard to transition to build."
+      elif [ -n "$handoff_context" ] && [ "$handoff_context" != "null" ] && [ -f "$handoff_context" ]; then
+        echo "Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c)."
+      else
+        echo "Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package)."
+      fi
+      ;;
+    build)
+      echo "  Build decisions:"
+      field_status "isolation" "$isolation"
+      field_status "build_mode" "$build_mode"
+      if [ "$build_mode" = "direct" ] && [ "$workflow" != "hotfix" ] && [ "$workflow" != "tweak" ]; then
+        field_status "direct_override" "$direct_override"
+      fi
+      echo ""
+      echo "  Plan:"
+      field_status "plan" "$plan" "$plan"
+      echo ""
+      # Count completed vs pending tasks
+      local tasks_file="$change_dir/tasks.md"
+      local total=0 done=0 pending=0
+      if [ -f "$tasks_file" ]; then
+        total=$(grep -c '^\- \[' "$tasks_file" 2>/dev/null || echo "0")
+        done=$(grep -c '^\- \[x\]' "$tasks_file" 2>/dev/null || echo "0")
+        pending=$((total - done))
+        echo "  Tasks: ${done}/${total} done, ${pending} pending"
+      else
+        echo "  Tasks: tasks.md MISSING"
+      fi
+      echo ""
+      if [ "$isolation" = "null" ] || [ -z "$isolation" ]; then
+        echo "Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice."
+      elif [ "$build_mode" = "null" ] || [ -z "$build_mode" ]; then
+        echo "Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method."
+      elif [ ! -f "$tasks_file" ]; then
+        echo "Recovery action: tasks.md missing. Verify change directory integrity."
+      elif [ "$pending" -gt 0 ]; then
+        echo "Recovery action: Read tasks.md and continue from first unchecked task."
+      else
+        echo "Recovery action: All tasks done. Run guard to transition to verify."
+      fi
+      ;;
+    verify)
+      echo "  Verification:"
+      field_status "verify_result" "$verify_result"
+      field_status "verify_mode" "$verify_mode"
+      field_status "verification_report" "$verification_report" "$verification_report"
+      field_status "branch_status" "$branch_status"
+      echo ""
+      if [ "$verify_result" = "pass" ] && [ "$branch_status" = "handled" ]; then
+        echo "Recovery action: Verification complete. Run guard to transition to archive."
+      elif [ "$verify_result" = "pass" ]; then
+        echo "Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled."
+      elif [ "$verify_result" = "fail" ]; then
+        echo "Recovery action: Verification failed and rolled back to build. Resume from /comet-build."
+      else
+        echo "Recovery action: Verification not yet started or in progress. Run scale assessment then verify."
+      fi
+      ;;
+    archive)
+      echo "  Archive:"
+      field_status "verify_result" "$verify_result"
+      field_status "archived" "$(cmd_get "$change_name" "archived")"
+      echo ""
+      echo "Recovery action: Run /comet-archive to complete archiving."
+      ;;
+    *)
+      red "ERROR: Unknown phase: $phase"
+      exit 1
+      ;;
+  esac
+
+  echo ""
+  echo "=== End Recovery Context ==="
+}
+
 cmd_scale() {
   local change_name="$1"
 
@@ -694,11 +858,16 @@ case "$SUBCOMMAND" in
     ;;
   check)
     if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh check <change-name> <phase>" >&2
+      red "Usage: comet-state.sh check <change-name> <phase> [--recover]" >&2
       red "Phases: open, design, build, verify, archive" >&2
       exit 1
     fi
-    cmd_check "$@"
+    # Detect --recover flag (3rd argument)
+    if [ "${3:-}" = "--recover" ]; then
+      cmd_recover "$1"
+    else
+      cmd_check "$@"
+    fi
     ;;
   scale)
     if [ $# -lt 1 ]; then

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

@@ -28,6 +28,8 @@ bash "$COMET_STATE" check <name> build
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
+**Idempotency**: All build phase operations can be safely re-executed. Read `.comet.yaml` `phase` field to confirm still in build, read plan header `base-ref`, then read tasks.md to find the first unchecked task. Already-committed tasks must not be re-committed.
+
 ### 1. Create Plan
 
 **Immediately execute:** Use the Skill tool to load the `superpowers:writing-plans` skill. Skipping this step is prohibited.
@@ -88,7 +90,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. 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.
+This is a user decision point. **Must use the AskUserQuestion tool to pause and wait for the user to explicitly choose both isolation method and execution method**. 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. Must not just output a text prompt and then continue executing.
 
 After user selection, update `isolation` and `build_mode` fields:
 
@@ -131,10 +133,10 @@ 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 | Pause and wait for user confirmation, then must use Skill tool to load `superpowers:brainstorming` to update Design Doc + delta spec |
-| Large | Brand-new capability requirements | Must pause and wait for user confirmation to split; after user confirms, create independent change through `/comet-open` |
+| Medium | Interface changes, new components, data flow changes | **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm**, then must use Skill tool to load `superpowers:brainstorming` to update Design Doc + delta spec |
+| Large | Brand-new capability requirements | **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm the split**; after user confirms, create independent change through `/comet-open` |
 
-**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, must pause and wait for the user to decide whether to split into new 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, **must use the AskUserQuestion tool to pause and wait for the user to decide whether to split into a new change**. Must not just output a text prompt and then continue executing.
 
 When creating an independent change, must invoke `/comet-open`, not `/opsx:new` directly. `/comet-open` creates both OpenSpec artifacts and `.comet.yaml`, preventing the new change from leaving the Comet state machine.
 
@@ -149,7 +151,7 @@ When creating an independent change, must invoke `/comet-open`, not `/opsx:new`
 Build is the longest phase and may span many tasks. To support resume after context compaction:
 
 - **After each task**: immediately check off tasks.md and commit code so `.comet.yaml` and file state are durable
-- **After context compaction**: read `.comet.yaml` to confirm the phase is still build, read the plan header `base-ref`, then read tasks.md to find the next unchecked task
+- **After context compaction**: first run `bash "$COMET_STATE" check <change-name> build --recover` — the script outputs structured recovery context (isolation/build_mode status, plan path, task progress, recovery action). Follow the Recovery action to determine next step.
 - **User manual-change resume**: handle uncommitted changes through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions. Build-specific handling:
   1. After attribution, if the diff implies plan or spec changes, handle it through Step 4 "Spec Incremental Updates"
 - **Long task split**: if a single task exceeds 200 lines of code changes, consider splitting it into multiple subtasks and commits
@@ -183,6 +185,6 @@ State file is automatically updated to `phase: verify`, `verify_result: pending`
 
 ## Automatic Transition
 
-After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
+After exit conditions are met (including user selecting workflow configuration), auto-transition to next phase:
 
 > **REQUIRED NEXT SKILL:** Invoke `comet-verify` skill to enter the verification and completion phase.

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

@@ -28,6 +28,8 @@ bash "$COMET_STATE" check <name> design
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
+**Idempotency**: All design phase operations can be safely re-executed. If `handoff_context` and `handoff_hash` already exist, confirm they match current artifacts before deciding whether to regenerate.
+
 ### 1a. Generate OpenSpec → Superpowers Handoff Package
 
 **Must be generated by script. Agent writing summaries on the fly is not allowed.**
@@ -103,7 +105,7 @@ The brainstorming phase does not write to the Design Doc file; it only produces
 
 ### 1c. User Confirms Design Proposal (Blocking Point)
 
-After brainstorming produces a design proposal, **must pause and wait for the user to explicitly confirm the design proposal**. Must not create the final Design Doc, write `design_doc`, run design guard, or enter `/comet-build` before user confirmation.
+After brainstorming produces a design proposal, **must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm the design proposal**. Must not create the final Design Doc, write `design_doc`, run design guard, or enter `/comet-build` before user confirmation. Must not just output a text prompt and then continue executing.
 
 When pausing, only present essential summary:
 - Technical approach adopted
@@ -147,8 +149,18 @@ Must use `--apply` before exit:
 bash "$COMET_GUARD" <change-name> design --apply
 ```
 
+## Context Compaction Recovery
+
+The design phase may trigger context compaction during brainstorming. To recover, first run:
+
+```bash
+bash "$COMET_STATE" check <change-name> design --recover
+```
+
+The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the Recovery action to determine next step.
+
 ## Automatic Transition
 
-After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
+After exit conditions are met (including user confirming the design proposal), auto-transition to next phase:
 
 > **REQUIRED NEXT SKILL:** Invoke `comet-build` skill to enter the plan and build phase.

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

@@ -126,7 +126,7 @@ 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). Handle through the upgrade-condition blocking confirmation
+1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to full workflow
 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
 
@@ -149,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 the user to explicitly confirm upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc.
+When upgrade conditions are met, **must use the AskUserQuestion tool to 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. Must not just output a text prompt and then continue executing.
 
 After user confirms upgrade, **must first update the workflow field** before entering full flow: