@rpamis/comet 0.3.9 → 0.4.0-beta.1

package/assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.8",
+  "version": "0.4.0-beta.1",
   "skills": [
     "comet/SKILL.md",
     "comet/reference/auto-transition.md",
@@ -9,14 +9,29 @@
     "comet/reference/decision-point.md",
     "comet/reference/dirty-worktree.md",
     "comet/reference/file-structure.md",
+    "comet/reference/intent-frame.md",
+    "comet/reference/scripts.md",
     "comet/reference/subagent-dispatch.md",
-    "comet/scripts/comet-env.sh",
-    "comet/scripts/comet-guard.sh",
-    "comet/scripts/comet-state.sh",
-    "comet/scripts/comet-handoff.sh",
-    "comet/scripts/comet-archive.sh",
-    "comet/scripts/comet-yaml-validate.sh",
-    "comet/scripts/comet-hook-guard.sh",
+    "comet-any/SKILL.md",
+    "comet-any/reference/authoring-subagents.md",
+    "comet-any/reference/authored-zone-example.md",
+    "comet-any/reference/bundle-authoring.md",
+    "comet-any/reference/eval-provider.md",
+    "comet-any/reference/subagents/script-author.md",
+    "comet-any/reference/subagents/reference-author.md",
+    "comet-any/reference/subagents/workflow-entry-author.md",
+    "comet-any/reference/subagents/skill-core-author.md",
+    "comet-any/reference/subagents/pause-points-author.md",
+    "comet-any/reference/subagents/skill-reviewer.md",
+    "comet/scripts/comet-runtime.mjs",
+    "comet/scripts/comet-env.mjs",
+    "comet/scripts/comet-guard.mjs",
+    "comet/scripts/comet-state.mjs",
+    "comet/scripts/comet-handoff.mjs",
+    "comet/scripts/comet-archive.mjs",
+    "comet/scripts/comet-yaml-validate.mjs",
+    "comet/scripts/comet-hook-guard.mjs",
+    "comet/scripts/comet-intent.mjs",
     "comet-open/SKILL.md",
     "comet-design/SKILL.md",
     "comet-build/SKILL.md",
@@ -25,17 +40,23 @@
     "comet-hotfix/SKILL.md",
     "comet-tweak/SKILL.md"
   ],
+  "internalSkills": [
+    "comet/runtime/classic/skill.yaml",
+    "comet/runtime/classic/guardrails.yaml",
+    "comet/runtime/classic/checks.yaml"
+  ],
   "rules": [
-    "comet/rules/comet-phase-guard.md"
+    "comet/rules/comet-phase-guard.md",
+    "comet/rules/comet-phase-guard.en.md"
   ],
   "hooks": {
-    "comet/scripts/comet-hook-guard.sh": {
+    "comet/scripts/comet-hook-guard.mjs": {
       "matcher": "Write|Edit",
       "description": "Block code writes in wrong Comet phase (open/design/archive)"
     }
   },
   "languages": [
-    { "id": "en", "name": "English", "skillsDir": "skills" },
-    { "id": "zh", "name": "中文", "skillsDir": "skills-zh" }
+    { "id": "en", "name": "English", "skillsDir": "skills", "artifactLanguage": "en" },
+    { "id": "zh", "name": "中文", "skillsDir": "skills-zh", "artifactLanguage": "zh-CN" }
   ]
 }

package/assets/skills/comet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comet
-description: "Comet — OpenSpec + Superpowers dual-star development workflow. Start with /comet for automatic phase detection and dispatch to subcommands. Five phases: open → design → build → verify → archive."
+description: "Use when the user wants to start or resume a Comet workflow and route by active change, .comet.yaml, and hotfix/tweak intent."
 ---
 
 # Comet — OpenSpec + Superpowers Dual-Star Development Workflow
@@ -22,23 +22,67 @@ Agents need only read this section for decision-making. Refer to the Reference A
 
 ### Output Language Rule
 
