@gong-ym/ai-spec-auto 0.2.3

package/.agents/commands/common/spec-continue.md

@@ -0,0 +1,74 @@
+这是协议继续入口，不是直接开发命令。
+
+绝对红线：
+
+- 在执行 `protocol-advance --json` 之前，禁止直接开始读项目代码、调用实现技能或修改业务文件
+- 不允许把当前轮次退化成“直接开始写页面/组件代码”
+- `task-orchestrator` 必须在每次专家完成后重新出现
+
+先判断当前这一轮用户输入：
+
+- 若用户这轮是在表达审批/放行意图，例如：
+  - `我同意继续实现`
+  - `同意`
+  - `继续`
+  - `开始`
+  - `愿意`
+- 或当前在归档确认门禁中，用户这轮是在表达归档决定，例如：
+  - `归档`
+  - `同意归档`
+  - `先不归档`
+  - `暂不归档`
+- 且当前运行态很可能已停在 `pending_gate`
+
+则优先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前这条用户原话>" --json
+```
+
+不要先空跑 `protocol-advance`。
+
+若 `protocol-update` 返回 `fast_path.executed = true`：
+
+- 说明当前是本地 fast-path，已经直接完成“归档”或“结束运行”
+- 不要再执行 `/spec-continue`
+- 不要再执行 `protocol-advance`
+- 直接读取返回结果里的 `turn` 或当前运行态，输出最终摘要
+
+其它情况再先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-advance --target . --json
+```
+
+然后只按返回的 `turn` 执行：
+
+1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
+2. 原样向用户播报 `turn.announcements.enter`
+3. 只读取 `turn.reads`，只写 `turn.writes`
+4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令
+5. 完成当前轮次后：
+   - 若当前专家执行结果为 `partial（部分完成）` 或任何非 `done / success / completed` 状态，不得写“交付完成”，不得交给下一位专家；必须继续停留在当前专家补齐后再推进
+   - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
+   - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
+   - 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command` 已完成归档与运行收尾；不要再写 `expert-execution` JSON，不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
+6. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
+7. 若用户中途补充新要求，或当前这条输入本身就是审批/放行意见，或是归档确认门禁下的“归档 / 不归档”决定，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
+8. `advance` 返回后，直接读取返回结果里的下一个 `turn` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
+9. 重复直到 `turn.status = terminal | blocked`
+
+若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`：
+- 明确告诉用户：当前停在该审批门禁，尚未批准，不能继续实现
+- 若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要：
+  只保留“当前状态 / 关键原因 / 下一步”，不要写长篇阶段说明，不要罗列 proposal/specs/design/tasks 或仓库文件路径，不要输出任何“对内说明”
+- 不要继续执行 `advance`
+- 若用户随后给出明确批准意见，或在归档确认门禁下给出“归档 / 不归档”决定，先执行 `turn.commands.update` 记录说明；若 `protocol-update` 返回 `fast_path.executed = true`，直接结束当前轮次，否则再让用户重新执行 `/spec-continue`
+
+`proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md` 门禁必须真实落盘。
+若存在 `turn.finalize_contract.user_report_contract`，最终摘要严格服从它：
+- `micro`：压成三句式，只保留交付结论、验证结果、残留风险；不要文件路径、实现结构细节、命令名
+- `standard`：只保留关键结果、验证结果、残留风险，必要时补一句下一步；不要协议细节、路径、OpenSpec 文件名或长篇实现说明
+- 不要出现 `proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md`、`terminal`、`success`、`waiting-approval` 等内部词
+- 不要额外输出“阶段说明（语义）”式逐角色播报
+- 不要默认附加 `pnpm dev`、浏览器打开路径等本地操作提示，除非用户明确要

package/.agents/commands/common/spec-orchestrate.md

