@rpamis/comet 0.2.9 → 0.3.1

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

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

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

@@ -16,9 +16,9 @@ Quick bug fix workflow: open → build → verify → archive. Skip brainstormin
 
 ---
 
-## Process (preset workflow, 4 phases)
+## Process (preset workflow, 5 steps)
 
-Execution chain: open → build → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, scale-based verification, archive after verification passes.
+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.
 
 Locate Comet scripts before starting:
 
@@ -47,6 +47,12 @@ Initialize Comet state file:
 bash "$COMET_STATE" init <name> hotfix
 ```
 
+Verify initialized state:
+
+```bash
+bash "$COMET_STATE" check <name> open
+```
+
 Run phase guard to transition open → build:
 
 ```bash
@@ -57,6 +63,8 @@ bash "$COMET_GUARD" <change-name> open --apply
 
 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).
 
+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".
+
 **Immediately execute:** Execute tasks one by one according to tasks.md:
 
 1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list
@@ -67,33 +75,34 @@ Use hotfix defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and
    - Check corresponding `- [ ]` to `- [x]` in tasks.md
    - Commit code, commit message format: `fix: <brief fix description>`
 3. After all tasks complete, explicitly run relevant project tests and build commands
-4. Run phase guard to transition build → verify:
-
-```bash
-bash "$COMET_GUARD" <change-name> build --apply
-```
-
-State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
 
 **If fix affects existing spec acceptance scenarios**:
 - Create delta spec in `openspec/changes/<name>/specs/<capability>/spec.md`
 - Only include `## MODIFIED Requirements` section
 
-### 3a. Hotfix-Exclusive Check: Root Cause Elimination
+### 3. Root Cause Elimination Check
 
-**Execute before loading comet-verify**, ensuring the fix actually eliminates the root cause:
+**Execute before running build guard**, ensuring the fix actually eliminates the root cause:
 
 1. Read bug description and root cause in proposal.md
 2. Search and verify problem code no longer exists
-3. If root cause not eliminated, return to Step 2 to continue fix
+3. If root cause not eliminated, return to Step 2 to continue fix (still in build phase, no state transition needed)
 
 **Upgrade conditions**:
-- Root cause check reveals deep architecture issues → Stop hotfix, upgrade to `/comet`
-- Fix requires additional interface changes → Stop hotfix, upgrade to `/comet`
+- Root cause check reveals deep architecture issues → Stop hotfix, handle per "Upgrade Conditions" section
+- Fix requires additional interface changes → Stop hotfix, handle per "Upgrade Conditions" section
+
+After root cause is confirmed eliminated, run phase guard to transition build → verify:
 
-### 3b. Verification (preset verify)
+```bash
+bash "$COMET_GUARD" <change-name> build --apply
+```
+
+State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
+
+### 4. Verification (preset verify)
 
-After root cause elimination check passes, reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight or full verification.
+Reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight or full verification.
 
 **Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
 
@@ -101,7 +110,7 @@ Small-scale hotfixes without delta spec usually meet lightweight verification co
 
 After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
 
-### 4. Archive (preset archive)
+### 5. Archive (preset archive)
 
 Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving.
 
