@rpamis/comet 0.3.5 → 0.3.6

package/README.md

@@ -309,6 +309,7 @@ All states and execution phases are updated via scripts, and each phase verifies
 workflow: full
 phase: build
 build_mode: subagent-driven-development
+build_pause: null
 isolation: branch
 verify_mode: null
 design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
@@ -325,7 +326,7 @@ handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
 handoff_hash: <sha256>
 ```
 
-In full workflow, `build_mode`, `isolation`, and `verify_mode` may temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override` is only needed for full-workflow direct builds, project commands may be absent unless configured, and `handoff_context` / `handoff_hash` are recorded by `comet-handoff.sh` before leaving design. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
+In full workflow, `build_mode`, `build_pause`, `isolation`, and `verify_mode` may temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `build_pause` records an internal build-phase pause point: `null` means no pause, while `plan-ready` means the plan has been generated and the user paused before choosing isolation and execution mode. It is not an execution mode and must not be written into `build_mode`. `verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override` is only needed for full-workflow direct builds, project commands may be absent unless configured, and `handoff_context` / `handoff_hash` are recorded by `comet-handoff.sh` before leaving design. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
 
 </details>
 
@@ -355,6 +356,7 @@ Comet ensures agent execution reliability through automated state transitions:
 4. **Build Decision Enforcement** — Guard and state transitions both block skipped build choices
    - `isolation` must be `branch` or `worktree`
    - `build_mode` must be selected before leaving build
+   - `build_pause: plan-ready` is a recoverable pause after plan generation, not a `build_mode`
    - Full workflow `build_mode: direct` requires `direct_override: true`
 
 5. **Verification Evidence** — Guard enforces proof before phase advance
