@kafka0102/onespec 0.1.2 → 0.1.14

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

@@ -1,22 +1,13 @@
----
-name: onespec-execute
-description: 当用户需要执行已批准 OpenSpec change、继续实现、生成 Superpowers plan、运行 OpenSpec apply、回填 tasks 或验证实现时使用。
----
-
-# OneSpec Execute
-
-用于 OneSpec 的执行阶段。目标是只在已批准范围内实现，并把实现结果回填 OpenSpec 状态。
+# Execute Phase
 
-开始时说明：
-
-> 我正在使用 `onespec-execute` 处理 apply / implement 阶段。
+供 `onespec` 在 `apply` 阶段按需读取。目标是只在已批准范围内实现，并把实现结果回填 OpenSpec 状态。
 
 ## 1. Apply 路由
 
 先恢复状态：
 
 ```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 @@ 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`，再决定是否继续执行阶段动作。
 
 apply 前至少读取：
 
@@ -51,20 +42,36 @@ apply 前至少读取：
 - 用户确认原生 `OpenSpec apply`：切换到原生 OpenSpec apply。
 - 用户尚未确认：提醒当前推荐路线，并用编号菜单要求用户选择，不要直接开始实现。
 
-如果必须在执行阶段补做路线确认，使用下面的编号菜单，用户回复数字即可：
-
-1. 按推荐路线继续
-2. 改成 `Superpowers`
-3. 改成原生 `OpenSpec apply`
-4. 先不要开始实现，我要先回去修改 proposal / design / tasks
+如果必须在执行阶段补做路线确认，先判断当前是否已经在附加 git worktree 中，再使用对应编号菜单；用户回复数字即可。
+
+当前不在附加 worktree 中时：
+1. 按推荐组合继续
+2. 改成 `Superpowers + subagent + new worktree`
+3. 改成 `Superpowers + local + new worktree`
+4. 改成 `Superpowers + local + current branch`
+5. 改成原生 `OpenSpec apply + native + current branch`
+6. 先不要开始实现，我要先回去修改 proposal / design / tasks
+
+当前已经在附加 worktree 中时：
+1. 按推荐组合继续
+2. 改成 `Superpowers + subagent + current worktree/current branch`
+3. 改成 `Superpowers + local + current worktree/current branch`
+4. 改成原生 `OpenSpec apply + native + current worktree/current branch`
+5. 先不要开始实现，我要先回去修改 proposal / design / tasks
 其他：如果意图不在以上选项里，允许用户直接补充说明
 
 菜单解释规则：
 
-- 用户回复 `1`：采用当前推荐路线。
-- 用户回复 `2`：切换到 `Superpowers`，并继续用编号菜单确认 `subagent/local` 与 `worktree/current-branch`。
-- 用户回复 `3`：切换到原生 `OpenSpec apply`。
-- 用户回复 `4`：停止执行，返回设计修订路径。
+- 用户回复 `1`：采用当前推荐组合；不要再二次询问 `subagent/local` 或 `worktree/current-branch`。
+- 当前不在附加 worktree 中时，用户回复 `2`：记录 `implementation_path=superpowers`、`execution_method=subagent`、`workspace=worktree`。
+- 当前不在附加 worktree 中时，用户回复 `3`：记录 `implementation_path=superpowers`、`execution_method=local`、`workspace=worktree`。
+- 当前不在附加 worktree 中时，用户回复 `4`：记录 `implementation_path=superpowers`、`execution_method=local`、`workspace=current-branch`。
+- 当前不在附加 worktree 中时，用户回复 `5`：记录 `implementation_path=openspec-apply`、`execution_method=native`、`workspace=current-branch`。
+- 当前不在附加 worktree 中时，用户回复 `6`：停止执行，返回设计修订路径。
+- 当前已经在附加 worktree 中时，用户回复 `2`：记录 `implementation_path=superpowers`、`execution_method=subagent`、`workspace=current-branch`。
+- 当前已经在附加 worktree 中时，用户回复 `3`：记录 `implementation_path=superpowers`、`execution_method=local`、`workspace=current-branch`。
+- 当前已经在附加 worktree 中时，用户回复 `4`：记录 `implementation_path=openspec-apply`、`execution_method=native`、`workspace=current-branch`。
+- 当前已经在附加 worktree 中时，用户回复 `5`：停止执行，返回设计修订路径。
 - 用户输入数字外的自由文本：如果意图清晰，按用户自定义意图处理；若不清晰，只补一个最短澄清问题。
 
 ## 2. Superpowers Make Plan 与实现
