@kafka0102/onespec 0.1.2 → 0.2.2

package/README.md

@@ -2,83 +2,80 @@
 
 > 中文说明见 [README-zh.md](README-zh.md)
 
-OneSpec is a Codex skill package for running an OpenSpec + Superpowers workflow.
+OneSpec is a CLI and agent skill bundle for running an OpenSpec + Superpowers workflow.
 
-## Install
+## What It Does
 
-Use one of these installation methods.
+### `onespec`
 
-### Via `npm install -g`
+`onespec` turns OpenSpec from a set of manual commands into an agent-operated workflow. It prepares the design, spec, and task artifacts, asks the human to confirm the design before implementation, recommends the implementation method and path based on complexity, then carries the change through execution, review, and archive.
 
-Install the CLI globally:
+Use it when a change needs normal design confirmation and acceptance review. You invoke the workflow in natural language instead of manually chaining multiple OpenSpec commands.
 
-```bash
-npm install -g @kafka0102/onespec
-```
+### `onespec-fast`
 
-Then install the bundled skills into Codex:
+`onespec-fast` is the shorter path for explicitly automatic OpenSpec changes. It creates the needed OpenSpec context, skips the complexity check, uses native `OpenSpec apply`, runs validation, and archives directly.
 
-```bash
-onespec init --scope global --yes
-```
+## Workflow
 
-Or install into the current project only:
+`onespec`
 
-```bash
-onespec init . --scope project --yes
+```mermaid
+flowchart LR
+  A[User request] --> B[Draft design, spec, and tasks] --> C{Human confirms design} --> D[Recommend method and path by complexity] --> E[Execute approved change] --> F{Human reviews acceptance} --> G[Archive]
 ```
 
-### Via `npx`
-
-If you publish the package to npm:
+`onespec-fast`
 
-```bash
-npx @kafka0102/onespec init
+```mermaid
+flowchart LR
+  A[Fast-path request] --> B[Create compact OpenSpec context] --> C[Native OpenSpec apply] --> D[Test and validate] --> E[Archive]
 ```
 
-### Via Repository Source
+## Install
 
-Install the skill bundle directly from this repository:
+Requires:
 
-```bash
-npx skills add https://github.com/kafka0102/onespec/tree/main/assets/skills-en -a codex -y
-```
+- Node.js 20+
+- npm / npx
+- a shell with `bash`
 
-For the Chinese bundle:
+Global install:
 
 ```bash
-npx skills add https://github.com/kafka0102/onespec/tree/main/assets/skills -a codex -y
+npm install -g @kafka0102/onespec
 ```
 
-The `skills` CLI does not parse `owner/repo/tree/<ref>/...` shorthand correctly. Use the full GitHub URL above, or the shorthand form with an explicit ref such as `kafka0102/onespec/assets/skills#main`.
-
-## Use
+Run without a global install:
 
-`npm install -g @kafka0102/onespec` only installs the `onespec` CLI.
-`onespec init` is the step that copies the bundled skills into Codex.
-
-After `onespec init`, restart Codex and invoke the OneSpec skills in your task.
-During active work, OneSpec keeps runtime state in `openspec/changes/<change-id>/.onespec.yaml`; archive is the point where that file is cleaned up.
+```bash
+npx -y @kafka0102/onespec init
+```
 
-## Release
+If you use `npx`, run other commands the same way, for example:
 
-To publish from GitHub Actions:
+```bash
+npx -y @kafka0102/onespec doctor . --scope project
+```
 
-1. Recommended: configure npm Trusted Publishing for `@kafka0102/onespec` and this GitHub repository.
-2. Fallback: if you do not use Trusted Publishing, add repository secret `NPM_TOKEN` with an npm granular access token that has publish permission for `@kafka0102/onespec` and `bypass 2FA` enabled.
-3. Update `package.json` version.
-4. Create and push a matching tag such as `v0.1.2`.
+## Quick Start
 
 ```bash
-git tag v0.1.2
-git push origin main --tags
+cd your-project
+onespec init
 ```
 
-The workflow at `.github/workflows/publish.yml` runs on `v*` tags, checks that the tag matches `package.json`, runs `npm test`, previews the published package, and then publishes to npm.
+Then run:
 
-It now supports both modes:
+```bash
+onespec doctor . --scope project
+```
 
-1. Trusted Publishing if no `NPM_TOKEN` secret is configured.
-2. Token-based publishing if `NPM_TOKEN` is present.
+After `onespec init`, restart the agent session and use natural language, for example:
 
