@rpamis/comet 0.3.0 → 0.3.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 rpamis
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 rpamis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.6",
+  "version": "0.3.1",
   "skills": [
     "comet/SKILL.md",
     "comet/reference/dirty-worktree.md",

package/assets/skills/comet/SKILL.md

@@ -5,7 +5,7 @@ description: "Comet — OpenSpec + Superpowers dual-star development workflow. S
 
 # Comet — OpenSpec + Superpowers Dual-Star Development Workflow
 
-OpenSpec and Superpowers orbit the same goal like a binary star system. OpenSpec handles WHAT, Superpowers handles HOW.
+OpenSpec and Superpowers orbit the same goal like a binary star system.
 
 ```
 OpenSpec handles WHAT  — outline, proposal, spec lifecycle, archive
@@ -42,7 +42,7 @@ Agents need only read this section for decision-making. Refer to the Reference A
 
 <IMPORTANT>
 When the user chooses "create a new change", **must invoke `/comet-open`**. Do not call `/opsx:new` directly.
-`/comet-open` performs dual initialization: OpenSpec artifacts plus `.comet.yaml` state.
+`/comet-open` performs dual initialization: OpenSpec artifacts (created by internal `/opsx:new`) plus `.comet.yaml` state file.
 Calling `/opsx:new` directly leaves `.comet.yaml` missing and breaks later phase detection.
 </IMPORTANT>
 
@@ -53,18 +53,18 @@ 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`, read the next unchecked task from tasks.md and continue
-- If `phase: verify` and `verify_result: fail`, first run `bash "$COMET_STATE" transition <name> verify-fail`, then invoke `/comet-build`
-- If `phase: open` but proposal/design/tasks are complete, run `bash "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
+- 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: 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)
 
 1. `archived: true` or change moved to archive → Workflow complete
 2. `verify_result: pass` and `archived` is not `true` → Invoke `/comet-archive`
-3. `verify_result: fail` → run `bash "$COMET_STATE" transition <name> verify-fail`, then invoke `/comet-build`
+3. `verify_result: fail` → Enter verification failure decision blocking point (pause and ask fix or accept deviation; only after user chooses fix, run `verify-fail` then `/comet-build`)
 4. `phase: verify` or tasks.md all checked → Invoke `/comet-verify`
-5. `phase: build` or has Design Doc but plan/execution incomplete → Invoke `/comet-build`
+5. `phase: build` or has Design Doc but plan/execution incomplete → Route by workflow: `hotfix` → `/comet-hotfix`, `tweak` → `/comet-tweak`, `full` → `/comet-build`
 6. `phase: design` or has change but no Design Doc → Invoke `/comet-design`
 7. `phase: open` or active change exists but `.comet.yaml` is missing → Invoke `/comet-open`
 8. No active change → Invoke `/comet-open`
@@ -103,16 +103,19 @@ 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 without waiting for another user command, except at explicit decision points. After a phase completes, immediately enter the next phase.
+**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.
 
-Nodes requiring user participation:
+**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.
+
+Nodes requiring user participation (pause only at these nodes):
 1. Confirm design approach during brainstorming
-2. Select execution mode during build phase
-3. Decide to fix or accept deviation when verify fails
+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 can proceed automatically.
+Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway.
 </IMPORTANT>
 
 ---
@@ -137,11 +140,11 @@ Agents should not skip these decision points; other unambiguous phase transition
 
 /comet-hotfix (preset, skip brainstorming)
   open ──→ build ──→ verify ──→ archive
-    ↑ If upgrade triggered → supplement Design Doc → return to full workflow
+    ↑ If upgrade triggered → block for confirmation → supplement Design Doc → return to full workflow
 
 /comet-tweak (preset, skip brainstorming and full plan)
   open ──→ lightweight build ──→ light verify ──→ archive
-    ↑ If upgrade triggered → supplement Design Doc → return to full workflow
+    ↑ If upgrade triggered → block for confirmation → supplement Design Doc → return to full workflow
 ```
 
 ---
@@ -155,12 +158,14 @@ workflow: full
 phase: build
 design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+base_ref: a1b2c3d4e5f6...
 build_mode: subagent-driven-development
 isolation: branch
 verify_mode: light
 verify_result: pending
 verification_report: null
 branch_status: pending
+created_at: 2026-05-26
 verified_at: null
 archived: false
 ```
@@ -168,15 +173,17 @@ archived: false
 | Field | Meaning |
 |-------|---------|
 | `workflow` | `full`, `hotfix`, or `tweak` |
-| `phase` | Current phase: `open`, `design`, `build`, `verify`, `archive` |
+| `phase` | Current phase: `open`, `design`, `build`, `verify`, `archive` (init sets to `open` uniformly, guard handles transitions) |
 | `design_doc` | Associated Superpowers Design Doc path, can be empty |
 | `plan` | Associated Superpowers Plan path, can be empty |
-| `build_mode` | Selected execution mode, 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 |
 | `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` |
 | `verification_report` | Verification report file path; must point to an existing file before verify can pass |
 | `branch_status` | `pending` or `handled`; set to `handled` after branch handling completes |
+| `created_at` | Change creation date (auto-set at init), format `YYYY-MM-DD` |
 | `verified_at` | Verification pass time, can be empty |
 | `archived` | Whether change is archived |
 
@@ -202,9 +209,11 @@ Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** —
 COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
 COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
 COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_HANDOFF="${COMET_HANDOFF:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-handoff.sh' -type f -print -quit 2>/dev/null)}"
 COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"
 
-if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_ARCHIVE" ]; then
+# Stop workflow when script location fails
+if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
   echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
   return 1
@@ -234,7 +243,7 @@ bash "$COMET_STATE" transition <archive-name> archived
 bash "$COMET_ARCHIVE" <change-name>
 ```
 
-After loading comet, agents should run the three variable assignments above once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_ARCHIVE` throughout the session.
+After loading comet, agents should run the variable assignments above once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE` throughout the session.
 
 ### File Structure
 
@@ -248,6 +257,7 @@ openspec/                              # OpenSpec — WHAT
 │   │   ├── proposal.md                # Why + What
 │   │   ├── design.md                  # High-level architecture decisions
 │   │   ├── specs/<capability>/spec.md # Delta capability spec
+│   │   ├── .comet/handoff/            # Script-generated phase handoff packages
 │   │   └── tasks.md                   # Task checklist
 │   └── archive/YYYY-MM-DD-<name>/     # Archived
 └── specs/<capability>/spec.md         # Main specs (overwritten from delta at archive)
@@ -261,11 +271,12 @@ docs/superpowers/                      # Superpowers — HOW
 
 1. **brainstorming cannot be skipped** — Every change must undergo deep design (except hotfix and tweak)
 2. **delta spec is a living document** — Freely modify during phase 3, sync at archive
-3. **Keep tasks.md in sync** — Check off each completed task
-4. **Commit frequently** — One commit per task, message reflects design intent
-5. **Verify before archive** — Execute `/comet-archive` only after `/comet-verify` passes
-6. **Classify incremental updates** — Small edits, medium brainstorming, large new changes
-7. **Plan must associate with change** — File header contains `change:` and `design-doc:` metadata
-8. **Archive closure** — design doc and plan must mark `archived-with` status
-9. **Modifying existing features** — Just open a new change
-10. **Preset has limits** — Switch to full workflow promptly when hotfix/tweak meet upgrade conditions
+3. **Handoff packages are generated by scripts** — OpenSpec → Superpowers context must be generated through `comet-handoff.sh` as compact traceable excerpts (use `--full` when needed), and validated by guard for source/hash/mode
+4. **Keep tasks.md in sync** — Check off each completed task
+5. **Commit frequently** — One commit per task, message reflects design intent
+6. **Verify before archive** — Execute `/comet-archive` only after `/comet-verify` passes
+7. **Classify incremental updates** — Small edits, medium brainstorming, large new changes
+8. **Plan must associate with change** — File header contains `change:` and `design-doc:` metadata
+9. **Archive closure** — design doc and plan must mark `archived-with` status
+10. **Modifying existing features** — Just open a new change
+11. **Preset has limits** — Switch to full workflow promptly when hotfix/tweak meet upgrade conditions

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

@@ -194,17 +194,25 @@ cmd_init() {
   esac
 
   # Write .comet.yaml
+  # Record current HEAD as base_ref for scale assessment fallback
+  local base_ref="null"
+  if git rev-parse --verify HEAD >/dev/null 2>&1; then
+    base_ref=$(git rev-parse HEAD 2>/dev/null || echo "null")
+  fi
+
   cat > "$yaml_file" <<EOF
 workflow: $workflow
 phase: $phase
 build_mode: $build_mode
 isolation: $isolation
 verify_mode: $verify_mode
+base_ref: $base_ref
 design_doc: null
 plan: null
 verify_result: pending
 verification_report: null
 branch_status: pending
+created_at: $(date +%Y-%m-%d)
 verified_at: null
 archived: false
 EOF
@@ -251,7 +259,11 @@ cmd_set() {
 
   # Validate field name
   case "$field" in
-    workflow|phase|build_mode|isolation|verify_mode|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|direct_override|build_command|verify_command|handoff_context|handoff_hash)
+    phase)
+      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)
       # Valid field
       ;;
     *)
