@rpamis/comet 0.3.5 → 0.3.7

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

@@ -23,7 +23,7 @@ if [ -z "$COMET_ENV" ]; then
   return 1
 fi
 . "$COMET_ENV"
-bash "$COMET_STATE" check <name> design
+"$COMET_BASH" "$COMET_STATE" check <name> design
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -35,16 +35,25 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 **Must be generated by script. Agent writing summaries on the fly is not allowed.**
 
 ```bash
-bash "$COMET_HANDOFF" <change-name> design --write
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
 ```
 
-The script generates and records:
+The script reads the change `.comet.yaml` `context_compression` snapshot, then generates and records the matching handoff package.
+
+Default `context_compression: off` generates:
 
 ```
 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:
+
+```
+openspec/changes/<name>/.comet/handoff/spec-context.json
+openspec/changes/<name>/.comet/handoff/spec-context.md
+```
+
 And writes to `.comet.yaml`:
 
 ```yaml
@@ -57,10 +66,15 @@ The default handoff package is a **compact traceable excerpt**, not an agent sum
 - `design-context.md`: context for Superpowers to read, containing script markers, source path, line range, sha256, deterministic excerpts
 - When exceeding excerpt budget, marks `[TRUNCATED]` and retains Full source path
 
+The beta handoff package is a **structured spec projection** that reduces OpenSpec token load without replacing the canonical spec:
+- `spec-context.json`: machine index containing change, phase, canonical spec, source paths, hash, and file roles
+- `spec-context.md`: context for Superpowers to read, verbatim-projecting delta spec files and referencing supporting artifacts by hash
+- OpenSpec delta specs remain canonical; if the projection is missing, stale, or unclear, regenerate the handoff or read the source spec directly instead of writing an agent summary
+
 If full context is genuinely needed, explicitly run:
 
 ```bash
-bash "$COMET_HANDOFF" <change-name> design --write --full
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
 ```
 
 Handoff package sources come from OpenSpec open phase artifacts:
@@ -71,16 +85,29 @@ Handoff package sources come from OpenSpec open phase artifacts:
 
 ### 1b. Execute Brainstorming (with Context)
 
-**Immediately execute:** Use the Skill tool to load the `superpowers:brainstorming` skill, ARGUMENTS containing:
+**Immediately execute:** Use the Skill tool to load the Superpowers `brainstorming` skill. Skipping this step is prohibited.
+
+When loading the skill, ARGUMENTS must include:
+
+```text
+Language: Use the language of the user request that triggered this workflow
+```
+
+After the skill loads, follow its guidance and use the following context:
 
 ```
 Change: <change-name>
 OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/design-context.md
 Machine handoff: openspec/changes/<name>/.comet/handoff/design-context.json
 
-OpenSpec artifacts are the upstream source of truth. Do not redefine requirements, do not rewrite proposal/spec.
+If context_compression is beta, use:
+OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/spec-context.md
+Machine handoff: openspec/changes/<name>/.comet/handoff/spec-context.json
+
+OpenSpec artifacts are the upstream source of truth, but you must not weaken the Superpowers `brainstorming` clarification flow by "skipping redundant context exploration".
 Your task is to perform deep technical design based on the handoff package: implementation approach, technical risks, testing strategy, boundary conditions.
-If you find OpenSpec delta spec missing acceptance scenarios, you may only propose Spec Patches and write them back to OpenSpec delta spec; do not create a second requirements spec in the Design Doc.
+If goals, scope, non-goals, acceptance scenarios, or key constraints remain unclear, you must continue asking questions and form the design proposal first; must not create the Design Doc after only one Q&A turn.
+Do not rewrite proposal/spec; if you find OpenSpec delta spec missing acceptance scenarios, you may only propose Spec Patches and write them back to OpenSpec delta spec; do not create a second requirements spec in the Design Doc. Spec Patches are limited to supplementing acceptance scenarios, correcting ambiguous descriptions, or adding boundary conditions — they must not substantially rewrite the delta spec's structure or scope. If major changes are needed, flag them as design findings and return to brainstorming for confirmation.
 
 Design Doc frontmatter must be minimal, containing only:
 ---
@@ -89,23 +116,26 @@ role: technical-design
 canonical_spec: openspec
 ---
 
-Skip redundant context exploration, proceed directly to design questions.
+Proceed through the original `brainstorming` skill flow: clarifying questions, 2-3 approaches, and step-by-step design confirmation. Do not write the Design Doc early.
 ```
 