-Use the language of the user request that triggered this workflow as the default output language. When resuming an existing change with a clear dominant artifact language, preserve that language unless the user explicitly asks to switch.
+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_BASH" "$COMET_STATE" get <name> language`. Before `.comet.yaml` exists, read `language` from `.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 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
+
+**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
+  }
+}
+```
 
-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
+**Intent Recognition Slot Extraction**:
+See `comet/reference/intent-frame.md` for complete field meanings; normal routing only needs the minimal skeleton above.
 
-**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
+- `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` 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 | non-preset input | → Invoke `/comet-open` |
+| None | `full` route | → 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 |
@@ -57,16 +101,16 @@ Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall bac
 **Resume rules**:
 - On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
 - If there is an active change and the worktree has uncommitted changes, handle them through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions; this file does not repeat them
-- If `phase: build`, first check `build_pause`, `plan`, `build_mode`, and `isolation` (see details below):
-  - If `build_pause: plan-ready` but `isolation` and `build_mode` are already set, treat as stale pause: first output `[COMET] Detected stale pause (build_pause=plan-ready but isolation/build_mode already set), auto-clearing and continuing`, then run `"$COMET_BASH" "$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` or `build_mode` is not yet set, return to the `/comet-build` plan-ready resume point, prompt the user to choose isolation and execution method, and do not regenerate the plan
+- 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 `node "$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 `build_mode`, `isolation`, or `tdd_mode` is unset, return to the corresponding `/comet-build` step to supplement before executing
+  - 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 `phase: verify` and `verify_result: fail`, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
-- If `phase: open` but proposal/design/tasks are complete, first run `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
+- If `phase: 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 `node "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
+- If `phase: open` but proposal/design/tasks are complete, first run `node "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
 - If `phase: archive`, only invoke `/comet-archive`; `/comet-archive` must first wait for final archive confirmation. 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)
@@ -82,22 +126,19 @@ Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall bac
 
 If metadata conflicts with file state, use verifiable file state as source of truth and correct `.comet.yaml` before continuing.
 
-### Preset Upgrade Criteria
+### 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:
 
-**hotfix → full** (upgrade if any condition met):
-- Change involves **3+ files**
-- Architecture changes (new modules, new interfaces, new dependencies)
-- Database schema changes
-- Fix introduces new public API
-- Fix scope exceeds a single function/module
+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
 
-**tweak → full** (upgrade if any condition met):
-- Change involves **5+ files**
-- Cross-module coordination required
-- **5+** new test cases needed
-- Config item additions or deletions (not value changes)
-- New capability needed
-- Delta spec needed (existing spec affected)
+**Upgrade decision point (user chooses one of two)**:
+- Continue the preset lightweight flow (user confirms scope is manageable)
+- Upgrade to full `/comet` (use `node "$COMET_STATE" transition <name> preset-escalate` to legally rewind to the design phase, supplementing Design Doc and Superpowers plan)
+
+See the "Upgrade Assessment" section of each `comet-hotfix` / `comet-tweak` for detailed rules.
 
 ### Error Handling Quick Reference
 
@@ -105,7 +146,7 @@ If metadata conflicts with file state, use verifiable file state as source of tr
 |----------|----------|
 | `openspec list --json` fails | Check if openspec is installed, prompt user to run `openspec init` |
 | Sub-skill unavailable | Stop workflow, prompt to install or enable the corresponding skill |
-| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `"$COMET_BASH" "$COMET_STATE" set` then continue |
+| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `node "$COMET_STATE" set` then continue |
 | Build/test fails | Return to build phase for fixes, do not enter verify |
 | Incomplete change directory structure | Fill missing files according to `comet-open` artifact requirements |
 
@@ -118,18 +159,18 @@ 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_BASH" "$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, show a manual run hint). Therefore `auto_transition` **only controls next skill invocation, not phase advancement**. Regardless of `auto_transition`, user decision points below remain blocking.
+**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 `node "$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, show a manual run hint). Therefore `auto_transition` **only controls next skill invocation, not phase advancement**. Regardless of `auto_transition`, user decision points below remain blocking.
 
 **Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet` 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. Open phase proposal/design/tasks review and confirmation
 2. Confirm design approach during brainstorming
-3. Plan-ready pause choice during build phase, followed by workflow configuration selection (isolation + execution method + TDD mode)
+3. Plan-ready pause choice during build phase, followed by workflow configuration selection (workspace isolation + execution method + TDD mode + code review mode)
 4. Decide to fix or accept deviation when verify fails (including Spec drift handling)
 5. Choose branch handling method for finishing-branch
 6. Archive phase final confirmation before running the archive script
-7. Encounter upgrade conditions (hotfix/tweak → full workflow)
+7. Encounter an upgrade-assessment signal (hotfix/tweak → user chooses one of two: continue preset / upgrade to full workflow)
 8. Build phase scope expansion requiring redesign or new change split
 9. Open phase large PRD requiring confirmation to split into multiple changes
 
@@ -158,7 +199,7 @@ Agents should not skip these decision points; other unambiguous phase transition
 | `/comet-verify` | 4. Verify and Close | Both | Verification report, branch handling |
 | `/comet-archive` | 5. Archive | OpenSpec | delta→main spec sync, design doc markup, archive |
 | `/comet-hotfix` | Preset path | Both | Quick fix (skip brainstorming) |
-| `/comet-tweak` | Preset path | Both | Small change (skip brainstorming and full plan) |
+| `/comet-tweak` | Preset path | Both | OpenSpec-chained medium change (delta spec is first-class, skip brainstorming and full plan) |
 
 ```
 /comet
