@gong-ym/ai-spec-auto 0.2.3

package/.agents/commands/README.md

@@ -0,0 +1,33 @@
+# IDE Command Templates
+
+这里存放项目级 `IDE（开发工具）` 命令模板的源定义。
+
+目录约定：
+
+- `common/`
+  - 所有 `IDE（开发工具）` 共用的命令模板主源
+- `cursor/`
+  - 仅在 `Cursor（开发工具）` 需要差异化覆盖时才放文件
+  - 例如 `/opsx-propose`、`/opsx-apply` 这类连字符兼容入口
+- `claude/`
+  - 仅在 `Claude（开发工具）` 需要差异化覆盖时才放文件
+- `codex/`
+  - 仅在 `Codex（代码代理）` 需要显式项目级命令契约时放文件
+  - 当前首期与 `common/` 保持同名模板，后续若 `Codex` 需要差异化引导，再在这里覆盖
+- `qoder/`
+  - 仅在 `Qoder（开发工具）` 需要差异化覆盖时才放文件
+  - 当前与 `common/` 保持同名模板，后续若需要差异化引导，再在这里覆盖
+- `opencode/`、`trae/`
+  - 同上，仅在需要差异化时创建目录
+
+这些文件在源仓库中统一维护于 `.agents/commands/`。
+
+安装到目标项目时：
+
+- 先把 `common/*.md` 复制到对应 `IDE（开发工具）` 的 `commands/` 目录
+- 如果存在 `cursor/*.md`、`claude/*.md` 或 `codex/*.md`，再用同名文件覆盖
+
+这样可以保持：
+
+- 命令模板主源只有一份
+- 目标项目仍然保留 `IDE（开发工具）` 原生消费结构

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

@@ -0,0 +1,88 @@
+这是协议驱动入口，不是直接开发命令。
+
+本次 `/spec-start-review` 命令尾部原文如下：
+
+```text
+$ARGUMENTS
+```
+
+这个入口的目标很单一：
+
+- 默认启用 `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（任务编排专家）`
+
+先按 `CLI flags（命令行标志位）` 解析 `$ARGUMENTS（全部参数占位符）`：
+
+- 支持 `--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/codex/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/codex/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/codex/spec-start-review.md

@@ -0,0 +1,88 @@
+这是协议驱动入口，不是直接开发命令。
+
+本次 `/spec-start-review` 命令尾部原文如下：
+
+```text
+$ARGUMENTS
+```
+
+这个入口的目标很单一：
+
+- 默认启用 `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（任务编排专家）`
+
+先按 `CLI flags（命令行标志位）` 解析 `$ARGUMENTS（全部参数占位符）`：
+
+- 支持 `--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/codex/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/codex/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/codex/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/codex/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/common/branch-review.md

