@rpamis/comet 0.4.0-beta.5 → 0.4.0-beta.7

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

@@ -1,6 +1,6 @@
 ---
 name: comet-any
-description: "Use only when explicitly invoked as /comet-any or when the user explicitly wants to customize Comet's five-phase workflow or create/upgrade a workflow Skill managed by Comet Creator. Do not use for general Skill authoring, cleanup, or review."
+description: "Use only when explicitly invoked as /comet-any or when the user explicitly wants to customize the /comet-classic five-phase workflow or create/upgrade a workflow Skill managed by Comet Creator. Do not use for general Skill authoring, cleanup, or review."
 ---
 
 # Comet Any - Skill Creator
@@ -9,7 +9,7 @@ description: "Use only when explicitly invoked as /comet-any or when the user ex
 
 Ordinary users see three starting points:
 
-- `customize existing Comet Skills`: overlay the existing five phase Skills for `open / design / build / verify / archive` without modifying the `/comet` command itself.
+- `customize /comet-classic five-phase Skills`: overlay the existing `open / design / build / verify / archive` Skills without modifying the permanent `/comet-classic` entry itself.
 - `create a new workflow Skill`: generate a new `workflow-kernel` from the goal and candidate Skills.
 - `upgrade an existing Skill`: read existing Skills and add Workflow Nodes, Skill Bindings, Output Schemas, Guardrails, Handoffs, eval, and readiness.
 
@@ -30,7 +30,7 @@ Every path compiles to one Workflow Contract:
 
 ## Protected Boundary
 
-`comet-five-phase-overlay` preserves the Comet control flow and `.comet.yaml` state semantics. In ordinary mode:
+`comet-five-phase-overlay` preserves the Comet Classic five-phase control flow and `.comet.yaml` state semantics. In ordinary mode:
 
 - `comet-five-phase-overlay` primary state comes only from `openspec/changes/<name>/.comet.yaml`; no active change or multiple active changes must block and ask the user to choose.
 - The overlay must not create `.comet/runs/<workflow>/state.json` as the Comet overlay primary state. Bundle drafts, eval evidence, and publish readiness may keep their own evidence files, but they cannot replace `.comet.yaml`.