-If npm returns `E403` with a message about 2FA or granular access tokens, the token is not valid for publishing under npm's current policy. Replace it with a granular token that can bypass 2FA, or switch the package to Trusted Publishing.
+```text
+use onespec: design a login audit feature
+use onespec: apply the approved change for login audit
+use onespec: review and archive the login audit change
+use onespec-fast: add a validation message
+```

package/assets/skills/onespec/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: onespec
-description: 当用户需要用 OpenSpec 与 Superpowers 管理完整 AI Coding 变更生命周期，或不确定应进入设计、执行还是归档阶段时使用。
+description: 当用户需要用 OpenSpec 与 Superpowers 管理完整 AI Coding 变更生命周期，或不确定应进入设计、执行、归档还是 fast path 时使用。
 ---
 
 # OneSpec 工作流
 
-OneSpec 是组合路由 Skill。它只负责恢复状态、判断阶段并切换到 `onespec-design`、`onespec-execute` 或 `onespec-archive`；具体阶段规则以对应子 Skill 为准。
+OneSpec 是单一入口 Skill。它负责恢复状态、判断阶段，并按需读取 `references/` 下的阶段模块；不要再调用已废弃的阶段子 Skill。
 
 开始时说明：
 
@@ -16,7 +16,7 @@ OneSpec 是组合路由 Skill。它只负责恢复状态、判断阶段并切换
 每次进入先检查状态，不依赖聊天历史：
 
 ```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,31 +28,39 @@ ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.agents "$HOME"/.con
 ```
 
 运行时状态文件是 `openspec/changes/<change-id>/.onespec.yaml`。handoff 摘要、哈希和 touched files 都写回这里；archive 前保留，archive 后删除。
-`recover` 的输出是执行合同，不是参考信息。至少先读取 `phase`、`next_skill`、`next_gate` 与 `allowed_actions`，再决定是否继续。
+`recover` 的输出是执行合同，不是参考信息。至少先读取 `phase`、`next_skill`、`next_reference`、`next_gate` 与 `allowed_actions`，再决定是否继续。
 
 ## 阶段路由
 
 先判断当前请求属于哪一类：
 
-- `propose`：定义新 change、梳理范围、生成 `proposal.md`、`design.md`、`tasks.md` 与 spec delta。使用 `onespec-design`。
-- `apply`：实现已批准 change、继续已有 change、生成或恢复 Superpowers plan、回填 OpenSpec 状态。使用 `onespec-execute`。
-- `review-closeout`：用户评审、处理反馈、删除 worktree 或执行归档。使用 `onespec-archive`。
+- `propose`：定义新 change、梳理范围、生成 `proposal.md`、`design.md`、`tasks.md` 与 spec delta。读取 `references/design.md`。
+- `apply`：实现已批准 change、继续已有 change、生成或恢复 Superpowers plan、回填 OpenSpec 状态。读取 `references/execute.md`。
+- `review-closeout`：用户评审、处理反馈、删除 worktree 或执行归档。读取 `references/archive.md`。
+- `fast`：用户明确要求 `onespec-fast`、快速路径、fast apply、OpenSpec 自动贯通或自动 proposal/开发/归档时。读取 `references/fast.md`；独立 `onespec-fast` 入口也转入同一 reference。
 
 如果用户意图不清，只问一个简短问题，不要同时问多个。
 
 默认意图映射：
 
