@rpamis/comet 0.3.4 → 0.3.6

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
@@ -204,6 +205,7 @@ cmd_init() {
 workflow: $workflow
 phase: $phase
 build_mode: $build_mode
+build_pause: null
 isolation: $isolation
 verify_mode: $verify_mode
 base_ref: $base_ref
@@ -263,13 +265,13 @@ cmd_set() {
       yellow "WARNING: Setting 'phase' directly bypasses state machine constraints." >&2
       yellow "  Consider using: comet-state.sh transition <change-name> <event>" >&2
       ;;
-    workflow|build_mode|isolation|verify_mode|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|created_at|direct_override|build_command|verify_command|handoff_context|handoff_hash|base_ref)
+    workflow|build_mode|build_pause|isolation|verify_mode|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|created_at|direct_override|build_command|verify_command|handoff_context|handoff_hash|base_ref)
       # Valid field
       ;;
     *)
       red "ERROR: Unknown field: '$field'" >&2
       red "Valid fields:" >&2
-      red "  workflow, phase, design_doc, plan, build_mode, isolation," >&2
+      red "  workflow, phase, design_doc, plan, build_mode, build_pause, isolation," >&2
       red "  verify_mode, verify_result, verification_report, branch_status," >&2
       red "  verified_at, created_at, archived, base_ref, direct_override," >&2
       red "  build_command, verify_command, handoff_context, handoff_hash" >&2
@@ -288,6 +290,9 @@ cmd_set() {
     build_mode)
       validate_enum "$value" "subagent-driven-development" "executing-plans" "direct"
       ;;
+    build_pause)
+      validate_enum "$value" "null" "plan-ready"
+      ;;
     isolation)
       validate_enum "$value" "branch" "worktree"
       ;;
