@kafka0102/onespec 0.1.2 → 0.1.14

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,23 +28,32 @@ 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
 
@@ -53,5 +62,5 @@ Default intent mapping:
 - 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.
 - 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,190 @@
+# 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.
+
+## 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 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
+
+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 Worktree Closeout Rules
+
+If the current workspace is a temporary worktree, 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 current checkout is not a temporary worktree, the current branch already equals `origin_branch`, and that branch is `main` or `master`, 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, without merging
+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, on `master/main`, do not prompt for branch merge or worktree deletion.
+
+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`, archive first, then merge into the target branch, and set state to `archived`.
+- If the user selects `archive-only`, run OpenSpec archive and set state to `archived`; do not auto-merge and do not auto-delete the current 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,7 +18,7 @@ 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:
 
@@ -141,7 +132,10 @@ 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
 
 ## 4. Proposal Approval Gate and Path Selection
@@ -150,9 +144,17 @@ Default intent mapping, issue-workflow routing, or implementation recommendation
 
 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`.
 
-1. approve the current proposal / design / spec and continue with the recommended implementation path (Recommended)
+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 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 +166,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:
-
-- 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 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:
 
-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 +215,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
 

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

@@ -1,22 +1,13 @@
----
-name: onespec-execute
-description: Use when the user needs to execute an approved OpenSpec change, continue implementation, generate a Superpowers plan, run OpenSpec apply, sync tasks, or verify the result.
----
-
-# OneSpec Execute
-
-Handles the execution phase for OneSpec. The goal is to implement only within approved scope and sync the outcome back into OpenSpec state.
+# Execute Phase
 
-Announce at the start:
-
-> I am using `onespec-execute` for the apply / implementation phase.
+Read on demand from `onespec` during the `apply` phase. The goal is to implement only within approved scope and sync the outcome back into OpenSpec state.
 
 ## 1. Apply Routing
 
 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,7 +18,7 @@ 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 execution-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 execution-phase work.
 
 Before apply, read at least:
 
@@ -51,20 +42,36 @@ If the proposal phase already confirmed the implementation path:
 - user chose native `OpenSpec apply`: switch to native apply.
 - user still has not confirmed: restate the recommendation and require a numbered choice before implementation starts.
 
-If execution-time route confirmation is still needed, use this menu and let the user reply with digits:
-
-1. continue with the recommended route
-2. switch to `Superpowers`
-3. switch to native `OpenSpec apply`
-4. do not start implementation yet; go back and revise proposal / design / tasks
+If execution-time route confirmation is still needed, first detect whether the current checkout is already an attached git worktree, then use the matching numbered menu. The user may reply with digits.
+
+When not currently inside an attached worktree:
+1. continue with the recommended combination
+2. switch to `Superpowers + subagent + new worktree`
+3. switch to `Superpowers + local + new worktree`
+4. switch to `Superpowers + local + current branch`
+5. switch to native `OpenSpec apply + native + current branch`
+6. do not start implementation yet; go back and revise proposal / design / tasks
+
+When already inside an attached worktree:
+1. continue with the recommended combination
+2. switch to `Superpowers + subagent + current worktree/current branch`
+3. switch to `Superpowers + local + current worktree/current branch`
+4. switch to native `OpenSpec apply + native + current worktree/current branch`
+5. do not start implementation yet; go back and revise proposal / design / tasks
 Other: if intent is not covered by the menu, allow free-form instructions
 
 Menu handling rules:
 
-- reply `1`: use the current recommendation
-- reply `2`: switch to `Superpowers`, then keep using numbered menus for `subagent/local` and `worktree/current-branch`
-- reply `3`: switch to native `OpenSpec apply`
-- reply `4`: stop execution and return to design revision
+- reply `1`: use the current recommended combination; do not ask a second round for `subagent/local` or `worktree/current-branch`
+- when not currently inside an attached worktree, reply `2`: record `implementation_path=superpowers`, `execution_method=subagent`, and `workspace=worktree`
+- when not currently inside an attached worktree, reply `3`: record `implementation_path=superpowers`, `execution_method=local`, and `workspace=worktree`
+- when not currently inside an attached worktree, reply `4`: record `implementation_path=superpowers`, `execution_method=local`, and `workspace=current-branch`
+- when not currently inside an attached worktree, reply `5`: record `implementation_path=openspec-apply`, `execution_method=native`, and `workspace=current-branch`
+- when not currently inside an attached worktree, reply `6`: stop execution and return to design revision
+- when already inside an attached worktree, reply `2`: record `implementation_path=superpowers`, `execution_method=subagent`, and `workspace=current-branch`
+- when already inside an attached worktree, reply `3`: record `implementation_path=superpowers`, `execution_method=local`, and `workspace=current-branch`
+- when already inside an attached worktree, reply `4`: record `implementation_path=openspec-apply`, `execution_method=native`, and `workspace=current-branch`
+- when already inside an attached worktree, reply `5`: stop execution and return to design revision
 - free-form text instead of digits: if intent is clear, follow it; otherwise ask one minimal clarification question
 
 ## 2. Superpowers Make Plan and Execution