@@ -419,13 +421,23 @@ Track our development progress and upcoming features on the [Comet Roadmap](http
 ## 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" />
+  <img src="https://contrib.rocks/image?repo=rpamis/comet&columns=12&anon=1" />
 </a>
 
 ## License
 
 [MIT](LICENSE)
 
+## Community
+
+<p align="center">
+  <img src="https://github.com/rpamis/comet/blob/master/img/wechat.jpg" alt="WeChat Group" width="200" />
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="https://github.com/rpamis/comet/blob/master/img/qq.jpg" alt="QQ Group" width="200" />
+</p>
+
+<p align="center">WeChat Group &nbsp;&nbsp;|&nbsp;&nbsp; QQ Group</p>
+
 ## Reference
 
 [LINUX DO - 新的理想型社区](https://linux.do/)

package/assets/skills/comet/SKILL.md

@@ -53,9 +53,13 @@ Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall bac
 **Resume rules**:
 - On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
 - If there is an active change and the worktree has uncommitted changes, handle them through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions; this file does not repeat them
-- If `phase: build`, first check whether `build_mode` and `isolation` are set; if any fields are unset, return to `/comet-build` corresponding step to supplement before executing; if both are set, read the next unchecked task from tasks.md and continue
-- If `phase: verify` and `verify_result: fail`, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run `bash "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
-- If `phase: open` but proposal/design/tasks are complete, first run `bash "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
+- If `phase: build`, first check `build_pause`, `plan`, `build_mode`, and `isolation`:
+  - If `build_pause: plan-ready` and the plan file exists, return to the `/comet-build` plan-ready resume point, prompt the user to continue choosing isolation and execution method, and do not regenerate the plan
+  - If `build_pause: plan-ready` but the plan file is missing, return to `/comet-build` to handle corrupted state or regenerate the plan
+  - If `build_mode` or `isolation` is unset, return to the corresponding `/comet-build` step to supplement before executing
+  - If both are set, read the next unchecked task from tasks.md and continue
+- If `phase: verify` and `verify_result: fail`, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
+- If `phase: open` but proposal/design/tasks are complete, first run `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
 - If `phase: archive`, only invoke `/comet-archive`; after archive succeeds, the change moves to the archive directory, so do not run guard against the old active directory
 
 **Step 2: Phase Determination** (check in order, first match wins)
@@ -92,7 +96,7 @@ If metadata conflicts with file state, use verifiable file state as source of tr
 |----------|----------|
 | `openspec list --json` fails | Check if openspec is installed, prompt user to run `openspec init` |
 | Sub-skill unavailable | Stop workflow, prompt to install or enable the corresponding skill |
-| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `bash $COMET_STATE set` then continue |
+| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `"$COMET_BASH" "$COMET_STATE" set` then continue |
 | Build/test fails | Return to build phase for fixes, do not enter verify |
 | Incomplete change directory structure | Fill missing files according to `comet-open` artifact requirements |
 
@@ -110,7 +114,7 @@ Flow chain: open → design → build → verify → archive
 Nodes requiring user participation (pause only at these nodes):
 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)
+3. Plan-ready pause choice during build phase, followed by workflow configuration selection (isolation + execution method)
 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)
@@ -171,6 +175,7 @@ design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
 base_ref: a1b2c3d4e5f6...
 build_mode: subagent-driven-development
+build_pause: null
 isolation: branch
 verify_mode: light
 verify_result: pending
@@ -189,6 +194,7 @@ archived: false
 | `plan` | Associated Superpowers Plan path, can be empty |
 | `base_ref` | Git commit SHA recorded at init, used for scale assessment. Serves as fallback when no plan exists |
 | `build_mode` | Selected execution method, can be empty |
+| `build_pause` | Internal build-phase pause point. `null` means no pause; `plan-ready` means the plan has been generated and the user chose to pause for switching models |
 | `isolation` | `branch` or `worktree`, workspace isolation method. Full workflow init may leave this as `null`, but only until `/comet-build` Step 3; hotfix/tweak default to `branch` |
 | `verify_mode` | `light` or `full`, can be empty |
 | `verify_result` | `pending`, `pass`, or `fail` |
@@ -210,6 +216,7 @@ State-machine hard constraints:
 - Before `build → verify`, `isolation` must be `branch` or `worktree`
 - Before `build → verify`, `build_mode` must be selected
 - `build_mode: direct` is allowed by default only for `hotfix` / `tweak`; full workflow requires `direct_override: true`
+- `build_pause` is not an execution method and must not be written to `build_mode`
 - These constraints are enforced by both `comet-guard.sh build --apply` and `comet-state.sh transition <name> build-complete`
 
 ### Script Location
@@ -235,24 +242,24 @@ fi
 **Auto state update**: Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
 
 ```bash
-bash "$COMET_GUARD" <change-name> <phase> --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply
 ```
 
 `--apply` delegates to `comet-state transition`. Use these semantic events when state changes need to be expressed directly:
 
 ```bash
-bash "$COMET_STATE" transition <change-name> open-complete
-bash "$COMET_STATE" transition <change-name> design-complete
-bash "$COMET_STATE" transition <change-name> build-complete
-bash "$COMET_STATE" transition <change-name> verify-pass
-bash "$COMET_STATE" transition <change-name> verify-fail
-bash "$COMET_STATE" transition <archive-name> archived
+"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
+"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
+"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
+"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
+"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
 ```
 
 **Archive script**: Complete all archive steps in one command:
 
 ```bash
-bash "$COMET_ARCHIVE" <change-name>
+"$COMET_BASH" "$COMET_ARCHIVE" <change-name>
 ```
 
 After loading comet, agents should run the variable assignments above once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE` throughout the session.

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

@@ -5,6 +5,8 @@
 
 set -euo pipefail
 
+COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
+
 red() { echo -e "\033[31m$1\033[0m" >&2; }
 green() { echo -e "\033[32m$1\033[0m" >&2; }
 yellow() { echo -e "\033[33m$1\033[0m" >&2; }
@@ -70,7 +72,7 @@ echo "=== Comet Archive: $CHANGE ===" >&2
 yaml_field() {
   local field="$1"
   if [ -f "$STATE_SH" ]; then
-    bash "$STATE_SH" get "$CHANGE" "$field" 2>/dev/null
+    "$COMET_BASH" "$STATE_SH" get "$CHANGE" "$field" 2>/dev/null
   else
     if [ -f "$YAML" ]; then
       local value
@@ -270,7 +272,7 @@ if [ "$DRY_RUN" -eq 1 ]; then
   step_dry_run "Would set archived: true in $ARCHIVE_YAML"
 else
   if [ -f "$ARCHIVE_YAML" ]; then
-    bash "$STATE_SH" transition "$ARCHIVE_NAME" archived >/dev/null
+    "$COMET_BASH" "$STATE_SH" transition "$ARCHIVE_NAME" archived >/dev/null
     step_ok "archived: true"
   else
     step_fail "archived: true (.comet.yaml not found after move)"

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

@@ -17,15 +17,65 @@ 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_bash_is_usable() {
+  local _comet_bash_candidate="$1"
+  if [ -z "$_comet_bash_candidate" ]; then
+    return 1
+  fi
+  case "$_comet_bash_candidate" in
+    */Windows/System32/bash.exe|*/windows/system32/bash.exe|*\\Windows\\System32\\bash.exe|*\\windows\\system32\\bash.exe)
+      return 1
+      ;;
+  esac
+  "$_comet_bash_candidate" -lc 'printf comet-bash-ok' >/dev/null 2>&1
+}
+
+_comet_resolve_bash() {
+  local _comet_bash_candidate
+
+  if _comet_bash_is_usable "${COMET_BASH:-}"; then
+    printf '%s\n' "$COMET_BASH"
+    return 0
+  fi
+
+  if _comet_bash_is_usable "${BASH:-}"; then
+    printf '%s\n' "$BASH"
+    return 0
+  fi
+
+  _comet_bash_candidate="$(command -v sh 2>/dev/null | awk '{ sub(/\/sh(\.exe)?$/, "/bash.exe"); print }')"
+  if _comet_bash_is_usable "$_comet_bash_candidate"; then
+    printf '%s\n' "$_comet_bash_candidate"
+    return 0
+  fi
+
+  _comet_bash_candidate="$(command -v bash 2>/dev/null || true)"
+  if _comet_bash_is_usable "$_comet_bash_candidate"; then
+    printf '%s\n' "$_comet_bash_candidate"
+    return 0
+  fi
+
+  return 1
+}
+
+COMET_BASH="$(_comet_resolve_bash || true)"
+export COMET_BASH
+
 _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_bash_fail() {
+  echo "ERROR: usable bash not found. Install Git Bash or set COMET_BASH to a working bash executable." >&2
+  echo "Windows WSL launcher bash.exe is not supported for Comet scripts." >&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
+  unset _comet_bash_candidate
+  unset -f _comet_env_fail _comet_bash_fail _comet_bash_is_usable _comet_resolve_bash
   if [ "$_comet_env_was_sourced" -eq 1 ]; then
     unset -f _comet_env_abort
     return 1
@@ -34,6 +84,10 @@ _comet_env_abort() {
 }
 
 _comet_env_missing=0
+if [ -z "$COMET_BASH" ]; then
+  _comet_bash_fail
+  _comet_env_missing=1
+fi
 for _comet_script in \
   "$COMET_GUARD" \
   "$COMET_STATE" \
@@ -51,5 +105,6 @@ 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
+  unset _comet_bash_candidate
+  unset -f _comet_env_fail _comet_bash_fail _comet_bash_is_usable _comet_resolve_bash _comet_env_abort
 fi

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

@@ -7,6 +7,8 @@
 
 set -euo pipefail
 
+COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
+
 red() { echo -e "\033[31m$1\033[0m" >&2; }
 green() { echo -e "\033[32m$1\033[0m" >&2; }
 warn() { echo -e "\033[33m$1\033[0m" >&2; }
@@ -181,7 +183,7 @@ is_windows_bash() {
 run_command_string() {
   local command="$1"
   echo "+ $command" >&2
-  bash -lc "$command"
+  "$COMET_BASH" -lc "$command"
 }
 
 hash_stream() {
@@ -240,8 +242,8 @@ preflight() {
   local validate_script
   validate_script="$SCRIPT_DIR/comet-yaml-validate.sh"
   if [ -f "$validate_script" ]; then
-    if ! bash "$validate_script" "$CHANGE" 2>/dev/null; then
-      bash "$validate_script" "$CHANGE"
+    if ! "$COMET_BASH" "$validate_script" "$CHANGE" 2>/dev/null; then
+      "$COMET_BASH" "$validate_script" "$CHANGE" || true
       red "FATAL: .comet.yaml schema validation failed"
       exit 1
     fi
@@ -300,7 +302,7 @@ isolation_selected() {
     *)
       echo "isolation must be branch or worktree, got '${isolation:-null}'" >&2
       echo "Next: ask the user to choose branch or worktree, create the chosen isolation, then run:" >&2
-      echo "  bash \"\$COMET_STATE\" set $CHANGE isolation <branch|worktree>" >&2
+      echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE isolation <branch|worktree>" >&2
       return 1
       ;;
   esac
@@ -313,8 +315,8 @@ build_mode_selected() {
     subagent-driven-development|executing-plans|direct) return 0 ;;
     *)
       echo "build_mode must be selected before leaving build, got '${build_mode:-null}'" >&2
-      echo "Next: ask the user to choose an implementation mode, then run:" >&2
-      echo "  bash \"\$COMET_STATE\" set $CHANGE build_mode <subagent-driven-development|executing-plans>" >&2
+      echo "Next: ask the user to choose an execution mode, then run:" >&2
+      echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE build_mode <subagent-driven-development|executing-plans>" >&2
       return 1
       ;;
   esac
@@ -336,7 +338,7 @@ build_mode_allowed_for_workflow() {
         return 0
       fi
       echo "build_mode=direct is only allowed for hotfix/tweak unless direct_override: true is recorded" >&2
-      echo "Next: switch build_mode to executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override." >&2
+      echo "Next: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override." >&2
       return 1
       ;;
   esac
@@ -367,7 +369,7 @@ design_handoff_context_valid() {
 
   if [ -z "$context" ] || [ "$context" = "null" ]; then
     echo "handoff_context is missing from .comet.yaml" >&2
-    echo "Next: run bash \"\$COMET_HANDOFF\" $CHANGE design --write before invoking Superpowers." >&2
+    echo "Next: run \"\$COMET_BASH\" \"\$COMET_HANDOFF\" $CHANGE design --write before invoking Superpowers." >&2
     return 1
   fi
   if [ ! -s "$context" ]; then
@@ -545,10 +547,10 @@ apply_state_update() {
 
   if [ -f "$state_sh" ]; then
     case "$p" in
-      open)   bash "$state_sh" transition "$CHANGE" open-complete ;;
-      design) bash "$state_sh" transition "$CHANGE" design-complete ;;
-      build)  bash "$state_sh" transition "$CHANGE" build-complete ;;
-      verify) bash "$state_sh" transition "$CHANGE" verify-pass ;;
+      open)   "$COMET_BASH" "$state_sh" transition "$CHANGE" open-complete ;;
+      design) "$COMET_BASH" "$state_sh" transition "$CHANGE" design-complete ;;
+      build)  "$COMET_BASH" "$state_sh" transition "$CHANGE" build-complete ;;
+      verify) "$COMET_BASH" "$state_sh" transition "$CHANGE" verify-pass ;;
     esac
   else
     red "FATAL: comet-state.sh not found; cannot apply state transition"

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

