@rpamis/comet 0.3.6 → 0.3.7

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

@@ -1,6 +1,6 @@
 ---
 name: comet-archive
-description: "Comet Phase 5: Archive. Invoke with /comet-archive. Sync delta spec to main spec, archive change."
+description: "Comet Phase 5: Archive. Invoke with /comet-archive. Merge delta specs into main specs with OpenSpec semantics, archive change."
 ---
 
 # Comet Phase 5: Archive (Archive)
@@ -13,6 +13,10 @@ description: "Comet Phase 5: Archive. Invoke with /comet-archive. Sync delta spe
 
 ## Steps
 
+### 0. Output Language Constraint
+
+Archive summaries and lifecycle closure notes must use the language of the user request that triggered this workflow.
+
 ### 0. Entry State Verification (Entry Check)
 
 Execute entry verification:
@@ -29,7 +33,24 @@ fi
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
-### 1. Execute Archive
+### 1. Final Archive Confirmation (Blocking Point)
+
+After entry verification passes, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to confirm whether to archive immediately**. Must not run `"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"` 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.
+
+Before confirmation, show the user a brief summary:
+- Change name
+- Verification report path and result
+- Branch handling status
+- Irreversible actions this archive will perform: merge main specs with OpenSpec delta semantics, annotate design doc / plan, and move the change to the archive directory
+
+The user confirmation question must be presented as a single-select question with these options:
+- "Confirm archive" — immediately run the archive script to complete spec merge and change movement
+- "Needs adjustment or re-verification" — do not archive; run `"$COMET_BASH" "$COMET_STATE" transition <change-name> archive-reopen` to return to `phase: verify`, then invoke `/comet-verify`. If verification confirms fixes are needed, follow `/comet-verify`'s verification-failure decision flow back to `/comet-build`
+- "Do not archive yet" — do not archive; keep the current `phase: archive` state and wait for the user to invoke `/comet-archive` again later
+
+Only after the user selects "Confirm archive" may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually.
+
+### 2. Execute Archive
 
 Run the archive script to automatically complete all steps:
 
@@ -39,25 +60,25 @@ Run the archive script to automatically complete all steps:
 
 The script automatically executes:
 1. Entry state validation (phase=archive, verify_result=pass, archived=false)
-2. Delta spec sync to main spec (overwrite)
-3. Design doc frontmatter annotation (archived-with, status)
-4. Plan frontmatter annotation (archived-with)
-5. Move change to archive directory
+2. Design doc frontmatter annotation (archived-with, status)
+3. Plan frontmatter annotation (archived-with)
+4. OpenSpec archive for delta-merge semantics and moving the change to the archive directory
+5. Main spec guard against leaked delta-only section headings
 6. Update `archived: true` through `comet-state transition <archive-name> archived`
 
 If script returns non-zero exit code, report error and stop.
 If script returns zero exit code, archive is complete.
 The summary `X/Y steps succeeded` counts real executed steps and does not double-count delta spec sync or document annotation.
 
-When a delta spec differs from an existing main spec, the script prints a unified diff preview before overwrite to help confirm archive sync content.
+The script calls OpenSpec archive to merge `ADDED/MODIFIED/REMOVED/RENAMED` delta semantics into main specs, then verifies main specs do not contain delta-only section headings.
 
 Use `--dry-run` flag to preview without executing.
 
-### 2. Lifecycle Closed Loop
+### 3. Lifecycle Closed Loop
 
 Spec lifecycle completes here:
 ```
-brainstorming → delta spec → implementation → verification → main spec overwrite → design doc annotation → archive
+brainstorming → delta spec → implementation → verification → main spec merge → design doc annotation → archive
 ```
 
 ## Exit Conditions
@@ -66,8 +87,20 @@ brainstorming → delta spec → implementation → verification → main spec o
 - Archive directory `openspec/changes/archive/YYYY-MM-DD-<change-name>/` exists
 - Archived `.comet.yaml` contains `archived: true`
 
-The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After successful archive, **do not run** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Archive completeness is determined by script exit code and archived directory state.
+The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
+
+> **WARNING**: After successful archive, **do not run** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Doing so will cause the guard to error with "change directory not found". Archive completeness is determined by script exit code and archived directory state.
 
 ## Complete
 
 Comet workflow complete. To start new work, invoke `/comet` or `/comet-open`.