@@ -0,0 +1,117 @@
+---
+description: 启动分支代码评审,分析当前分支与主分支的差异和风险项
+---
+# /branch-review - 分支代码评审
+
+启动分支代码评审流程,对比功能分支与主分支(master/main)的代码差异,自动识别技术风险和业务风险,生成可视化 HTML 评审报告。
+
+## 用法
+
+```
+/branch-review [需求文档路径]
+```
+
+## 参数
+
+- **需求文档路径**(可选): 本次开发需求的文档路径,用于业务风险分析
+  - 支持格式: PRD / 用户故事 / 需求规格说明 / Markdown
+  - 示例: `docs/prd-order-module.md`
+
+## 示例
+
+### 示例 1: 仅技术风险分析
+
+```
+/branch-review
+```
+
+**效果**: 
+- 对比当前分支与主分支的代码差异
+- 分析技术类风险(性能、安全、错误处理等)
+- 生成可视化 HTML 报告
+
+### 示例 2: 技术 + 业务风险分析
+
+```
+/branch-review docs/prd-order-module.md
+```
+
+**效果**:
+- 读取需求文档,提取业务目标和验收标准
+- 对比代码差异,分析技术风险
+- 对照需求文档,分析业务风险(功能缺失、流程错误等)
+- 生成包含技术风险和业务风险的完整报告
+
+### 示例 3: 指定分支对比
+
+在对话中说明:
+
+```
+请对比 feature/new-payment 和 master 分支的差异,需求文档在 docs/payment-requirements.md
+```
+
+**效果**:
+- 使用指定的功能分支和主分支
+- 读取需求文档进行业务风险分析
+- 生成完整评审报告
+
+## 报告输出
+
+报告将保存到:
+```
+.code-review/review-[分支名]-[日期].html
+```
+
+报告包含:
+1. **概览面板**: 变更统计、风险统计、通过率
+2. **文件导航**: 文件树、变更行数、风险标记
+3. **代码差异**: 并排/统一模式、语法高亮
+4. **技术风险**: 按严重程度分级、关联代码行
+5. **业务风险**: 需求覆盖度、缺失功能、流程问题
+6. **交互功能**: 搜索、过滤、评论、导出
+
+## 风险等级说明
+
+| 等级 | 技术风险 | 业务风险 |
+|------|---------|---------|
+| 🔴 严重 | 崩溃、安全漏洞、数据丢失 | 缺失核心功能、业务流程错误 |
+| 🟡 警告 | 性能问题、可维护性差 | 缺少异常处理、边界条件遗漏 |
+| 🔵 建议 | 代码优化、重构建议 | 体验优化、流程改进 |
+| ⚪ 提示 | 信息说明、最佳实践 | - |
+
+## 工作流程
+
+```mermaid
+graph LR
+    A[确认分支] --> B[收集代码差异]
+    B --> C{有需求文档?}
+    C -->|是| D[分析技术+业务风险]
+    C -->|否| E[仅分析技术风险]
+    D --> F[生成HTML报告]
+    E --> F
+    F --> G[输出评审结果]
+```
+
+## 相关命令
+
+- `/spec-start` - 启动需求交付
+- `/spec-continue` - 继续需求交付
+- `/spec-status` - 查看需求状态
+- `execute-task` 技能 - 基于评审结果创建修复任务
+
+## 注意事项
+
+- 必须在 Git 仓库中执行
+- 确保功能分支已提交变更
+- 业务风险分析需要提供需求文档
+- 报告为独立 HTML 文件,无需外部依赖
+- 不会修改任何源代码文件
+
+## 后续操作
+
+评审完成后可执行:
+
+1. **修复风险**: 使用 `execute-task` 技能创建修复任务
+2. **更新需求**: 使用 `/spec-update` 补充需求文档
+3. **重新评审**: 修复后再次运行 `/branch-review` 验证
+4. **合并代码**: 解决所有严重风险后可安全合并

package/.agents/commands/common/project-init.md

@@ -0,0 +1,25 @@
+这是项目规范初始化入口。目标不是只生成 `01/03`，而是按当前项目的 profiles 补齐本次应写的全部规范文件。
+
+先读取并严格遵守：
+
+- `.agents/skills/common/project-init/SKILL.md`
+
+执行要求：
+
+1. 读取 `.ai-spec/manifest.json` 中的 `profile`（字符串）或 `profiles`（数组），统一为 profile 列表。
+2. 从 `.agents/registry/profiles.json` 查询各 profile 的 `project_init_rule_ids`，合并为本次应生成的规则集合。
+3. 固定写入（统一写入 `.agents/rules/`）：
+   - `01-项目概述.md`
+   - `03-项目结构.md`
+   - `context/PROJECT.md`
+4. 若项目存在 `openspec/`，同步 `openspec/project.md`。
+5. 若 `.agents/rules/` 下缺失规则集合中任意文件，必须在本次一并补生成。
+
+绝对红线：
+
+- 不能只写 `01/03 + PROJECT` 就结束
+- 不能把缺失的能力规则只写进摘要或建议，不落盘
+- 对已存在的能力规则不覆盖
+- 内容必须基于当前仓库实际代码、目录和依赖，不能照搬通用模板
+
+把用户触发本命令视为明确授权：信息足够时直接完成写入；只有在项目事实明显不足、无法判断时，才先给出简短确认摘要。