@@ -113,6 +120,27 @@ apply 前至少读取：
 "$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_mode "$( "$ONESPEC_BASH" "$ONESPEC_STATE" get <change-id> workspace )"
 ```
 
+如果接下来要从当前分支创建临时 worktree，先检查当前工作区是否有未提交改动：
+
+- 若当前工作区是 dirty，必须先处理这些改动，再创建 worktree。
+- 若当前分支是 `main`/`master` 且存在未提交改动，默认要求先按项目提交规范创建本地 commit，再创建 worktree；不允许把未提交的 base 分支代码直接带进新的实现分支。
+- 若用户不接受先提交当前 dirty 改动，则不要继续创建 worktree；应暂停，或改走 `current-branch` 路线并明确风险。
+
+### 2.1 实现工作区定位
+
+创建或选择实现 worktree 后，必须立即把实现工作区绝对路径绑定为 `implementation_workspace_path`，并在写计划前验证它就是后续命令的工作目录：
+
+```bash
+implementation_workspace_path="$(pwd -P)"
+git -C "$implementation_workspace_path" status --short
+```
+
+- 如果选择 `workspace=worktree`，必须先进入新 worktree，再设置 `implementation_workspace_path`；不要在原工作区继续生成计划。
+- 如果选择 `workspace=current-branch` 或当前已经在附加 worktree 中，`implementation_workspace_path` 就是当前 `pwd -P`。
+- 所有读取 OpenSpec artifacts、写入 Superpowers plan、更新 `.onespec.yaml`、生成 handoff 与后续实现命令，都必须以实现工作区为工作目录。
+- 计划路径 `docs/superpowers/plans/YYYY-MM-DD-<change-id>.md` 始终相对于 `implementation_workspace_path`。不得在原工作区先写计划再复制到实现 worktree。
+- 记录计划与 handoff 前，必须用 `git -C "$implementation_workspace_path" status --short` 确认 plan 和 `.onespec.yaml` 出现在同一个实现工作区。
+
 默认执行路径：
 
 - 优先使用 `subagent-driven-development`。
@@ -156,7 +184,7 @@ apply 前至少读取：
 
 > ⚠️ 这是强制 gate。如果 gate 未通过，不允许输出任何总结或收尾建议，不允许进入下一阶段。
 
-完成实现与验证后，必须明确暂停，不允许直接继续做 merge、删除 worktree、归档或“顺手收尾”。这里的目标是进入用户评审 / `review-closeout` 等待态；开发完成后只需询问是否进行归档，不需要再要求用户先确认 review。
+完成实现与验证后，必须明确暂停，不允许直接继续做 merge、删除 worktree、归档或“顺手收尾”。这里的目标是进入用户评审 / `review-closeout` 等待态；开发完成后直接给出收尾动作菜单，不需要再要求用户先确认 review，也不要把归档拆成二次确认。
 
 ### 5.1 强制脚本调用
 
@@ -196,15 +224,37 @@ apply 前至少读取：
 📍 当前工作区: `<path>`
 📍 origin: `<origin_branch>` @ `<origin_workspace_path>`
 
-1. 进入 `onespec-archive`，选择删除 worktree / 归档相关操作
-2. 保持当前分支 / worktree 不变，先停在这里，稍后再继续
-其他：任意非编号内容视为继续修改当前实现；如果意图不在以上选项里，也可以直接补充说明
+1. 归档当前 change，并合并分支到 base 分支
+2. 直接归档，不合并到 base 分支
+3. 删除当前临时 worktree，废弃代码
+其他：任意非编号内容视为继续修改当前实现；用户未输入时默认停留在当前评审阶段
 ---
 ```
 
+如果当前不在临时 worktree，且当前分支就是 `origin_branch`，并且该分支是 `main` 或 `master`，则不要提示“合并分支到 base 分支”或“删除当前临时 worktree”。此时收尾菜单必须收缩为仅归档一个选项：
+
+```
+---
+✅ 实现与验证已完成。
+
+📍 当前分支: `<branch>`
+📍 当前工作区: `<path>`
+📍 origin: `<origin_branch>` @ `<origin_workspace_path>`
+
+1. 直接归档（当前已在 `main/master`，无需额外合并分支）
+其他：任意非编号内容视为继续修改当前实现；用户未输入时默认停留在当前评审阶段
+---
+```
+
+也就是说，`master/main` 分支就不要提示合并分支/删除 worktree。
+
 如果当前分支或工作区不同于 `origin_*`，还必须额外说明："当前实现位于临时分支或临时 worktree；若你直接回复非编号内容，我会按继续修改处理。"
 
-不要只停在“下一步应进入 `onespec-archive`”这种抽象提示，也不要只说“做 `review-closeout`”。必须同时给出用户可直接回复的编号选项。
+- 选择 `1` 时，archive phase 必须按“先归档，再合并分支到 base 分支”的固定顺序执行。
+- 选择 `2` 时，archive phase 只做归档，不合并分支，也不自动删除当前 worktree。
+- 选择 `3` 时，archive phase 删除当前临时 worktree 并废弃代码，不执行归档。
+
+不要只停在“下一步应进入 archive phase”这种抽象提示，也不要只说“做 `review-closeout`”。必须同时给出用户可直接回复的编号选项。
 
 ### 5.4 反模式（NEVER）
 