+
+## Context Compaction Recovery
+
+The archive phase may trigger context compaction during execution. On resume, first run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <change-name> archive --recover
+```
+
+The script outputs structured recovery context (archive status, completed steps). Follow the Recovery action to determine next steps. If `archived: true` and the archive directory exists, archiving is already complete — no need to run the archive operation again.

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

@@ -28,13 +28,22 @@ fi
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
-**Idempotency**: All build phase operations can be safely re-executed. Read `.comet.yaml` `phase` field to confirm still in build, read plan header `base-ref`, then read tasks.md to find the first unchecked task. Already-committed tasks must not be re-committed.
+**Idempotency**: All build phase operations can be safely re-executed. Read `.comet.yaml` `phase` field to confirm still in build, read plan header `base-ref`, then use `grep -n '\- \[ \]' tasks.md | head -1` to find the first unchecked task. Already-committed tasks must not be re-committed.
 
-### 1. Create Plan
+### 1. Create Plan (Subagent Offload)
 
-**Immediately execute:** Use the Skill tool to load the Superpowers `writing-plans` skill. Skipping this step is prohibited.
+Create the implementation plan through a subagent, avoiding planning skill occupying main session context. Plan files and execution feedback must use the language of the user request that triggered this workflow.
 
-After the skill loads, follow its guidance to create a plan. Plan requirements:
+**Subagent instructions**:
+
+You are an implementation planning expert. Create an implementation plan based on the following inputs:
+
+1. **Immediately execute:** Use the Skill tool to load the Superpowers `writing-plans` skill. Skipping this step is prohibited. After the skill loads, ARGUMENTS must include: `Language: Use the language of the user request that triggered this workflow`
+2. Read the Design Doc (technical design document under `docs/superpowers/specs/`)
+3. Read `openspec/changes/<name>/tasks.md` (task boundaries)
+4. Follow the skill's guidance to create the plan
+
+Plan requirements:
 - Save to `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
 - Reference design document, break down into executable tasks
 - **Plan file header must contain associated metadata**:
@@ -53,6 +62,14 @@ base-ref: <git rev-parse HEAD before implementation>
 git rev-parse HEAD
 ```
 
+Write the plan to file, then return the file path.
+
+**Execute subagent**: Use the current platform's subagent dispatch mechanism to send the above task.
+
+After the subagent completes:
+- If a valid file path is returned and the file exists, record it as the plan
+- If the subagent fails or returns an invalid path, fall back to loading the Superpowers `writing-plans` skill inline in the main session (degraded fallback)
+
 ### 2. Update Plan Status and Provide Plan-Ready Pause Point
 
 Record plan path:
@@ -70,7 +87,7 @@ After the plan is recorded, immediately provide a new user decision point:
 | A | Continue execution | Stay in the current model and proceed to Step 3 to choose workspace isolation and execution method |
 | B | Pause to switch model | Record `build_pause: plan-ready`, stop this `/comet-build` invocation, and allow the user to resume later from `/comet` or `/comet-build` |
 
-This is a user decision point. **Must use the AskUserQuestion tool to pause and wait for the user to explicitly choose**. Must not auto-continue and must not write the pause into `build_mode`.
+This is a user decision point. **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly choose**. Must not auto-continue and must not write the pause into `build_mode`. If the current platform has no structured question tool, ask equivalent options in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
 When the user chooses to continue:
 
@@ -121,17 +138,33 @@ Plan has been written to the current branch. Before starting execution, **ask th
 - Task count ≤ 2 and no cross-module dependencies → Recommend B
 - From hotfix path → Recommend B
 
-This is a user decision point. **Must use the AskUserQuestion tool to pause and wait for the user to explicitly choose both isolation method and execution method**. Must not choose `branch` or `worktree` based on recommendation rules, and must not choose the execution method based on recommendation rules. Recommendation rules are for suggestion only, not a substitute for user confirmation. Must not just output a text prompt and then continue executing.
+This is a user decision point. **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly choose isolation method, execution method, and TDD mode**. Must not choose `branch` or `worktree` based on recommendation rules, and must not choose the execution method or TDD mode based on recommendation rules. Recommendation rules are for suggestion only, not a substitute for user confirmation. If the current platform has no structured question tool, ask equivalent options in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
-After user selection, update `isolation` and `build_mode` fields:
+After user selection, update `isolation`, execution method, and TDD mode fields:
 
 ```bash
 "$COMET_BASH" "$COMET_STATE" set <name> isolation <branch|worktree>