@@ -113,6 +120,27 @@ If `origin_branch` or `origin_workspace_path` is still `unknown`, fill them in i
 "$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_mode "$( "$ONESPEC_BASH" "$ONESPEC_STATE" get <change-id> workspace )"
 ```
 
+If the next step is to create a temporary worktree from the current branch, check for uncommitted changes first:
+
+- if the current workspace is dirty, handle those changes before creating the worktree
+- if the current branch is `main`/`master` and has uncommitted changes, require a local commit that follows the project commit policy before creating the worktree; do not carry dirty base-branch code straight into a new implementation branch
+- if the user refuses to commit the current dirty changes first, do not continue creating the worktree; pause, or switch to `current-branch` with an explicit risk callout
+
+### 2.1 Implementation Workspace Binding
+
+After creating or selecting the implementation worktree, immediately bind the absolute implementation workspace path as `implementation_workspace_path`, and verify that it is the working directory for subsequent commands before writing the plan:
+
+```bash
+implementation_workspace_path="$(pwd -P)"
+git -C "$implementation_workspace_path" status --short
+```
+
+- If `workspace=worktree`, enter the new worktree first, then set `implementation_workspace_path`; do not keep generating the plan in the origin workspace.
+- If `workspace=current-branch`, or if the current checkout is already an attached worktree, `implementation_workspace_path` is the current `pwd -P`.
+- Every OpenSpec artifact read, Superpowers plan write, `.onespec.yaml` update, handoff generation, and implementation command must run with the implementation workspace as the working directory.
+- The plan path `docs/superpowers/plans/YYYY-MM-DD-<change-id>.md` is always relative to `implementation_workspace_path`. Do not write the plan in the origin workspace and then copy it into the implementation worktree.
+- Before recording the plan and handoff, run `git -C "$implementation_workspace_path" status --short` to confirm that the plan and `.onespec.yaml` are in the same implementation workspace.
+
 Default execution path:
 
 - prefer `subagent-driven-development`
@@ -156,7 +184,7 @@ Pause and explain if:
 
 > This gate is mandatory. If it is not satisfied, do not output a completion summary, do not give closeout suggestions, and do not enter the next phase.
 
-After implementation and verification, the flow must pause explicitly. Do not continue directly into merge, worktree deletion, archive, or any implicit closeout. The goal here is to enter user-review / `review-closeout` waiting state. After development finishes, ask only whether archive-related cleanup should happen; do not require a separate review-confirmation step first.
+After implementation and verification, the flow must pause explicitly. Do not continue directly into merge, worktree deletion, archive, or any implicit closeout. The goal here is to enter user-review / `review-closeout` waiting state. After development finishes, present the closeout action menu directly; do not require a separate review-confirmation step first and do not split archive into a second confirmation round.
 
 ### 5.1 Mandatory Script Calls
 
@@ -196,15 +224,37 @@ Current branch: <branch>
 Current workspace: <path>
 Origin: <origin_branch> @ <origin_workspace_path>
 
-1. Enter `onespec-archive` and choose delete-worktree / archive actions
-2. Keep the current branch / worktree as-is and stop here for now
-Other: any non-numbered content means continue modifying the current implementation; if the intent is outside the menu, the user may also describe it directly
+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
 ---
 ```
 
+If the current checkout is not a temporary worktree, the current branch already equals `origin_branch`, and that branch is `main` or `master`, do not show "merge the branch into the base branch" or "delete the current temporary worktree". In that case the closeout menu must collapse to a single archive-only option:
+
+```text
+---
+Implementation and verification are complete.
+
+Current branch: <branch>
+Current workspace: <path>
+Origin: <origin_branch> @ <origin_workspace_path>
+
+1. Archive only, without merging
+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, on `master/main`, do not prompt for branch merge or worktree deletion.
+
 If the current branch or workspace differs from `origin_*`, add an explicit note that implementation currently lives in a temporary branch or temporary worktree and that any non-numbered reply will be treated as a request for more implementation work.
 
-Do not stop at an abstract note such as "the next step is `onespec-archive`" or just "do review-closeout". You must also give the user a concrete numbered menu.
+- If the user chooses `1`, archive phase must archive first, then merge the branch into the base branch.
+- If the user chooses `2`, archive phase must archive only, without merging and without auto-deleting the current worktree.
+- If the user chooses `3`, archive phase must delete the temporary worktree and discard the code without archiving.
+
+Do not stop at an abstract note such as "the next step is archive phase" or just "do review-closeout". You must also give the user a concrete numbered menu.
 
 ### 5.4 Anti-Patterns (NEVER)
 
@@ -213,7 +263,7 @@ The following are gate violations:
 - reporting "done" without first running the scripts in 5.1
 - omitting current branch / workspace information from the report
 - omitting a concrete numbered next-step menu
-- mixing archive, merge, or worktree-deletion actions into the implementation-complete report
-- entering `onespec-archive` before the user replies
-- replacing the concrete numbered menu with an abstract "next step is onespec-archive" statement
+- executing archive, merge, or worktree-deletion actions before the user has chosen one
+- entering archive phase before the user replies
+- replacing the concrete numbered menu with an abstract "next step is archive phase" statement
 - deleting a temporary worktree before review is complete and the user explicitly asks for closeout