@gong-ym/ai-spec-auto 0.2.3

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

@@ -0,0 +1,53 @@
+---
+name: /spec-orchestrate
+id: spec-orchestrate
+category: Workflow
+description: Cursor 兼容入口：统一协议编排，自动选择 protocol-step、protocol-update 或 protocol-advance
+---
+
+这是 Cursor 的统一协议编排入口。
+
+硬性要求：
+
+- 在任何项目搜索、文件读取、技能调用、代码修改之前，必须先执行当前轮次命令
+- 这是协议驱动，不是自由发挥
+- 未轮到 `frontend-implementer` 前禁止写业务代码
+- 未执行当前轮次命令前禁止调用 `create-view`、`create-component`、`theme-variables`、`execute-task`
+
+执行规则：
+
+- 新任务：先执行
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<用户需求>" --json
+```
+
+- 已有运行态：
+  - 若当前这条用户输入本身是在表达审批/放行，优先执行
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前用户原话>" --json
+```
+
+  - 若当前在归档确认门禁，且用户输入是在表达“归档 / 不归档”决定，同样优先执行
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前用户原话>" --json
+```
+
+  - 其它情况执行
+
+```bash
+./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.enforcement.current_command_finalizes_run = true`，不要再写 `expert-execution` JSON，不要再执行 `protocol-advance`
+- 若 `protocol-update` 返回 `fast_path.executed = true`，不要再执行 `protocol-advance`
+- `advance` 返回后，必须直接消费返回结果里的下一个 `turn`；禁止 `sleep`、`tail`、`timeout`、`cat` 日志或额外重跑 `protocol-step`
+- 若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`，明确告诉用户当前在审批门禁中；若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要；不要继续执行 `advance`
+
+对用户只展示阶段进度与最终结果，不回显 scratch JSON，不额外输出协议细节、内部文件名或长篇阶段播报。

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

@@ -0,0 +1,78 @@
+---
+name: /spec-start-review
+id: spec-start-review
+category: Workflow
+description: Cursor（开发工具）兼容入口：默认启用人工审核，并支持命令尾部 flags（标志位）
+---
+
+这是 Cursor（开发工具） 的人工审核协议入口，不是直接开发命令。
+
+这个入口的目标很单一：
+
+- 默认启用 `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（任务编排专家）`
+
+先从本次命令尾部解析参数与需求原文：
+
+- 支持 `--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`
+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.enforcement.current_command_finalizes_run = true`，说明当前命令已完成归档与运行收尾；不要再写 `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`，严格按它输出极简摘要，只保留“当前状态 / 关键原因 / 下一步”
+- 不要继续执行 `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`，最终摘要严格服从它，不要额外输出协议细节、内部文件名或阶段播报。

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

@@ -0,0 +1,59 @@
+---
+name: /spec-start
+id: spec-start
+category: Workflow
+description: Cursor 兼容入口：先执行 protocol-step，再按 turn 契约推进
+---
+
+这是 Cursor 的协议驱动入口，不是直接开发命令。
+
+绝对红线：
+
+- 在执行 `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`
+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` 状态，不得写“交付完成”，不得交给下一位专家；必须继续停留在当前专家补齐后再推进
+10. 若 `turn.enforcement.current_command_finalizes_run = true`，说明当前命令已完成归档与运行收尾；不要再写 `expert-execution` JSON，不要再执行 `protocol-advance`
+11. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
+12. 若用户中途补充新要求，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
+13. `advance` 返回后，直接读取返回结果里的下一个 `turn` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
+14. 重复直到 `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。
+若存在 `turn.finalize_contract.user_report_contract`，最终摘要严格服从它，不要额外输出协议细节、内部文件名或阶段播报。

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

@@ -0,0 +1,30 @@
+---
+name: /spec-status
+id: spec-status
+category: Workflow
+description: Cursor 兼容入口：只读执行 protocol-status，不推进运行态
+---
+
+这是 Cursor 的协议状态查看入口，只读，不推进、不修改运行态。
+
+绝对红线：
+
+- 先执行 `protocol-status --json`
+- 不要先搜索项目、读取业务代码、调用实现技能或修改任何文件
+- 只做状态摘要，不做推进动作
+
+先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-status --target . --json
+```
+
+然后只输出高信号摘要：
+
+- 当前阶段
+- 当前状态
+- 是否存在审批门禁
+- 是否有待吸收的补充输入
+- 下一步建议
+
+不要输出协议过程日志、scratch/current-run/current-dispatch 等内部文件名、大段文件清单或无关实现细节。

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