-"$COMET_BASH" "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
 ```
 
+- If the user chooses `executing-plans`: run `"$COMET_BASH" "$COMET_STATE" set <name> subagent_dispatch null`, then run `"$COMET_BASH" "$COMET_STATE" set <name> build_mode executing-plans`
+- If the user chooses `subagent-driven-development`: first confirm the current platform has real background subagent / Task / multi-agent dispatch capability; after confirming, run `"$COMET_BASH" "$COMET_STATE" set <name> subagent_dispatch confirmed`, then run `"$COMET_BASH" "$COMET_STATE" set <name> build_mode subagent-driven-development`
+- If real background dispatch capability cannot be confirmed, must not write `build_mode: subagent-driven-development`; must pause and wait for the user to choose `executing-plans` instead
+
+**TDD Mode**:
+
+| Option | Meaning | Applicable Scenario |
+|--------|---------|---------------------|
+| `tdd` | Write a failing test first for each task, then implement | Recommended. Changes involving business logic, new features, APIs |
+| `direct` | Implement directly, no enforced TDD flow | Changes that don't need test coverage, or user chooses to skip tests and write code directly. hotfix/tweak presets default to `direct` |
+
+Run `"$COMET_BASH" "$COMET_STATE" set <name> tdd_mode <tdd|direct>`
+
 `isolation` is a script-enforced hard constraint. Full workflow init may temporarily leave it as `null`, but only before this step. If it remains `null`, both the `build → verify` guard and `comet-state transition build-complete` will fail.
 
+`subagent_dispatch` is a script-enforced hard constraint. `build_mode: subagent-driven-development` requires `subagent_dispatch: confirmed` before leaving the build phase, otherwise both `comet-guard.sh build --apply` and `comet-state transition build-complete` will fail.
+
+`tdd_mode` is a script-enforced hard constraint. Full workflow must have `tdd_mode` selected as `tdd` or `direct` before leaving the build phase, otherwise both `comet-guard.sh build --apply` and `comet-state transition build-complete` will fail.
+
 `build_mode` defaults to `direct` only for hotfix/tweak presets. Full workflow must not default to `direct`. Use it only when the user explicitly asks to bypass the plan execution skills and you record an explicit override:
 
 ```bash
@@ -143,20 +176,67 @@ Without `direct_override: true`, `build_mode=direct` in full workflow is blocked
 
 **Execute isolation**:
 
-- **branch**: Run `git checkout -b <change-name>`, subsequent work on the new branch
+- **branch**: Recommend a branch name based on the workflow type and current date, then let the user confirm or input a custom name. This is a user decision point — **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm or override the branch name**. Must not skip this step and create the branch directly.
+
+  Branch naming convention:
+  - Read the `workflow` field from `.comet.yaml` to determine the prefix
+  - `workflow: full` → recommend `feature/YYYYMMDD/<change-name>`
+  - `workflow: hotfix` → recommend `hotfix/YYYYMMDD/<change-name>`
+  - `workflow: tweak` → recommend `tweak/YYYYMMDD/<change-name>`
+  - Date is derived from `date +%Y%m%d` at runtime
+
+  Example: if change name is `fix-login-bug` and today is 2026-06-09, recommend `feature/20260609/fix-login-bug`
+
+  After the user confirms or provides a custom branch name, run `git checkout -b <branch-name>`, subsequent work on the new branch.
+
 - **worktree**: Must use the Skill tool to load the Superpowers `using-git-worktrees` skill to create isolated workspace. Do not bypass this skill with plain shell commands or native tools; if the skill is unavailable, stop the process and prompt to install or enable Superpowers skills.
 
-After creating isolation, confirm plan file is accessible (naturally accessible with branch method; for worktree method, confirm plan has been committed).
+After creating isolation, confirm plan file is accessible (naturally accessible with branch method; for worktree method, confirm plan has been committed). If the plan file has not been committed under worktree mode, commit it first before creating the worktree:
 
-**Load execution skill**: Use the Skill tool to load the corresponding skill. Skipping this step is prohibited.
+```bash
+git add docs/superpowers/plans/YYYY-MM-DD-feature.md
+git commit -m "chore: add implementation plan"
+```
+
+**Execute plan**: Must handle execution according to the actual runtime of `build_mode`.
 