@@ -113,11 +122,15 @@ 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 complete all 4 phases, without pausing to wait for user input mid-way (unless encountering upgrade conditions requiring 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. But the following situations must pause and wait for user confirmation:
 
-Execution order: quick open → direct build → verification → archive → complete
+1. Encountering upgrade conditions (see "Upgrade Conditions" section)
+2. When tasks exceed 3 and transfer to `/comet-build` for workspace isolation and execution method selection
+3. Verification phase (comet-verify) verification failure decision and branch handling decision
 
-After each phase completes, immediately enter next phase, no need for user input again. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements.
+Execution order: quick open → direct build → root cause check → verification → archive → complete
+
+After each step completes, immediately enter next step. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements; if the called skill has its own user decision points, follow that skill's rules.
 </IMPORTANT>
 
 ---
@@ -134,7 +147,15 @@ 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 |
 
-Upgrade method: On current change basis, supplement Design Doc (execute `/comet-design`), then proceed normally with full workflow.
+When upgrade conditions are met, must pause and wait for user to explicitly confirm upgrade to full `/comet` workflow. Must not directly enter `/comet-design`, must not automatically supplement Design Doc.
+
+After user confirms upgrade, **must first update the workflow field** before entering full flow:
+
+```bash
+bash "$COMET_STATE" set <name> workflow full
+```
+
+Then on current change basis, supplement Design Doc: **immediately use Skill tool to load `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.
 
 ---
 

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

@@ -1,40 +1,25 @@
 ---
 name: comet-open
-description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas through OpenSpec and create change structure (proposal + design + tasks)."
+description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas through OpenSpec, create change structure (proposal + design + tasks)."
 ---
 
 # Comet Phase 1: Open
 
 ## Prerequisites
 
-- No active change, or user wishes to create a new change
+- No active change, or user wants to create a new change
 
 ## Steps
 
-### 0. Locate Comet Scripts
-
-Locate scripts before creating state:
-
-```bash
-COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
-COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
-COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
-
-if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
-  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
-  return 1
-fi
-```
-
-### 1. Explore Idea
+### 1. Explore Ideas
 
 **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.
 
-### 2. Create Change Structure
+### 2. Create Change Structure + Initialize State
 
-**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. If user intent is unclear and needs to form a proposal first, load `openspec-propose` instead. Skipping this step is prohibited.
+**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.
 
 Confirm the following artifacts have been created:
 
@@ -43,40 +28,59 @@ openspec/changes/<name>/
 ├── .openspec.yaml
 ├── .comet.yaml
 ├── proposal.md       # Why + What: problem, goals, scope
-├── design.md         # How (high-level): architectural decisions, solution selection
+├── design.md         # How (high-level): architecture decisions, approach selection
 └── tasks.md          # Task checklist (checkboxes)
 ```
 
-### 3. Initialize Comet State
-
-Initialize Comet state file:
+Create `.comet.yaml` state file:
 
 ```bash
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
+
+if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
+  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+
 bash "$COMET_STATE" init <name> full
 ```
 
+### 3. Entry State Verification
+
+Verify state machine has been correctly initialized:
+
+```bash
+bash "$COMET_STATE" check <name> open
+```
+
+Proceed to Step 4 after verification passes. The script outputs specific failure reasons when verification fails.
+
 ### 4. Content Completeness Check
 
 Confirm the three documents have complete content:
 - **proposal.md**: problem background, goals, scope, non-goals
-- **design.md**: high-level architectural decisions, solution selection, data flow
+- **design.md**: high-level architecture decisions, approach selection, data flow
 - **tasks.md**: task list, each task has a clear description
 
 ## Exit Conditions
 
-- proposal.md, design.md, and tasks.md are all created with complete content
-- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> open --apply`; after all PASS, state automatically advances to the next phase
+- proposal.md, design.md, tasks.md all created with complete content
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
 
-You must use `--apply` before exiting. Otherwise `.comet.yaml` stays at `phase: open`, and the next phase entry check will fail.
+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
 ```
 
-Full workflow advances to `phase: design`; hotfix/tweak presets advance to `phase: build`.
+Full workflow auto-transitions to `phase: design`; hotfix/tweak presets auto-transition to `phase: build`.
 
 ## Automatic Transition
 
 After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
 
-> **REQUIRED NEXT SKILL:** Invoke `comet-design` skill to enter the deep design phase.
+> **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.

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

@@ -5,17 +5,17 @@ description: "Comet preset path: Non-bug small changes (tweak). Skip brainstormi
 
 # Comet Preset Path: Tweak
 
-Tweak is a preset workflow of Comet's five-phase capabilities, not a separate parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.
+Tweak is a preset workflow of Comet's five-phase capabilities, not an independent parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.
 
-Applicable for small-scale non-bug changes, such as copy adjustments, configuration adjustments, documentation or prompt local optimization.
+Applicable for non-bug small scope changes, such as copy adjustment, configuration adjustment, documentation or prompt local optimization.
 
 **Applicable conditions** (all must be met):
 1. No new capability
 2. No architecture changes
-3. No interface changes involved
-4. Usually not exceeding 3 tasks, 4 files
+3. No interface changes
+4. Typically no more than 3 tasks, 4 files
 
-**Not applicable**: If change process discovers need for capability, architecture, or interface adjustments, should upgrade to full `/comet` workflow.
+**Not applicable**: If change process discovers need for capability, architecture or interface adjustments, should upgrade to full `/comet` workflow.
 
 ---
 
@@ -41,8 +41,8 @@ Reuse Comet open capability to create change, but use tweak defaults: do not exe
 After the skill loads, follow its guidance to create streamlined artifacts:
   - `proposal.md` — change motivation + goals + scope
   - `design.md` — brief implementation description (no solution comparison needed)
-  - `tasks.md` — not exceeding 3 tasks
-- **No delta spec needed** (unless change changes existing spec acceptance scenarios; once delta spec needed, upgrade to full `/comet`)
+  - `tasks.md` — no more than 3 tasks
+- **No delta spec needed** (unless change modifies existing spec acceptance scenarios; once delta spec is needed, upgrade to full `/comet`)
 
 Initialize Comet state file:
 
@@ -50,6 +50,12 @@ Initialize Comet state file:
 bash "$COMET_STATE" init <name> tweak
 ```
 
+Verify initialized state:
+
+```bash
+bash "$COMET_STATE" check <name> open
+```
+
 Run phase guard to transition open → build:
 
 ```bash
@@ -60,11 +66,13 @@ bash "$COMET_GUARD" <change-name> open --apply
 
 Use tweak defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans`.
 
+Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows scope exceeds tweak, handle it through this file's "Upgrade Conditions".
+
 **Immediately execute:** Execute tasks one by one according to tasks.md:
 
 1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list
 2. For each incomplete task:
-   - Modify target file according to task description
+   - Modify target files according to task description
    - Run project formatter (e.g., `mvn spotless:apply`, `npm run format`)
    - Run related tests to confirm pass
    - Check corresponding `- [ ]` to `- [x]` in tasks.md
@@ -84,7 +92,7 @@ Reuse `/comet-verify`. Tweak must maintain lightweight verification conditions:
 
 **Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
 
-If scale assessment enters full verification path, stop tweak, upgrade to full `/comet`.
+If scale assessment enters full verification path, stop tweak, handle per upgrade conditions blocking confirmation.
 
 After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
 
@@ -99,11 +107,14 @@ Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` befo
 ## Continuous Execution Mode
 
 <IMPORTANT>
-Tweak workflow is **one-time continuous execution**. After invoking `/comet-tweak`, agent must automatically complete all 4 phases, without pausing to wait for user input mid-way (unless encountering upgrade conditions requiring user confirmation).
+Tweak workflow is **one-time continuous execution**. After invoking `/comet-tweak`, agent must automatically advance through tweak steps, without pausing to wait for user input mid-way. But the following situations must pause and wait for user confirmation:
+
+1. Encountering upgrade conditions (see "Upgrade Conditions" section)
+2. Verification phase (comet-verify) verification failure decision and branch handling decision
 
 Execution order: quick open → lightweight build → lightweight verification → archive → complete
 
-After each phase completes, immediately enter next phase, no need for user input again. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements.
+After each phase completes, immediately enter next phase. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements; if the called skill has its own user decision points, follow that skill's rules.
 </IMPORTANT>
 
 ---
@@ -115,13 +126,21 @@ Upgrade to full `/comet` when **any** of the following conditions are met:
 | Condition | Explanation |
 |-----------|-------------|
 | Change involves **5+ files** | Exceeds small change scope |
-| Cross-module coordination required | Needs coordination across components |
-| **5+** new test cases needed | Change complexity increasing |
-| Config item additions or deletions | Non-value config changes |
+| Cross-module coordination required | Requires cross-component coordination |
+| **5+** new test cases needed | Change complexity rising |
+| Config item additions or deletions | Config changes beyond value modifications |
 | New capability needed | Exceeds local optimization |
-| Delta spec needed | Affects existing specifications |
+| Delta spec needed | Affects existing specs |
+
+When upgrade conditions are met, must pause and wait for user to explicitly confirm upgrade to full `/comet` workflow. Must not directly enter `/comet-design`, must not automatically supplement Design Doc.
+
+After user confirms upgrade, **must first update the workflow field** before entering full flow:
+
+```bash
+bash "$COMET_STATE" set <name> workflow full
+```
 
-Upgrade method: On current change basis, supplement Design Doc (execute `/comet-design`), then proceed normally with full workflow.
+Then on current change basis, supplement Design Doc: **immediately use Skill tool to load `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop tweak and report that current change has exceeded tweak scope.
 
 ---
 
@@ -129,5 +148,5 @@ Upgrade method: On current change basis, supplement Design Doc (execute `/comet-
 
 - Small change completed, tests pass
 - Change archived
-- No new capability, architecture adjustments, or interface changes
+- No new capability, architecture adjustments or interface changes
 - **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`