@@ -59,7 +59,7 @@ Component-library and whitebox-review requirements should produce a plan like:
 
 ```json
 {
-  "goal": "Customize existing Comet Skills with component and whitebox review requirements.",
+  "goal": "Customize /comet-classic five-phase Skills with component and whitebox review requirements.",
   "skillCreatorIntent": "customize-comet",
   "workflow": {
     "kind": "comet-five-phase-overlay",

package/assets/skills/comet-any/reference/authoring-subagents.md

@@ -58,7 +58,7 @@ Every subagent must receive the same common context:
   the derived internal `callChain` source inventory from Skill Creator metadata.
 - `reference/resolved-skills.json` or an equivalent real Skill source summary.
 - `reference/workflow-protocol.json` or the workflow protocol that will be written there.
-- For customize existing Comet Skills, the protected boundary: `open / design / build / verify / archive`, `.comet.yaml`, decision point, verify-result-transition, and archive-delta-sync.
+- For `/comet-classic` customization, the protected boundary is `open / design / build / verify / archive`, `.comet.yaml`, decision point, verify-result-transition, and archive-delta-sync.
 - Project preferences, missing or ambiguous candidate decisions, deviation reasons, and scripts/hooks executable disclosures.
 
 ## Output Format

package/assets/skills/comet-any/reference/bundle-authoring.md

@@ -8,7 +8,7 @@ The new `plan.json` uses `workflow` as the primary input:
 
 ```json
 {
-  "goal": "Customize existing Comet Skills with component and whitebox review requirements.",
+  "goal": "Customize /comet-classic five-phase Skills with component and whitebox review requirements.",
   "skillCreatorIntent": "customize-comet",
   "workflow": {
     "kind": "comet-five-phase-overlay",

package/assets/skills/comet-any/reference/subagents/reference-author.md

@@ -20,7 +20,7 @@ Read the common input from the main session, especially:
 - Resolved Skill name, source, description, hash, references, rules, scripts, and hooks.
 - `sourceSummaries`, which must come from real `SKILL.md` bodies and direct references.
 - Project preferences, missing or ambiguous candidate handling, deviation reasons, and executable disclosures.
-- The five-phase Comet semantics preserved when users customize existing Comet Skills.
+- The five-phase Comet semantics preserved when users customize `/comet-classic`.
 
 Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not read main-session history, and do not copy entire source Skills into reference.
 

package/assets/skills/comet-any/reference/subagents/script-author.md

@@ -22,7 +22,7 @@ Read the common input from the main session, especially:
 - `workflow.kind`, `workflow.nodes`, `engineMode`, and `runnerMode` from `plan.json`, plus the
   derived internal `callChain` source inventory from Skill Creator metadata
 - `reference/resolved-skills.json`
-- Protected `.comet.yaml` semantics when users customize existing Comet Skills; `comet-five-phase-overlay` primary state comes only from `openspec/changes/<name>/.comet.yaml` and must not create `.comet/runs/<workflow>/state.json` as the Comet overlay primary state.
+- Protected `.comet.yaml` semantics when users customize `/comet-classic`; `comet-five-phase-overlay` primary state comes only from `openspec/changes/<name>/.comet.yaml` and must not create `.comet/runs/<workflow>/state.json` as the Comet overlay primary state.
 
 Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not read main-session history or ask the user to restate content already written to artifacts.
 

package/assets/skills/comet-any/reference/subagents/skill-core-author.md

@@ -94,7 +94,7 @@ Return internal Node Skill drafts that show:
 - If the Node goal is not complete, continue working instead of exiting because a checklist is exhausted.
 - Automatic advancement must come from script outputs `NEXT:` and `SKILL:`, not agent guesses.
 - Nested Skill calls use only Skill names, not provider prefixes.
-- When users customize existing Comet Skills, preserve `open / design / build / verify / archive` and `.comet.yaml` semantics.
+- When users customize `/comet-classic`, preserve `open / design / build / verify / archive` and `.comet.yaml` semantics.
 - For arbitrary Skill composition, organize the result as a Comet-like multi-Node workflow.
 
 Forbidden:

package/assets/skills/comet-any/reference/subagents/skill-reviewer.md

@@ -67,12 +67,12 @@ Any of these must produce blocking findings:
 - English Skills mix in Chinese process sentences.
 - Nested Skill calls use provider prefixes.
 - User-visible `SKILL.md` leaks generated audit sections, source hashes, or internal metadata.
-- Customizing existing Comet Skills replaces or removes `open / design / build / verify / archive`, `.comet.yaml`, decision point, verify-result-transition, or archive-delta-sync.
+- Customizing `/comet-classic` replaces or removes `open / design / build / verify / archive`, `.comet.yaml`, decision point, verify-result-transition, or archive-delta-sync.
 - Arbitrary Skill composition is missing automatic advancement, script guards, user pause points, recovery, or current draft hash eval evidence.
 
 ## Severity
 
-- Critical: makes the generated Skill unusable, unrecoverable, unauditable, or breaks protected `/comet` semantics.
+- Critical: makes the generated Skill unusable, unrecoverable, unauditable, or breaks protected `/comet-classic` semantics.
 - Important: makes the Node flow, script guards, pause points, Skill calls, or evidence chain untrustworthy; must be fixed before ready.
 - Minor: clarity, naming, or maintainability improvements that do not block ready.
 

package/assets/skills/comet-any/reference/subagents/workflow-entry-author.md

@@ -35,7 +35,7 @@ Read the common input from the main session, especially:
 - Node order, Required Skill Calls, and recovery paths from
   `reference/workflow-protocol.json`.
 - The script author's `status`, `init`, `next`, `NEXT:`, `SKILL:`, and guard contracts.
-- The open / design / build / verify / archive boundary that must be preserved when users customize existing Comet Skills.
+- The open / design / build / verify / archive boundary that must be preserved when users customize `/comet-classic`.
 
 Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not inherit main-session history; use only this brief, common input, script contracts, and reference evidence.
 
@@ -64,10 +64,10 @@ The entry draft must show:
 - If not started, initialize state before querying `next`.
 - Only after scripts output `NEXT: auto` and `SKILL: <node-skill>` should the agent load that single Node Skill.
 - The Node route table is reference only; it must not use "immediately execute" or "must load" execution directives.
-- When users customize existing Comet Skills, the entry must list Required Skill Calls as Node-local obligations,
+- When users customize `/comet-classic`, the entry must list Required Skill Calls as Node-local obligations,
   not as an immediate execution checklist.
 - User decisions, automatic handling, stop conditions, manual handoffs, recovery paths, and reference files are visible. Pause only when at least two real valid options remain, and merge adjacent choices.
-- When users customize existing Comet Skills, preserve the open / design / build / verify / archive main path and Guardrails.
+- When users customize `/comet-classic`, preserve the open / design / build / verify / archive main path and Guardrails.
 
 Forbidden:
 

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

@@ -28,6 +28,8 @@ comet state check <name> archive
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
+If the `select` / `check` output is `BLOCKED` because `bound_branch` does not match the current branch, immediately pause under `comet/reference/decision-point.md` and let the user choose one option: switch back to the bound branch and rerun entry verification, or run `comet state rebind <change-name>` after the user explicitly confirms the current branch should take over this change, then rerun entry verification. Do not switch branches or rebind on your own.
+
 ### 1. Final Archive Confirmation (Blocking Point)
 
 After entry verification passes, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to confirm whether to archive immediately**. Must not run `comet archive "<change-name>"` before user confirmation.
@@ -104,20 +106,16 @@ Stop if the commit fails or the staged diff contains unrelated paths.
 
 ### 5. Handle the Branch After the Archive Commit
 
-After the archive commit succeeds, **immediately execute:** use the Skill tool to load Superpowers `finishing-a-development-branch`. This ordering ensures the final branch or PR contains the main-spec merge and archive metadata.
-
-If the skill is unavailable, stop and prompt the user to enable/install it; do not mark `branch_status` handled. After loading it, pause under `comet/reference/decision-point.md` and let the user choose:
+After the archive commit succeeds, first read `comet state get <change-name> isolation` and route by isolation:
 
-1. Merge locally into the main branch
-2. Push and create a PR
-3. Keep the current branch for later
+- `isolation !== current`: **immediately execute:** use the Skill tool to load Superpowers `finishing-a-development-branch`. This ordering ensures the final branch or PR contains the main-spec merge and archive metadata. If the skill is unavailable, stop and prompt the user to enable/install it; do not mark `branch_status` handled. After loading it, pause under `comet/reference/decision-point.md` and let the user choose: merge locally into the main branch, push and create a PR, or keep the current branch for later.
+- `isolation === current`: skip Superpowers `finishing-a-development-branch`. Pause under `comet/reference/decision-point.md` and let the user choose one option: push the current branch, or do not push yet and keep the local state.
 
-Archive is already complete, so do not offer "discard work". Only after the selected operation succeeds (or the user explicitly keeps the branch), run:
+Archive is already complete, so do not offer "discard work". Only after the selected operation succeeds, the user explicitly keeps the branch, or the user explicitly chooses not to push in `current` mode, run:
 
 ```bash
 comet state set <change-name> branch_status handled
 comet guard <change-name> archive
-comet state clear-selection
 ```
 
 The archive guard must verify both archive completeness and `branch_status: handled`; a failure means the workflow is still incomplete.
@@ -137,7 +135,7 @@ The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive
 
 ## Complete
 
-Comet workflow complete. To start new work, invoke `/comet` or `/comet-open`.
+Comet Classic workflow complete. To start new Classic work, invoke `/comet-classic` or `/comet-open`.
 
 ## Context Compression Recovery
 

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

@@ -23,6 +23,8 @@ comet state check <name> build
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
+If the `select` / `check` output is `BLOCKED` because `bound_branch` does not match the current branch, immediately pause under `comet/reference/decision-point.md` and let the user choose one option: switch back to the bound branch and rerun entry verification, or run `comet state rebind <change-name>` after the user explicitly confirms the current branch should take over this change, then rerun entry verification. Do not switch branches or rebind on your own.
+
 **Idempotency**: All build phase operations can be safely re-executed. Read `.comet.yaml` `phase` to confirm build, read the plan header `base-ref`, then parse tasks.md checkboxes in document order and resume from the first unchecked task. Already-committed tasks must not be re-committed.
 
 ### 1. Create Plan (Subagent Offload)
@@ -82,7 +84,7 @@ After recording the plan, provide exactly **one joint decision point** that coll
 | Option | Behavior | Description |
 |--------|----------|-------------|
 | A | Continue with configuration | Provide all Step 3 isolation, execution, TDD, and review choices in the same response; include the branch name when branch is selected |
-| 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` |
+| B | Pause to switch model | Record `build_pause: plan-ready`, stop this `/comet-build` invocation, and allow the user to resume later from `/comet-classic` or `/comet-build` |
 
 This is a user decision point. **Follow `comet/reference/decision-point.md` once and show the plan summary, pause option, and every executable Step 3 setting together**. Continuing requires all settings and any conditional branch name in the same response. Do not auto-select or write the pause into `build_mode`.
 
@@ -116,12 +118,14 @@ The plan is on the current branch. These settings are all part of the single Ste
 
 | Option | Method | Description |
 |--------|--------|-------------|
-| A | Create branch | Create a new branch in the current repo, simple and fast |
-| B | Create Worktree | Isolated workspace, fully independent, suitable for parallel development |
+| A | Work on current branch | Do not create a new branch; truthfully bind the current Git branch |
+| B | Create branch | Create a new branch in the current repo, simple and fast |
+| C | Create Worktree | Isolated workspace, fully independent, suitable for parallel development |
 
 **Recommendation rules**:
-- Change involves ≤ 3 files → Recommend A
-- Need parallel development, current branch has uncommitted work → Recommend B
+- User explicitly wants to keep the current branch, or the current branch is already the target branch for this change → Recommend A
+- Change involves ≤ 3 files and the current branch is clean → Recommend B
+- Need parallel development, current branch has uncommitted work → Recommend C
 
 **Execution Method**:
 
@@ -135,12 +139,12 @@ The plan is on the current branch. These settings are all part of the single Ste
 - Task count ≤ 2 and no cross-module dependencies → Recommend B
 - From hotfix path → Recommend B
 
-These tables are part of the Step 2 joint decision and do not create another pause. First remove options that capability preflight found unavailable. When multiple valid options remain, do not choose `branch` or `worktree`, execution method, TDD mode, or review mode from recommendations. Recommendations explain a preference; they never replace user confirmation.
+These tables are part of the Step 2 joint decision and do not create another pause. First remove options that capability preflight found unavailable. When multiple valid options remain, do not choose `current`, `branch`, or `worktree`, execution method, TDD mode, or review mode from recommendations. Recommendations explain a preference; they never replace user confirmation.
 
 After user selection, update `isolation`, execution method, TDD mode, and code review mode fields:
 
 ```bash
-comet state set <name> isolation <branch|worktree>
+comet state set <name> isolation <current|branch|worktree>
 ```
 
 - If the user chooses `executing-plans`: run `comet state set <name> subagent_dispatch null`, then run `comet state set <name> build_mode executing-plans`
@@ -166,7 +170,7 @@ Run `comet state set <name> tdd_mode <tdd|direct>`
 
 Run `comet state set <name> review_mode <off|standard|thorough>`
 
-`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.
+`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 allows `current`, `branch`, or `worktree`, but `current` must be written only after the user explicitly selects it in Step 2; never make it a silent default.
 
 `subagent_dispatch` is a script-enforced hard constraint. `build_mode: subagent-driven-development` requires `subagent_dispatch: confirmed` before leaving the build phase, otherwise both `comet guard build --apply` and `comet state transition build-complete` will fail.
 
@@ -185,6 +189,8 @@ Without `direct_override: true`, `build_mode=direct` in full workflow is blocked
 
 **Execute isolation**:
 
+- **current**: Do not create a new branch or worktree; execute directly on the current Git branch. Run `comet state set <name> isolation current` immediately; the command writes the current branch to `bound_branch`. If HEAD is detached, stop and ask the user to check out a real branch first, because there is no auditable branch binding.
+
 - **branch**: Use the branch name already confirmed in Step 2; do not pause again. If legacy recovery no longer has the branch name from that joint decision, re-enter the same Step 2 decision instead of creating a separate branch-naming decision.
 
   Branch naming convention:
@@ -196,7 +202,7 @@ Without `direct_override: true`, `build_mode=direct` in full workflow is blocked
 
   Example: if change name is `fix-login-bug` and today is 2026-06-09, recommend `feature/20260609/fix-login-bug`
 
-  Immediately after Step 2 confirms the branch name, run `git checkout -b <branch-name>` and continue on the new branch.
+  Immediately after Step 2 confirms the branch name, run `git checkout -b <branch-name>`, then run `comet state set <name> isolation branch` to write the new branch to `bound_branch`. Continue on the new branch.
 
 - **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.
 
@@ -207,7 +213,7 @@ git add docs/superpowers/plans/YYYY-MM-DD-feature.md
 git commit -m "chore: add implementation plan"
 ```
 
-After entering the final execution branch or worktree, bind the current change again inside that actual workspace. A branch switch invalidates the entry binding, and a new worktree does not inherit the original workspace-local selection file:
+After entering the final execution branch or worktree, bind the current change again inside that actual workspace. Branch mode is bound after checkout with `isolation branch`; worktree mode must run `comet state set <name> isolation worktree` inside the new workspace to write that worktree's current branch to `bound_branch`. A new worktree does not inherit the original workspace-local selection file, so select the current change too:
 
 ```bash
 comet state select <change-name>
@@ -288,7 +294,7 @@ Build is the longest phase and may span many tasks. To support resume after cont
 - All tasks.md checked
 - Code committed
 - Project-specific build/tests explicitly run and pass; do not rely only on guard auto-detection
-- `isolation` has been written as `branch` or `worktree`
+- `isolation` has been written as `current`, `branch`, or `worktree`
 - `build_mode` has been written as `subagent-driven-development`, `executing-plans`, or `direct` with explicit override; if `subagent-driven-development`, `subagent_dispatch` must be `confirmed`
 - `tdd_mode` has been written as `tdd` or `direct`
 - `review_mode` has been written as `off`, `standard`, or `thorough`

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

@@ -0,0 +1,293 @@
+---
+name: comet-classic
+description: "Use when the user explicitly invokes /comet-classic, asks to start or resume the permanent Comet Classic workflow, or repository evidence identifies one unambiguous active Classic change; route through the intent runtime and .comet.yaml."
+---
+
+# Comet Classic — OpenSpec + Superpowers Dual-Star Development Workflow
+
+OpenSpec and Superpowers orbit the same goal like a binary star system.
+
+```
+OpenSpec handles WHAT  — outline, proposal, spec lifecycle, archive
+Superpowers handles HOW — technical design, planning, execution, closing
+```
+
+**Core principle: brainstorming cannot be skipped. Every change must undergo deep design (except hotfix and tweak presets).**
+
+---
+
+## Decision Core
+
+Agents need only read this section for decision-making. Refer to the Reference Appendix as needed.
+
+### Output Language Rule
+
+Use the configured Comet artifact language as the output language for every OpenSpec and Superpowers artifact. The configured value is a normalized language id, `en` or `zh-CN`. For an existing change, read `language` from `openspec/changes/<name>/.comet.yaml` using `comet state get <name> language`. Before `.comet.yaml` exists, read `classic.language` from project `.comet/config.yaml`, then fall back to global `~/.comet/config.yaml`; if neither exists, fall back to the current user request language. Include the resolved language explicitly in every prompt or ARGUMENTS passed to external OpenSpec/Superpowers skills.
+
+### Automatic Phase Detection
+
+**Step 0: Active Change Discovery and Intent Resolution**
+
+1. First load script locations through `comet/reference/scripts.md` and ensure `$COMET_INTENT` is available.
+2. Run `openspec list --json` to collect active changes.
+3. Fill a `CometIntentFrame` from the user request, active change list, and necessary repository state.
+4. Prefer `node "$COMET_INTENT" route --stdin` to pass the frame JSON and get the runtime-normalized route. `CometIntentFrame + runtime scorer` is the source of truth; this prose is only for intent recognition slot extraction.
+5. Handle the runtime route:
+   - `hotfix` → invoke `/comet-hotfix`
+   - `tweak` → invoke `/comet-tweak`
+   - `full` → follow the active-change table to invoke `/comet-open` or ask for confirmation
+   - `resume` → continue to Step 1 and read the selected change `.comet.yaml`
+   - `ask_user` → pause through `comet/reference/decision-point.md` and wait for the user's choice
+   - `out_of_scope` → explain that the input is not a Comet workflow start/resume request and do not initialize a change
+
+After the runtime route, Ambient Resume, or user choice resolves one explicit change, bind the current execution context before entering its phase Skill:
+
+```bash
+comet state select <change-name>
+```
+
+When multiple active changes exist and the user has not selected one, do not bind early; keep the existing `ask_user` decision point.
+
+### Comet Ambient Resume
+
+When the user did not explicitly invoke `/comet-classic`, but this repository may already have an active Comet change, run the read-only probe before starting work that may need code changes or investigation:
+
+```bash
+node "$COMET_RESUME_PROBE" probe --stdin
+```
+
+The probe only reads repository state. Follow the returned action:
+
+- `auto_resume`: print one line, `[COMET] Detected active change <name>; resuming via <nextCommand>.`, then enter `nextCommand`.
+- `ask_user`: ask one short question and wait.
+- `out_of_scope` or `none`: do not enter the Comet workflow.
+
+Never attach unrelated work to an active Comet change only because `.comet.yaml` exists.
+
+**Minimal CometIntentFrame Skeleton**:
+
+```json
+{
+  "schema_version": "comet.intent.v1",
+  "utterance": "<user request>",
+  "intent": { "name": "start_change", "confidence": 0.8 },
+  "slots": {
+    "requested_action": "start",
+    "workflow_candidate": "full",
+    "user_explicit_workflow": null,
+    "change_id": null,
+    "existing_behavior": null,
+    "new_capability": null,
+    "public_api_change": null,
+    "schema_change": null,
+    "cross_module_change": null
+  },
+  "context": {
+    "active_changes_count": 0,
+    "active_change_names": []
+  },
+  "evidence": [],
+  "proposed_route": {
+    "name": "ask_user",
+    "confidence": 0.5
+  }
+}
+```
+
+**Intent Recognition Slot Extraction**:
+See `comet/reference/intent-frame.md` for complete field meanings; normal routing only needs the minimal skeleton above.
+
+- `fix_bug` + `existing_behavior: true` + no new capability/public API/schema/cross-module signal → prefer `hotfix`
+- User explicitly describes a lightweight/medium change that can fit in a single OpenSpec change, should be executed through OpenSpec apply, and does not need full `/comet-classic` deep design/plan → prefer `tweak`
+- Copy, config, docs, prompt, or a lightweight/medium single OpenSpec change → prefer `tweak`
+- New capability, public API, schema change, cross-module coordination, or architecture work → prefer `full`
+- Multiple active changes without an explicit change → `ask_user`
+- Low confidence, missing key evidence, or explicit workflow conflicting with risk signals → `ask_user`
+
+| Active changes | User input | Behavior |
+|----------------|------------|----------|
+| None | `full` route | → Invoke `/comet-open` |
+| Exactly 1 | `/comet-classic <description>` | → **Ask**: continue this change or create a new change |
+| Multiple | `/comet-classic <description>` | → **Ask**: continue existing or create new; if continuing, list changes for selection |
+| Exactly 1 | `/comet-classic` with no description | → Auto-select, enter Step 1 |
+| Multiple | `/comet-classic` with no description | → List changes for user selection |
+
+<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 (created by internal `/opsx:new`) plus `.comet.yaml` state file.
+Calling `/opsx:new` directly leaves `.comet.yaml` missing and breaks later phase detection.
+</IMPORTANT>
+
+**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 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 `build_pause`, `plan`, `isolation`, `build_mode`, `tdd_mode`, and `review_mode` (see details below):
+  - If `build_pause: plan-ready` but `isolation`, `build_mode`, `tdd_mode`, and `review_mode` are all already set, treat as stale pause: first output `[COMET] Detected stale pause (build_pause=plan-ready but isolation/build_mode/tdd_mode/review_mode are set), auto-clearing and continuing`, then run `comet state set <name> build_pause null`, then read the next unchecked task from tasks.md and resume execution per `build_mode`
+  - If `build_pause: plan-ready` and the plan file exists, but `isolation`, `build_mode`, `tdd_mode`, or `review_mode` is not yet set, return to the `/comet-build` plan-ready resume point, prompt the user to complete/confirm workspace isolation, execution method, TDD mode, and code review mode, 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 `isolation`, `build_mode`, `tdd_mode`, or `review_mode` is unset, return to the corresponding `/comet-build` step to supplement before executing
+  - If all are set, read the next unchecked task from tasks.md and continue:
+    - If `build_mode: subagent-driven-development`, do not execute tasks directly in the main window; return to `/comet-build`'s background subagent dispatch rules, main window only coordinates
+    - Other execution modes follow `/comet-build`'s corresponding rules
+- If `verify_result: fail`, read `verify_failures`. At 3 or fewer failures, invoke `/comet-build` directly to continue the recorded repair loop without re-asking. Above the automatic limit, return to `/comet-verify` for the exception decision. User input is required only to accept a WARNING/SUGGESTION deviation or choose a strategy after the retry limit
+- If `phase: open` but OpenSpec `applyRequires` is complete, run `comet guard <change-name> open --apply` to repair state, then continue detection
+- If `phase: archive`, only invoke `/comet-archive`; confirm first, archive, commit exact archive paths, then handle the branch and run the archive guard
+
+**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` (first perform final archive confirmation)
+3. `verify_result: fail` → Invoke `/comet-build` automatically to continue repair. If `verify_failures` exceeds the automatic limit, enter `/comet-verify`'s retry-limit strategy decision
+4. `phase: verify` or tasks.md all checked → Invoke `/comet-verify`
+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`
+
+If metadata conflicts with file state, use verifiable file state as source of truth and correct `.comet.yaml` before continuing.
+
+### Preset Upgrade Assessment
+
+hotfix/tweak scope assessment uses a three-layer division of labor, avoiding "using pure file count as a hard upgrade condition" that wrongly blocks normal small changes:
+
+1. **Qualitative-change signals** (agent semantic recognition; hitting any one pauses and delegates a two-choice decision to the user): cross-module coordinated change, new capability needed, database schema change, introduces new public API, hits deep architecture issues (each preset reuses this core signal set and may add its own context-specific signal, such as tweak's "needing to split into multiple OpenSpec changes")
+2. **File-count tripwire** (user decides; not an automatic upgrade): when changed files exceed a hint threshold, pause and let the user decide whether to continue the preset or upgrade to full; do not auto-kick
+3. **Verification weight** (scale script decides): `comet state scale` only decides `verify_mode` (verification weight); it does not block the flow or trigger an upgrade
+
+**Upgrade decision point (user chooses one of two)**:
+- Continue the preset lightweight flow (user confirms scope is manageable)
+- Upgrade to full `/comet-classic` (use `comet state transition <name> preset-escalate` to legally rewind to design and clear preset-only build settings; after the Design Doc, choose the full workflow configuration again in one joint decision)
+
+See the "Upgrade Assessment" section of each `comet-hotfix` / `comet-tweak` for detailed rules.
+
+### Error Handling Quick Reference
+
+| Scenario | Handling |
+|----------|----------|
+| `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` missing | Enter the relevant preset's `/comet-open` initialization, then run `comet state select`; never skip initialization |
+| `.comet.yaml` malformed | Stop and report the parse error; repair from version control, backup, or verifiable artifacts, never overwrite it with `comet state set` |
+| 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 |
+
+### Phase Transitions
+
+<IMPORTANT>
+A single `/comet-classic` invocation starts from the detected phase and advances to the next phase when exit conditions are met.
+
+Flow chain: open → design → build → verify → archive
+
+**Continuous execution requirement**: starting from the detected phase, the agent automatically continues through all later phases. But **auto-advancing only applies at transition points without user decisions**. When encountering user decision points, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user's explicit response**. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation, and must not just output a text prompt and then continue executing.
+
+**Distinguish phase advancement vs automatic handoff**: each sub-skill runs phase guard `--apply` before exit to advance the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. After that, the sub-skill runs `comet state next <name>` to resolve the next action: when `auto_transition` is not `false`, output is `NEXT: auto` (auto-invoke next skill); when `auto_transition` is `false`, output is `NEXT: manual` (do not invoke next skill; return control with `HINT`). `NEXT: manual` is not a user decision point and must not ask whether to continue. Therefore `auto_transition` **only controls next skill invocation, not phase advancement**. Regardless of `auto_transition`, genuine user decision points below remain blocking.
+
+**Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet-classic` invocation must stop, and follow the `comet/reference/decision-point.md` protocol to obtain the user's explicit choice. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes.
+
+Nodes requiring user participation (pause only at these nodes):
+1. Workflow target selection: multiple active changes, continue an existing change versus create a new one, or choose which completed batch item starts first
+2. Open-phase final proposal/design/tasks review, including the change name and scope; clear requests have no pre-artifact summary/name confirmation
+3. Confirm the design approach during brainstorming
+4. One joint build decision: plan-ready pause or all available workflow settings (workspace isolation + execution method + TDD mode + code review mode, plus branch name when branch is selected)
+5. Verify-phase acceptance of WARNING/SUGGESTION deviations, Spec drift handling, or continue/stop after the 4th failure; the first 3 clearly repairable failures close automatically
+6. Archive phase final confirmation before running the archive script
+7. Choose finishing-branch handling after exact archive changes are committed
+8. Encounter an upgrade-assessment signal (hotfix/tweak → user chooses one of two: continue preset / upgrade to full workflow)
+9. Build phase scope expansion requiring redesign or new change split
+10. Open phase large PRD split confirmation
+
+Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. At decision points, **must not skip user confirmation or choose automatically — must explicitly obtain the user's choice through the current platform's available user input/confirmation mechanism before continuing**.
+
+**Red Flags** — when these thoughts appear, STOP and check:
+
+| Agent Thought | Actual Risk |
+|--------------|-------------|
+| "The user would probably agree with this approach" | Cannot decide for the user — use the current platform's user input/confirmation mechanism |
+| "This is a small change, confirmation isn't needed" | Decision points have no size exception — blocking points must wait |
+| "The user chose A last time, so A again" | Historical preference cannot substitute for current confirmation |
+| "I explained the plan and the user didn't object" | No objection ≠ consent — must use tool to get explicit choice |
+| "The flow has reached this point, should be fine" | Verification not passed ≠ passed — check verify_result |
+</IMPORTANT>
+
+---
+
+## Subcommand Quick Reference
+
+| Command | Phase | Owner | Artifacts |
+|---------|-------|-------|-----------|
+| `/comet-open` | 1. Open | OpenSpec | proposal.md, design.md, tasks.md |
+| `/comet-design` | 2. Deep Design | Superpowers | Design Doc, delta spec |
+| `/comet-build` | 3. Plan and Build | Superpowers | Implementation plan, code commits |
+| `/comet-verify` | 4. Verify | Both | Verification report |
+| `/comet-archive` | 5. Archive and Close | OpenSpec | delta→main spec sync, design doc markup, archive commit, branch handling |
+| `/comet-hotfix` | Preset path | Both | Quick fix (skip brainstorming) |
+| `/comet-tweak` | Preset path | Both | OpenSpec-chained medium change (delta spec is first-class, skip brainstorming and full plan) |
+
+```
+/comet-classic
+  ↓ Auto-detect
+/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
+  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
+
+/comet-hotfix (preset, skip brainstorming)
+  open ──→ build ──→ verify ──→ archive
+    ↑ Upgrade-assessment signal hit → user chooses one of two (continue preset / upgrade full) → if upgrade, transition preset-escalate → supplement Design Doc → return to full workflow
+
+/comet-tweak (lightweight preset, chains OpenSpec, delta spec is first-class)
+  open ──→ build ──→ verify ──→ archive
+    ↑ Upgrade-assessment signal hit → user chooses one of two (continue preset / upgrade full) → if upgrade, transition preset-escalate → supplement Design Doc → return to full workflow
+```
+
+---
+
+## Reference Appendix
+
+### State Machine Hard Constraints
+
+- Before full-workflow `build → verify`, `isolation` must be `branch` or `worktree`; hotfix/tweak may truthfully use `current`
+- Before `build → verify`, `build_mode` must be selected
+- `build_mode: subagent-driven-development` must also have `subagent_dispatch: confirmed`
+- Before full workflow leaves build phase, `tdd_mode` must be selected as `tdd` or `direct`
+- Before full workflow leaves build phase, `review_mode` must be selected as `off`, `standard`, or `thorough`
+- `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 <name> build --apply` and `comet state transition <name> build-complete`
+
+### .comet.yaml Field Reference
+
+See `comet/reference/comet-yaml-fields.md` for complete field reference with examples and descriptions.
+
+### File Structure
+
+See `comet/reference/file-structure.md` for the complete directory layout and artifact organization.
+
+### Auto-Transition Protocol
+
+See `comet/reference/auto-transition.md` for the complete automatic handoff workflow.
+
+### Context Recovery
+
+See `comet/reference/context-recovery.md` for structured recovery after context compression.
+
+### Decision Point Protocol
+
+See `comet/reference/decision-point.md` for the complete user decision point protocol.
+
+### Debug Gate Protocol
+
+See `comet/reference/debug-gate.md` for the complete debug gate protocol.
+
+### Script Location
+
+Use the stable `comet` CLI for workflow state, guards, handoff, and archive. Locate internal launchers through `comet/reference/scripts.md` only for intent/resume probes that do not yet have a public subcommand. Key entry points:
+
+```bash
+comet guard <change-name> <phase> --apply             # phase guard + state update
+comet state transition <change-name> <event>          # open-complete | design-complete | build-complete | verify-pass | verify-fail
+comet state next <change-name>                        # NEXT: auto|manual|done + SKILL: <skill-name>
+comet archive <change-name>                           # full archive in one command
+```

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

@@ -44,7 +44,7 @@ openspec/changes/<name>/.comet/handoff/design-context.json
 openspec/changes/<name>/.comet/handoff/design-context.md
 ```
 
-Beta mode (`context_compression: beta` in project `.comet/config.yaml`, snapshotted into `.comet.yaml` when the change is created) generates:
+Beta mode (`classic.context_compression: beta` in project `.comet/config.yaml`, snapshotted into `.comet.yaml` when the change is created) generates:
 
 ```
 openspec/changes/<name>/.comet/handoff/spec-context.json