-- 用户说“新需求”、“设计一下”、“写 proposal / spec”、“定义 change”时，进入 `onespec-design`。
-- 用户说“开始实现”、“执行这个 change”、“apply 这个 proposal / change”、“继续做这个 change”、“开始 coding / 开发”、“make plan”时，进入 `onespec-execute`。如果 proposal 尚未批准，`onespec-execute` 必须停止并转回 `onespec-design` 的批准 gate。
-- 用户说“review”、“收尾”、“归档”、“archive”、“删除 worktree”时，进入 `onespec-archive`。
+- 用户说“新需求”、“设计一下”、“写 proposal / spec”、“定义 change”时，读取 `references/design.md`。
+- 用户说“开始实现”、“执行这个 change”、“apply 这个 proposal / change”、“继续做这个 change”、“开始 coding / 开发”、“make plan”时，读取 `references/execute.md`。如果 proposal 尚未批准，必须停止并转回 `references/design.md` 的批准 gate。
+- 用户说“review”、“收尾”、“归档”、“archive”、“删除 worktree”时，读取 `references/archive.md`。
+- 用户明确说“onespec-fast”、“快速路径”、“fast apply”、“OpenSpec 自动贯通”或“自动 proposal/开发/归档”时，读取 `references/fast.md`。
+
+## Reference 读取规则
+
+- 每次只读取当前阶段需要的一个 reference；不要预读其他阶段。
+- 如果 `recover` 输出 `next_reference`，默认先读取它；只有用户当前请求明确改变阶段，且上一阶段 gate 已完成时，才允许覆盖。
+- `references/fast.md` 可以复用 `design.md`、`execute.md` 和 `archive.md` 的过程段，但 fast path 会覆盖普通 proposal approval、review pause 和 closeout menu gate。
+- 如果需要跨阶段校验，只读取与 gate 直接相关的最小段落。
 
 ## 共同约束
 
 - OpenSpec 负责“要做什么”、formal artifacts、approval gate、spec delta 与归档语义。
 - Superpowers 负责高歧义需求澄清、实现计划、TDD、分任务 review 与工程执行质量。
 - 不要询问变更名称。根据任务自动生成简短短横线命名的 `change-id`，如冲突则追加数字。
-- 读取最少必要上下文：`openspec/config.yaml`、`openspec/project.md`、相关 `openspec/specs/**`、项目入口文档、当前分支和工作区状态。
+- 读取最少必要上下文：`openspec/config.yaml`、相关 `openspec/specs/**`、项目入口文档、当前分支和工作区状态。
 - 只问会改变 proposal、执行路径、分支处理或归档结果的问题。
-- 当阶段规则冲突时，以当前阶段子 Skill 的停止条件为准。
-- 每个阶段子 Skill 定义了强制暂停 gate（如 `onespec-execute` 的"实现完成 Gate"、`onespec-design` 的"批准 Gate"）。路由进入下一阶段前，必须确认上一阶段的 gate 已完成。如果 gate 未完成就试图进入下一阶段，必须拒绝并指出缺失步骤。
-- 如果 `recover` 已经给出 `next_skill`，默认先按它恢复；只有在用户当前请求明确改变阶段，且上一阶段的 gate 已完成时，才允许覆盖该恢复结果。
+- 当共同规则与阶段规则冲突时，以当前阶段 reference 的停止条件为准。
+- 每个阶段 reference 定义了强制暂停 gate（如 `references/execute.md` 的“实现完成 Gate”、`references/design.md` 的“批准 Gate”）。路由进入下一阶段前，必须确认上一阶段的 gate 已完成。如果 gate 未完成就试图进入下一阶段，必须拒绝并指出缺失步骤。

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