-If the selected Superpowers skill is unavailable, stop the process and prompt to install or enable the corresponding skill. Do not substitute this step with normal conversation.
+- `build_mode: executing-plans`: **Immediately execute:** Use the Skill tool to load the Superpowers `executing-plans` skill. Skipping this step is prohibited. If the skill is unavailable, stop the process and prompt to install or enable the corresponding skill; do not substitute with normal conversation. After the skill loads, ARGUMENTS must include the same Language constraint as Step 1: `Language: Use the language of the user request that triggered this workflow`. Execute according to plan.
+- `build_mode: subagent-driven-development`: The main window only coordinates; must not run `subagent-driven-development` as the main window execution skill directly. Must use the confirmed real background subagent / Task / multi-agent dispatch capability to dispatch the next unchecked task to a background subagent. When dispatching each subagent, the prompt must explicitly require: after the skill loads, ARGUMENTS must include the same Language constraint as Step 1: `Language: Use the language of the user request that triggered this workflow`; after the task is complete and validated, immediately check off the corresponding plan task in `docs/superpowers/plans/<plan-file>.md`; if that plan task maps to an item in `openspec/changes/<name>/tasks.md`, also change that OpenSpec task from `- [ ]` to `- [x]`; if the plan added a step that does not exist in OpenSpec, only the corresponding plan task needs to be checked off. Do not only update the built-in Todo or an in-chat checklist. The background subagent loads the Superpowers `subagent-driven-development` execution flow on its own and follows its guidance for implementation, review, and commit.
+- If the current platform has no real background subagent / Task / multi-agent dispatch capability, must pause and wait for the user to choose main window execution instead. After the user chooses, must run `"$COMET_BASH" "$COMET_STATE" set <name> build_mode executing-plans`, then follow the `build_mode: executing-plans` branch to load the Superpowers `executing-plans` skill. Must not continue executing tasks before the user explicitly chooses.
 
-After the skill loads, follow its guidance to execute:
+After execution begins, follow the chosen branch to completion:
 - Execute tasks according to plan
-- Complete tasks.md check (`- [ ]` → `- [x]`)
+- Check off the corresponding Superpowers plan task; if the task maps to OpenSpec tasks.md, also check off the corresponding OpenSpec task (`- [ ]` → `- [x]`)
 - Commit code after each task completion
 
+**TDD Mode Execution Constraints**:
+
+If `tdd_mode: tdd`:
+- `build_mode: executing-plans`: After loading the execution skill and before executing the first task, **Immediately execute:** Use the Skill tool to load the Superpowers `test-driven-development` skill once. Skipping this step is prohibited. After the skill loads, start from the first unchecked task and follow the loaded TDD Red-Green-Refactor cycle for each task. Must not skip the failing test verification phase. Do not reload this skill for subsequent tasks; follow the already-loaded flow. If resuming after context compaction, re-run this step to load the TDD skill once, then continue from the first unchecked task.
+- `build_mode: subagent-driven-development`: When dispatching each subagent, must inject the TDD hard constraint into the prompt: **"You MUST follow TDD: for each task, write a failing test first, watch it fail, then write minimal code to pass. No production code without a failing test first."**. The same prompt must also include the OpenSpec tasks.md and Superpowers plan persistent check-off requirement above. Must not rely on implementer-prompt.md's conditional trigger; must explicitly write it in the dispatch prompt.
+
+If `tdd_mode: direct`: Follow normal flow, no enforced TDD.
+
+**`executing-plans` review gate**:
+
+When `build_mode` is `executing-plans`, after all planned tasks are complete and before running the build → verify phase guard, must use the Skill tool to load the Superpowers `requesting-code-review` skill and request code review at least once.
+
+Requirements:
+- the `requesting-code-review` skill must be loaded before `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`
+- if `requesting-code-review` skill is unavailable, skip the review gate but must record `<!-- review skipped: skill unavailable -->` in tasks.md, then continue guard transition
+- CRITICAL review findings (security vulnerabilities, data loss risk, build/test failures) must be fixed first and must not be carried into verify
+- if non-CRITICAL review findings are accepted, record the acceptance reason and impact scope in tasks.md, the commit body, a verification report draft, or another durable artifact
+
+### 3b. In-Execution Debugging (Debug Gate)
+
+During task 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
+
 ### 4. Spec Incremental Updates
 
 When the initial spec is found incomplete during implementation, handle by scale:
@@ -164,13 +244,17 @@ When the initial spec is found incomplete during implementation, handle by scale
 | Scale | Trigger Conditions | Approach |
 |------|-------------------|----------|
 | Small | Missing acceptance scenarios, edge cases | Directly edit delta spec + design.md, append tasks.md tasks |
