@rpamis/comet 0.2.9 → 0.3.1

package/README.md

@@ -32,7 +32,11 @@
 
 **OpenSpec + Superpowers dual-star development workflow** — one command from idea to archive.
 
-OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving). Superpowers handles **HOW** (technical design, planning, execution, wrap-up). Comet chains both into a five-phase automated pipeline.
+OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving). 
+
+Superpowers handles **HOW** (technical design, planning, execution, wrap-up). 
+
+Comet chains both into a five-phase automated pipeline.
 
 ## Why Comet
 
@@ -94,6 +98,12 @@ comet init
 >
 > `comet update` or `npm install -g @rpamis/comet@latest` to get the latest features and fixes.
 
+## Support for OpenClaw and Hermes, and other AI platforms
+
+```bash
+npx skills add rpamis/comet
+```
+
 ## Screenshots
 
 <p align="center">
@@ -389,6 +399,10 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
 
 Track our development progress and upcoming features on the [Comet Roadmap](https://github.com/orgs/rpamis/projects/1).
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=rpamis/comet&type=Date)](https://star-history.com/#rpamis/comet&Date)
+
 ## License
 
 [MIT](LICENSE.md)

package/assets/manifest.json

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

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
@@ -22,13 +22,19 @@ Agents need only read this section for decision-making. Refer to the Reference A
 
 ### Automatic Phase Detection
 
-**Step 0: Active Change Discovery**
+**Step 0: Active Change Discovery and Intent Detection**
 
-1. Run `openspec list --json` to get all active changes
+1. Detect presets first; if hotfix/tweak matches, invoke the corresponding preset skill directly and do not enter the normal open branch
+2. When no preset matches, run `openspec list --json` to get all active changes
+
+**Preset detection has highest priority**:
+- User explicitly describes a bug fix / hotfix + meets hotfix conditions → directly invoke `/comet-hotfix`
+- User explicitly describes copy/config/docs/prompt small adjustment + meets tweak conditions → directly invoke `/comet-tweak`
+- No preset match → follow the table below
 
 | Active changes | User input | Behavior |
 |----------------|------------|----------|
-| None | any | → Invoke `/comet-open` |
+| None | non-preset input | → Invoke `/comet-open` |
 | Exactly 1 | `/comet <description>` | → **Ask**: continue this change or create a new change |
 | Multiple | `/comet <description>` | → **Ask**: continue existing or create new; if continuing, list changes for selection |
 | Exactly 1 | `/comet` with no description | → Auto-select, enter Step 1 |
@@ -36,32 +42,29 @@ 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>
 
-**Preset detection**:
-- User describes as bug fix / hotfix + meets hotfix conditions → directly invoke `/comet-hotfix`
-- User describes as copy, config, docs, prompt or small non-bug adjustment + meets tweak conditions → directly invoke `/comet-tweak`
-
 **Step 1: Read `.comet.yaml` state metadata**
 
 Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall back to `openspec status --change "<name>" --json`, `tasks.md`, and `docs/superpowers/` file checks.
 
 **Resume rules**:
 - On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
-- 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 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: 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`
@@ -100,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.
+
+**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:
+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>
 
 ---
@@ -134,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
 ```
 
 ---
@@ -152,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
 ```
@@ -165,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 |
 
@@ -199,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
@@ -231,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
 
@@ -245,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)
@@ -258,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/reference/dirty-worktree.md

@@ -0,0 +1,58 @@
+# Dirty Worktree Protocol
+
+Canonical path: `comet/reference/dirty-worktree.md`
+
+This protocol is shared by all Comet sub-skills that may modify code. When an agent resumes context or continues execution, it must handle uncommitted working tree changes through this protocol.
+
+## 1. Checks
+
+Before continuing or starting code changes, run:
+
+```bash
+git status --short
+git diff --stat
+git diff --cached --stat
+git ls-files --others --exclude-standard
+```
+
+When needed, inspect `git diff`, `git diff --cached`, and newly created file contents.
+
+## 2. Core Rules
+
+- The user may not say which files they changed. If the worktree is dirty, including new files shown as `??` in Git status, assume changes may come from the user or mixed sources.
+- A dirty worktree is code evidence only. It does not automatically advance `.comet.yaml` `phase` or check off `tasks.md`; Comet state may advance only after attribution, verification, required document synchronization, and the relevant phase guard.
+
+## 3. Attribution
+
+Classify dirty diffs into three groups:
+
+1. **Belongs to the current change**: Files and content match the current change goal, tasks.md, plan, or delta spec. Incorporate the diff into the current task and avoid redoing the same work.
+2. **Does not belong to the current change**: Files or content are unrelated. Pause and ask whether to include it in the current change, split it into a new change, leave it alone, or discard it with explicit authorization.
+3. **Unclear source**: The diff and documents are not enough to determine ownership. Pause, report the file list and reasoning, and do not advance the phase.
+
+## 4. Common Patterns
+
+### Implemented But tasks.md Is Not Checked
+
+Verify the implementation with build and tests. If it passes, check off the task. Do not redo work just because the task is unchecked, and do not ignore code evidence because state files lag behind. If the current sub-skill defines a phase-specific rule, follow that sub-skill.
+
+### Plan Or Scope Changed
+
+Follow the current sub-skill's escalation, incremental-update, or rollback rules. This protocol does not repeat phase-specific details.
+
+### Ambiguous Resume Intent
+
+When the user says things like "continue", "keep going", "I changed a bit", "I wasn't happy with it", "redo it", "code changed", or "use what is there", follow this protocol. Do not require the user to remember exactly what they changed.
+
+### Code Changes During open/design
+
+If the current phase is still `open` or `design` but the dirty worktree already contains code changes, first attribute the changes through this protocol and do not advance the phase directly:
+
+- If the changes belong to the current change, treat them as requirements or design input and record them in proposal/design/spec/design doc/tasks as appropriate. The current phase guard must still pass before entering build.
+- If the changes do not belong to the current change or ownership is unclear, pause and ask whether to include them, split them into a new change, leave them alone, or discard them with explicit authorization.
+- Do not treat code changes made during open/design as completed implementation ready for verify.
+
+## 5. Prohibitions
+
+- Do not overwrite, revert, reformat over, or ignore user changes before understanding the dirty diff source.
+- Do not mark verification as passed while dirty diff remains unexplained.

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,12 +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 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