@@ -0,0 +1,214 @@
+# Archive Phase
+
+供 `onespec` 在 `review-closeout` 阶段按需读取。目标是在用户确认后处理临时 worktree 的代码去向，并按用户已授权的动作完成合并、废弃或归档。
+
+## 1. 评审入口
+
+先恢复状态：
+
+```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
+```
+
+如果发现相关 change，必须继续执行：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
+```
+
+`recover` 的输出是当前阶段合同，不是参考信息。至少先读取 `phase`、`next_skill`、`next_reference`、`next_gate` 与 `allowed_actions`，再决定是否继续收尾阶段动作。
+
+读取最少必要上下文：
+
+- `openspec/changes/<change-id>/proposal.md`
+- `openspec/changes/<change-id>/tasks.md`
+- `openspec/changes/<change-id>/design.md`，如果存在
+- 相关 `openspec/specs/**`
+- 最新测试结果与 `openspec validate <change-id> --strict` 结果
+- 当前分支、worktree 和工作区状态
+- `origin_branch`、`origin_workspace_path`、`origin_workspace_mode`
+
+如果状态尚未到 `review`，先说明缺少什么：未实现、未验证、未回填 `tasks.md`，或 proposal 尚未批准。
+
+入口校验：如果 phase 已到 `review`，但 `.onespec.yaml` 里的 `handoff_purpose` 不是 `review`，或 `handoff_hash` 为空，说明 execute gate 可能未正常完成。此时必须告诉用户："执行阶段的 review handoff 状态未写回，建议先回到执行阶段补充汇报（回复 `补充汇报` 或重新触发 execute gate）。" 不允许静默跳过。
+
+### 1.1 用户确认请求规则
+
+当归档阶段需要用户确认归档、合并、废弃 worktree、继续修改或停留评审时，必须把“需要用户选择”作为独立块输出，标题固定为 `用户确认请求`。不要把当前状态、推荐收尾动作和等待用户确认混成同一段。
+
+确认块必须包含：
+
+- 一句明确指令：`请回复编号。`
+- 1-3 个编号选项，其中第 1 项通常是推荐项，并标注“推荐”
+- `其他：` 说明非编号内容如何处理，通常视为继续修改当前实现
+- 如果用户补充了新条件但还没有形成明确选择，继续给出新的编号选项，直到用户明确选择、终止或要求继续往下走
+
+如果平台提供结构化询问能力，例如 `ask user questions`、`request_user_input` 或等价 UI，优先用结构化询问承载这些编号选项；如果当前环境没有这类能力，则在普通消息中输出上述 `用户确认请求` 块。无论使用哪种形式，都不能只给一句“建议归档”或“下一步进入收尾”就结束。
+
+## 2. 用户评审
+
+实现完成后让用户评审。若用户指出问题，继续修改并重新验证。
+
+开发完成后不需要再次让用户确认是否 review，也不需要展示常规“继续评审 / 保留分支”类选项。收尾应先处理临时 worktree 中的代码去向；如果用户回复任意非编号内容，默认视为“继续修改当前实现”，直接回到代码处理环节。
+
+不要让用户自己猜“下一步该输入什么”。如果用户是直接进入 archive phase，尚未做收尾选择，则必须给出用户只需回复数字编号的选项。
+
+如果用户是从 execute phase 的完成汇报进入这里，并且已经回复了收尾编号，则把那次回复视为唯一有效授权，不得再次展示一轮相同菜单，也不得再追加“是否处理合并/归档”之类的中间确认。此时只需汇报必要状态检查，并按用户已选动作直接执行，不需要拆成两轮确认。
+
+进入收尾选择前，必须显式向用户汇报：
+
+- 当前分支名
+- 当前工作区路径
+- 最初开始这次 change 时记录的 `origin_branch` 与 `origin_workspace_path`
+- 当前是否仍在原始分支/原始工作区
+
+如果当前分支或工作区不同于 `origin_*`，必须明确说明“你当前看到的是临时实现分支或临时 worktree”。如果用户改为输入任意非编号内容，则表示当前功能还有问题，需要继续修改。
+
+可选收尾路径必须先按当前是否临时 worktree 差异化判断，不允许凭感觉直接给固定菜单。先执行：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" recommend-actions <change-id>
+```
+
+如果 `temporary_worktree: true`，可选收尾路径只有以下三种：
+
+- 归档当前 change，并合并分支到 base 分支
+- 直接归档，不合并到 base 分支
+- 删除当前临时 worktree并废弃代码
+
+如果 `temporary_worktree: false`，可选收尾路径只有一种：
+
+- 直接归档（不合并分支，不删除 worktree）
+
+合并、废弃、删除与归档都是有后果的操作；但只要用户已经在编号菜单里明确授权，就直接执行，不要再拆成二次确认。
+
+## 2.1 Superpowers Worktree 优先规则
+
+如果 `origin_workspace_mode=worktree`，或当前路径是实现期新建的临时 worktree，收尾时必须把“回收到原始分支/工作区”的动作提到最前面说明。
+
+必须显式告诉用户：
+
+- 当前实现位于临时 worktree
+- 原始分支是 `origin_branch`
+- 原始工作区是 `origin_workspace_path`
+- 收尾后是否会删除本地临时 branch 与 worktree
+
+默认推荐顺序：
+
+1. 先在临时 worktree 完成 review。
+2. 如果无需继续修改，先归档，再把当前实现分支合并回 base 分支，并删除临时 worktree。
+3. 如果用户只需要保留归档记录而不合并代码，则允许“仅归档”。
+4. 如果用户要废弃代码，则删除 worktree 并丢弃本地临时分支。
+
+## 2.2 差异化收尾规则
+
+如果脚本探测到 `temporary_worktree: true`，必须展示以下编号菜单：
+
+```text
+1. 归档当前 change，并合并分支到 base 分支
+2. 直接归档，不合并到 base 分支
+3. 删除当前临时 worktree，废弃代码
+其他：任意非编号内容视为继续修改当前实现；用户未输入时默认停留在当前评审阶段
+```
+
+菜单解释规则：
+
+- 用户回复 `1`：执行 `archive-then-merge-worktree`。必须先归档，再合并代码到 base 分支，最后删除临时 worktree 和已合入的本地临时分支。
+- 用户回复 `2`：执行 `archive-only`。直接归档，不合并到 base 分支，也不自动删除当前 worktree。
+- 用户回复 `3`：执行 `discard-worktree`，删除临时 worktree 并删除对应本地分支；废弃代码后不归档。
+- 用户输入数字外的自由文本：默认视为继续修改当前实现，直接回到代码处理环节；只有意图不清晰时才补一个最短澄清问题。
+
+如果当前不是临时 worktree，且代码已经真正位于目标分支，也允许执行 `archive-only`。
+
+如果脚本探测到 `temporary_worktree: false`，说明代码已经真正位于目标分支/目标工作区。无论当前目标分支是否为 `main`/`master`，都不要再展示“归档后合并”或“删除当前临时 worktree”两个选项。此时收尾菜单只保留一个编号：
+
+```text
+1. 直接归档（当前不在临时 worktree，无需额外合并分支或删除 worktree）
+其他：任意非编号内容视为继续修改当前实现；用户未输入时默认停留在当前评审阶段
+```
+
+也就是说，不在临时 worktree 时，不管当前目标分支叫 `main`、`master`、`develop`、`feature/*` 还是其他名称，都不要提示合并分支/删除 worktree。
+
+如果用户之前已经在 execute phase 的完成菜单里选了收尾编号，则这里不再重复相同菜单，而是结合实际工作区状态直接执行对应动作。
+
+## 3. 归档规则
+
+进入归档、合并或废弃收尾前，必须检查当前是否仍有“与本次 change 相关的未提交代码”：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" related-dirty <change-id>
+```
+
+- 如果结果为空，继续后续收尾。
+- 如果结果为空，即使工作区里还有无关未跟踪目录，也不要阻塞收尾；例如未记录到 `.onespec.yaml` tracked file 列表里的 `.superpowers/` 可以明确说明“未纳入本次提交”，但不应视为本次 change 的阻塞项。
+- 如果结果非空，不要停在“请你自己先提交”这一步。收尾脚本必须自动提交这些文件，而且只能提交本次 change 相关文件：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" commit-related <change-id> <closeout|archive|preserve-state>
+```
+
+- 提交信息优先遵循项目自身指定的 Git 提交策略。先探测项目内文档和配置：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" detect-policy <change-id>
+```
+
+- 如果项目里存在明确规范，按项目要求处理 commit message 的格式、scope 和语言。
+- 如果项目里没有明确规范，回退到通用 Conventional Commits：`<type>(<scope>): <简要描述>`。
+- 只能提交 `.onespec.yaml` 中记录的 tracked files 与当前脏文件的交集；如果 `.onespec.yaml` 本身是脏的，也应一并提交，不允许把无关改动一并提交。
+- 例外：位于 `openspec/changes/<change-id>/` 下、专属于本次 change 的临时压缩包、导出包或交接工件，也视为本次 change 相关文件；自动提交时要一并带上，这样 archive 后仍能保留在 change 历史里。
+- 自动提交只覆盖 closeout 所需的本地 commit。用户在收尾编号菜单中选中的本地合并/归档动作，视为已授权；未包含在用户选择里的 merge / rebase / push 仍不自动执行。
+- 推荐顺序：
+  1. closeout 前先自动提交当前工作区里与本次 change 相关的脏文件。
+  2. 如果 archive 产生了新的归档工件或删除了 `.onespec.yaml`，archive 之后再自动补一笔归档提交。
+  3. 如果用户选择“先归档再合并”，则必须在 archive 提交完成后，再把当前实现分支合并回 base 分支。
+- 如果用户选择 `archive-then-merge-worktree`，必须仅在 `temporary_worktree: true` 时执行；先归档，再合并到目标分支，最后删除临时 worktree，并将状态设为 `archived`。
+- 如果用户选择 `archive-only`，直接执行 OpenSpec archive，并将状态设为 `archived`；不自动合并。若 `temporary_worktree: false`，也不得删除工作区或 worktree。
+- 如果用户选择 `discard-worktree`，不执行归档，不把废弃分支代码合入 base 分支。
+- 只有真正执行 archive 后，才删除运行时状态文件：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" cleanup-runtime <change-id>
+```
+
+实际执行收尾动作时，优先使用：
+
+```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>
+```
+
+归档前必须确认：
+
+- `tasks.md` 已按实际完成项勾选
+- 项目测试已通过，或未通过项已明确说明
+- `openspec validate <change-id> --strict` 已通过
+- 用户明确选择了合并、废弃、删除 worktree 或归档策略
+- 没有未处理的用户评审反馈
+
+## 4. 汇报
+
+收尾汇报必须覆盖：
+
+- 用户评审结果
+- 选择的收尾路径：先归档再合并、仅归档，或废弃 worktree
+- 分支/worktree 的最终状态
+- 当前分支与 `origin_branch` 的关系，以及是否仍保留临时 worktree
+- `tasks.md`、测试与 OpenSpec validate 状态
+- archive 字段：`skipped` 或 `archived`
+
+## 5. 停止条件
+
+以下情况必须暂停并向用户说明：
+
+- 用户还没有完成最终评审
+- 用户没有明确选择收尾路径
+- 用户没有明确确认归档并合并、仅归档，或废弃 worktree
+- 代码尚未归档时，却要求直接合并到目标分支
+- 测试或 `openspec validate <change-id> --strict` 未通过且用户未明确接受风险

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

@@ -1,22 +1,13 @@
----
-name: onespec-design
-description: 当用户需要为 OpenSpec change 做需求澄清、proposal、design、tasks、spec delta、复杂度分析或批准路径选择时使用。
----
+# Design Phase
 
-# OneSpec Design
-
-用于 OneSpec 的设计与提案阶段。目标是把需求转成已审批前的 OpenSpec artifacts，并推荐后续执行路径。
-
-开始时说明：
-
-> 我正在使用 `onespec-design` 处理 proposal / design 阶段。
+供 `onespec` 在 `propose` 阶段按需读取。目标是把需求转成已审批前的 OpenSpec artifacts，并推荐后续执行路径。
 
 ## 1. 接入
 
 先恢复状态：
 
 ```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 @@ ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.agents "$HOME"/.con
 "$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
 ```
 
-`recover` 的输出是当前阶段合同，不是参考信息。至少先读取 `phase`、`next_skill`、`next_gate` 与 `allowed_actions`，再决定是否继续设计阶段动作。
+`recover` 的输出是当前阶段合同，不是参考信息。至少先读取 `phase`、`next_skill`、`next_reference`、`next_gate` 与 `allowed_actions`，再决定是否继续设计阶段动作。
 
 读取最少必要上下文：
 
-- `openspec/config.yaml`、`openspec/project.md`、`openspec/specs/**` 中与任务相关的部分
+- `openspec/config.yaml`、`openspec/specs/**` 中与任务相关的部分
 - 项目入口文档，如 `AGENTS.md`、`README.md`、`docs/**` 中与任务相关的部分
 - 当前分支和工作区状态
 
@@ -141,64 +132,77 @@ OpenSpec artifacts 写完后，不要只汇报“proposal 已生成”。必须
 - change id 与 artifact 位置
 - 对 task artifact 的简短摘要
 - 复杂度等级与具体原因
-- 推荐路线：`建议使用 Superpowers 实现` 或 `建议直接使用 OpenSpec apply`
+- 推荐组合，而不是只推荐抽象路线：
+  - `OpenSpec apply + native + current branch`
+  - `Superpowers + subagent + new worktree`
+  - `Superpowers + subagent + current worktree/current branch`
 - 用户可覆盖推荐
 
+### 3.1 用户确认请求规则
+
+当输出结果后需要用户决定是否批准、是否进入实现、是否改路径或是否继续停留时，必须把“需要用户选择”作为独立块输出，标题固定为 `用户确认请求`。不要把结论、推荐意见和等待用户确认混成同一段。
+
+确认块必须包含：
+
+- 一句明确指令：`请回复编号。`
+- 2-4 个编号选项，其中第 1 项通常是推荐项，并标注“推荐”
+- `其他：` 说明用户可以补充条件或提出不在菜单中的操作
+- 如果用户补充了新条件但还没有形成明确选择，继续给出新的编号选项，直到用户明确选择、终止或要求继续往下走
+
+如果平台提供结构化询问能力，例如 `ask user questions`、`request_user_input` 或等价 UI，优先用结构化询问承载这些编号选项；如果当前环境没有这类能力，则在普通消息中输出上述 `用户确认请求` 块。无论使用哪种形式，都不能只给一句“推荐使用某路径”就结束。
+
 ## 4. Proposal 批准 Gate 与路径选择
 
 默认意图映射、issue workflow 路由或实现路径推荐，不等于 proposal 已获批。
 
-只有用户明确批准 proposal / design / spec 后，才允许进入实现计划。设计阶段结束时，不要只给一句自由文本，也不要只要求用户输入 `批准`、`yes`、`continue` 等完整词；必须给出“显式选项 + 推荐项 + 可直接回复的口令”菜单。用户可以回复数字，也可以直接回复对应口令。沉默、“看起来还行”、最初的“开始实现”、“执行这个 change”或“make plan”都不算对 proposal 产物的批准。
+只有用户明确批准 proposal / design / spec 后，才允许进入实现计划。设计阶段结束时，不要只给一句自由文本，也不要要求用户输入 `批准`、`yes`、`continue` 等完整词；必须给出“显式编号选项 + 推荐项”菜单。用户只需回复数字编号。沉默、“看起来还行”、最初的“开始实现”、“执行这个 change”或“make plan”都不算对 proposal 产物的批准。
+
+生成批准菜单前先确定推荐组合：
 
-默认使用下面这组批准菜单，并把推荐路径写进第 1 项：
+- 如果推荐 `OpenSpec apply`，组合固定为 `OpenSpec apply + native + current branch`，记录 `implementation_path=openspec-apply`、`execution_method=native`、`workspace=current-branch`（如果当前是 `main`/`master` 且项目文档禁止直接修改主分支，先暂停提示风险）。
+- 如果推荐 `Superpowers`，默认执行方式是 `subagent`；只有 task 强耦合、不适合逐 task 派发，或用户/平台明确不能使用 subagent 时，才推荐 `local`。
+- 判断当前是否已经位于附加 git worktree：分别读取 `git rev-parse --path-format=absolute --git-dir` 与 `git rev-parse --path-format=absolute --git-common-dir`；两者不相同则当前就是附加 worktree。若命令不可用，可退回 `git worktree list --porcelain` 并用当前 `pwd -P` 匹配 `worktree` 条目。
+- 如果当前已经在附加 worktree 中，不推荐再创建新 worktree；推荐组合写成 `Superpowers + <subagent|local> + current worktree/current branch`，状态里记录 `workspace=current-branch`，因为执行位置就是当前 checkout。
+- 如果当前不在附加 worktree 中且推荐 `Superpowers`，默认推荐 `Superpowers + subagent + new worktree`，以便隔离实现分支；状态里记录 `workspace=worktree`。
 
-1. 批准当前 proposal / design / spec，并按推荐路径继续实现（推荐）
-   可直接回复：`批准，按推荐路径继续`
+默认使用下面这组批准菜单，并把推荐组合写进第 1 项。菜单必须解释组合由三部分构成：实现路径 + 执行方式 + 工作区策略。
+
+1. 批准当前 proposal / design / spec，并按推荐组合继续实现：`<recommended-combination>`（推荐）
 2. 批准当前 proposal / design / spec，但我要改实现路径、执行方式或工作区
-   可直接回复：`批准，但我要改实现路径`
 3. 先修改 proposal / design / tasks / spec；我会补充要改的点
-   可直接回复：`先修改 proposal`
 4. 先停在设计阶段，暂不进入实现
-   可直接回复：`先停在设计阶段`
 其他：如果意图不在以上选项里，允许用户直接补充说明其他操作
 
 菜单解释规则：
 
-- 用户回复 `1` 或 `批准，按推荐路径继续`：视为批准当前 artifacts，并接受当前推荐路径。
-- 用户回复 `2` 或 `批准，但我要改实现路径`：视为批准当前 artifacts，但要覆盖推荐路线；此时继续给出下一层显式选项，只询问仍未确认的维度。
-- 用户回复 `3` 或 `先修改 proposal`：继续留在 `onespec-design`，根据用户反馈修改 artifacts，不进入实现。
-- 用户回复 `4` 或 `先停在设计阶段`：暂停在设计阶段，等待用户后续指令。
+- 用户回复 `1`：视为批准当前 artifacts，并接受当前推荐组合；不要再二次询问 `subagent/local` 或 `worktree/current-branch`，直接记录该组合对应的 `implementation_path`、`execution_method` 与 `workspace`。
+- 用户回复 `2`：视为批准当前 artifacts，但要覆盖推荐组合；此时继续给出组合菜单，不要把 `subagent/local` 与 `worktree/current-branch` 拆成两轮问题。
+- 用户回复 `3`：继续留在 design phase，根据用户反馈修改 artifacts，不进入实现。
+- 用户回复 `4`：暂停在设计阶段，等待用户后续指令。
 - 用户输入其他自由文本：如果意图清晰，按用户自定义意图处理；如果仍有歧义，只追问一个最短的澄清问题。
 
-如果用户选择 `Superpowers`，一次性确认两个选择：
-
-- 执行方式：`subagent` 或 `local`。默认推荐 `subagent`，对应 `subagent-driven-development`；`local` 对应当前 agent 使用 `executing-plans`。
-- 工作区：`worktree` 或 `current-branch`。
-
-当用户选择第 2 项，后续确认也改成“显式选项 + 推荐项 + 可直接回复口令”菜单，不要只给数字或只给一句自由文本。推荐顺序如下：
-
-- 实现路径：
-  1. `Superpowers`（推荐）
-     可直接回复：`使用 Superpowers`
-  2. `OpenSpec apply`
-     可直接回复：`使用 OpenSpec apply`
-- 如果选择 `Superpowers`，执行方式：
-  1. `subagent`（推荐）
-     可直接回复：`使用 subagent`
-  2. `local`
-     可直接回复：`使用 local`
-- 工作区：
-  1. `worktree`（推荐）
-     可直接回复：`使用 worktree`
-  2. `current-branch`
-     可直接回复：`使用 current-branch`
-  其他：允许用户补充说明特殊工作区安排
+当用户选择第 2 项，后续确认也使用“显式编号组合选项 + 推荐项”菜单；用户只需回复数字编号。不要只给一句自由文本，也不要在每个选项下附加口令提示。根据当前是否已经在附加 worktree 中生成菜单：
+
+- 如果当前不在附加 worktree 中，默认菜单：
+  1. `Superpowers + subagent + new worktree`（推荐）
+  2. `Superpowers + local + new worktree`
+  3. `Superpowers + local + current branch`
+  4. `OpenSpec apply + native + current branch`
+  其他：允许用户补充说明特殊组合；例如明确要求 `Superpowers + subagent + current branch`
+- 如果当前已经在附加 worktree 中，默认菜单：
+  1. `Superpowers + subagent + current worktree/current branch`（推荐）
+  2. `Superpowers + local + current worktree/current branch`
+  3. `OpenSpec apply + native + current worktree/current branch`
+  其他：允许用户补充说明特殊组合；不要推荐再创建新的 worktree
 
 `main`/`master` 规则：
 
 - 不在 `main`/`master` 上直接实现，除非用户在看到风险提示后明确要求。
-- 如果当前在 `main`/`master` 且选择 `Superpowers`，不因分支名自动创建 worktree；按用户或项目默认工作区设置处理。若使用 `current-branch`，先提示风险并记录为 `main-override`。
+- 如果当前在 `main`/`master` 且选择 `Superpowers + current branch`，先提示风险并记录为 `main-override`；若选择 `new worktree`，按 worktree 创建规则处理。
 - 如果当前在功能分支且工作区干净，可以使用 `current-branch`。
+- 如果准备切到 `worktree`，但当前工作区存在未提交改动，必须先处理这些改动，再创建 worktree。尤其当前分支是 `main`/`master` 时，不允许带着未提交代码直接创建临时 worktree。
+- 对 `main`/`master` 上的未提交改动，默认要求先按项目提交规范创建本地 commit，再创建临时分支 / worktree；不要把未提交的 base 分支代码隐式带进新的实现分支。
+- 如果用户明确拒绝先提交当前 dirty 改动，则不要继续创建 worktree；此时只能停下等待、改走 `current-branch`，或让用户先整理当前分支状态。
 
 确认后记录：
 
@@ -213,7 +217,7 @@ OpenSpec artifacts 写完后，不要只汇报“proposal 已生成”。必须
 "$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase approved
 ```
 
-这里的 `origin_*` 字段表示“用户最初开始这次 change 时所在的分支和工作区”。后续如果实现发生在新 branch 或临时 worktree 中，`onespec-execute` 与 `onespec-archive` 必须拿它来提示用户当前 review 位置与收尾选项。
+这里的 `origin_*` 字段表示“用户最初开始这次 change 时所在的分支和工作区”。后续如果实现发生在新 branch 或临时 worktree 中，execute phase 与 archive phase 必须拿它来提示用户当前 review 位置与收尾选项。
 
 ## 5. 停止条件