@@ -0,0 +1,35 @@
+这是统一协议编排入口。
+
+规则：
+
+- 在任何项目搜索、文件读取、技能调用、代码修改之前，必须先执行当前轮次命令
+- 新任务：先执行 `./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<用户需求>" --json`
+- 已有运行态：
+  - 若当前这条用户输入本身是在表达审批/放行（如“我同意继续实现 / 同意 / 继续 / 开始 / 愿意”），优先执行 `./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前用户原话>" --json`
+  - 若当前在归档确认门禁，且用户输入是在表达“归档 / 不归档”决定（如“归档 / 同意归档 / 先不归档 / 暂不归档”），同样优先执行 `./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前用户原话>" --json`
+  - 否则执行 `./node_modules/.bin/ai-spec-auto protocol-advance --target . --json`
+- 之后一律按返回的 `turn.enforcement`、`turn.actor`、`turn.announcements`、`turn.reads`、`turn.writes`、`turn.guidance`、`turn.execution_contract` 执行
+- 若存在 `turn.commands`、`turn.requires_advance`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令
+- 每进入新 `turn` 前，必须原样播报 `turn.announcements.enter`
+- 每完成当前轮次后：
+  - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
+  - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
+- 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command` 已完成归档与运行收尾；不要再写 `expert-execution` JSON，不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
+- 若 `protocol-update` 返回 `fast_path.executed = true`，说明归档确认已走本地 fast-path；不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
+- 每完成一轮，若 `turn.requires_advance = true`，按 `turn.finalize_contract.advance_command` 执行推进；若用户补充了新需求，或当前输入本身是审批/放行意见，或归档确认门禁下的“归档 / 不归档”决定，使用 `turn.finalize_contract.update_command`
+- `advance` 返回后，必须直接消费返回结果里的下一个 `turn`；禁止 `sleep`、`tail`、`timeout`、`cat` 日志或额外重跑 `protocol-step`
+- 直到 `turn.status` 变成 `terminal` 或 `blocked`
+- 若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`，明确告诉用户当前在审批门禁中；若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要：只保留“当前状态 / 关键原因 / 下一步”，不要长篇说明、文件路径或任何“对内说明”；不要继续执行 `advance`；收到明确批准意见，或在归档确认门禁下收到“归档 / 不归档”决定后，先执行 `turn.commands.update` 记录说明；若 `protocol-update` 返回 `fast_path.executed = true`，直接结束当前轮次，否则再让用户重新执行 `/spec-continue`
+
+硬性要求：
+
+- 这是协议驱动，不是自由发挥
+- 未轮到 `frontend-implementer` 前禁止写业务代码
+- 未执行当前轮次命令前禁止调用 `create-view`、`create-component`、`theme-variables`、`execute-task`
+- 对用户只展示阶段进度与最终结果，不回显 scratch JSON
+- 若存在 `turn.finalize_contract.user_report_contract`，最终摘要严格服从它：
+  `micro`：压成三句式，只保留交付结论、验证结果、残留风险；不要文件路径、实现结构细节、命令名
+  `standard`：只保留关键结果、验证结果、残留风险，必要时补一句下一步；不要协议细节、路径、OpenSpec 文件名或长篇实现说明
+- 不要出现 `proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md`、`terminal`、`success`、`waiting-approval` 等内部词
+- 不要额外输出“阶段说明（语义）”式逐角色播报
+- 不要默认附加 `pnpm dev`、浏览器打开路径等本地操作提示，除非用户明确要

package/.agents/commands/common/spec-start-review.md