@@ -168,11 +209,11 @@ Agents should not skip these decision points; other unambiguous phase transition
 
 /comet-hotfix (preset, skip brainstorming)
   open ──→ build ──→ verify ──→ archive
-    ↑ If upgrade triggered → block for confirmation → supplement Design Doc → return to full workflow
+    ↑ 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 (preset, skip brainstorming and full plan)
-  open ──→ lightweight build ──→ light verify ──→ archive
-    ↑ If upgrade triggered → block for confirmation → 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
 ```
 
 ---
@@ -185,9 +226,10 @@ Agents should not skip these decision points; other unambiguous phase transition
 - 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.sh build --apply` and `comet-state.sh transition <name> build-complete`
+- These constraints are enforced by both `comet-guard.mjs build --apply` and `comet-state.mjs transition <name> build-complete`
 
 ### .comet.yaml Field Reference
 
@@ -215,68 +257,11 @@ See `comet/reference/debug-gate.md` for the complete debug gate protocol.
 
 ### Script Location
 
-Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars. This block is a standard boilerplate repeated in every sub-skill for independent loadability; changes must be kept in sync across all files (boilerplate version: `v2`, update this version when changing to help locate files needing sync):
+Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars. The full bootstrap block, command reference (`--apply`, `transition`, `next`, `archive`), and output formats live in `comet/reference/scripts.md`. Run that bootstrap once per session, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE`, `$COMET_RUNTIME` throughout. Key entry points:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
-if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
-  return 1
-fi
-. "$COMET_ENV"
-
-# 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
-fi
+node "$COMET_GUARD" <change-name> <phase> --apply    # phase guard + auto state update
+node "$COMET_STATE" transition <change-name> <event> # open-complete | design-complete | build-complete | verify-pass | verify-fail
+node "$COMET_STATE" next <change-name>               # NEXT: auto|manual|done  + SKILL: <skill-name>; auto_transition:false → manual, which pauses only the next skill invocation and does not block phase updates
+node "$COMET_ARCHIVE" <change-name>                  # full archive in one command
 ```