@@ -294,7 +306,7 @@ cmd_set() {
     direct_override)
       validate_enum "$value" "true" "false"
       ;;
-    design_doc|plan|verification_report|verified_at|build_command|verify_command|handoff_context|handoff_hash)
+    design_doc|plan|verification_report|verified_at|created_at|build_command|verify_command|handoff_context|handoff_hash)
       # No validation for path fields, date fields, or project command strings
       ;;
   esac
@@ -605,16 +617,20 @@ cmd_scale() {
     delta_spec_count=$(find "$change_dir/specs" -name "spec.md" -type f 2>/dev/null | wc -l | tr -d ' ')
   fi
 
-  # 3. Changed files: prefer plan base-ref, fall back to worktree diff
+  # 3. Changed files: prefer plan base-ref, then .comet.yaml base_ref, fall back to worktree diff
   local changed_files=0
   if git rev-parse --git-dir > /dev/null 2>&1; then
-    local plan_file base_ref
+    local plan_file base_ref=""
     plan_file=$(cmd_get "$change_name" "plan" 2>/dev/null || true)
     if [ -n "$plan_file" ] && [ "$plan_file" != "null" ] && [ -f "$plan_file" ]; then
       base_ref=$(grep '^base-ref:' "$plan_file" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
     fi
+    # Fallback to base_ref stored in .comet.yaml (set during init)
+    if [ -z "$base_ref" ] || [ "$base_ref" = "null" ]; then
+      base_ref=$(cmd_get "$change_name" "base_ref" 2>/dev/null || true)
+    fi
 
-    if [ -n "${base_ref:-}" ] && git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
+    if [ -n "${base_ref:-}" ] && [ "$base_ref" != "null" ] && git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
       changed_files=$(git diff --name-only "$base_ref"...HEAD 2>/dev/null | wc -l | tr -d ' ')
     else
       changed_files=$(git diff --name-only HEAD 2>/dev/null | wc -l | tr -d ' ')
@@ -623,7 +639,7 @@ cmd_scale() {
 
   # Decision rules
   local result="light"
-  if [ "$task_count" -gt 3 ] || [ "$delta_spec_count" -gt 1 ] || [ "$changed_files" -gt 5 ]; then
+  if [ "$task_count" -gt 3 ] || [ "$delta_spec_count" -gt 1 ] || [ "$changed_files" -gt 4 ]; then
     result="full"
   fi
 
@@ -631,7 +647,7 @@ cmd_scale() {
   echo "=== Scale Assessment: $change_name ===" >&2
   echo "  Tasks: $task_count (threshold: 3)" >&2
   echo "  Delta specs: $delta_spec_count capabilities (threshold: 1)" >&2
-  echo "  Changed files: $changed_files (threshold: 5)" >&2
+  echo "  Changed files: $changed_files (threshold: 4)" >&2
   echo "  → Result: $result" >&2
 
   # Update verify_mode in .comet.yaml

package/assets/skills/comet/scripts/comet-yaml-validate.sh

@@ -174,7 +174,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 archived direct_override build_command verify_command handoff_context handoff_hash"
+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"
 while IFS=: read -r key _; do
   key="${key// /}"
   [ -z "$key" ] && continue

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

@@ -45,7 +45,7 @@ If script returns non-zero exit code, report error and stop.
 If script returns zero exit code, archive is complete.
 The summary `X/Y steps succeeded` counts real executed steps and does not double-count delta spec sync or document annotation.
 
-When a delta spec differs from an existing main spec, the script prints a unified diff before overwrite so the archive sync content is visible.
+When a delta spec differs from an existing main spec, the script prints a unified diff preview before overwrite to help confirm archive sync content.
 
 Use `--dry-run` flag to preview without executing.
 
@@ -62,7 +62,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 the 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** `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

@@ -1,6 +1,6 @@
 ---
 name: comet-build
-description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create plans and choose execution method (subagent or direct) for implementation."
+description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create plans and select execution method (subagent or direct) for implementation."
 ---
 
 # Comet Phase 3: Plan and Build (Build)
@@ -58,9 +58,11 @@ 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.
 
-### 3. Workspace Isolation
+### 3. Select Workflow Configuration
 
-Plan has been written to the current branch. Before starting execution, choose workspace isolation 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**:
 
 | Option | Method | Description |
 |--------|--------|-------------|
@@ -71,52 +73,30 @@ Plan has been written to the current branch. Before starting execution, choose w
 - Change involves ≤ 3 files → Recommend A
 - Need parallel development, current branch has uncommitted work → Recommend B
 
-After user selection, update `isolation` field. `isolation` only allows one of the following values:
-
-```bash
-bash "$COMET_STATE" set <name> isolation <value>
-```
-
-- `branch`
-- `worktree`
-
-<IMPORTANT>
-This is a script-enforced hard constraint, not a suggestion. Full workflow init may temporarily leave `isolation` as `null`, but only before this step.
-Before implementation starts, stop and ask the user, then write either `branch` or `worktree`. If it remains `null`, both the `build → verify` guard and `comet-state transition build-complete` will fail.
-</IMPORTANT>
-
-**Execute isolation**:
-
-- **branch**: Run `git checkout -b <change-name>`, subsequent work on the new branch
-- **worktree**: Invoke `superpowers:using-git-worktrees` skill or use native `EnterWorktree` tool to create isolated workspace
-
-After creating isolation, confirm plan file is accessible (naturally accessible with branch method; for worktree method, confirm plan has been committed).
-
-### 4. Select Execution Method
-
-Present plan summary to user (task count, involved modules), then ask for execution method:
+**Execution Method**:
 
 | 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 |
 
-**Recommendation rules**:
+**Execution method recommendation rules**:
 - Task count ≥ 3 → Recommend A
 - Task count ≤ 2 and no cross-module dependencies → Recommend B
 - From hotfix path → Recommend B
 
-After user selection, update `build_mode` field. `build_mode` only allows one of the following values:
+This is a user decision point. Must pause and wait for the user to explicitly choose both isolation method and execution method. **Must not select based on recommendation rules**. Recommendation rules are for suggestion only, not a substitute for user confirmation.
+
+After user selection, update `isolation` and `build_mode` fields:
 
 ```bash
-bash "$COMET_STATE" set <name> build_mode <value>
+bash "$COMET_STATE" set <name> isolation <branch|worktree>
+bash "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
 ```
 
-- `subagent-driven-development`
-- `executing-plans`
-- `direct` (default only for hotfix/tweak preset use)
+`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.
 
-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:
+`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
@@ -125,7 +105,14 @@ 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.
 
-Then, **immediately execute:** Use the Skill tool to load the corresponding skill. Skipping this step is prohibited.
+**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.
+
+After creating isolation, confirm plan file is accessible (naturally accessible with branch method; for worktree method, confirm plan has been committed).
+
+**Load execution skill**: Use the Skill tool to load the corresponding skill. Skipping this step is prohibited.
 
 If the selected Superpowers skill is unavailable, stop the process and prompt to install or enable the corresponding skill. Do not substitute this step with normal conversation.
 
@@ -134,17 +121,19 @@ After the skill loads, follow its guidance to execute:
 - Complete tasks.md check (`- [ ]` → `- [x]`)
 - Commit code after each task completion
 
-### 5. Spec Incremental Updates
+### 4. Spec Incremental Updates
 
 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 | Re-run `superpowers:brainstorming` to update Design Doc + delta spec |
-| Large | Brand-new capability requirements | `/opsx:new` to create independent change |
+| 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` |
+
+**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, should consider splitting into new change.
+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.
 
 **Principles**:
 - Delta spec is a living document, can be modified at any time during this phase
@@ -152,14 +141,14 @@ When the initial spec is found incomplete during implementation, handle by scale
 - Do not sync to main spec in advance, sync uniformly during archiving
 - For small-scale incremental direct delta spec edits, note in commit message to facilitate design doc drift assessment during archiving
 
-### 6. Context Management
+### 5. Context Management
 
 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
 - **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 5 "Spec Incremental Updates"
+  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
 
 ## Exit Conditions

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

@@ -20,58 +20,126 @@ Execute entry verification:
 COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
 COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
 COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
+COMET_HANDOFF="${COMET_HANDOFF:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-handoff.sh' -type f -print -quit 2>/dev/null)}"
 bash "$COMET_STATE" check <name> design
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
-### 1a. Read Existing Context
+### 1a. Generate OpenSpec → Superpowers Handoff Package
 
-Read `proposal.md` and `design.md` under the active change, organize core content into summaries:
-- **Proposal summary**: goals, motivation, scope
-- **Design summary**: architectural decisions, high-level design
+**Must be generated by script. Agent writing summaries on the fly is not allowed.**
 
-### 1b. Execute Brainstorming (With Context)
+```bash
+bash "$COMET_HANDOFF" <change-name> design --write
+```
+
+The script generates and records:
+
+```
+openspec/changes/<name>/.comet/handoff/design-context.json
+openspec/changes/<name>/.comet/handoff/design-context.md
+```
+
+And writes to `.comet.yaml`:
 
-**Immediately execute:** Use the Skill tool to load the `superpowers:brainstorming` skill, ARGUMENTS contains:
+```yaml
+handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
+handoff_hash: <sha256>
+```
+
+The default handoff package is a **compact traceable excerpt**, not an agent summary:
+- `design-context.json`: machine index containing change, phase, canonical spec, source paths, hash
+- `design-context.md`: context for Superpowers to read, containing script markers, source path, line range, sha256, deterministic excerpts
+- When exceeding excerpt budget, marks `[TRUNCATED]` and retains Full source path
+
+If full context is genuinely needed, explicitly run:
+
+```bash
+bash "$COMET_HANDOFF" <change-name> design --write --full
+```
+
+Handoff package sources come from OpenSpec open phase artifacts:
+- `proposal.md`: goals, motivation, scope, non-goals
+- `design.md`: high-level architecture decisions, approach constraints
+- `tasks.md`: initial task boundaries
+- `specs/*/spec.md`: delta capability specs
+
+### 1b. Execute Brainstorming (with Context)
+
+**Immediately execute:** Use the Skill tool to load the `superpowers:brainstorming` skill, ARGUMENTS containing:
 
 ```
 Change: <change-name>
-Proposal summary: <proposal core content>
-Design summary: <design.md architectural decisions>
-Skip context exploration, proceed directly to design questioning.
+OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/design-context.md
+Machine handoff: openspec/changes/<name>/.comet/handoff/design-context.json
+
+OpenSpec artifacts are the upstream source of truth. Do not redefine requirements, do not rewrite proposal/spec.
+Your task is to perform deep technical design based on the handoff package: implementation approach, technical risks, testing strategy, boundary conditions.
+If you find OpenSpec delta spec missing acceptance scenarios, you may only propose Spec Patches and write them back to OpenSpec delta spec; do not create a second requirements spec in the Design Doc.
+
+Design Doc frontmatter must be minimal, containing only:
+---
+comet_change: <change-name>
+role: technical-design
+canonical_spec: openspec
+---
+
+Skip redundant context exploration, proceed directly to design questions.
 ```
 
-Skipping this step is prohibited, and continuing without loading this skill is prohibited.
+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.
 
-After the skill loads, follow its guidance to produce:
-- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — design document (technical RFC)
-- `openspec/changes/<name>/specs/<capability>/spec.md` — capability specification (delta)
+After the skill loads, follow its guidance to produce design proposals (presented as conversation):
+- Technical approach: architecture, data flow, key technology choices and risks
+- Testing strategy
+- If acceptance scenarios need supplementing, indicate delta spec changes to be written back
+
+The brainstorming phase does not write to the Design Doc file; it only produces design proposals for Step 1c user confirmation. Only after confirmation should `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` be created and delta spec written back.
+
+### 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.
+
+When pausing, only present essential summary:
+- Technical approach adopted
+- Key trade-offs and risks
+- Testing strategy
+- If there are Spec Patches, list the delta spec changes to be written back
+
+Only after the user explicitly confirms, proceed to Step 2. If the user requests adjustments, continue brainstorming iteration until the user confirms.
 
 ### 2. Update Comet State
 
-Record design_doc path, then run guard to auto-transition:
+First record the design_doc path. If Step 1c wrote back delta spec (added or modified `specs/*/spec.md`), must regenerate handoff to update hash:
 
 ```bash
 # Record design_doc path
 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
+
 # Auto-transition to next phase
 bash "$COMET_GUARD" <change-name> design --apply
 ```
 
-State file is updated automatically. No manual editing of other fields required.
+If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
 
 ## Exit Conditions
 
-- Design Doc has been created and saved
-- Delta spec has been created if there are new capabilities
+- Design Doc created and saved
+- Design Doc frontmatter contains `comet_change`, `role: technical-design`, `canonical_spec: openspec`
+- `handoff_context` and `handoff_hash` written to `.comet.yaml` (enforced by guard)
+- `handoff_hash` matches current OpenSpec open phase artifacts (enforced by guard)
+- `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, state advances to `phase: build`
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
 
-You must use `--apply` before exiting:
+Must use `--apply` before exit:
 
 ```bash
 bash "$COMET_GUARD" <change-name> design --apply
@@ -81,4 +149,4 @@ bash "$COMET_GUARD" <change-name> design --apply
 
 After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
 
-> **REQUIRED NEXT SKILL:** Invoke `comet-build` skill to enter the planning and build phase.
+> **REQUIRED NEXT SKILL:** Invoke `comet-build` skill to enter the plan and build phase.