@kafka0102/onespec 0.1.2 → 0.2.2

package/assets/skills-en/onespec/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: onespec
-description: Use when the user wants to manage the full AI coding change lifecycle with OpenSpec and Superpowers, or is unsure whether they should be in design, execution, or archive.
+description: Use when the user wants to manage the full AI coding change lifecycle with OpenSpec and Superpowers, or is unsure whether they should be in design, execution, archive, or the fast path.
 ---
 
 # OneSpec Workflow
 
-OneSpec is a routing skill. It restores state, determines the current phase, and hands off to `onespec-design`, `onespec-execute`, or `onespec-archive`. Phase-specific rules live in the child skills.
+OneSpec is a single-entry workflow skill. Restore state, determine the current phase, then read the matching module under `references/`; do not call deprecated phase child skills.
 
 Announce at the start:
 
@@ -16,7 +16,7 @@ Announce at the start:
 Always check state before relying on chat history:
 
 ```bash
-ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
+ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.claude "$HOME"/.cursor "$HOME"/.gemini "$HOME"/.copilot "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
 . "$ONESPEC_ENV"
 "$ONESPEC_BASH" "$ONESPEC_STATE" list
 ```
@@ -28,30 +28,39 @@ If a relevant change exists, run:
 ```
 
 Runtime state lives in `openspec/changes/<change-id>/.onespec.yaml`. Handoff summary, hashes, and touched-file tracking all live there; keep it until archive, then delete it during archive cleanup.
-Treat `recover` output as the execution contract, not as a hint. Read at least `phase`, `next_skill`, `next_gate`, and `allowed_actions` before deciding what to do next.
+Treat `recover` output as the execution contract, not as a hint. Read at least `phase`, `next_skill`, `next_reference`, `next_gate`, and `allowed_actions` before deciding what to do next.
 
 ## Phase Routing
 
 Classify the current request first:
 
-- `propose`: define a new change, clarify scope, generate `proposal.md`, `design.md`, `tasks.md`, and spec deltas. Use `onespec-design`.
-- `apply`: implement an approved change, continue an existing change, generate or resume a Superpowers plan, and sync OpenSpec state. Use `onespec-execute`.
-- `review-closeout`: user review, feedback handling, worktree deletion, or archive. Use `onespec-archive`.
+- `propose`: define a new change, clarify scope, generate `proposal.md`, `design.md`, `tasks.md`, and spec deltas. Read `references/design.md`.
+- `apply`: implement an approved change, continue an existing change, generate or resume a Superpowers plan, and sync OpenSpec state. Read `references/execute.md`.
+- `review-closeout`: user review, feedback handling, worktree deletion, or archive. Read `references/archive.md`.
+- `fast`: the user explicitly asks for `onespec-fast`, the fast path, fast apply, automatic OpenSpec end-to-end execution, or automatic proposal/implementation/archive. Read `references/fast.md`; the standalone `onespec-fast` entrypoint also routes to this same reference.
 
 If intent is unclear, ask one short question only.
 
 Default intent mapping:
 
-- Requests like "new requirement", "design this", "write a proposal/spec", or "define a change" go to `onespec-design`.
-- Requests like "start implementation", "execute this change", "apply this proposal/change", "continue this change", "start coding/development", or "make plan" go to `onespec-execute`. If the proposal is not approved yet, `onespec-execute` must stop and send the flow back to the approval gate in `onespec-design`.
-- Requests like "review", "close out", "archive", or "delete the worktree" go to `onespec-archive`.
+- Requests like "new requirement", "design this", "write a proposal/spec", or "define a change" read `references/design.md`.
+- Requests like "start implementation", "execute this change", "apply this proposal/change", "continue this change", "start coding/development", or "make plan" read `references/execute.md`. If the proposal is not approved yet, stop and send the flow back to the approval gate in `references/design.md`.
+- Requests like "review", "close out", "archive", or "delete the worktree" read `references/archive.md`.
+- Requests like "onespec-fast", "fast path", "fast apply", "automatic OpenSpec end-to-end execution", or "automatic proposal/implementation/archive" read `references/fast.md`.
+
+## Reference Loading
+
+- Read only the one reference needed for the current phase; do not preload other phases.
+- If `recover` returns `next_reference`, read it by default. Override it only when the user explicitly changes phase and the previous phase gate is already complete.
+- `references/fast.md` may reuse procedure sections from `design.md`, `execute.md`, and `archive.md`, but the fast path overrides the normal proposal approval, review pause, and closeout-menu gates.
+- For cross-phase checks, read only the smallest section directly required by the gate.
 
 ## Shared Constraints
 
 - OpenSpec owns scope, formal artifacts, approval gates, spec deltas, and archive semantics.
 - Superpowers owns high-ambiguity clarification, implementation planning, TDD, per-task review, and execution quality.
 - Do not ask the user to name the change. Generate a short kebab-case `change-id` from the task and append a suffix if needed.
-- Read the minimum necessary context: `openspec/config.yaml`, `openspec/project.md`, relevant `openspec/specs/**`, project entry docs, and current branch/worktree state.
+- Read the minimum necessary context: `openspec/config.yaml`, relevant `openspec/specs/**`, project entry docs, and current branch/worktree state.
 - Only ask questions that can change the proposal, execution path, branch handling, or archive result.
-- If shared and phase-specific rules conflict, the child skill for the current phase wins.
-- If `recover` already points to a `next_skill`, resume there by default. Only override it when the user explicitly changes phase and the previous phase gate is already complete.
+- If shared and phase-specific rules conflict, the current phase reference wins.
+- Each phase reference defines mandatory pause gates, such as the approval gate in `references/design.md` and the implementation-complete gate in `references/execute.md`. Before routing to the next phase, confirm the previous gate is complete; if it is not, refuse to continue and name the missing gate.

package/assets/skills-en/onespec/references/archive.md

@@ -0,0 +1,213 @@
+# Archive Phase
+
+Read on demand from `onespec` during the `review-closeout` phase. The goal is to resolve the code fate of temporary worktrees and complete merge, discard, or archive actions according to the user's explicit closeout selection.
+
+## 1. Review Entry
+
+Recover state first:
+
+```bash
+ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.claude "$HOME"/.cursor "$HOME"/.gemini "$HOME"/.copilot "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
+. "$ONESPEC_ENV"
+"$ONESPEC_BASH" "$ONESPEC_STATE" list
+```
+
+If a relevant change exists, you must continue with:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
+```
+
+Treat `recover` output as the current phase contract, not as reference information. Read at least `phase`, `next_skill`, `next_reference`, `next_gate`, and `allowed_actions` before deciding whether to continue closeout-phase work.
+
+Read the minimum necessary context:
+
+- `openspec/changes/<change-id>/proposal.md`
+- `openspec/changes/<change-id>/tasks.md`
+- `openspec/changes/<change-id>/design.md`, if present
+- relevant `openspec/specs/**`
+- latest test results and `openspec validate <change-id> --strict` result
+- current branch, worktree, and workspace status
+- `origin_branch`, `origin_workspace_path`, and `origin_workspace_mode`
+
+If state has not reached `review`, explain what is still missing: implementation, verification, `tasks.md` sync, or proposal approval.
+
+Entry validation: if phase is already `review` but `.onespec.yaml` does not show `handoff_purpose: review` or does not have a `handoff_hash`, treat that as an incomplete execute gate. Tell the user the review handoff state was not written back and send them to re-run the execute report instead of silently continuing.
+
+### 1.1 User Confirmation Request Rules
+
+When archive phase requires the user to confirm archive, merge, discard-worktree, continued implementation, or staying in review, render "user choice required" as a standalone block titled `User Confirmation Request`. Do not mix current state, recommended closeout action, and pending confirmation into one paragraph.
+
+The confirmation block must include:
+
+- one explicit instruction: `Reply with a number.`
+- 1-3 numbered options, with item 1 usually marked as `Recommended`
+- `Other:` explaining how non-numbered content will be handled, usually as continued implementation work
+- if the user adds constraints but still has not made a clear choice, continue presenting updated numbered options until the user chooses, stops, or explicitly tells you to continue
+
+If the platform provides structured question UI such as `ask user questions`, `request_user_input`, or an equivalent mechanism, prefer that for these numbered options. If no such mechanism is available, render the `User Confirmation Request` block in the normal message. In either form, do not end with only a sentence like "archive is recommended" or "the next step is closeout."
+
+## 2. User Review
+
+Let the user review the implementation. If they raise issues, continue editing and re-verify.
+
+After implementation is done, do not require another explicit review-confirmation step and do not show a generic "continue review / preserve branch" menu. First decide what happens to the temporary worktree code. If the user replies with any non-numbered content, treat that as a request to keep modifying the implementation and return directly to code work.
+
+Do not make the user guess what to type next. If the user enters archive phase without having made a closeout choice yet, provide a numbered menu.
+
+If the user arrived from the execute phase completion report and already replied with a closeout number there, treat that earlier reply as the only required authorization. Do not show the same menu again and do not add an intermediate "should I handle merge/archive?" confirmation. At that point, only report the required state checks and execute the selected actions directly without splitting closeout into a second confirmation round.
+
+Before offering closeout choices, explicitly tell the user:
+
+- the current branch name
+- the current workspace path
+- the recorded `origin_branch` and `origin_workspace_path`
+- whether the current review location still matches the original branch/workspace
+
+If the current branch or workspace differs from the recorded `origin_*` fields, explicitly say that the implementation is now living in a temporary branch or temporary worktree. If the user switches to free-form text, treat it as a request for more code changes.
+
+Supported closeout paths must first be selected from the actual temporary-worktree state. Do not show a fixed menu by intuition. First run:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" recommend-actions <change-id>
+```
+
+If `temporary_worktree: true`, supported closeout paths are limited to these three outcomes:
+
+- Archive the current change, then merge the branch into the base branch
+- Archive only, without merging
+- Delete the current temporary worktree and discard the code
+
+If `temporary_worktree: false`, the only supported closeout path is:
+
+- Archive only, without merging or deleting a worktree
+
+Merge, discard, deletion, and archive are consequential actions, but once the user has explicitly selected them in the numbered menu, execute them directly without another confirmation round.
+
+## 2.1 Superpowers Worktree Priority
+
+If `origin_workspace_mode=worktree`, or the current path is a temporary implementation worktree created during execution, make the "return to the original branch/workspace" consequence explicit before any destructive action.
+
+The agent must tell the user:
+
+- implementation currently lives in a temporary worktree
+- the original branch is `origin_branch`
+- the original workspace is `origin_workspace_path`
+- whether local temporary branch/worktree cleanup will happen after closeout
+
+Default recommended order:
+
+1. finish review inside the temporary worktree
+2. if no more implementation work is needed, archive first, then merge the temporary worktree into the base branch and delete the temporary worktree
+3. if the user only wants to preserve the archive record without merging code, allow archive-only
+4. if the user wants to discard the code, delete the worktree and drop the local temporary branch
+
+## 2.2 State-Specific Closeout Rules
+
+If the script reports `temporary_worktree: true`, show this menu:
+
+```text
+1. Archive the current change, then merge the branch into the base branch
+2. Archive only, without merging
+3. Delete the current temporary worktree and discard the code
+Other: any non-numbered content means continue modifying the current implementation; if the user gives no input, remain paused in the current review stage
+```
+
+Menu interpretation:
+
+- reply `1`: run `archive-then-merge-worktree`; archive first, then merge into the base branch, then delete the temporary worktree and the merged local temporary branch.
+- reply `2`: run `archive-only`; archive immediately, do not merge into the base branch, and do not auto-delete the current worktree.
+- reply `3`: run `discard-worktree`; delete the temporary worktree and delete the matching local branch. Do not archive discarded code.
+- any non-numbered content means continue modifying the current implementation; ask only one short clarification if the intent is unclear.
+
+If the current workspace is not a temporary worktree and the code is already truly on the target branch, `archive-only` is allowed.
+
+If the script reports `temporary_worktree: false`, the code is already truly on the target branch/workspace. Regardless of whether the target branch is `main`, `master`, `develop`, `feature/*`, or any other name, do not show the "archive then merge" or "delete the current temporary worktree" options. In that case the closeout menu must contain only:
+
+```text
+1. Archive only (current checkout is not a temporary worktree; no branch merge or worktree deletion is needed)
+Other: any non-numbered content means continue modifying the current implementation; if the user gives no input, remain paused in the current review stage
+```
+
+In other words, when `temporary_worktree: false`, do not prompt for branch merge or worktree deletion on any target branch.
+
+If the user already selected a closeout number in the execute phase completion menu, do not repeat the same menu here; combine that reply with the actual workspace state and execute the matching action directly.
+
+## 3. Archive Rules
+
+Before merge, discard, delete, or archive is finalized, always check whether there is still uncommitted code related to the current change:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" related-dirty <change-id>
+```
+
+- if the result is empty, continue with closeout
+- if the result is empty, unrelated untracked directories must not block closeout; for example, `.superpowers/` that is not recorded in the tracked-file list inside `.onespec.yaml` can be called out as "not included in this change" and then ignored for closeout purposes
+- if the result is not empty, do not stop at "please commit first". The closeout scripts must auto-commit those files, and they must only commit files related to this change:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" commit-related <change-id> <closeout|archive|preserve-state>
+```
+
+- prefer the repository's own Git commit policy for commit-message format, scope, and language; detect project docs and config first:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" detect-policy <change-id>
+```
+
+- if the project defines an explicit policy, follow it
+- if the project does not define a policy, fall back to general Conventional Commits: `<type>(<scope>): <short summary>`
+- only commit the intersection of the tracked-file list stored in `.onespec.yaml` and current dirty files; if `.onespec.yaml` itself is dirty, include it too; never include unrelated changes
+- exception: temporary zip files, export bundles, or other change-local artifacts under `openspec/changes/<change-id>/` are also part of the current change; auto-commit should include them so archive preserves them in change history
+- auto-commit only covers the local commits needed for closeout. Local merge/archive actions included in the numbered closeout selection are already authorized. Merge, rebase, or push actions outside that selection still require explicit user approval.
+- recommended order:
+  1. auto-commit current-workspace dirty files related to the change before closeout continues
+  2. if archive creates new archive artifacts or removes `.onespec.yaml`, auto-commit the archive result after archive finishes
+  3. if the user chooses archive-then-merge, merge the implementation branch back into the base branch only after the archive commit is complete
+- If the user selects `archive-then-merge-worktree`, run it only when `temporary_worktree: true`; archive first, then merge into the target branch, then delete the temporary worktree, and set state to `archived`.
+- If the user selects `archive-only`, run OpenSpec archive and set state to `archived`; do not auto-merge. When `temporary_worktree: false`, also do not delete any workspace or worktree.
+- If the user discards the worktree, do not archive and do not merge discarded branch code into the base branch.
+- Only after archive actually runs should the runtime state file be removed:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" cleanup-runtime <change-id>
+```
+
+For actual closeout execution, prefer:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" run-actions <change-id> [archive-then-merge-worktree|archive-only|discard-worktree]
+```
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase done
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> archive <skipped|archived>
+```
+
+Before archiving, confirm:
+
+- `tasks.md` is checked off to match reality
+- project tests passed, or any failures are explicitly called out
+- `openspec validate <change-id> --strict` passed
+- the user explicitly chose archive-then-merge, archive-only, or discard-worktree
+- no user-review feedback remains unresolved
+
+## 4. Report
+
+The closeout report must cover:
+
+- user review result
+- selected closeout path: archive then merge, archive only, or discard worktree
+- final branch/worktree state
+- how the current branch relates to `origin_branch`, and whether a temporary worktree is still kept locally
+- status of `tasks.md`, tests, and OpenSpec validate
+- archive field: `skipped` or `archived`
+
+## 5. Stop Conditions
+
+Pause and explain if:
+
+- the user has not finished final review
+- the user has not explicitly chosen a closeout path
+- the user has not explicitly approved archive-then-merge, archive-only, or discard-worktree
+- tests or `openspec validate <change-id> --strict` are failing and the user has not explicitly accepted the risk

package/assets/skills-en/{onespec-design/SKILL.md → onespec/references/design.md}

@@ -1,22 +1,13 @@
----
-name: onespec-design
-description: Use when the user needs requirement clarification, proposal/design/tasks/spec deltas, complexity analysis, or approval-path selection for an OpenSpec change.
----
+# Design Phase
 
-# OneSpec Design
-
-Handles the design and proposal phase for OneSpec. The goal is to turn a request into pre-approval OpenSpec artifacts and recommend the correct implementation path.
-
-Announce at the start:
-
-> I am using `onespec-design` for the proposal/design phase.
+Read on demand from `onespec` during the `propose` phase. The goal is to turn a request into pre-approval OpenSpec artifacts and recommend the correct implementation path.
 
 ## 1. Intake
 
 Recover state first:
 
 ```bash
-ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
+ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.claude "$HOME"/.cursor "$HOME"/.gemini "$HOME"/.copilot "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
 . "$ONESPEC_ENV"
 "$ONESPEC_BASH" "$ONESPEC_STATE" list
 ```
@@ -27,11 +18,11 @@ If a relevant change exists, you must continue with:
 "$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
 ```
 
-Treat `recover` output as the current phase contract, not as reference information. Read at least `phase`, `next_skill`, `next_gate`, and `allowed_actions` before deciding whether to continue design-phase work.
+Treat `recover` output as the current phase contract, not as reference information. Read at least `phase`, `next_skill`, `next_reference`, `next_gate`, and `allowed_actions` before deciding whether to continue design-phase work.
 
 Read the minimum necessary context:
 
-- Relevant parts of `openspec/config.yaml`, `openspec/project.md`, and `openspec/specs/**`
+- Relevant parts of `openspec/config.yaml` and `openspec/specs/**`
 - Relevant project entry docs such as `AGENTS.md`, `README.md`, or `docs/**`
 - Current branch and workspace state
 
@@ -141,18 +132,42 @@ Always state:
 - change id and artifact locations
 - a short summary of the task artifact
 - complexity level and concrete reasons
-- recommended route: `recommend Superpowers` or `recommend direct OpenSpec apply`
+- the recommended combination, not only an abstract route:
+  - `OpenSpec apply + native + current branch`
+  - `Superpowers + subagent + new worktree`
+  - `Superpowers + subagent + current worktree/current branch`
 - that the user may override the recommendation
 
+### 3.1 User Confirmation Request Rules
+
+When the result requires the user to decide whether to approve, start implementation, change the path, or stay in design, render "user choice required" as a standalone block titled `User Confirmation Request`. Do not mix the conclusion, recommendation, and pending confirmation into one paragraph.
+
+The confirmation block must include:
+
+- one explicit instruction: `Reply with a number.`
+- 2-4 numbered options, with item 1 usually marked as `Recommended`
+- `Other:` explaining that the user may add constraints or request an operation not listed
+- if the user adds constraints but still has not made a clear choice, continue presenting updated numbered options until the user chooses, stops, or explicitly tells you to continue
+
+If the platform provides structured question UI such as `ask user questions`, `request_user_input`, or an equivalent mechanism, prefer that for these numbered options. If no such mechanism is available, render the `User Confirmation Request` block in the normal message. In either form, do not end with only a sentence like "I recommend this path."
+
 ## 4. Proposal Approval Gate and Path Selection
 
 Default intent mapping, issue-workflow routing, or implementation recommendations do not count as proposal approval.
 
 Implementation planning is only allowed after the user explicitly approves the proposal / design / spec. At the end of the design phase, do not fall back to a single free-form sentence, and do not require the user to type words like `approve`, `yes`, or `continue`. Present an "explicit options + recommendation + direct reply phrase" menu. The user may reply with digits or with the matching phrase. Silence, "looks okay", the original "start implementation", "execute this change", or "make plan" do not count as artifact approval.
 
-Use this default approval menu, with the recommended implementation path baked into item 1:
+Before rendering the approval menu, determine the recommended combination:
+
+- If recommending `OpenSpec apply`, the combination is fixed as `OpenSpec apply + native + current branch`; record `implementation_path=openspec-apply`, `execution_method=native`, and `workspace=current-branch` (if the current branch is `main`/`master` and project docs forbid direct main-branch changes, pause and warn first).
+- If recommending `Superpowers`, default the execution method to `subagent`; recommend `local` only when tasks are tightly coupled, unsuitable for per-task dispatch, or the user/platform clearly cannot use subagents.
+- Detect whether the current checkout is already an attached git worktree: compare `git rev-parse --path-format=absolute --git-dir` with `git rev-parse --path-format=absolute --git-common-dir`; if they differ, the current checkout is an attached worktree. If that command is unavailable, fall back to `git worktree list --porcelain` and match the current `pwd -P` against `worktree` entries.
+- If already inside an attached worktree, do not recommend creating another worktree; recommend `Superpowers + <subagent|local> + current worktree/current branch`, and record `workspace=current-branch` because execution happens in the current checkout.
+- If not inside an attached worktree and recommending `Superpowers`, default to `Superpowers + subagent + new worktree` for implementation-branch isolation; record `workspace=worktree`.
+
+Use this default approval menu, with the recommended combination baked into item 1. The menu must explain that the combination has three parts: implementation path + execution method + workspace policy.
 
-1. approve the current proposal / design / spec and continue with the recommended implementation path (Recommended)
+1. approve the current proposal / design / spec and continue with the recommended combination: `<recommended-combination>` (Recommended)
    Direct reply phrase: `approve and use the recommended path`
 2. approve the current proposal / design / spec, but change the implementation path, execution method, or workspace
    Direct reply phrase: `approve but change the implementation path`
@@ -164,41 +179,41 @@ Other: if the user's intent is not covered by the menu, allow free-form instruct
 
 Menu handling rules:
 
-- reply `1` or `approve and use the recommended path`: treat this as approval of the current artifacts and acceptance of the recommended path
-- reply `2` or `approve but change the implementation path`: treat this as approval of the current artifacts, but continue with another explicit-options menu for only the still-unconfirmed dimensions
-- reply `3` or `revise the proposal first`: stay in `onespec-design`, revise artifacts based on feedback, and do not enter implementation
+- reply `1` or `approve and use the recommended path`: treat this as approval of the current artifacts and acceptance of the recommended combination; do not ask a second round for `subagent/local` or `worktree/current-branch`; directly record the combination's `implementation_path`, `execution_method`, and `workspace`
+- reply `2` or `approve but change the implementation path`: treat this as approval of the current artifacts, but continue with a combination menu; do not split `subagent/local` and `worktree/current-branch` into two rounds
+- reply `3` or `revise the proposal first`: stay in design phase, revise artifacts based on feedback, and do not enter implementation
 - reply `4` or `stay in design for now`: pause at the design phase and wait for later instructions
 - free-form text instead of digits: if intent is clear, follow it; otherwise ask one minimal clarification question
 
-If the user chooses `Superpowers`, confirm two choices together:
+If the user picked item 2, keep using the same "explicit combination options + recommendation + direct reply phrase" format instead of only digits or only free-form words. Generate the menu based on whether the current checkout is already an attached worktree:
 
-- execution method: `subagent` or `local`. Recommend `subagent` by default, which maps to `subagent-driven-development`; `local` maps to `executing-plans`.
-- workspace: `worktree` or `current-branch`.
-
-If the user picked item 2, keep using the same "explicit options + recommendation + direct reply phrase" format instead of only digits or only free-form words. Recommended order:
-
-- implementation path:
-  1. `Superpowers` (Recommended)
-     Direct reply phrase: `use Superpowers`
-  2. `OpenSpec apply`
+- If not currently inside an attached worktree, use this default menu:
+  1. `Superpowers + subagent + new worktree` (Recommended)
+     Direct reply phrase: `use Superpowers subagent worktree`
+  2. `Superpowers + local + new worktree`
+     Direct reply phrase: `use Superpowers local worktree`
+  3. `Superpowers + local + current branch`
+     Direct reply phrase: `use Superpowers local current-branch`
+  4. `OpenSpec apply + native + current branch`
+     Direct reply phrase: `use OpenSpec apply`
+  Other: allow a special combination, for example an explicit `Superpowers + subagent + current branch`
+- If already inside an attached worktree, use this default menu:
+  1. `Superpowers + subagent + current worktree/current branch` (Recommended)
+     Direct reply phrase: `use Superpowers subagent current worktree`
+  2. `Superpowers + local + current worktree/current branch`
+     Direct reply phrase: `use Superpowers local current worktree`
+  3. `OpenSpec apply + native + current worktree/current branch`
      Direct reply phrase: `use OpenSpec apply`
-- if `Superpowers` is selected, execution method:
-  1. `subagent` (Recommended)
-     Direct reply phrase: `use subagent`
-  2. `local`
-     Direct reply phrase: `use local`
-- workspace:
-  1. `worktree` (Recommended)
-     Direct reply phrase: `use worktree`
-  2. `current-branch`
-     Direct reply phrase: `use current-branch`
-  Other: allow the user to describe a special workspace arrangement
+  Other: allow a special combination; do not recommend creating another worktree
 
 `main`/`master` rules:
 
 - Do not implement directly on `main`/`master` unless the user explicitly accepts the risk after being warned.
-- If the current branch is `main`/`master` and the user chooses `Superpowers`, do not auto-create a worktree from the branch name alone. Follow the chosen workspace policy. If `current-branch` is selected, warn and record `main-override`.
+- If the current branch is `main`/`master` and the user chooses `Superpowers + current branch`, warn first and record `main-override`; if the user chooses `new worktree`, follow the worktree creation rules.
 - If already on a feature branch and the workspace is clean, `current-branch` is acceptable.
+- If the plan is to switch into a `worktree` but the current workspace is dirty, handle those changes first before creating the worktree. In particular, do not create a temporary worktree while carrying uncommitted `main`/`master` changes.
+- For uncommitted changes on `main`/`master`, require a local commit that follows the project's commit policy before creating the temporary branch/worktree. Do not implicitly carry dirty base-branch code into a new implementation branch.
+- If the user refuses to commit the current dirty changes first, do not continue creating the worktree. Stop, switch to `current-branch`, or ask the user to clean up the branch state first.
 
 After confirmation record:
 
@@ -213,7 +228,7 @@ After confirmation record:
 "$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase approved
 ```
 
-These `origin_*` fields represent the branch and workspace where the user originally started the change. If implementation later happens in a different branch or temporary worktree, `onespec-execute` and `onespec-archive` must use them when prompting for review and closeout.
+These `origin_*` fields represent the branch and workspace where the user originally started the change. If implementation later happens in a different branch or temporary worktree, execute phase and archive phase must use them when prompting for review and closeout.
 
 ## 5. Stop Conditions