@@ -589,6 +594,177 @@ 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 build_pause 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")
+  build_pause=$(cmd_get "$change_name" "build_pause" 2>/dev/null || true)
+  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"
+      field_status "build_pause" "$build_pause"
+      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 [ "$build_pause" = "plan-ready" ] && [ -n "$plan" ] && [ "$plan" != "null" ] && [ -f "$plan" ] && { [ "$isolation" = "null" ] || [ -z "$isolation" ] || [ "$build_mode" = "null" ] || [ -z "$build_mode" ]; }; then
+        echo "Recovery action: Plan-ready pause detected. Ask the user whether to continue, then choose isolation and build mode without regenerating the plan."
+      elif [ "$build_pause" = "plan-ready" ] && { [ -z "$plan" ] || [ "$plan" = "null" ] || [ ! -f "$plan" ]; }; then
+        echo "Recovery action: Plan-ready pause is recorded, but the plan file is missing. Restore the plan file or rerun writing-plans before choosing execution."
+      elif [ "$build_pause" = "plan-ready" ]; then
+        echo "Recovery action: Plan-ready pause is stale because build decisions are already selected. Clear build_pause to null, then continue from the first unchecked task."
+      elif [ "$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 +870,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/scripts/comet-yaml-validate.sh

@@ -126,6 +126,7 @@ validate_enum() {
 workflow=$(field_value "workflow")
 phase=$(field_value "phase")
 build_mode=$(field_value "build_mode")
+build_pause=$(field_value "build_pause")
 isolation=$(field_value "isolation")
 verify_mode=$(field_value "verify_mode")
 verify_result=$(field_value "verify_result")
@@ -140,6 +141,7 @@ handoff_hash=$(field_value "handoff_hash")
 validate_enum "workflow"      "$workflow"      "full hotfix tweak"
 validate_enum "phase"         "$phase"          "open design build verify archive"
 validate_enum "build_mode"    "$build_mode"     "subagent-driven-development executing-plans direct"
+validate_enum "build_pause"   "$build_pause"     "null plan-ready"
 validate_enum "isolation"     "$isolation"      "branch worktree"
 validate_enum "verify_mode"   "$verify_mode"    "light full"
 validate_enum "verify_result" "$verify_result"  "pending pass fail"
@@ -174,7 +176,7 @@ if [ -n "$handoff_hash" ] && [ "$handoff_hash" != "null" ]; then
 fi
 
 # --- Unknown keys check ---
-KNOWN_KEYS="workflow phase design_doc plan build_mode isolation verify_mode verify_result verification_report branch_status verified_at created_at archived direct_override build_command verify_command handoff_context handoff_hash base_ref"
+KNOWN_KEYS="workflow phase design_doc plan build_mode build_pause isolation verify_mode verify_result verification_report branch_status verified_at created_at archived direct_override build_command verify_command handoff_context handoff_hash base_ref"
 while IFS=: read -r key _; do
   key="${key// /}"
   [ -z "$key" ] && continue

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

@@ -24,7 +24,7 @@ if [ -z "$COMET_ENV" ]; then
   return 1
 fi
 . "$COMET_ENV"
-bash "$COMET_STATE" check <name> archive
+"$COMET_BASH" "$COMET_STATE" check <name> archive
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -34,7 +34,7 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 Run the archive script to automatically complete all steps:
 
 ```bash
-bash "$COMET_ARCHIVE" "<change-name>"
+"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"
 ```
 
 The script automatically executes:
@@ -66,7 +66,7 @@ brainstorming → delta spec → implementation → verification → main spec o
 - Archive directory `openspec/changes/archive/YYYY-MM-DD-<change-name>/` exists
 - Archived `.comet.yaml` contains `archived: true`
 
-The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After successful archive, **do not run** `bash "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Archive completeness is determined by script exit code and archived directory state.
+The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After successful archive, **do not run** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Archive completeness is determined by script exit code and archived directory state.
 
 ## Complete
 

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

@@ -23,14 +23,16 @@ if [ -z "$COMET_ENV" ]; then
   return 1
 fi
 . "$COMET_ENV"
-bash "$COMET_STATE" check <name> build
+"$COMET_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.
+**Immediately execute:** Use the Skill tool to load the Superpowers `writing-plans` skill. Skipping this step is prohibited.
 
 After the skill loads, follow its guidance to create a plan. Plan requirements:
 - Save to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
@@ -51,18 +53,49 @@ base-ref: <git rev-parse HEAD before implementation>
 git rev-parse HEAD
 ```
 
-### 2. Update Plan Status
+### 2. Update Plan Status and Provide Plan-Ready Pause Point
 
 Record plan path:
 
 ```bash
-bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+"$COMET_BASH" "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 ```
 
 No manual phase update needed — guard auto-transitions when exit conditions are met.
 
+After the plan is recorded, immediately provide a new user decision point:
+
+| Option | Behavior | Description |
+|--------|----------|-------------|
+| A | Continue execution | Stay in the current model and proceed to Step 3 to choose workspace isolation and execution method |
+| B | Pause to switch model | Record `build_pause: plan-ready`, stop this `/comet-build` invocation, and allow the user to resume later from `/comet` or `/comet-build` |
+
+This is a user decision point. **Must use the AskUserQuestion tool to pause and wait for the user to explicitly choose**. Must not auto-continue and must not write the pause into `build_mode`.
+
+When the user chooses to continue:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+```
+
+When the user chooses to pause:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> build_pause plan-ready
+```
+
+After setting `build_pause: plan-ready`, stop the current invocation. Do not choose `isolation` or `build_mode`, and do not load an execution skill.
+
 ### 3. Select Workflow Configuration
 
+If resuming with `build_pause: plan-ready` and the `plan` file exists, do not rerun `writing-plans`. First tell the user the workflow is stopped at the plan-ready pause point; after the user confirms continuing, set:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+```
+
+Then continue this step to choose workspace isolation and execution method.
+
 Plan has been written to the current branch. Before starting execution, **ask the user to choose both workspace isolation and execution method in a single interaction**:
 
 **Workspace Isolation**:
@@ -80,21 +113,21 @@ Plan has been written to the current branch. Before starting execution, **ask th
 
 | Option | Skill | Applicable Scenario |
 |------|------|-------------------|
-| A | `superpowers:subagent-driven-development` | Independent tasks, high complexity, requires two-phase review |
-| B | `superpowers:executing-plans` | Simple tasks, no subagent environment, lightweight and fast |
+| A | Superpowers `subagent-driven-development` | Independent tasks, high complexity, requires two-phase review |
+| B | Superpowers `executing-plans` | Simple tasks, no subagent environment, lightweight and fast |
 
 **Execution method recommendation rules**:
 - Task count ≥ 3 → Recommend A
 - 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:
 
 ```bash
-bash "$COMET_STATE" set <name> isolation <branch|worktree>
-bash "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
+"$COMET_BASH" "$COMET_STATE" set <name> isolation <branch|worktree>
+"$COMET_BASH" "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
 ```
 
 `isolation` is a script-enforced hard constraint. Full workflow init may temporarily leave it as `null`, but only before this step. If it remains `null`, both the `build → verify` guard and `comet-state transition build-complete` will fail.
@@ -102,8 +135,8 @@ bash "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing
 `build_mode` defaults to `direct` only for hotfix/tweak presets. Full workflow must not default to `direct`. Use it only when the user explicitly asks to bypass the plan execution skills and you record an explicit override:
 
 ```bash
-bash "$COMET_STATE" set <name> direct_override true
-bash "$COMET_STATE" set <name> build_mode direct
+"$COMET_BASH" "$COMET_STATE" set <name> direct_override true
+"$COMET_BASH" "$COMET_STATE" set <name> build_mode direct
 ```
 
 Without `direct_override: true`, `build_mode=direct` in full workflow is blocked by both guard and state transition.
@@ -111,7 +144,7 @@ Without `direct_override: true`, `build_mode=direct` in full workflow is blocked
 **Execute isolation**:
 
 - **branch**: Run `git checkout -b <change-name>`, subsequent work on the new branch
-- **worktree**: Must use the Skill tool to load `superpowers:using-git-worktrees` skill to create isolated workspace. Do not bypass this skill with plain shell commands or native tools; if the skill is unavailable, stop the process and prompt to install or enable Superpowers skills.
+- **worktree**: Must use the Skill tool to load the Superpowers `using-git-worktrees` skill to create isolated workspace. Do not bypass this skill with plain shell commands or native tools; if the skill is unavailable, stop the process and prompt to install or enable Superpowers skills.
 
 After creating isolation, confirm plan file is accessible (naturally accessible with branch method; for worktree method, confirm plan has been committed).
 
@@ -131,10 +164,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 the Superpowers `brainstorming` skill 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 +182,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 `"$COMET_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
@@ -161,7 +194,7 @@ Build is the longest phase and may span many tasks. To support resume after cont
 - Project-specific build/tests explicitly run and pass; do not rely only on guard auto-detection
 - `isolation` has been written as `branch` or `worktree`
 - `build_mode` has been written as `subagent-driven-development`, `executing-plans`, or `direct` with explicit override
-- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
+- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
 
 Guard reads project command configuration first:
 
@@ -176,13 +209,13 @@ Only when no command is configured does guard fall back to `npm run build`, Mave
 Before exit, run guard to auto-transition:
 
 ```bash
-bash "$COMET_GUARD" <change-name> build --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
 ```
 
 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

@@ -23,17 +23,19 @@ if [ -z "$COMET_ENV" ]; then
   return 1
 fi
 . "$COMET_ENV"
-bash "$COMET_STATE" check <name> design
+"$COMET_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.**
 
 ```bash
-bash "$COMET_HANDOFF" <change-name> design --write
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
 ```
 
 The script generates and records:
@@ -58,7 +60,7 @@ The default handoff package is a **compact traceable excerpt**, not an agent sum
 If full context is genuinely needed, explicitly run:
 
 ```bash
-bash "$COMET_HANDOFF" <change-name> design --write --full
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
 ```
 
 Handoff package sources come from OpenSpec open phase artifacts:
@@ -69,7 +71,7 @@ Handoff package sources come from OpenSpec open phase artifacts:
 
 ### 1b. Execute Brainstorming (with Context)
 
-**Immediately execute:** Use the Skill tool to load the `superpowers:brainstorming` skill, ARGUMENTS containing:
+**Immediately execute:** Use the Skill tool to load the Superpowers `brainstorming` skill, ARGUMENTS containing:
 
 ```
 Change: <change-name>
@@ -92,7 +94,7 @@ Skip redundant context exploration, proceed directly to design questions.
 
 Skipping this step is prohibited. Proceeding without loading this skill is prohibited.
 
-If `superpowers:brainstorming` is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.
+If the Superpowers `brainstorming` skill 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 produce design proposals (presented as conversation):
 - Technical approach: architecture, data flow, key technology choices and risks
@@ -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
@@ -119,13 +121,13 @@ First record the design_doc path. If Step 1c wrote back delta spec (added or mod
 
 ```bash
 # Record design_doc path
-bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+"$COMET_BASH" "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # If delta spec changes exist, regenerate handoff (update hash)
-bash "$COMET_HANDOFF" <change-name> design --write
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
 
 # Auto-transition to next phase
-bash "$COMET_GUARD" <change-name> design --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
 ```
 
 If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
@@ -139,16 +141,26 @@ If there are no delta spec changes, skip the handoff regeneration step. The stat
 - `design-context.md` must be script-generated and contain source path, mode, sha256 traceability markers (enforced by guard)
 - If new capabilities or supplementary acceptance scenarios exist, OpenSpec delta spec has been created/updated
 - `design_doc` written to `.comet.yaml`
-- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
+- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
 
 Must use `--apply` before exit:
 
 ```bash
-bash "$COMET_GUARD" <change-name> design --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
 ```
 
+## Context Compaction Recovery
+
+The design phase may trigger context compaction during brainstorming. To recover, first run:
+
+```bash
+"$COMET_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

@@ -46,24 +46,24 @@ After the skill loads, follow its guidance to create streamlined artifacts:
 Initialize Comet state file:
 
 ```bash
-bash "$COMET_STATE" init <name> hotfix
+"$COMET_BASH" "$COMET_STATE" init <name> hotfix
 ```
 
 Verify initialized state:
 
 ```bash
-bash "$COMET_STATE" check <name> open
+"$COMET_BASH" "$COMET_STATE" check <name> open
 ```
 
 Run phase guard to transition open → build:
 
 ```bash
-bash "$COMET_GUARD" <change-name> open --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. Direct Build (preset build)
 
-Use hotfix defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection).
+Use hotfix defaults: `build_mode: direct`. Skip Superpowers `brainstorming` and `writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection).
 
 Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the fix scope exceeds hotfix, handle it through this file's "Upgrade Conditions".
 
@@ -97,7 +97,7 @@ Before continuing or starting changes, handle uncommitted changes through `comet
 After root cause is confirmed eliminated, run phase guard to transition build → verify:
 
 ```bash
-bash "$COMET_GUARD" <change-name> build --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
 ```
 
 State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
@@ -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,12 +149,12 @@ 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:
 
 ```bash
-bash "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> workflow full
 ```
 
 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.
@@ -166,4 +166,4 @@ Then on current change basis, supplement Design Doc: **Immediately use the Skill
 - Bug fixed, tests pass
 - Change archived
 - If spec changes, synced to main spec
-- **Phase guard**: Before build → verify run `bash "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `bash "$COMET_GUARD" <change-name> verify --apply`
+- **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`