@kafka0102/onespec 0.1.2

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

@@ -0,0 +1,226 @@
+---
+name: onespec-design
+description: 当用户需要为 OpenSpec change 做需求澄清、proposal、design、tasks、spec delta、复杂度分析或批准路径选择时使用。
+---
+
+# OneSpec Design
+
+用于 OneSpec 的设计与提案阶段。目标是把需求转成已审批前的 OpenSpec artifacts，并推荐后续执行路径。
+
+开始时说明：
+
+> 我正在使用 `onespec-design` 处理 proposal / design 阶段。
+
+## 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_BASH" "$ONESPEC_STATE" list
+```
+
+如果发现相关 change，必须继续执行：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
+```
+
+`recover` 的输出是当前阶段合同，不是参考信息。至少先读取 `phase`、`next_skill`、`next_gate` 与 `allowed_actions`，再决定是否继续设计阶段动作。
+
+读取最少必要上下文：
+
+- `openspec/config.yaml`、`openspec/project.md`、`openspec/specs/**` 中与任务相关的部分
+- 项目入口文档，如 `AGENTS.md`、`README.md`、`docs/**` 中与任务相关的部分
+- 当前分支和工作区状态
+
+不要询问变更名称。根据任务自动生成简短短横线命名的 `change-id`，如冲突则追加数字。
+
+## 2. 歧义扫描与 Proposal 路由
+
+生成任何 OpenSpec artifact 前，显式做一次 ambiguity scan，并写明分类结果和触发原因。
+
+至少检查：
+
+- 是否存在多个合理 scope
+- 是否存在多个合理行为解释
+- 是否存在多个合理技术方案
+- 是否需要用户肉眼确认视觉方向、布局或交互方案
+- 验收标准是否缺失
+- non-goals 是否缺失
+- rollout / migration / compatibility 假设是否缺失
+- 是否一次跨了多个本该拆分的独立子系统
+
+分类规则：
+
+- `低歧义`：范围基本单一，方案基本清晰，验收标准大部分可从项目文档或现有 spec 推出。
+- `高歧义`：存在两个以上合理解释，或如果现在直接写 proposal 很可能会把猜测写进正式文档。
+
+完成 ambiguity scan 后，必须先给用户一个明确的分类输出，再进入下一步；不允许静默直接写 proposal、design、tasks 或 spec。
+
+用户可见输出至少包含：
+
+- 判定结果：`低歧义` 或 `高歧义`
+- 触发原因：1-3 条，说明为什么这样分类
+- 处理方式：接下来会做什么，以及是否需要用户先确认
+
+推荐输出模板：
+
+- `低歧义：当前需求属于低歧义，因为 <原因1>、<原因2>。处理方式：我将直接起草 OpenSpec proposal；如果过程中发现还缺一个关键前提，我只会先问一个简短问题，不会带着猜测写入正式文档。`
+- `高歧义：当前需求属于高歧义，因为 <原因1>、<原因2>。处理方式：我不会直接写 proposal；我会先进入 brainstorming，先和你确认 scope / 行为 / 技术方案中的关键分歧，再基于确认结果回填 OpenSpec artifacts。`
+
+低歧义流程：
+
+- 先输出一次明确的低歧义结论和处理方式。
+- 如果无需用户交互式 UI / 视觉确认，且没有必须进一步询问的问题，再进入 OpenSpec proposal。
+- 如果仍有必须补齐的问题，只问一个简短问题，得到回答后重新执行 ambiguity scan。
+- 如果存在必须补齐的问题，在拿到回答前不要创建任何 OpenSpec artifact。
+- 对低歧义任务不要调用 brainstorming。
+
+高歧义流程：
+
+- 先输出一次明确的高歧义结论和处理方式。
+- 在完成这次说明前，不要创建任何 OpenSpec artifact。
+- 明确说明将先进入 `brainstorming`，再写 OpenSpec artifacts。
+- 使用 `brainstorming` 或 `superpowers:brainstorming`，一次只问一个问题，提出 2-3 个可行方案并说明 trade-off，形成已确认的设计文档。
+- Brainstorming 文档被用户确认后，以该文档、相关 `docs/**` 与相关 `openspec/specs/**` 为输入，回填 OpenSpec artifacts。不要重复追问已确认的问题。
+
+视觉设计触发规则：
+
+- 如果用户要求“给我看设计效果”、“给我看页面方案”、“出 UI / UX 方案”、“做视觉设计 / 视觉升级”、“出原型 / mockup / wireframe”、“浏览器里给我看效果”，或明确要求比较布局、样式、视觉方向，默认视为需要视觉化设计确认。
+- 出现这类诉求时，不要继续按纯文本澄清推进；只要当前 change 还没有被批准为固定视觉方案，就应路由到带 visual companion 的 brainstorming。
+- visual companion 是可扩展模块，不绑定固定仓库文件名或固定实现。它可以由项目内现成模块、本地原型、浏览器预览页或其他可视化工作流承载。
+- 涉及 mockup、wireframe、布局比较、视觉风格比较或页面效果确认时，先单独发送 visual companion offer，消息里不能混入其他内容；等待用户确认后，启动当前环境里可用的 visual companion 流程，提供本地 URL、原型入口或等价的可视化载体，并给出第一版可视化方案。用户拒绝后，才允许继续纯文本 brainstorming。
+- 不要因为仓库里缺少某个固定的 visual companion 文件就中止流程，也不要把“检查某个预设文件是否存在”当成前置 gate。只有当当前环境里完全没有可用的可视化实现路径时，才退回 `text-only` brainstorming，并明确告知这是降级路径。
+
+## 3. Proposal 完成后的任务分析
+
+生成或更新 OpenSpec 产物：
+
+- `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|high>
+"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> proposal --write
+```
+
+OpenSpec artifacts 写完后，不要只汇报“proposal 已生成”。必须读取 task artifact 并给出实现路径推荐。
+
+任务分析输入：
+
+- `openspec/changes/<change-id>/tasks.md`
+- `proposal.md`
+- `design.md`，如果存在
+- 相关 `openspec/specs/**`
+- 如果当前 schema 不是 `spec-driven`，读取 `openspec status --change "<change-id>" --json` 或 `openspec instructions apply --change "<change-id>" --json` 中定义的任务 artifact 或等价 apply context
+
+至少分析：
+
+- 未完成 task 总数，以及是否能自然拆成独立小步
+- 是否跨多个 workspace、业务模块或 capability
+- 是否同时涉及前端、后端、数据库、后台任务、共享包、spec/doc 回填
+- 是否存在 migration、兼容性、上线顺序、异步流程、数据修复或人工验证环节
+- task 之间是否强依赖，是否需要严格的 review gate / TDD / 分步验收
+
+复杂度分级与推荐：
+
+- `低复杂度`：默认推荐原生 `OpenSpec apply`。task 数量少，路径线性，单模块或少量文件改动，几乎没有跨层依赖，也不涉及 migration / schema / 多端联动。
+- `中复杂度`：存在少量跨模块或跨端协作，但边界清晰。若更需要分工、TDD、review gate、分阶段验证，推荐 `Superpowers`；若 task 线性且边界稳定，推荐 `OpenSpec apply`。
+- `高复杂度`：明显跨多个 workspace 或 capability，涉及 API、数据库、任务系统、共享包、视觉确认中的多个维度，或 task 依赖强。默认推荐 `Superpowers`。
+
+输出时必须明确：
+
+- change id 与 artifact 位置
+- 对 task artifact 的简短摘要
+- 复杂度等级与具体原因
+- 推荐路线：`建议使用 Superpowers 实现` 或 `建议直接使用 OpenSpec apply`
+- 用户可覆盖推荐
+
+## 4. Proposal 批准 Gate 与路径选择
+
+默认意图映射、issue workflow 路由或实现路径推荐，不等于 proposal 已获批。
+
+只有用户明确批准 proposal / design / spec 后，才允许进入实现计划。设计阶段结束时，不要只给一句自由文本，也不要只要求用户输入 `批准`、`yes`、`continue` 等完整词；必须给出“显式选项 + 推荐项 + 可直接回复的口令”菜单。用户可以回复数字，也可以直接回复对应口令。沉默、“看起来还行”、最初的“开始实现”、“执行这个 change”或“make plan”都不算对 proposal 产物的批准。
+
+默认使用下面这组批准菜单，并把推荐路径写进第 1 项：
+
+1. 批准当前 proposal / design / spec，并按推荐路径继续实现（推荐）
+   可直接回复：`批准，按推荐路径继续`
+2. 批准当前 proposal / design / spec，但我要改实现路径、执行方式或工作区
+   可直接回复：`批准，但我要改实现路径`
+3. 先修改 proposal / design / tasks / spec；我会补充要改的点
+   可直接回复：`先修改 proposal`
+4. 先停在设计阶段，暂不进入实现
+   可直接回复：`先停在设计阶段`
+其他：如果意图不在以上选项里，允许用户直接补充说明其他操作
+
+菜单解释规则：
+
+- 用户回复 `1` 或 `批准，按推荐路径继续`：视为批准当前 artifacts，并接受当前推荐路径。
+- 用户回复 `2` 或 `批准，但我要改实现路径`：视为批准当前 artifacts，但要覆盖推荐路线；此时继续给出下一层显式选项，只询问仍未确认的维度。
+- 用户回复 `3` 或 `先修改 proposal`：继续留在 `onespec-design`，根据用户反馈修改 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`
+  其他：允许用户补充说明特殊工作区安排
+
+`main`/`master` 规则：
+
+- 不在 `main`/`master` 上直接实现，除非用户在看到风险提示后明确要求。
+- 如果当前在 `main`/`master` 且选择 `Superpowers`，不因分支名自动创建 worktree；按用户或项目默认工作区设置处理。若使用 `current-branch`，先提示风险并记录为 `main-override`。
+- 如果当前在功能分支且工作区干净，可以使用 `current-branch`。
+
+确认后记录：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> complexity <low|medium|high>
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> implementation_path <openspec-apply|superpowers>
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> execution_method <subagent|local|native>
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> workspace <worktree|current-branch|main-override>
+"$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 <worktree|current-branch|main-override>
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase approved
+```
+
+这里的 `origin_*` 字段表示“用户最初开始这次 change 时所在的分支和工作区”。后续如果实现发生在新 branch 或临时 worktree 中，`onespec-execute` 与 `onespec-archive` 必须拿它来提示用户当前 review 位置与收尾选项。
+
+## 5. 停止条件
+
+以下情况必须暂停并向用户说明：
+
+- 一个请求实际跨了多个应该拆开的子系统
+- OpenSpec 必需上下文缺失到无法安全继续
+- 用户明确要求视觉设计效果，但 visual companion offer 未单独发送或尚未等到用户确认
+- proposal / design / spec 尚未明确批准，但用户要求开始实现
+- 实现路径、执行方式或工作区选择会影响风险但尚未确认

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