@@ -0,0 +1,29 @@
+---
+name: /spec-stop
+id: spec-stop
+category: Workflow
+description: Cursor 兼容入口：执行 protocol-stop，暂停当前 run
+---
+
+这是 Cursor 的协议暂停入口，不是取消命令。
+
+语义固定为：
+
+- 暂停当前 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/cursor/spec-update.md

@@ -0,0 +1,41 @@
+---
+name: /spec-update
+id: spec-update
+category: Workflow
+description: Cursor 兼容入口：先执行 protocol-update，按增量修订当前 change
+---
+
+这是 Cursor 的协议增量更新入口，不是重新开新任务，也不是直接开始写代码。
+
+绝对红线：
+
+- 优先把当前输入当作“补充需求 / 修正方向 / 归档前修正说明”处理
+- 先执行 `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` / `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` 内增量更新，不要推倒已有产物
+5. 若 `change_impact = re-scope`，按 `reconcile_strategy` 给出“建议新建 change”的最小结论
+6. 若 `change_impact = followup-patch`，继续沿返回的 patch run 推进，不要改旧 archive 目录
+7. 若存在 `turn.finalize_contract`，完成当前轮次后按契约推进，不要自行拼命令
+
+对用户只输出：
+
+- 当前识别到的变更类型
+- 会不会回退
+- 预计增量更新哪些产物
+- 下一步是什么
+
+不要输出大段协议日志、scratch JSON、内部运行态文件名，或“整份重写 proposal/tasks/design/specs”这类误导性说法。

package/.agents/flows/FRONTMATTER.md