@@ -0,0 +1,82 @@
+这是协议驱动入口，不是直接开发命令。
+
+这个入口的目标很单一：
+
+- 默认启用 `review-policy（审核策略） = main-flow-blocking（主流程阻塞审核）`
+- 允许开发者在命令尾部追加 `CLI flags（命令行标志位）`
+- 继续复用 `protocol-step（协议启动命令）`，不改运行状态机
+
+绝对红线：
+
+- 在执行 `protocol-step --json` 之前，禁止搜索项目、读取项目代码、调用实现技能、修改任何业务文件
+- 当前 `actor（执行角色）` 不是 `frontend-implementer（前端实现专家）` 时，禁止修改 Vue/TS/CSS 业务代码
+- 不允许跳过 `task-orchestrator（任务编排专家） -> requirement-analyst（需求解析专家） -> task-orchestrator（任务编排专家） -> frontend-implementer（前端实现专家） -> task-orchestrator（任务编排专家） -> code-guardian（规范守护专家） -> task-orchestrator（任务编排专家）`
+
+先解析本次 `/spec-start-review` 命令尾部输入：
+
+- 支持 `--mode <auto|suggest|manual>`
+- 支持 `--flow <flow-id>`
+- 支持 `--review-policy <none|main-flow-blocking>`
+- 未显式传入时，默认使用 `--mode auto --review-policy main-flow-blocking`
+- 除这些 `flags（标志位）` 之外的剩余文本，全部视为本次需求原文，并透传给 `--user-input`
+- 若 `flags（标志位）` 之外没有任何需求原文，先提示用户补完整需求，再执行
+- 若用户传了 `--mode manual` 但没有传 `--flow`，不要自行兜底，不要改写成别的模式；保持原样执行，让运行时自己返回 `manual-flow-required（手动流程必填门禁）`
+- 不要把 `manual（手动）` 理解成“每一步都人工审核”
+
+推荐示例：
+
+```text
+/spec-start-review 创建订单列表 mock 页面
+/spec-start-review --mode suggest 创建订单列表 mock 页面
+/spec-start-review --mode manual --flow prd-to-delivery 创建订单列表 mock 页面
+```
+
+完成解析后，执行等价协议命令：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<解析后的需求原文>" --mode <解析后的 mode（运行模式）> --review-policy <解析后的 review-policy（审核策略）> [--flow <解析后的 flow（流程模板）>] --json
+```
+
+然后只按返回的 `turn（当前轮次）` 执行：
+
+1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
+   若 `execute_current_command_first = true`，才需要先执行 `turn.enforcement.current_command`
+2. 原样向用户播报 `turn.announcements.enter`
+3. 只读取 `turn.reads`，只写 `turn.writes`
+4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令，不要自行补流程
+5. `task-orchestrator（任务编排专家）` 只写 `.ai-spec/internal/tmp/task-orchestrator-turn.json`，不写业务代码
+6. `requirement-analyst（需求解析专家）` 只产出 `proposal.md`、`spec.md`、`tasks.md`
+7. `frontend-implementer（前端实现专家）` 才允许改业务代码
+8. `code-guardian（规范守护专家）` 只产出 `checklist.md`、`iterations.md`
+9. 完成当前轮次后：
+   - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
+   - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
+   - 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command（当前命令）` 已完成归档与运行收尾；不要再写 `expert-execution（专家执行结果）` JSON，不要再执行 `protocol-advance（协议推进命令）`，直接读取当前运行态并输出最终摘要
+10. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
+11. 若用户中途补充新要求，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
+12. `advance（推进命令）` 返回后，直接读取返回结果里的下一个 `turn（当前轮次）` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
+13. 重复直到 `turn.status = terminal | blocked`
+
+若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`：
+
+- 明确告诉用户：当前停在该审批门禁，尚未批准，不能继续实现
+- 若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要：
+  只保留“当前状态 / 关键原因 / 下一步”，不要写长篇阶段说明，不要罗列 `proposal/specs/design/tasks` 或仓库文件路径，不要输出任何“对内说明”
+- 不要继续执行 `advance`
+- 若用户随后给出明确批准意见，或在归档确认门禁下给出“归档 / 不归档”决定，先执行 `turn.commands.update` 记录说明；若 `protocol-update（协议更新命令）` 返回 `fast_path.executed = true`，直接结束当前轮次，否则再让用户重新执行 `/spec-continue`
+
+若 `turn.status = blocked` 且存在 `turn.guidance.confirm_gate`：
+
+- 先判断是否是 `start-review（启动确认门禁）` 或 `manual-flow-required（手动流程必填门禁）`
+- `start-review（启动确认门禁）`：提示用户当前是 `suggest（建议）` 模式，先确认建议计划，再恢复到第一位专家
+- `manual-flow-required（手动流程必填门禁）`：提示用户必须补充 `--flow <flow-id>`
+- 不要把 `manual（手动）` 理解成“每一步都审核”
+
+对用户只输出阶段语义和最终摘要，不回显 `scratch JSON（中间草稿 JSON）`。
+若存在 `turn.finalize_contract.user_report_contract`，最终摘要严格服从它：
+
+- `micro`：压成三句式，只保留交付结论、验证结果、残留风险；不要文件路径、实现结构细节、命令名
+- `standard`：只保留关键结果、验证结果、残留风险，必要时补一句下一步；不要协议细节、路径、OpenSpec 文件名或长篇实现说明
+- 不要出现 `proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md`、`terminal`、`success`、`waiting-approval` 等内部词
+- 不要额外输出“阶段说明（语义）”式逐角色播报
+- 不要默认附加 `pnpm dev`、浏览器打开路径等本地操作提示，除非用户明确要

package/.agents/commands/common/spec-start.md

@@ -0,0 +1,67 @@
+这是协议驱动入口，不是直接开发命令。
+
+绝对红线：
+
+- 在执行 `protocol-step --json` 之前，禁止搜索项目、读取项目代码、调用实现技能、修改任何业务文件
+- 当前 `actor` 不是 `frontend-implementer` 时，禁止修改 Vue/TS/CSS 业务代码
+- 不允许跳过 `task-orchestrator -> requirement-analyst -> task-orchestrator -> frontend-implementer -> task-orchestrator -> code-guardian -> task-orchestrator`
+
+先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<本次 /spec-start 的用户原始需求>" --mode auto --review-policy none --json
+```
+
+若用户明确要求先看建议计划，再改用：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<本次 /spec-start 的用户原始需求>" --mode suggest --review-policy none --json
+```
+
+若用户明确要求手动锁定流程模板，再改用：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<本次 /spec-start 的用户原始需求>" --mode manual --flow <flow-id> --review-policy main-flow-blocking --json
+```
+
+然后只按返回的 `turn` 执行：
+
+1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
+   若 `execute_current_command_first = true`，才需要先执行 `turn.enforcement.current_command`
+2. 原样向用户播报 `turn.announcements.enter`
+3. 只读取 `turn.reads`，只写 `turn.writes`
+4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令，不要自行补流程
+5. `task-orchestrator` 只写 `.ai-spec/internal/tmp/task-orchestrator-turn.json`，不写业务代码
+6. `requirement-analyst` 只产出 `proposal.md`、`spec.md`、`tasks.md`
+7. `frontend-implementer` 才允许改业务代码
+8. `code-guardian` 只产出 `checklist.md`、`iterations.md`
+9. 完成当前轮次后：
+   - 若当前专家执行结果为 `partial（部分完成）` 或任何非 `done / success / completed` 状态，不得写“交付完成”，不得交给下一位专家；必须继续停留在当前专家补齐后再推进
+   - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
+   - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
+   - 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command` 已完成归档与运行收尾；不要再写 `expert-execution` JSON，不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
+10. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
+11. 若用户中途补充新要求，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
+12. `advance` 返回后，直接读取返回结果里的下一个 `turn` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
+13. 重复直到 `turn.status = terminal | blocked`
+
+若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`：
+- 明确告诉用户：当前停在该审批门禁，尚未批准，不能继续实现
+- 若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要：
+  只保留“当前状态 / 关键原因 / 下一步”，不要写长篇阶段说明，不要罗列 proposal/specs/design/tasks 或仓库文件路径，不要输出任何“对内说明”
+- 不要继续执行 `advance`
+- 若用户随后给出明确批准意见，或在归档确认门禁下给出“归档 / 不归档”决定，先执行 `turn.commands.update` 记录说明；若 `protocol-update` 返回 `fast_path.executed = true`，直接结束当前轮次，否则再让用户重新执行 `/spec-continue`
+
+若 `turn.status = blocked` 且存在 `turn.guidance.confirm_gate`：
+- 先判断是否是 `start-review（启动确认门禁）` 或 `manual-flow-required（手动流程必填门禁）`
+- `start-review（启动确认门禁）`：提示用户当前是 `suggest（建议）` 模式，先确认建议计划，再恢复到第一位专家
+- `manual-flow-required（手动流程必填门禁）`：提示用户必须补充 `--flow <flow-id>`
+- 不要把 `manual（手动）` 理解成“每一步都审核”
+
+对用户只输出阶段语义和最终摘要，不回显 scratch JSON。
+若存在 `turn.finalize_contract.user_report_contract`，最终摘要严格服从它：
+- `micro`：压成三句式，只保留交付结论、验证结果、残留风险；不要文件路径、实现结构细节、命令名
+- `standard`：只保留关键结果、验证结果、残留风险，必要时补一句下一步；不要协议细节、路径、OpenSpec 文件名或长篇实现说明
+- 不要出现 `proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md`、`terminal`、`success`、`waiting-approval` 等内部词
+- 不要额外输出“阶段说明（语义）”式逐角色播报
+- 不要默认附加 `pnpm dev`、浏览器打开路径等本地操作提示，除非用户明确要