@@ -0,0 +1,219 @@
+---
+name: onespec-execute
+description: 当用户需要执行已批准 OpenSpec change、继续实现、生成 Superpowers plan、运行 OpenSpec apply、回填 tasks 或验证实现时使用。
+---
+
+# OneSpec Execute
+
+用于 OneSpec 的执行阶段。目标是只在已批准范围内实现，并把实现结果回填 OpenSpec 状态。
+
+开始时说明：
+
+> 我正在使用 `onespec-execute` 处理 apply / implement 阶段。
+
+## 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_BASH" "$ONESPEC_STATE" list
+```
+
+如果发现相关 change，必须继续执行：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
+```
+
+`recover` 的输出是当前阶段合同，不是参考信息。至少先读取 `phase`、`next_skill`、`next_gate` 与 `allowed_actions`，再决定是否继续执行阶段动作。
+
+apply 前至少读取：
+
+- `openspec/changes/<change-id>/proposal.md`
+- `openspec/changes/<change-id>/tasks.md`
+- `openspec/changes/<change-id>/design.md`，如果存在
+- 相关 `openspec/specs/**`
+- 相关 `docs/**`
+
+默认意图映射：
+
+- 用户说“开始实现”、“执行这个 change”、“apply 这个 proposal / change”、“继续做这个 change”、“开始 coding / 开发”、“make plan”时，默认解释为进入已批准 change 的 Superpowers 实现准备路径，而不是直接原生 `openspec apply`。
+- 只有用户明确说“不用 Superpowers plan”、“不用 subagent”或“直接按 OpenSpec apply”时，才允许走原生 OpenSpec apply。
+- 如果 proposal 阶段已经确认过实现路线，后续 apply 优先遵循该确认结果，不要用默认映射覆盖用户已确认的路线。
+
+如果 proposal 尚未批准，直接停止，不要开始实现。
+
+如果 proposal 阶段已经确认实现路径：
+
+- 用户确认 `Superpowers`：继续 Superpowers Make Plan。
+- 用户确认原生 `OpenSpec apply`：切换到原生 OpenSpec apply。
+- 用户尚未确认：提醒当前推荐路线，并用编号菜单要求用户选择，不要直接开始实现。
+
+如果必须在执行阶段补做路线确认，使用下面的编号菜单，用户回复数字即可：
+
+1. 按推荐路线继续
+2. 改成 `Superpowers`
+3. 改成原生 `OpenSpec apply`
+4. 先不要开始实现，我要先回去修改 proposal / design / tasks
+其他：如果意图不在以上选项里，允许用户直接补充说明
+
+菜单解释规则：
+
+- 用户回复 `1`：采用当前推荐路线。
+- 用户回复 `2`：切换到 `Superpowers`，并继续用编号菜单确认 `subagent/local` 与 `worktree/current-branch`。
+- 用户回复 `3`：切换到原生 `OpenSpec apply`。
+- 用户回复 `4`：停止执行，返回设计修订路径。
+- 用户输入数字外的自由文本：如果意图清晰，按用户自定义意图处理；若不清晰，只补一个最短澄清问题。
+
+## 2. Superpowers Make Plan 与实现
+
+在 Superpowers 路径下，apply 默认不是“直接实现”，而是先把已批准的 OpenSpec change 翻译成 Superpowers 可执行计划。
+
+必须执行：
+
+- 读取并总结 `proposal.md`、`design.md`、`tasks.md`、相关 spec delta 与相关项目文档。
+- 从 `tasks.md` 中提取未完成 task，作为 planning scope。
+- 使用 `writing-plans` 或 `superpowers:writing-plans` 生成计划，保存到 `docs/superpowers/plans/YYYY-MM-DD-<change-id>.md`。
+- 计划必须覆盖每个未完成 OpenSpec task，可拆细，但不得遗漏或扩大范围。
+- 如果已有对应 plan，先检查它是否仍覆盖当前未完成 tasks；不覆盖就更新或重写。
+- 如果 plan 与 OpenSpec artifacts 冲突，先修正 OpenSpec artifacts，再重写 plan。
+- 从开始实现到进入 review 之前，为当前 change 维护 `openspec/changes/<change-id>/.onespec.yaml` 这个唯一运行时状态文件；本次直接修改的仓库相对路径写入其中的 `touched_files_b64`。优先使用：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" track <change-id> <path>...
+```
+
+- 不要把用户原本就存在但不属于本次 change 的脏文件写入这个 tracked file 列表。
+- 如果在 `openspec/changes/<change-id>/` 下生成了临时压缩包、导出包或其他仅服务于本次 change 的工件，也要视为本次 change 的一部分保留到 archive；它们不要求单独写进 `touched_files_b64`，但后续自动提交必须把这些工件与 `.onespec.yaml` 一并提交。
+- 后续如果进入自动提交，`.onespec.yaml` 本身也应随当前 change 一起提交；它不是要提前删除的中间产物，而是 review / archive 前的恢复依据。
+
+记录计划并创建交接包：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> plan <plan-path>
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase plan-ready
+"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> plan --write
+```
+
+在真正开始写代码、运行原生 apply 或派发子任务前，必须先把状态切到 `implementing`：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase implementing
+```
+
+如果还停留在 `approved` 或 `plan-ready`，说明实现尚未正式开始；此时不允许把中途代码编辑误报为“继续实现”。
+
+如果 `origin_branch` 或 `origin_workspace_path` 仍是 `unknown`，则在真正创建 worktree、切换 branch 或开始实现前立即补记当前上下文：
+
+```bash
+"$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 "$( "$ONESPEC_BASH" "$ONESPEC_STATE" get <change-id> workspace )"
+```
+
+默认执行路径：
+
+- 优先使用 `subagent-driven-development`。
+- 子 agent 按 task 执行时，强制遵守 `test-driven-development`。
+- controller 在每个任务后做规格符合性评审和代码质量评审，再进入下一个任务。
+- 如果用户明确要求不用 subagent，或任务强耦合到不适合逐 task 派发，说明原因后改用 `executing-plans`。
+- 需要隔离时使用 `using-git-worktrees`，不要手写绕过它的安全检查。
+
+实现完成后必须回填 OpenSpec artifacts：
+
+- 在 `tasks.md` 中勾选本次完成的任务。
+- 如果 Superpowers plan 将一个 OpenSpec task 拆成多步，只有对应实现、测试和必要 review 完成后，才允许回填该 OpenSpec task。
+- 如果实现改变了已批准事实，先同步更新 `design.md`、`proposal.md` 或 spec delta，再继续。
+- 不允许实现结果与已批准 OpenSpec 范围静默漂移。
+- 运行项目测试和 `openspec validate <change-id> --strict`。
+
+## 3. 原生 OpenSpec Apply
+
+只有当用户选择 `OpenSpec apply`、接受低复杂度推荐，或明确拒绝 Superpowers 时，才允许走原生 OpenSpec apply。
+
+原生 apply 执行后同样要：
+
+- 勾选 `tasks.md`
+- 如实现中暴露新的歧义或设计冲突，先暂停并修正 OpenSpec artifacts，必要时回到 brainstorming
+- 运行项目测试
+- 运行 `openspec validate <change-id> --strict`
+- 进入用户评审，并使用与 5.3 一致的数字菜单暂停等待后续动作
+- 将状态置为 `review`
+
+## 4. 停止条件
+
+以下情况必须暂停并向用户说明：
+
+- proposal 未批准但用户要求直接实现
+- Superpowers plan 与已批准 OpenSpec artifacts 发生冲突
+- `tasks.md` 尚未被翻译成可执行 Superpowers plan，但模型试图直接编码
+- 实现过程中发现会改变 scope、design 或 spec 的新需求
+- 测试或 `openspec validate <change-id> --strict` 未通过且尚未修复
+
+## 5. 实现完成 Gate（强制暂停）
+
+> ⚠️ 这是强制 gate。如果 gate 未通过，不允许输出任何总结或收尾建议，不允许进入下一阶段。
+
+完成实现与验证后，必须明确暂停，不允许直接继续做 merge、删除 worktree、归档或“顺手收尾”。这里的目标是进入用户评审 / `review-closeout` 等待态；开发完成后只需询问是否进行归档，不需要再要求用户先确认 review。
+
+### 5.1 强制脚本调用
+
+回填 artifacts 完成且测试通过后，必须执行以下两条命令：
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase review
+"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> review --write
+```
+
+**如果这两条命令未执行，则 gate 未通过。** 不允许跳过这一步直接输出完成汇报。
+
+### 5.2 强制汇报 checklist
+
+执行完上述脚本后，必须向用户输出汇报。汇报 MUST 覆盖以下全部条目，缺一不可：
+
+1. 当前分支名
+2. 当前工作区路径
+3. `origin_branch` 与 `origin_workspace_path`（是否与当前一致）
+4. 使用了哪一个 Superpowers plan 文件
+5. 本次完成了哪些 OpenSpec task
+6. `tasks.md` 回填情况
+7. 是否更新了 `proposal.md`、`design.md` 或 spec delta
+8. 测试结果
+9. `openspec validate <change-id> --strict` 结果
+10. 下一步编号选项（必须给出可直接回复的数字菜单，并明确任意非编号内容视为继续修改当前实现）
+
+### 5.3 下一步编号菜单模板
+
+汇报结尾必须包含以下格式的编号提示（可微调措辞，但结构和编号语义不可省略）：
+
+```
+---
+✅ 实现与验证已完成。
+
+📍 当前分支: `<branch>`
+📍 当前工作区: `<path>`
+📍 origin: `<origin_branch>` @ `<origin_workspace_path>`
+
+1. 进入 `onespec-archive`，选择删除 worktree / 归档相关操作
+2. 保持当前分支 / worktree 不变，先停在这里，稍后再继续
+其他：任意非编号内容视为继续修改当前实现；如果意图不在以上选项里，也可以直接补充说明
+---
+```
+
+如果当前分支或工作区不同于 `origin_*`，还必须额外说明："当前实现位于临时分支或临时 worktree；若你直接回复非编号内容，我会按继续修改处理。"
+
+不要只停在“下一步应进入 `onespec-archive`”这种抽象提示，也不要只说“做 `review-closeout`”。必须同时给出用户可直接回复的编号选项。
+
+### 5.4 反模式（NEVER）
+
+以下行为构成 gate 违规，绝不允许：
+
+- 实现完成后直接输出"已完成"总结，而未执行 5.1 的脚本
+- 汇报中缺少当前分支/工作区信息（checklist 第 1-3 项）
+- 未给出明确的下一步编号选项
+- 将 archive / merge / worktree 删除操作混入实现完成汇报
+- 在用户未回复前自行进入 `onespec-archive` 阶段
+- 用"下一步应进入 onespec-archive"这种抽象描述替代具体编号菜单
+- 在用户完成 review 并明确要求收尾前，擅自删除临时 worktree

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

@@ -0,0 +1,57 @@
+---
+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.
+---
+
+# 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.
+
+Announce at the start:
+
+> I am using the `onespec` workflow.
+
+## Recovery First
+
+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_BASH" "$ONESPEC_STATE" list
+```
+
+If a relevant change exists, run:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
+```
+
+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.
+
+## 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`.
+
+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`.
+
+## 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.
+- 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.