@@ -0,0 +1,263 @@
+# 流程模板 Frontmatter 解析约定
+
+本文件定义 `.agents/flows/` 下流程模板的统一 frontmatter 结构，供后续 CLI、插件页面、OpenClaw 调度层和本地脚本共同解析。
+
+目标不是把流程元数据做复杂，而是保证：
+
+- 可稳定解析
+- 可渐进扩展
+- 不依赖正文做关键决策
+
+与 `ai-spec-auto run` 的最小 JSON 输出约定见：
+
+- [RUN_OUTPUT.md](RUN_OUTPUT.md)
+
+## 1. 基本规则
+
+### 1.1 文件格式
+
+每个流程模板文件必须是 Markdown 文件，并在文件开头包含 YAML frontmatter：
+
+```md
+---
+id: prd-to-delivery
+version: 1
+name: PRD 到交付
+status: active
+type: flow-template
+owner: task-orchestrator
+description: 面向新需求、设计还原和增量交付的基础协作模板。
+triggers:
+  - prd-input
+required_roles:
+  - requirement-analyst
+optional_roles:
+  - design-collaborator
+approval_gates:
+  - before-implementation
+artifacts:
+  - openspec/changes/<change-id>/proposal.md
+---
+```
+
+### 1.2 解析范围
+
+解析器只应将首个 `---` 与第二个 `---` 之间的 YAML 视为结构化元数据。
+
+正文部分：
+
+- 用于人读
+- 不作为关键调度依据
+- 可以辅助解释，但不能替代 frontmatter 中的关键字段
+
+### 1.3 解析失败原则
+
+若以下情况成立，应将该流程模板判定为不可执行：
+
+- 缺少 frontmatter
+- YAML 语法非法
+- 缺少必填字段
+- `id` 或角色字段格式非法
+
+建议处理方式：
+
+- CLI：给出明确错误并停止使用该模板
+- 插件页面：隐藏或标记为异常模板
+- OpenClaw 调用层：禁止直接进入执行
+
+## 2. 字段定义
+
+### 2.1 必填字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | string | 流程模板稳定 ID，使用英文 `kebab-case` |
+| `version` | number | frontmatter 结构版本，当前固定为 `1` |
+| `name` | string | 流程中文展示名 |
+| `status` | string | 模板状态：`active / draft / planned / deprecated` |
+| `type` | string | 当前固定为 `flow-template` |
+| `owner` | string | 当前负责路由该模板的主代理角色 ID，当前一般为 `task-orchestrator` |
+| `description` | string | 模板简介，面向人和页面展示 |
+| `triggers` | string[] | 触发该模板的任务信号 |
+| `required_roles` | string[] | 必选专家列表，按默认执行骨架顺序排列 |
+| `optional_roles` | string[] | 可选专家列表，按推荐插入优先级排列 |
+| `approval_gates` | string[] | 审批点列表，按时间顺序排列 |
+| `artifacts` | string[] | 模板执行完成后至少应产生的产物列表 |
+
+### 2.2 可选字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `visibility` | string | `public / internal`，用于页面展示控制 |
+| `tags` | string[] | 补充标签，如 `frontend`、`design-to-code` |
+| `profiles` | string[] | 技术栈约束，如 `vue`、`react` |
+| `domains` | string[] | 关联能力域，便于平台检索 |
+| `notes` | string[] | 对调度器有帮助的补充说明，不作为硬校验字段 |
+
+## 3. 字段约束
+
+### 3.1 `id`
+
+- 必须唯一
+- 使用英文小写 `kebab-case`
+- 不允许空格、中文或大写字母
+
+示例：
+
+- `prd-to-delivery`
+- `bugfix-to-verification`
+
+### 3.2 `status`
+
+允许值：
+
+- `active`
+- `draft`
+- `planned`
+- `deprecated`
+
+解析建议：
+
+- `active`：可参与执行
+- `draft`：仅供开发和测试，不默认执行
+- `planned`：仅作为规划模板展示，不进入实际路由
+- `deprecated`：保留兼容，不再推荐
+
+### 3.3 `type`
+
+当前固定值：
+
+- `flow-template`
+
+后续若有扩展，也应保持向后兼容。
+
+### 3.4 `owner`
+
+- 应引用已存在的主代理角色 ID
+- 当前默认使用 `task-orchestrator`
+
+### 3.5 `required_roles`
+
+- 至少包含 1 个角色
+- 角色 ID 必须可映射到 `.agents/roles/INDEX.md`
+- 数组顺序表示默认基础骨架顺序
+
+说明：
+
+- 这不是“绝对写死的执行顺序”
+- 但它代表默认协作主链
+
+### 3.6 `optional_roles`
+
+- 可为空数组
+- 角色 ID 必须可映射到 `.agents/roles/INDEX.md`
+- 数组顺序表示推荐插入优先级，不是强制执行顺序
+
+### 3.7 `approval_gates`
+
+- 可为空数组
+- 使用英文 `kebab-case`
+- 应表达“什么时候需要人确认”，而不是“专家名称”
+
+示例：
+
+- `before-implementation`
+- `before-archive`
+
+### 3.8 `artifacts`
+
+- 可为空数组，但生产型模板不建议为空
+- 使用相对项目根目录的路径表达
+- 可包含占位符，如 `<change-id>`
+
+## 4. 解析约定
+
+### 4.1 解析输出对象
+
+建议统一解析成如下结构：
+
+```yaml
+id: prd-to-delivery
+version: 1
+name: PRD 到交付
+status: active
+type: flow-template
+owner: task-orchestrator
+description: 面向新需求、设计还原和增量交付的基础协作模板。
+triggers:
+  - prd-input
+required_roles:
+  - requirement-analyst
+optional_roles:
+  - design-collaborator
+approval_gates:
+  - before-implementation
+artifacts:
+  - openspec/changes/<change-id>/proposal.md
+source: .agents/flows/common/prd-to-delivery.md
+```
+
+其中：
+
+- `source` 不是 frontmatter 原字段
+- 而是解析器补充的来源路径
+
+### 4.2 未知字段处理
+
+为保证后续扩展能力：
+
+- 未知字段默认保留
+- 但当前解析器不应依赖未知字段
+- 不因未知字段直接报错
+
+这可以避免模板升级时老版本 CLI 立即失效。
+
+### 4.3 空值处理
+
+建议遵循以下规则：
+
+- 缺少必填字段：报错
+- 可选数组字段缺失：按空数组处理
+- 可选字符串字段缺失：按空值处理
+
+## 5. 执行层解释规则
+
+解析后，各字段的含义应统一如下：
+
+- `required_roles`
+  - 表示本模板的最小协作骨架
+- `optional_roles`
+  - 表示主代理可按条件动态插入的专家池
+- `approval_gates`
+  - 表示执行过程中可能暂停并等待人工确认的节点
+- `artifacts`
+  - 表示本次任务完成时至少要落下的结果
+
+重要说明：
+
+> 流程模板只定义“骨架和边界”，真正的激活结果仍由主代理结合输入任务动态决定。
+
+## 6. 推荐校验顺序
+
+后续 CLI 或平台服务解析流程模板时，建议按以下顺序校验：
+
+1. 文件是否存在
+2. frontmatter 是否存在
+3. YAML 是否可解析
+4. 必填字段是否完整
+5. `type` 是否为 `flow-template`
+6. `status` 是否允许执行
+7. `owner` 是否存在
+8. `required_roles` / `optional_roles` 是否都能映射到角色索引
+
+## 7. 当前建议
+
+当前阶段不要把流程模板 frontmatter 做成大而全 schema。
+
+最稳的做法是：
+
+- 先固定一套小字段集合
+- 先让 `prd-to-delivery` 跑通
+- 后续再扩展 `profiles / domains / visibility`
+
+这样最适合当前项目的渐进式推进路径。