@@ -4,6 +4,8 @@
 
 set -euo pipefail
 
+COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
+
 red() { echo -e "\033[31m$1\033[0m" >&2; }
 green() { echo -e "\033[32m$1\033[0m" >&2; }
 
@@ -249,8 +251,8 @@ write_markdown_context "$CONTEXT_MD"
 write_json_context "$CONTEXT_JSON"
 
 if [ -x "$STATE_SH" ] || [ -f "$STATE_SH" ]; then
-  bash "$STATE_SH" set "$CHANGE" handoff_context "$CONTEXT_JSON" >/dev/null
-  bash "$STATE_SH" set "$CHANGE" handoff_hash "$CONTEXT_HASH" >/dev/null
+  "$COMET_BASH" "$STATE_SH" set "$CHANGE" handoff_context "$CONTEXT_JSON" >/dev/null
+  "$COMET_BASH" "$STATE_SH" set "$CHANGE" handoff_hash "$CONTEXT_HASH" >/dev/null
 else
   red "ERROR: comet-state.sh not found; cannot record handoff fields"
   exit 1

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

@@ -205,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
@@ -264,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
@@ -289,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"
       ;;
@@ -632,7 +636,7 @@ cmd_recover() {
 
   # 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
+  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")
@@ -643,6 +647,7 @@ cmd_recover() {
   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:"
@@ -688,6 +693,7 @@ cmd_recover() {
       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
@@ -707,7 +713,13 @@ cmd_recover() {
         echo "  Tasks: tasks.md MISSING"
       fi
       echo ""
-      if [ "$isolation" = "null" ] || [ -z "$isolation" ]; then
+      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."

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,7 +23,7 @@ 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.
@@ -32,7 +32,7 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 
 ### 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`
@@ -53,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**:
@@ -82,8 +113,8 @@ 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
@@ -95,8 +126,8 @@ This is a user decision point. **Must use the AskUserQuestion tool to pause and
 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.
@@ -104,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.
@@ -113,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).
 
@@ -133,7 +164,7 @@ 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 | **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 |
+| 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 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.
@@ -151,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**: 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.
+- **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
@@ -163,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:
 
@@ -178,7 +209,7 @@ 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`.