-Skipping this step is prohibited. Proceeding without loading this skill is prohibited.
+Proceeding without loading this skill is prohibited.
 
-If `superpowers:brainstorming` is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.
+If the Superpowers `brainstorming` skill is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.
 
 After the skill loads, follow its guidance to produce design proposals (presented as conversation):
 - Technical approach: architecture, data flow, key technology choices and risks
 - Testing strategy
+- Requirement/scope gaps and Spec Patches to be written back
 - If acceptance scenarios need supplementing, indicate delta spec changes to be written back
 
 The brainstorming phase does not write to the Design Doc file; it only produces design proposals for Step 1c user confirmation. Only after confirmation should `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` be created and delta spec written back.
 
+For context compaction recovery, the agent must incrementally update `brainstorm-summary.md` during brainstorming. After each clarification round or proposal iteration, update the file whenever new confirmed facts, key constraints, candidate approaches, trade-offs/risks, testing strategy, or Spec Patch candidates emerge; mark unconfirmed items as "pending" or "candidate". This file is a recovery checkpoint, not the Design Doc, and must not replace the Step 1c user confirmation.
+
 ### 1c. User Confirms Design Proposal (Blocking Point)
 
-After brainstorming produces a design proposal, **must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm the design proposal**. Must not create the final Design Doc, write `design_doc`, run design guard, or enter `/comet-build` before user confirmation. Must not just output a text prompt and then continue executing.
+After brainstorming produces a design proposal, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm the design proposal**. Must not create the final Design Doc, write `design_doc`, run design guard, or enter `/comet-build` before user confirmation. If the current platform has no structured question tool, ask a confirmation question in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
 When pausing, only present essential summary:
 - Technical approach adopted
@@ -115,19 +145,85 @@ When pausing, only present essential summary:
 
 Only after the user explicitly confirms, proceed to Step 2. If the user requests adjustments, continue brainstorming iteration until the user confirms.
 