-
-**Auto state update**: Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
-
-```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply
-```
-
-`--apply` delegates to `comet-state transition`. Use these semantic events when state changes need to be expressed directly:
-
-```bash
-"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
-"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
-```
-
-**Resolve next action**: after guard-based phase advancement, use the `next` subcommand to determine whether to auto-invoke the next skill:
-
-```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
-```
-
-Output format: `NEXT: auto|manual|done` + `SKILL: <skill-name>` (omitted for `done`) + `HINT` (for `manual` only). With `auto_transition: false`, output is `manual`, which pauses only the next skill invocation and does not block phase updates.
-
-**Archive script**: Complete all archive steps in one command:
-
-```bash
-"$COMET_BASH" "$COMET_ARCHIVE" <change-name>
-```
-
-After loading comet, agents should run the variable assignments above once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE` throughout the session.
-
-
-### Best Practices
-
-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. **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 confirmation** — Enter `/comet-archive` only after `/comet-verify` passes, but wait for final user confirmation before running the archive script
-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/auto-transition.md

@@ -13,7 +13,7 @@ This protocol is shared by all comet sub-skills. It defines the automatic handof
 After exit conditions are met and the phase guard has advanced phase, run:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
+node "$COMET_STATE" next <change-name>
 ```
 
 The script outputs a deterministic next step based on `phase`, `workflow`, and `auto_transition`:

package/assets/skills/comet/reference/comet-yaml-fields.md

@@ -8,6 +8,7 @@ This file is the field reference for the `.comet.yaml` state file. Consult on de
 
 ```yaml
 workflow: full
+language: en
 phase: build
 design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
@@ -16,6 +17,8 @@ build_mode: subagent-driven-development
 build_pause: null
 subagent_dispatch: confirmed
 tdd_mode: tdd
+review_mode: standard
+auto_transition: true
 isolation: branch
 verify_mode: light
 verify_result: pending
@@ -31,14 +34,16 @@ archived: false
 | Field | Meaning |
 |-------|---------|
 | `workflow` | `full`, `hotfix`, or `tweak` |
+| `language` | Artifact language, `en` or `zh-CN`. Written to `.comet/config.yaml` by `comet init`, snapshotted into `.comet.yaml` when a change is created, and used as the main-language constraint for OpenSpec / Superpowers artifacts |
 | `phase` | Current phase: `open`, `design`, `build`, `verify`, `archive` (init sets `open`; guard handles transitions) |
 | `design_doc` | Associated Superpowers Design Doc path; may be empty |
 | `plan` | Associated Superpowers Plan path; may be empty |
 | `base_ref` | Git commit SHA recorded at init for scale assessment. Used as baseline for changed-file counting when no plan exists |
-| `build_mode` | Selected execution mode; may be empty |
+| `build_mode` | Selected execution mode; may be empty. Values: `subagent-driven-development` (isolated background subagents implement and review each task), `executing-plans` (main session executes sequentially by plan), `direct` (main session codes directly; allowed by default only for hotfix/tweak, full workflow requires `direct_override: true`) |
 | `build_pause` | Build phase internal pause point. `null` = no pause, `plan-ready` = plan generated, paused for user model switch |
 | `subagent_dispatch` | `null` or `confirmed`. Only when the platform's real background subagent/Task/multi-agent dispatch capability is confirmed may `build_mode: subagent-driven-development` be written and used to leave the build phase |
 | `tdd_mode` | `tdd` or `direct`. Full workflow must select before leaving build. `tdd` forces write-failing-test-first per task; `direct` skips TDD enforcement. hotfix/tweak default to `direct` |
+| `review_mode` | `off`, `standard`, or `thorough`. Full workflow must select before leaving build; hotfix/tweak default to `off` |
 | `isolation` | `branch` or `worktree`, workspace isolation mode. Full init may be `null` but only until `/comet-build` Step 3; hotfix/tweak default to `branch` |
 | `verify_mode` | `light` or `full`; may be empty |
 | `auto_transition` | `true` or `false`. Only controls whether to automatically invoke the next skill after phase guard advances phase; `false` outputs `manual` from `comet-state next`, pausing next-skill invocation but not blocking phase field updates |
@@ -54,8 +59,8 @@ archived: false
 | Field | Meaning |
 |-------|---------|
 | `direct_override` | `true`/`false`. Full workflow must explicitly set to `true` to use `build_mode: direct` |
-| `build_command` | Project build command. Guard runs this first; prints command output on failure |
-| `verify_command` | Project verify command. Verify guard runs this first; falls back to build command when unset |
+| `build_command` | Project build command. Guard runs this first; supports restricted command words/quotes/paths plus `&&` sequential steps; rejects `;`, pipes, bare `&`, `$`, and backticks |
+| `verify_command` | Project verify command. Verify guard runs this first; same restricted command grammar as `build_command`; falls back to build command when unset |
 
 ## State Machine Hard Constraints
 
@@ -63,6 +68,8 @@ archived: false
 - Before `build → verify`, `build_mode` must be selected
 - `build_mode: subagent-driven-development` requires `subagent_dispatch: confirmed`
 - Full workflow must select `tdd_mode` as `tdd` or `direct` before leaving build
+- Full workflow must select `review_mode` as `off`, `standard`, or `thorough` before leaving build
 - `build_mode: direct` defaults to `hotfix`/`tweak` only; full workflow requires `direct_override: true`
 - `build_pause` is not an execution mode; must not be written to `build_mode`
-- These constraints exist in both `comet-guard.sh build --apply` and `comet-state.sh transition <name> build-complete`
+- These constraints exist in both `comet-guard.mjs build --apply` and `comet-state.mjs transition <name> build-complete`
+- `preset-escalate` event: only allows `hotfix`/`tweak` workflow at `phase: build`; atomically sets `workflow`/`classic_profile` to `full`, rewinds `phase` to `design`, and clears `design_doc` (satisfying the comet-design entry requirement). This is the only legal channel for a preset → full upgrade — direct `set phase design` is hard-blocked by the state machine, and `set classic_profile` is a machine-owned field that cannot be set manually

package/assets/skills/comet/reference/context-recovery.md

@@ -4,10 +4,20 @@ Canonical path: `comet/reference/context-recovery.md`
 
 This protocol is shared by all comet sub-skills that may trigger context compression. When the agent suspects context compression has occurred (previous conversation summarized, cannot find previously discussed content), follow this protocol to recover.
 
+## Any-Entry Recovery Principle
+
+The user may resume the workflow directly from `/comet-open`, `/comet-design`, `/comet-build`, `/comet-verify`, `/comet-archive`, `/comet-hotfix`, or `/comet-tweak`. On entry to any sub-skill, first locate scripts via `comet/reference/scripts.md`, then run the entry check or recovery check for that sub-skill's phase. Do not infer phase from conversation history.
+
+```bash
+node "$COMET_STATE" check <change-name> <phase> --recover
+```
+
+If the check shows the actual phase, workflow, or evidence belongs to another skill, switch according to script output and `/comet` routing rules; do not keep writing state in the wrong phase. If the worktree has uncommitted changes, attribute them first via `comet/reference/dirty-worktree.md`.
+
 ## Recovery Steps
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> <phase> --recover
+node "$COMET_STATE" check <change-name> <phase> --recover
 ```
 
 The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the **Recovery action** output for next steps.