package/.agents/commands/common/spec-status.md

@@ -0,0 +1,22 @@
+这是协议状态查看入口，只读，不推进、不修改运行态。
+
+先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-status --target . --json
+```
+
+然后只输出高信号摘要：
+
+- 当前阶段
+- 当前状态
+- 是否存在审批门禁
+- 是否有待吸收的补充输入
+- 下一步建议
+
+不要输出：
+
+- 协议过程日志
+- scratch/current-run/current-dispatch/current-execution 等内部文件名
+- 大段文件清单
+- 无关实现细节

package/.agents/commands/common/spec-stop.md

@@ -0,0 +1,29 @@
+这是协议暂停入口，不是取消命令。
+
+语义固定为：
+
+- 暂停当前 run
+- 保留当前产物、当前专家停点和门禁上下文
+- 后续可通过 `/spec-continue` 或自然语言“继续 / 恢复执行”恢复
+
+先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-stop --target . --json
+```
+
+然后：
+
+1. 若当前没有活动 run 或当前已是终态，只输出当前状态说明
+2. 若成功暂停，只告诉用户：
+   - 当前已暂停
+   - 当前停在哪个阶段
+   - 如何恢复
+3. 不要把 `/spec-stop` 解释成取消
+4. 不要清理当前 OpenSpec 产物、运行态或上下文
+
+对用户摘要保持简洁：
+
+- 当前状态
+- 当前停点
+- 恢复方式

