@gong-ym/ai-spec-auto 0.2.13 → 0.2.15

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

@@ -1,48 +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`
+---
+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

@@ -1,45 +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`
+---
+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

@@ -1,59 +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`
+---
+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

@@ -1,63 +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 或内部文件名。
+---
+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 或内部文件名。

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

@@ -1,53 +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，不额外输出协议细节、内部文件名或长篇阶段播报。
+---
+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，不额外输出协议细节、内部文件名或长篇阶段播报。