@@ -21,7 +31,7 @@ If the recovery script outputs `build_mode: subagent-driven-development`:
 3. Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the current task or final review, implementation commit, RED/GREEN evidence, passed reviews, unresolved feedback, and review-fix round
 4. Do not execute tasks directly in the main session
 5. Resume from the checkpoint's exact stage; begin implementer dispatch for the first unchecked task only when the checkpoint is missing or mismatched
-6. After dual review and targeted checkoff verification pass, immediately continue to the next task without summarizing or asking whether to continue
+6. After `review_mode` validation and targeted checkoff verification pass, immediately continue to the next task without summarizing or asking whether to continue
 
 ## Design Phase Special Recovery
 

package/assets/skills/comet/reference/debug-gate.md

@@ -14,4 +14,20 @@ This protocol is shared by comet sub-skills that directly modify code, including
 1. Reproduce and locate the root cause first by reading the full error, checking recent changes, and tracing data flow
 2. If the root cause is a source bug, first add a minimal failing test that reproduces the crash or unexpected behavior, then modify the source
 3. After the fix, run that failing test, related tests, and the project's build or verification commands until all pass
-4. Keep the test, the source fix, and the tasks.md checkoff in the current change; do not replace the current change verification loop by starting a separate “write test cases” change
+4. Keep the test, the source fix, and the tasks.md checkoff in the current change; do not replace the current change verification loop by starting a separate “write test cases” change
+
+## Parallel Investigation of Multiple Failures
+
+Before entering the four-stage flow, run a failure-independence assessment to decide serial vs. parallel investigation:
+
+- **No parallelism (keep existing serial `systematic-debugging`)**: ≤ 2 failures; failures are related (fixing one might fix others); shared state; would touch the same set of files; failure independence not yet established
+- **Parallel (load the Superpowers `dispatching-parallel-agents` skill)**: ≥ 3 failures from distinct problem domains (different test files with different root causes, different subsystems broken independently), mutually independent and non-interfering
+
+When parallel conditions are met:
+
+1. Immediately use the Skill tool to load the Superpowers `dispatching-parallel-agents` skill
+2. Dispatch one background investigation agent per independent failure, grouped by problem domain, with all dispatches in a single response for concurrent execution. Each agent prompt must be self-contained (specific failure, error messages, allowed investigation scope, prohibition on touching other problem domains' code)
+3. All agents remain bound by this protocol's "no source changes before the root cause is identified" constraint; they only locate the root cause and return findings — **they do not submit fixes directly**
+4. Once all investigations return, the main session serially consolidates findings and performs fixes; fixes still go through the current `review_mode` verification and review loop
+
+> Parallelism applies only to **investigation**. Fixes are always serial, avoiding conflicts from multiple agents editing the same set of files at once — consistent with the `subagent-driven-development` red flag of "never dispatch multiple implementation subagents in parallel."

package/assets/skills/comet/reference/decision-point.md

@@ -7,14 +7,25 @@ This protocol is shared by all comet sub-skills that contain user decision point
 ## Core Rules
 
 - Decision points are blocking points. Pause and wait for an explicit user choice before continuing
-- Use the current platform's available user input or confirmation mechanism to collect the choice
+- Use the current platform's available user input or confirmation mechanism to collect the choice; when platforms such as Claude Code provide `AskUserQuestion`, prefer `AskUserQuestion` to present single-select or multi-select options
+- If the current tool list does not include `AskUserQuestion`, or the first `AskUserQuestion` call fails, treat structured questions as unavailable for this session; do not repeatedly retry `AskUserQuestion` for later decision points in the same session, and use the text-options fallback directly
 - If the current platform has no structured question tool, ask clear options in the conversation and stop until the user replies
 - Never substitute recommendation rules, defaults, historical preferences, or “the user would probably agree” for current confirmation
 - Do not write state fields, execute the chosen branch, or auto-continue before the user explicitly chooses
 
+## `AskUserQuestion` Priority Strategy
+
+When using structured questions:
+
+- Use a single-select `AskUserQuestion` question for single-choice decision points, and a multi-select question for multi-choice decision points
+- Each option must include a short label and impact description; recommendations may explain tradeoffs but must not auto-select
+- If the tool call succeeds, wait for the user to answer through that question; do not also print a duplicate text option list
+- If the tool is missing, the call fails, or the host reports an error, record that structured questions are unavailable for this session, then use the text-options fallback
+
 ## Minimum Presentation Requirements
 
 - State what the current decision point is deciding
 - Present clear options; when the user must pick one option, keep the options mutually exclusive and actionable
+- In text-options fallback mode, explicitly state "single-select" or "multi-select", number the options, describe each option's impact, ask the user to reply with the option number(s), then stop until the user replies
 - Recommendations may explain tradeoffs, but may not replace user confirmation
-- Only execute the corresponding commands or state updates after the user chooses
+- Only execute the corresponding commands or state updates after the user chooses

package/assets/skills/comet/reference/intent-frame.md

@@ -0,0 +1,74 @@
+# CometIntentFrame Field Reference
+
+Read this file only when field meanings are needed. Normal `/comet` routing only needs the minimal skeleton in the main Skill; the runtime fills omitted defaults and outputs the final `route`.
+
+## Top-Level Fields
+
+| Field | Meaning |
+|-------|---------|
+| `schema_version` | Frame version. Currently fixed to `comet.intent.v1`. |
+| `utterance` | The user request that triggered `/comet`. |
+| `intent` | High-level user intent and confidence. If confidence is below the runtime threshold, routing falls back to `ask_user`. |
+| `slots` | Routing slots normalized from the user request. |
+| `context` | Repository context read from local state; this is not extracted from the user utterance. |
+| `evidence` | Evidence for key routing conclusions. Missing key evidence makes the runtime prefer `ask_user`. |
+| `proposed_route` | Agent-submitted route candidate. Minimal input only needs `name` and `confidence`; the runtime reviews it and outputs the final `route`. |
+
+## `intent`
+
+| Field | Meaning |
+|-------|---------|
+| `intent.name` | High-level user intent: start, resume, fix bug, make tweak, ask question, or unknown. |
+| `intent.confidence` | Agent confidence in the high-level intent. This participates in low-confidence fallback; `proposed_route.confidence` does not. |
+
+## `slots`
+
+| Field | Meaning |
+|-------|---------|
+| `requested_action` | The action the user wants, such as `start`, `resume`, `continue`, `fix`, `modify`, `create`, `verify`, `archive`, or `question`. |
+| `workflow_candidate` | Agent-inferred candidate workflow: `full`, `hotfix`, `tweak`, or `null`. This is an inference and the runtime reviews it. |
+| `user_explicit_workflow` | Whether the user explicitly named a workflow. If the user says "use hotfix", set `hotfix`; otherwise set `null`. Explicit workflow still falls back to `ask_user` when it conflicts with risk signals. |
+| `change_id` | Active change name explicitly requested by the user for resume or operation. Use `null` when unspecified. |
+| `existing_behavior` | Whether the request fixes existing behavior or a regression. `true` with no new capability/API/schema/cross-module risk tends toward `hotfix`. |
+| `new_capability` | Whether the request adds a new capability. Usually tends toward `full`. |
+| `public_api_change` | Whether the request changes a user-visible contract, such as CLI flags, config fields, JSON output, or public Skill flow. Usually tends toward `full`. |
+| `schema_change` | Whether the request changes structured data formats, such as `.comet.yaml`, `run-state.json`, eval manifests, bundle manifests, or config schema. Usually tends toward `full`. |
+| `cross_module_change` | Whether the request crosses module or workflow boundaries. Usually tends toward `full`. |
+| `target_area` | Optional explanation field for the target area the user mentioned. The minimal skeleton does not need it. |
+| `scope` | Optional explanation field for rough scope size. The current scorer does not let it drive routing by itself, and the minimal skeleton does not need it. |
+
+## `context`
+
+| Field | Meaning |
+|-------|---------|
+| `active_changes_count` | Number of unarchived active changes from `openspec list --json`. Multiple active changes without a `change_id` route to `ask_user`. |
+| `active_change_names` | Names of active changes. When the user supplies `change_id`, the runtime checks it against this list. |
+| `dirty_worktree` | Optional state field. The entry-route minimal skeleton does not need it; dirty worktree handling belongs to `comet/reference/dirty-worktree.md`. |
+
+## `evidence`
+
+Each evidence item contains:
+
+| Field | Meaning |
+|-------|---------|
+| `field` | Frame field supported by the evidence, such as `intent.name` or `slots.workflow_candidate`. |
+| `quote` | Evidence snippet from the user request, repository state, or `.comet.yaml`. |
+| `source` | Evidence source: `user`, `repo`, or `state`. |
+
+## `proposed_route`
+
+| Field | Meaning |
+|-------|---------|
+| `name` | Agent route candidate: `full`, `hotfix`, `tweak`, `resume`, `ask_user`, or `out_of_scope`. |
+| `confidence` | Agent confidence in the route candidate. Diagnostic only; it does not participate in low-confidence fallback. |
+| `next_skill` | Derived field normalized by the runtime. The minimal skeleton does not need it. |
+| `requires_confirmation` | Derived field normalized by the runtime. The minimal skeleton does not need it. |
+| `fallback_reason` | Derived field normalized by the runtime. The minimal skeleton does not need it. |
+
+## Routing Notes
+
+- Existing bug, regression, or broken behavior with no new capability/API/schema/cross-module risk: prefer `hotfix`.
+- Copy, config, docs, prompt, or 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`.