package/.agents/commands/common/spec-update.md

@@ -0,0 +1,40 @@
+这是协议增量更新入口，不是重新开新任务，也不是直接开始写代码。
+
+绝对红线：
+
+- 优先把当前输入当作“补充需求 / 修正方向 / 归档前修正说明”处理
+- 先执行 `protocol-update --json`，不要跳过主代理直接改业务文件
+- 不要把当前 change 的产物整份重写；默认只做增量修订
+
+先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前这条用户原话>" --json
+```
+
+然后只按返回的 `turn` 执行：
+
+1. 若 `fast_path.executed = true`，优先消费 fast-path 结果：
+   - `archive-approved` / `complete-without-archive`：直接输出最终摘要，不再执行 `protocol-advance`
+   - `followup-patch-opened`：说明已打开补丁变更，再按返回的下一个 `turn` 继续
+   - `resume-paused-run`：说明已恢复停点，再按返回的下一个 `turn` 继续
+2. 若返回 `turn.mode = update-review`，必须先遵守 `turn.guidance.update_contract`
+3. 只读取 `turn.reads`，只写 `turn.writes`
+4. 若 `change_impact = patch | scope-delta | archive-fix`，默认在同一 `change_id` 内增量更新，不要推倒已有 proposal/specs/design/tasks/checklist/iterations
+5. 若 `change_impact = re-scope`，不要强行吞进当前 run；按 `reconcile_strategy` 给出“建议新建 change”的最小结论
+6. 若 `change_impact = followup-patch`，这是对已归档变更的补丁修正；继续沿返回的 patch run 推进，不要改旧 archive 目录
+7. 若存在 `turn.finalize_contract`，完成当前轮次后按契约推进，不要自行拼命令
+
+对用户只输出：
+
+- 当前识别到的变更类型
+- 会不会回退
+- 预计增量更新哪些产物
+- 下一步是什么
+
+不要输出：
+
+- 大段协议日志
+- scratch JSON
+- 内部运行态文件名
+- “整份重写 proposal/tasks/design/specs” 这类误导性说法

package/.agents/commands/cursor/opsx-apply.md

@@ -0,0 +1,55 @@
+---
+name: /opsx-apply
+id: opsx-apply
+category: Workflow
+description: Cursor 兼容入口：按 tasks.md 执行 OpenSpec 任务实现
+---
+
+这是 Cursor 的兼容入口，语义对齐 `/opsx:apply`。
+
+目标：
+- 选定一个 OpenSpec 变更
+- 读取 proposal / design / tasks 作为上下文
+- 按 `execute-task` 技能默认要求实施任务
+- 任务完成后更新 `tasks.md`
+- 全部完成时提示 `/opsx-archive`
+
+执行要求：
+
+1. 先确定当前要实施的变更  
+   - 若用户明确给了 change name，直接用它
+   - 若上下文里只有一个活跃变更，可直接采用
+   - 若存在多个候选，先用简短自然语言让用户确认，不使用旧版问答工具口吻
+
+2. 先读取变更状态与关键产物  
+   推荐先执行：
+   ```bash
+   npx openspec status --change "<change-name>" --json
+   ```
+   再读取：
+   - `openspec/changes/<change-name>/proposal.md`
+   - `openspec/changes/<change-name>/design.md`（若存在）
+   - `openspec/changes/<change-name>/tasks.md`
+
+3. 默认按 `execute-task` 技能执行  
+   优先读取：
+   - `.agents/skills/execute-task/SKILL.md`
+   若仓库仍保留源结构，再看：
+   - `.agents/skills/common/execute-task/SKILL.md`
+
+4. 实施时保持当前架构要求：
+   - 默认走 Superpowers 四步循环
+   - 逐项完成 `tasks.md` 中未勾选任务
+   - 每完成一项立即把 `- [ ]` 改成 `- [x]`
+   - 若遇到阻断、需求不清或高风险偏差，暂停并说明，不要硬猜
+
+5. 输出保持简洁：
+   - 当前使用的 change name
+   - 本轮完成了哪些任务
+   - 剩余任务或阻断
+   - 若全部完成，提示下一步 `/opsx-archive`
+
+守卫：
+- 不跳过 `proposal / design / tasks` 直接写代码
+- 不回退到旧版长篇流程播报
+- 不把 Cursor 连字符命令复制到其他 IDE

package/.agents/commands/cursor/opsx-archive.md

@@ -0,0 +1,48 @@
+---
+name: /opsx-archive
+id: opsx-archive
+category: Workflow
+description: Cursor 兼容入口：归档 OpenSpec 变更并合并规范
+---
+
+这是 Cursor 的兼容入口，语义对齐 `/opsx:archive`。
+
+目标：
+- 选定要归档的变更
+- 优先走当前 `archive-change` 增强层
+- 把增量规范合并到 `openspec/specs/`
+- 把变更归档到 `openspec/changes/archive/`
+- 输出简洁归档摘要
+
+执行要求：
+
+1. 先确定 change name  
+   - 用户明确给出则直接使用
+   - 若上下文中只有一个已完成或当前变更，可直接采用
+   - 若存在多个候选，用自然语言让用户确认
+
+2. 优先使用当前规范库提供的归档增强层  
+   首选命令：
+   ```bash
+   ./node_modules/.bin/ai-spec-auto archive-change --target . --change-id "<change-name>" --complete-run --json
+   ```
+   除非该命令不可用，否则不要手工拼 `mkdir`、`cp`、`mv` 去归档。
+
+3. 若确实无法使用 `ai-spec-auto archive-change`，再回到当前 OpenSpec 归档路径  
+   但不要回退到旧版的重型归档说明。
+
+4. 完成后只输出：
+   - 变更名称
+   - 归档路径
+   - 规范合并结果
+   - 是否存在未完成任务或风险提示
+
+5. 如需审查归档策略，优先参考：
+   - `.agents/skills/archive-change/SKILL.md`
+   若仓库仍保留源结构，再看：
+   - `.agents/skills/common/archive-change/SKILL.md`
+
+守卫：
+- 不绕开 `archive-change` 增强层直接做文件搬运
+- 不输出过长的内部执行日志
+- Cursor 用 `/opsx-archive`；其他 IDE 仍走 `/opsx:archive`

package/.agents/commands/cursor/opsx-explore.md

@@ -0,0 +1,45 @@
+---
+name: /opsx-explore
+id: opsx-explore
+category: Workflow
+description: Cursor 兼容入口：进入 OpenSpec 探索模式，先思考再落提案
+---
+
+这是 Cursor 的兼容入口，语义对齐 `/opsx:explore`。
+
+目标：
+- 围绕一个主题做探索、调研、架构讨论或范围澄清
+- 可以读代码、查现状、画结构、比方案
+- 不直接实现业务代码
+- 当思路收敛时，自然过渡到 `/opsx-propose`
+
+工作方式：
+
+1. 先确认探索主题  
+   - 若用户已给出主题，直接围绕它展开
+   - 若主题很模糊，可先问一两句自然语言澄清
+
+2. 允许做的事：
+   - 读代码和文档
+   - 搜索仓库
+   - 对比方案与权衡
+   - 用表格或 ASCII 图梳理结构
+   - 引用已有 OpenSpec 变更作为上下文
+
+3. 禁止做的事：
+   - 不直接写业务实现代码
+   - 不把探索直接变成实施
+   - 不在未达成一致时强行创建产物
+
+4. 当探索逐渐收敛时，可以主动提示：
+   - 若准备正式立项：`/opsx-propose`
+   - 若只是补充思路：继续探索即可
+
+5. 输出风格：
+   - 以讨论、比较、澄清为主
+   - 保持结构清楚
+   - 不使用旧版重型问答流程
+
+守卫：
+- 这是探索模式，不是实现模式
+- Cursor 用 `/opsx-explore`；其他 IDE 仍走 `/opsx:explore`

package/.agents/commands/cursor/opsx-propose.md

@@ -0,0 +1,59 @@
+---
+name: /opsx-propose
+id: opsx-propose
+category: Workflow
+description: Cursor 兼容入口：创建 OpenSpec 提案并生成 proposal/specs/design/tasks
+---
+
+这是 Cursor 的兼容入口，语义对齐 `/opsx:propose`。
+
+目标：
+- 创建或续用一个 OpenSpec 变更目录
+- 结合 `create-proposal` 技能完成前置分析
+- 生成 proposal / specs / design / tasks 等规划产物
+- 最后给出简洁摘要，并提示下一步使用 `/opsx-apply`
+
+执行要求：
+
+1. 优先读取并遵守 `create-proposal` 技能  
+   优先看：
+   - `.agents/skills/create-proposal/SKILL.md`
+   若仓库仍保留源结构，再看：
+   - `.agents/skills/common/create-proposal/SKILL.md`
+
+2. 若用户没有提供变更名称或需求描述不够明确，先用一两句自然语言补齐关键信息  
+   不使用旧版 `AskUserQuestion` 风格，也不要机械连问。
+
+3. 先做当前架构要求的前置分析  
+   至少收敛：
+   - 交付形态（页面 / 组件 / 模块 / 其它）
+   - 是否有设计稿或明确 UI 描述
+   - 是否接真实接口、走 mock，还是接口未就绪
+   - 是否存在高风险边界或范围不清
+
+4. 使用当前 OpenSpec 快速路径生成产物  
+   推荐顺序：
+   ```bash
+   npx openspec list --json
+   npx openspec new change "<change-name>"
+   npx openspec ff "<change-name>"
+   ```
+   若变更已存在，则不要重复新建，直接在现有变更上继续快进生成。
+
+5. 产物位置必须稳定落在：
+   - `openspec/changes/<change-name>/proposal.md`
+   - `openspec/changes/<change-name>/specs/`
+   - `openspec/changes/<change-name>/design.md`
+   - `openspec/changes/<change-name>/tasks.md`
+
+6. 完成后只做简洁收口：
+   - 变更名称
+   - 产物路径
+   - 提案范围摘要
+   - 下一步：`/opsx-apply`
+
+守卫：
+- 不直接开始写业务代码
+- 不回退到旧版重型 artifact loop
+- 不输出长篇协议细节
+- Cursor 用 `/opsx-propose`；其他 IDE 仍走 `/opsx:propose`

package/.agents/commands/cursor/spec-continue.md

@@ -0,0 +1,63 @@
+---
+name: /spec-continue
+id: spec-continue
+category: Workflow
+description: Cursor 兼容入口：按运行态优先执行 protocol-update 或 protocol-advance
+---
+
+这是 Cursor 的协议继续入口，不是直接开发命令。
+
+绝对红线：
+
+- 在执行 `protocol-advance --json` 之前，禁止直接开始读项目代码、调用实现技能或修改业务文件
+- 不允许把当前轮次退化成“直接开始写页面/组件代码”
+- `task-orchestrator` 必须在每次专家完成后重新出现
+
+先判断当前这一轮用户输入：
+
+- 若用户这轮是在表达审批/放行意图，例如 `我同意继续实现`、`同意`、`继续`、`开始`、`愿意`
+- 或当前在归档确认门禁中，用户这轮是在表达归档决定，例如 `归档`、`同意归档`、`先不归档`、`暂不归档`
+- 且当前运行态很可能已停在 `pending_gate`
+
+则优先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前这条用户原话>" --json
+```
+
+不要先空跑 `protocol-advance`。
+
+若 `protocol-update` 返回 `fast_path.executed = true`：
+
+- 说明当前是本地 fast-path，已经直接完成“归档”或“结束运行”
+- 不要再执行 `/spec-continue`
+- 不要再执行 `protocol-advance`
+- 直接读取返回结果里的 `turn` 或当前运行态，输出最终摘要
+
+其它情况再执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-advance --target . --json
+```
+
+然后只按返回的 `turn` 执行：
+
+1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
+2. 原样向用户播报 `turn.announcements.enter`
+3. 只读取 `turn.reads`，只写 `turn.writes`
+4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令
+5. 若当前专家执行结果为 `partial（部分完成）` 或任何非 `done / success / completed` 状态，不得写“交付完成”，不得交给下一位专家；必须继续停留在当前专家补齐后再推进
+6. 若 `turn.enforcement.current_command_finalizes_run = true`，不要再执行 `protocol-advance`
+7. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
+8. 若用户中途补充新要求，或当前这条输入本身就是审批/放行意见，或是归档确认门禁下的“归档 / 不归档”决定，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
+9. `advance` 返回后，直接读取返回结果里的下一个 `turn` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
+10. 重复直到 `turn.status = terminal | blocked`
+
+若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`：
+
+- 明确告诉用户：当前停在该审批门禁，尚未批准，不能继续实现
+- 若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要，只保留“当前状态 / 关键原因 / 下一步”
+- 不要继续执行 `advance`
+- 若用户随后给出明确批准意见，或在归档确认门禁下给出“归档 / 不归档”决定，先执行 `turn.commands.update` 记录说明；若 `protocol-update` 返回 `fast_path.executed = true`，直接结束当前轮次，否则再让用户重新执行 `/spec-continue`
+
+最终摘要只保留高信号结果、验证结果、残留风险，不要回显协议日志、scratch JSON 或内部文件名。