@@ -213,7 +263,7 @@ apply 前至少读取：
 - 实现完成后直接输出"已完成"总结，而未执行 5.1 的脚本
 - 汇报中缺少当前分支/工作区信息（checklist 第 1-3 项）
 - 未给出明确的下一步编号选项
-- 将 archive / merge / worktree 删除操作混入实现完成汇报
-- 在用户未回复前自行进入 `onespec-archive` 阶段
-- 用"下一步应进入 onespec-archive"这种抽象描述替代具体编号菜单
+- 在用户尚未选择前，直接执行 archive / merge / worktree 删除操作
+- 在用户未回复前自行进入 archive phase 阶段
+- 用"下一步应进入 archive phase"这种抽象描述替代具体编号菜单
 - 在用户完成 review 并明确要求收尾前，擅自删除临时 worktree

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

@@ -0,0 +1,110 @@
+# Fast Path
+
+供 `onespec` 和独立 `onespec-fast` 入口在 `fast` 路径按需读取。目标是省掉常规 proposal 批准 gate、复杂度检查、实现路径选择和实现完成后的人工归档选择。进入 fast 路径后，全程使用原生 `OpenSpec apply` 实现并直接归档。
+
+## 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`。
+
+适用规则：
+
+- 仅在用户明确要求 `onespec-fast`、快速路径、fast apply、OpenSpec 自动 proposal/开发/归档或自动贯通时使用。
+- 不要询问 change 名称。根据任务自动生成简短短横线命名的 `change-id`，如冲突则追加数字。
+- 读取最少必要上下文：`openspec/config.yaml`、`openspec/project.md`、相关 `openspec/specs/**`、项目入口文档、当前分支和工作区状态。
+- 只有 OpenSpec 必需上下文缺失到无法写出有效 proposal、或项目文档明确禁止自动修改当前分支时才暂停。
+
+## 2. 直接 Proposal
+
+快速路径跳过常规 design phase 的 proposal 前用户确认。
+
+必须直接进入 OpenSpec proposal 产出：
+
+- `openspec/changes/<change-id>/proposal.md`
+- `openspec/changes/<change-id>/design.md`，仅在确有技术设计价值时创建
+- `openspec/changes/<change-id>/tasks.md`
+- 必要的 `specs/**/spec.md`
+
+创建状态与交接包：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" init <change-id>
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase proposal-ready
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> ambiguity low
+"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> proposal --write
+```
+
+不要输出常规 proposal 批准菜单。`onespec-fast` 的用户意图表示授权继续使用原生 `OpenSpec apply` 开发并归档。
+
+## 3. OpenSpec 自动开发与归档
+
+proposal 产出后不要进行复杂度检查，也不要切换到 Superpowers plan/subagent。直接记录快速路径并进入实现：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> implementation_path openspec-apply
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> execution_method native
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> workspace current-branch
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_branch "$(git branch --show-current || echo detached)"
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_path "$(pwd -P)"
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_mode current-branch
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase approved
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase implementing
+```
+
+实现规则：
+
+- 使用原生 `OpenSpec apply` 路径，不生成 Superpowers plan，不派发 subagent。
+- 只实现 `tasks.md` 中的未完成任务，不扩大 proposal 范围。
+- 直接修改当前工作区；不自动创建 worktree，不自动 push，不自动 merge。
+- 如果当前分支是 `main`/`master`，把 `origin_workspace_mode` 改记为 `main-override`，但只有项目文档明确禁止直接修改主分支时才暂停。
+- 本次直接修改的仓库相对路径写入 `.onespec.yaml`，优先使用：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" track <change-id> <path>...
+```
+
+实现完成后必须：
+
+- 勾选 `tasks.md` 中已完成的任务。
+- 如实现暴露新的设计冲突，停止自动实现，修正 OpenSpec artifacts，并继续留在 OpenSpec proposal/apply 路径；只有用户另行要求时才切换到 Superpowers。
+- 运行项目测试。
+- 运行 `openspec validate <change-id> --strict`。
+- 写入 review handoff，但不要暂停等待用户评审：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase review
+"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> review --write
+```
+
+随后直接归档，不展示 archive phase 的收尾菜单：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" related-dirty <change-id>
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" commit-related <change-id> closeout
+"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" run-actions <change-id> archive-only
+```
+
+如果 `related-dirty` 为空，不需要执行 `commit-related <change-id> closeout`。`run-actions` 会把状态置为 `archived` / `archive archived`，并负责 archive 后提交与 runtime cleanup。
+
+## 4. 停止条件
+
+以下情况必须暂停：
+
+- OpenSpec 必需上下文缺失，无法写出有效 proposal。
+- 用户请求明显跨多个应该拆开的 change。
+- 测试或 `openspec validate <change-id> --strict` 未通过且无法在已批准范围内修复。
+- 实现过程中发现需要扩大 scope、改变 design 或修改 spec 语义。
+- 项目文档明确禁止当前分支上的自动实现或自动归档。