-| Medium | Interface changes, new components, data flow changes | **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm**, then must use Skill tool to load the Superpowers `brainstorming` skill to update Design Doc + delta spec |
-| Large | Brand-new capability requirements | **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm the split**; after user confirms, create independent change through `/comet-open` |
+| Medium | Interface changes, new components, data flow changes | **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm**, then must use Skill tool to load the Superpowers `brainstorming` skill to update Design Doc + delta spec |
+| Large | Brand-new capability requirements | **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm the split**; after user confirms, create independent change through `/comet-open` |
 
-**50% Threshold Determination**: Using initial task count in tasks.md as baseline, if new tasks exceed half of that total, it's considered outside original plan scope, **must use the AskUserQuestion tool to pause and wait for the user to decide whether to split into a new change**. Must not just output a text prompt and then continue executing.
+**50% Threshold Determination**: Using initial task count in tasks.md as baseline, if new tasks exceed half of that total, it's considered outside original plan scope, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to decide whether to split into a new change**. If the current platform has no structured question tool, ask split options in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
 When creating an independent change, must invoke `/comet-open`, not `/opsx:new` directly. `/comet-open` creates both OpenSpec artifacts and `.comet.yaml`, preventing the new change from leaving the Comet state machine.
 
+**User choices must include**:
+- "Split into new change" — create independent change via `/comet-open`
+- "Continue in current change" — record scope-expansion decision, update tasks.md and delta spec, then continue
+
 **Principles**:
 - Delta spec is a living document, can be modified at any time during this phase
 - Each update should be committed with commit message explaining the change reason
@@ -181,7 +265,7 @@ When creating an independent change, must invoke `/comet-open`, not `/opsx:new`
 
 Build is the longest phase and may span many tasks. To support resume after context compaction:
 
-- **After each task**: immediately check off tasks.md and commit code so `.comet.yaml` and file state are durable
+- **After each task**: immediately check off the corresponding task in the Superpowers plan; if the task maps to OpenSpec tasks.md, also check off the corresponding OpenSpec task; then commit code so `.comet.yaml` and file state are durable. Use `grep -c '\- \[ \]' tasks.md` to check remaining unchecked count; no need to re-read the entire file
 - **After context compaction**: first run `"$COMET_BASH" "$COMET_STATE" check <change-name> build --recover` — the script outputs structured recovery context (isolation/build_mode status, plan path, task progress, recovery action). Follow the Recovery action to determine next step.
 - **User manual-change resume**: handle uncommitted changes through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions. Build-specific handling:
   1. After attribution, if the diff implies plan or spec changes, handle it through Step 4 "Spec Incremental Updates"
@@ -193,7 +277,9 @@ Build is the longest phase and may span many tasks. To support resume after cont
 - Code committed
 - Project-specific build/tests explicitly run and pass; do not rely only on guard auto-detection
 - `isolation` has been written as `branch` or `worktree`
-- `build_mode` has been written as `subagent-driven-development`, `executing-plans`, or `direct` with explicit override
+- `build_mode` has been written as `subagent-driven-development`, `executing-plans`, or `direct` with explicit override; if `subagent-driven-development`, `subagent_dispatch` must be `confirmed`
+- `tdd_mode` has been written as `tdd` or `direct`
+- If `build_mode` is `executing-plans`, the Skill tool has been used to load the Superpowers `requesting-code-review` skill and request code review at least once, and CRITICAL review findings have been fixed or acceptance rationale for non-CRITICAL review findings has been recorded
 - **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
 
 Guard reads project command configuration first:
@@ -214,8 +300,17 @@ Before exit, run guard to auto-transition:
 
 State file is automatically updated to `phase: verify`, `verify_result: pending`.
 
-## Automatic Transition
+## Automatic Handoff to Next Phase
 
-After exit conditions are met (including user selecting workflow configuration), auto-transition 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 and guard-based phase advancement has completed, run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
 
-> **REQUIRED NEXT SKILL:** Invoke `comet-verify` skill to enter the verification and completion 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-design/SKILL.md

@@ -38,13 +38,22 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 "$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,6 +66,11 @@ 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
@@ -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 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,9 +145,75 @@ 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
@@ -138,7 +234,8 @@ 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 `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
@@ -159,8 +256,17 @@ The design phase may trigger context compaction during brainstorming. To 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