-### 2. Update Comet State
+### 1d. Brainstorming Checkpoint Finalization
+
+After the user confirms the design proposal, before creating the Design Doc, create or update the incrementally maintained checkpoint file and finalize it as the confirmed design summary:
+
+```bash
+mkdir -p openspec/changes/<name>/.comet/handoff
+```
+
+`openspec/changes/<name>/.comet/handoff/brainstorm-summary.md` structure:
+
+```markdown
+# Brainstorm Summary
+
+- Change: <change-name>
+- Date: <YYYY-MM-DD>
+
+## Confirmed Technical Approach
+
+<summary of the user-confirmed approach>
+
+## Key Trade-offs and Risks
+
+<major trade-offs and risks>
+
+## Testing Strategy
+
+<testing method overview>
 
-First record the design_doc path. If Step 1c wrote back delta spec (added or modified `specs/*/spec.md`), must regenerate handoff to update hash:
+## Spec Patches
+
+<delta spec changes to write back, or "None" if none>
+```
+
+**Context compaction note**: Each incremental update to `brainstorm-summary.md` is a relatively safe recovery point. After brainstorming completes, if the context window is tight, prefer compacting here. After compaction, reload the following files to continue Step 2:
+- `openspec/changes/<name>/.comet/handoff/brainstorm-summary.md`
+- `openspec/changes/<name>/.comet/handoff/design-context.md` (or `spec-context.md` in beta mode)
+- `openspec/changes/<name>/.comet/handoff/design-context.json` (or `spec-context.json` in beta mode)
+
+### 1e. Active Context Compaction Gate
+
+After Step 1d completes and `brainstorm-summary.md` is written, enter the active compaction gate before creating the Design Doc. At this point the OpenSpec handoff, brainstorming decisions, and pending items are durable, so the agent should proactively release the earlier Spec and brainstorming context to preserve window space for Step 2 and the later Build phase.
+
+Rules:
+- If the current platform provides a native context compaction/cleanup mechanism (for example, the host agent's compact/compaction command, tool, or UI action), trigger active compaction here once; do not try to fake compaction through a shell script.
+- The compaction resume prompt must include the change name, current step (Design Step 2), and the three handoff file categories listed above.
+- If the current platform cannot be compacted programmatically by the agent, pause and tell the user to run the host platform's manual compaction action; continue to Step 2 only after the user confirms compaction is unavailable or asks to continue.
+
+### 2. Create Design Doc
+
+Create the Design Doc based on the full brainstorming conversation context (still in the main session).
+
+Design Doc frontmatter must be minimal:
+
+```yaml
+---
+comet_change: <change-name>
+role: technical-design
+canonical_spec: openspec
+---
+```
+
+Write the Design Doc to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`.
+If Spec Patches need to be written back, also edit the corresponding `specs/*/spec.md`.
+
+**Context compaction recovery**: If context has been compacted, resume from `brainstorm-summary.md` + handoff context. If the user has not confirmed the design proposal yet, return to Step 1b/1c and continue brainstorming; if the user has confirmed it, continue creating the Design Doc. brainstorm-summary.md is the compaction checkpoint, not the sole input for the Design Doc — when creating, leverage the full recovered context as much as possible.
+
+### 3. Update Comet State
+
+First record the design_doc path. If Spec Patches wrote back delta spec (added or modified `specs/*/spec.md`), must regenerate handoff to update hash:
 
 ```bash
 # Record design_doc path
-bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+"$COMET_BASH" "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # If delta spec changes exist, regenerate handoff (update hash)
-bash "$COMET_HANDOFF" <change-name> design --write
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
 
 # Auto-transition to next phase
-bash "$COMET_GUARD" <change-name> design --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
 ```
 
 If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
@@ -138,15 +234,16 @@ If there are no delta spec changes, skip the handoff regeneration step. The stat
 - Design Doc frontmatter contains `comet_change`, `role: technical-design`, `canonical_spec: openspec`
 - `handoff_context` and `handoff_hash` written to `.comet.yaml` (enforced by guard)
 - `handoff_hash` matches current OpenSpec open phase artifacts (enforced by guard)
-- `design-context.md` must be script-generated and contain source path, mode, sha256 traceability markers (enforced by guard)
+- `design-context.md` or beta `spec-context.md` must be script-generated and contain source path, mode, sha256 traceability markers (enforced by guard)
+- In beta mode, `spec-context.json` must be structurally valid and reference the current source files (enforced by guard)
 - If new capabilities or supplementary acceptance scenarios exist, OpenSpec delta spec has been created/updated
 - `design_doc` written to `.comet.yaml`
-- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
+- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
 
 Must use `--apply` before exit:
 
 ```bash
-bash "$COMET_GUARD" <change-name> design --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
 ```
 
 ## Context Compaction Recovery
@@ -154,13 +251,22 @@ bash "$COMET_GUARD" <change-name> design --apply
 The design phase may trigger context compaction during brainstorming. To recover, first run:
 
 ```bash
-bash "$COMET_STATE" check <change-name> design --recover
+"$COMET_BASH" "$COMET_STATE" check <change-name> design --recover
 ```
 
 The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the Recovery action to determine next step.
 
-## Automatic Transition
+## Automatic Handoff to Next Phase
+
+> **Terminology distinction**: the "phase advancement" above is performed by guard `--apply`, which updates the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. This section's "automatic handoff" only controls whether to automatically invoke the next skill.
 
-After exit conditions are met (including user confirming the design proposal), auto-transition to next phase:
+After guard-based phase advancement, run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
 
-> **REQUIRED NEXT SKILL:** Invoke `comet-build` skill to enter the plan and build phase.
+The script determines the next action from `phase`, `workflow`, and `auto_transition`:
+- `NEXT: auto` -> invoke the `SKILL` target to continue to the next phase
+- `NEXT: manual` -> do not invoke the next skill; follow `HINT` and ask the user to run `/<SKILL>` manually
+- `NEXT: done` -> workflow is complete; no further action needed

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

@@ -16,9 +16,13 @@ Quick bug fix workflow: open → build → verify → archive. Skip brainstormin
 
 ---
 
-## Process (preset workflow, 5 steps)
+## Process (preset workflow, 6 steps)
 
-Execution chain: open → build → root cause check → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, root cause confirmation, scale-based verification, archive after verification passes.
+### 0. Output Language Constraint
+
+Streamlined OpenSpec artifacts must use the language of the user request that triggered this workflow.
+
+Execution chain: open → build → root cause check → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, root cause confirmation, scale-based verification, and final archive confirmation after verification passes.
 
 Locate Comet scripts before starting:
 
@@ -46,24 +50,33 @@ After the skill loads, follow its guidance to create streamlined artifacts:
 Initialize Comet state file:
 
 ```bash
-bash "$COMET_STATE" init <name> hotfix
+"$COMET_BASH" "$COMET_STATE" init <name> hotfix
 ```
 
 Verify initialized state:
 
 ```bash
-bash "$COMET_STATE" check <name> open
+"$COMET_BASH" "$COMET_STATE" check <name> open
 ```
 
 Run phase guard to transition open → build:
 
 ```bash
-bash "$COMET_GUARD" <change-name> open --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
 ```
 
+Check `auto_transition` to decide whether to continue:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
+```
+
+- `NEXT: auto` → continue to Step 2
+- `NEXT: manual` → pause, follow `HINT` to prompt user to run `/<SKILL>` manually
+
 ### 2. Direct Build (preset build)
 
-Use hotfix defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection).
+Use hotfix defaults: `build_mode: direct`. Skip Superpowers `brainstorming` and `writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection — note this does NOT trigger full workflow upgrade, only switches execution method).
 
 Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the fix scope exceeds hotfix, handle it through this file's "Upgrade Conditions".
 
@@ -82,6 +95,14 @@ Before continuing or starting changes, handle uncommitted changes through `comet
 - Create delta spec in `openspec/changes/<name>/specs/<capability>/spec.md`
 - Only include `## MODIFIED Requirements` section
 
+During hotfix execution, whenever a crash, unexpected behavior, test failure, or build failure appears while running the program, tests, build, or manual verification, must use the Skill tool to load the Superpowers `systematic-debugging` skill. Before root-cause investigation is complete, must not propose or implement source-code fixes.
+
+Handle it using the four-phase `systematic-debugging` flow:
+- First reproduce and locate the root cause, read full errors, check recent changes, and trace data flow
+- If root cause points to a source bug, first add a minimal failing test that reproduces the crash or unexpected behavior, then modify source code
+- After the fix, run that failing test, related tests, and project build/verification commands to confirm all pass
+- Keep the test, source fix, and tasks.md checkoff inside the current change; must not replace the current change verification loop by starting a separate "write test cases" change
+
 ### 3. Root Cause Elimination Check
 
 **Execute before running build guard**, ensuring the fix actually eliminates the root cause:
@@ -97,7 +118,7 @@ Before continuing or starting changes, handle uncommitted changes through `comet
 After root cause is confirmed eliminated, run phase guard to transition build → verify:
 
 ```bash
-bash "$COMET_GUARD" <change-name> build --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
 ```
 
 State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
@@ -110,11 +131,11 @@ Reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight
 
 Small-scale hotfixes without delta spec usually meet lightweight verification conditions (≤ 3 tasks, ≤ 2 files), comet-verify's scale assessment will select lightweight verification path (5 quick checks). If hotfix created delta spec, enter full verification path according to comet-verify's scale assessment rules.
 
-After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
+After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving. After verification passes, still enter `/comet-archive`'s final archive confirmation; do not automatically run the archive script.
 
 ### 5. Archive (preset archive)
 
-Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving.
+Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving, and wait for `/comet-archive`'s final archive confirmation.
 
 **Immediately execute:** Use the Skill tool to load the `comet-archive` skill to archive. Skipping this step is prohibited.
 If there is delta spec, sync to main spec according to comet-archive rules, and handle associated Design Doc and Plan archiving annotations.
@@ -124,11 +145,16 @@ If there is delta spec, sync to main spec according to comet-archive rules, and
 ## Continuous Execution Mode
 
 <IMPORTANT>
-Hotfix workflow is **one-time continuous execution**. After invoking `/comet-hotfix`, agent must automatically advance through hotfix steps, without pausing to wait for user input mid-way. But the following situations must pause and wait for user confirmation:
+Hotfix workflow is **one-time continuous execution**. After invoking `/comet-hotfix`, agent must automatically advance through hotfix steps, without pausing to wait for user input mid-way.
 
-1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to full workflow
+Exception: when `.comet.yaml` has `auto_transition: false`, after each phase guard advances `phase`, do not auto-invoke the next skill. In this case, use `"$COMET_BASH" "$COMET_STATE" next <name>` output and pause for manual continuation as instructed.
+
+The following situations must also pause and wait for user confirmation:
+
+1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm** upgrading to full workflow
 2. workspace isolation and execution-method selection when tasks exceed 3 and transfer to `/comet-build`
 3. verify phase (comet-verify) verification-failure and branch-handling decisions
+4. Final archive confirmation (before comet-archive runs the archive script)
 
 Execution order: quick open → direct build → root cause check → verification → archive → complete
 
@@ -149,12 +175,13 @@ Upgrade to full `/comet` when **any** of the following conditions are met:
 | Introduces new public API | Fix creates new external interface |
 | Fix scope exceeds single function/module | Requires coordinated changes |
 
-When upgrade conditions are met, **must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. Must not just output a text prompt and then continue executing.
+When upgrade conditions are met, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. If the current platform has no structured question tool, ask an upgrade confirmation question in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
-After user confirms upgrade, **must first update the workflow field** before entering full flow:
+After user confirms upgrade, **must first update the workflow and phase fields** before entering full flow:
 
 ```bash
-bash "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> phase design
 ```
 
 Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop hotfix and report that current change has exceeded hotfix scope.
@@ -166,4 +193,19 @@ Then on current change basis, supplement Design Doc: **Immediately use the Skill
 - Bug fixed, tests pass
 - Change archived
 - If spec changes, synced to main spec
-- **Phase guard**: Before build → verify run `bash "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `bash "$COMET_GUARD" <change-name> verify --apply`
+- **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+
+## Automatic Handoff to Next Phase
+
+> **Terminology distinction**: phase guard `--apply` advances the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. This section's "automatic handoff" only controls whether to automatically invoke the next skill.
+
+After each phase guard or state transition advances phase, run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
+```
+
+The script determines the next action from `phase`, `workflow`, and `auto_transition`:
+- `NEXT: auto` -> invoke the `SKILL` target to continue the hotfix flow (`phase: build` returns `comet-hotfix`, `verify` returns `comet-verify`, `archive` returns `comet-archive`)
+- `NEXT: manual` -> do not invoke the next skill; follow `HINT` and ask the user to run `/<SKILL>` manually
+- `NEXT: done` -> workflow is complete; no further action needed

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

@@ -1,6 +1,6 @@
 ---
 name: comet-open
-description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas through OpenSpec, create change structure (proposal + design + tasks)."
+description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas through OpenSpec, confirm requirements clarification, then create change structure (proposal + design + tasks)."
 ---
 
 # Comet Phase 1: Open
@@ -11,17 +11,81 @@ description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas throug
 
 ## Steps
 
-### 1. Explore Ideas
+### 0. Output Language Constraint
+
+Every prompt and artifact request passed to OpenSpec must include the output-language constraint: use the language of the user request that triggered this workflow. When resuming an existing change with a clear dominant artifact language, preserve that language unless the user explicitly asks to switch.
+
+### 1. Explore Ideas and Clarify Requirements
 
 **Immediately execute:** Use the Skill tool to load the `openspec-explore` skill. Skipping this step is prohibited.
 
-After the skill loads, freely explore the problem space following its guidance.
+After the skill loads, explore the problem space following its guidance, but do not treat one Q&A turn as sufficient clarification. You must continue asking, align with the user, and form a clarification summary covering:
+- Goals: the problem the user truly wants to solve and the expected outcome
+- Non-goals: what is explicitly out of scope for this change
+- Scope boundaries: included/excluded modules, users, platforms, or data
+- Key unknowns: unresolved assumptions, risks, or dependencies
+- Draft acceptance scenarios: at least the core success scenario and important boundary scenarios
+
+The clarification summary must include: goals, non-goals, scope boundaries, key unknowns, and draft acceptance scenarios.
+
+### 1a. PRD Split Preflight (Blocking Point)
+
+When the user input is a large PRD, roadmap, complete product plan, or the clarification summary shows multiple independent capabilities, modules, user journeys, or milestones, must evaluate whether it should be split into multiple changes before creating OpenSpec artifacts.
+
+The split preflight must be based on clarified information and output a proposed split list. Each proposed split item must include:
+- Suggested change name
+- Goals and scope boundaries
+- Explicit non-goals
+- Dependencies or recommended execution order
+- Core acceptance scenarios
+
+Recommend splitting when any condition applies:
+- The PRD contains multiple capabilities that can be independently designed, built, verified, and archived
+- Multiple modules or user journeys are involved, and part of them can be delivered independently
+- Clear phased milestones exist
+- The work is expected to produce multiple delta specs or more than 3 large tasks
+- Failure or delay in one part should not block other parts from entering later phases
+
+When splitting is recommended, must use the current platform's available user input/confirmation mechanism to pause and wait for the user's choice. If the current platform has no structured question tool, ask an equivalent single-select question in the conversation, stop the workflow, and wait for the user's reply before continuing.
+
+The user choices must include:
+- "Create multiple OpenSpec changes" — create independent changes from the proposed split
+- "Keep everything as one change" — continue the single-change flow and record the reason for not splitting in proposal/design/tasks
+- "Adjust the split plan before continuing" — after the user describes the adjustment, output the revised proposed split list and ask for confirmation again
+
+Every accepted split item must be created as an independent change through `/comet-open`, not by calling `/opsx:new` directly. `/comet-open` creates both OpenSpec artifacts and `.comet.yaml`, ensuring each change enters the Comet state machine.
+
+Must not create proposal.md, design.md, or tasks.md before the user completes the PRD split choice. If the user chooses to create multiple changes, the current `/comet-open` invocation only completes split confirmation and coordination, then enters `/comet-open` for each split item in the user-confirmed order.
+
+In batch split mode, entering `/comet-open` for each split item must explicitly mark it as a "confirmed split item" and carry that split item's goals, scope, non-goals, and acceptance scenarios. Confirmed split items skip the PRD split preflight by default, unless the split item itself still clearly contains multiple independent capabilities.
+
+In batch split mode, a single split item must not auto-advance to `/comet-design` after completing the open phase. After splitting is complete, must pause and ask the user which change to start; after the user chooses, advance only that change into `/comet-design`, while other changes remain active and can be resumed later through `/comet`.
+
+Minimal resume rule: do not add a dedicated batch state file. On resume, first check already-created active changes; split items that already exist and contain `.comet.yaml` must not be created again, while uncreated split items continue through `/comet-open` according to the user-confirmed split list. If the confirmed split list cannot be recovered from the conversation, must ask the user to confirm the split list again before continuing.
+
+### 1b. Requirements Clarification Completion Confirmation (Blocking Point)
+
+Before creating OpenSpec artifacts, must use the current platform's available user input/confirmation mechanism to pause and wait for the user to confirm requirements clarification is complete. If the current platform has no structured question tool, present the clarification summary in the conversation, ask a confirmation question, stop the workflow, and wait for the user's reply before continuing.
+
+When pausing, present the clarification summary: goals, non-goals, scope boundaries, key unknowns, and draft acceptance scenarios.
+
+Must not create proposal.md, design.md, or tasks.md before the user confirms requirements clarification is complete, and must not use the Skill tool to load the `openspec-propose` skill to generate all artifacts in one pass.
 
 ### 2. Create Change Structure + Initialize State
 
-**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. If the user's intent is unclear and needs proposal formation first, load `openspec-propose` instead. Skipping this step is prohibited.
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
+
+Full `/comet` workflow must not use the Skill tool to load the `openspec-propose` skill by default; only load it when the user explicitly requests generating the proposal and artifacts in one pass.
+
+After the skill loads, follow its guidance to create the change skeleton, but override its "STOP and wait for user direction" behavior when a confirmed clarification summary from Step 1b is already available in the conversation context. Specifically:
+
+1. Run `openspec new change`, `openspec status`, and `openspec instructions` as the skill directs
+2. If the user has already confirmed a clarification summary (Step 1b), use that summary directly to draft proposal.md — do NOT ask the user to describe the change again
+3. If no clarification summary exists (edge case), fall back to the skill's default behavior of asking the user
 
-**Naming and scope guard**: Change name must use a user-specified or AskUserQuestion-confirmed name — must not auto-generate or infer. Change scope must match the user's description — must not expand or narrow it independently.
+Then fill in design.md and tasks.md one by one; every document must be based on the confirmed clarification summary.
+
+**Naming and scope guard**: Change name must use a user-specified name or a name confirmed through the current platform's available user input/confirmation mechanism — must not auto-generate or infer. Change scope must match the user's description — must not expand or narrow it independently.
 
 Confirm the following artifacts have been created:
 
@@ -49,7 +113,7 @@ if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
   return 1
 fi
 
-bash "$COMET_STATE" init <name> full
+"$COMET_BASH" "$COMET_STATE" init <name> full
 ```
 
 ### 3. Entry State Verification
@@ -57,7 +121,7 @@ bash "$COMET_STATE" init <name> full
 Verify state machine has been correctly initialized:
 
 ```bash
-bash "$COMET_STATE" check <name> open
+"$COMET_BASH" "$COMET_STATE" check <name> open
 ```
 
 Proceed to Step 4 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -75,9 +139,9 @@ Confirm the three documents have complete content:
 
 ### 5. User Review and Confirmation (Blocking Point)
 
-After the three documents are created and content completeness check passes, **must use the AskUserQuestion tool to pause and wait for user confirmation**. Must not execute phase guard or auto-transition before user confirmation.
+After the three documents are created and content completeness check passes, **must use the current platform's available user input/confirmation mechanism to pause and wait for user confirmation**. Must not execute phase guard or auto-transition before user confirmation. If the current platform has no structured question tool, ask an equivalent single-select question in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
-AskUserQuestion must be presented as a single-select question with the following summary and options:
+The user confirmation question must be presented as a single-select question with the following summary and options:
 
 **Summary content**:
 - **proposal.md**: problem background, goals, scope
@@ -88,26 +152,35 @@ AskUserQuestion must be presented as a single-select question with the following
 - "Confirm, proceed to next phase" — artifacts meet expectations, execute phase guard transition
 - "Needs adjustment" — include adjustment notes, modify and re-request confirmation
 
-After user selects "Confirm", proceed to exit conditions. When user selects "Needs adjustment", modify the corresponding files per their notes, then re-use AskUserQuestion to request confirmation.
+After user selects "Confirm", proceed to exit conditions. When user selects "Needs adjustment", modify the corresponding files per their notes, then request confirmation again.
 
 ## Exit Conditions
 
 - proposal.md, design.md, tasks.md all created with complete content
 - **User has confirmed** proposal, design, tasks content meets expectations
-- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
+- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
 
 Must use `--apply` before exit, otherwise `.comet.yaml` remains at `phase: open` and the next phase entry check will fail.
 
 ```bash
-bash "$COMET_GUARD" <change-name> open --apply
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
 ```
 
 Full workflow auto-transitions to `phase: design`; hotfix/tweak presets auto-transition to `phase: build`.
 
-## Automatic Transition
+## Automatic Handoff to Next Phase
+
+> **Terminology distinction**: the "phase advancement" above is performed by guard `--apply`, which updates the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. This section's "automatic handoff" only controls whether to automatically invoke the next skill.
+
+After user confirmation and guard-based phase advancement, run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
 
-After user confirmation and exit conditions are met, auto-transition to next phase:
+The script determines the next action from `phase`, `workflow`, and `auto_transition`:
+- `NEXT: auto` -> invoke the `SKILL` target to continue to the next phase
+- `NEXT: manual` -> do not invoke the next skill; follow `HINT` and ask the user to run `/<SKILL>` manually
+- `NEXT: done` -> workflow is complete; no further action needed
 
-> **REQUIRED NEXT SKILL (full workflow):** Invoke `comet-design` skill to enter the deep design phase.
->
-> Hotfix/tweak presets are controlled by their corresponding preset skill for subsequent transitions (phase goes directly to build), and do not go through this section.
+Hotfix/tweak presets are controlled by their preset skills (phase goes directly to build), and their `next` output points to the preset path.