@gong-ym/ai-spec-auto 0.2.3

package/.agents/flows/common/prd-to-delivery.md

@@ -0,0 +1,184 @@
+---
+id: prd-to-delivery
+version: 1
+name: PRD 到交付
+status: active
+type: flow-template
+owner: task-orchestrator
+description: 面向新需求、设计还原和增量交付的基础协作模板。主代理基于该模板动态选择必选专家和可选专家。
+triggers:
+  - prd-input
+  - design-input
+  - new-feature
+  - incremental-change
+required_roles:
+  - requirement-analyst
+  - frontend-implementer
+  - code-guardian
+optional_roles:
+  - design-collaborator
+  - api-contract-specialist
+  - unit-test-specialist
+  - verification-reviewer
+  - performance-auditor
+approval_gates: []
+artifacts:
+  - openspec/changes/<change-id>/proposal.md
+  - openspec/changes/<change-id>/specs/
+  - openspec/changes/<change-id>/design.md
+  - openspec/changes/<change-id>/tasks.md
+  - code
+  - openspec/changes/<change-id>/checklist.md
+  - openspec/changes/<change-id>/iterations.md
+visibility: internal
+domains:
+  - demand-design
+  - engineering
+  - testing
+---
+
+# prd-to-delivery
+
+## 模板定位
+
+这不是“写死所有步骤的固定流程”，而是一条基础协作模板。
+
+它定义：
+
+- 本类任务最少需要哪些专家
+- 哪些专家可以按条件插入
+- 哪些节点必须人工确认
+- 本次交付至少要沉淀哪些产物
+
+真正运行时，由 `task-orchestrator` 基于输入任务动态生成本次执行计划。
+
+## 模板目标
+
+把一个输入需求转成可验证、可回溯的交付结果。
+
+它既适用于：
+
+- PRD 驱动的新功能开发
+- 设计稿驱动的页面还原
+- 有明确范围的增量改造
+
+## 不适用场景
+
+以下场景不建议直接套用本模板：
+
+- 纯文档补写且不涉及实现
+- 纯流水线配置或部署变更
+- 纯线上问题排查
+- 无需求边界且缺少任何上下文的探索性任务
+
+这些场景应由 `task-orchestrator` 选择其它模板，或退回人工确认。
+
+## 基础骨架
+
+本模板的默认骨架如下：
+
+1. `requirement-analyst`
+2. `frontend-implementer`
+3. `code-guardian`
+
+这 3 个角色是本模板的必选角色，不应被主代理直接跳过。
+
+## 可选专家插入规则
+
+主代理可根据任务特征插入下列专家：
+
+| 条件 | 建议插入专家 | 作用 |
+| --- | --- | --- |
+| 有设计稿、复杂交互或设计还原要求 | `design-collaborator` | 在实现前补充设计约束和 UI 风险 |
+| 涉及接口契约、字段调整、Mock 设计 | `api-contract-specialist` | 在实现前对接口边界做补充 |
+| 改动存在较高回归风险或需补关键测试 | `unit-test-specialist` | 在实现中或实现后补充测试策略 |
+| 需要对交付结果做更强验证 | `verification-reviewer` | 在守护阶段补强验收结论 |
+| 存在明显性能风险或关键指标目标 | `performance-auditor` | 在交付前补充性能审计意见 |
+
+## 审批点
+
+本模板默认不内建阻塞审批点，主流程会自动推进。
+
+当运行时显式启用 `review_policy = main-flow-blocking（主流程阻塞审核）` 时，才会按顺序注入以下审批点：
+
+1. `before-implementation`
+说明：
+需求边界、关键假设或方案取舍未确认时，不能直接进入实现。
+
+2. `before-guardian`
+说明：
+实现结果需要先经过人工确认，再进入 `code-guardian（规范守护专家）` 守护审查。
+
+3. `before-archive`
+说明：
+存在阻断项、验证结论不清晰或残留风险较高时，不能直接判定交付完成。
+
+## 主要产物
+
+至少要沉淀以下产物：
+
+- `openspec/changes/<change-id>/proposal.md`
+- `openspec/changes/<change-id>/specs/`
+- `openspec/changes/<change-id>/design.md`
+- `openspec/changes/<change-id>/tasks.md`
+- 与本次变更相关的代码实现
+- `openspec/changes/<change-id>/checklist.md`
+- `openspec/changes/<change-id>/iterations.md`
+
+## 完成标准
+
+当满足以下条件时，模板执行才可视为完成：
+
+- 需求边界已被收敛为 `proposal.md`
+- 增量规范已落在 `specs/`，且允许按 domain 拆分多份 spec
+- 技术方案已沉淀为 `design.md`
+- 实施任务已被拆解为 `tasks.md`
+- 代码实现与任务范围一致
+- 交付前检查已完成并形成 `checklist.md`
+- 本轮问题和经验已记录到 `iterations.md`
+
+## 说明
+
+当前阶段这仍然是最小 MVP 模板。
+
+后续新增专家时，不需要推翻这条模板，只需要：
+
+- 保持基础骨架稳定
+- 扩充可选专家条件
+- 扩充审批点和产物约束
+
+## 运行档位
+
+同一条 `prd-to-delivery` 模板支持两种运行档位，但都保留相同的三专家骨架：
+
+### micro
+
+适用于：
+
+- Mock 页面
+- 单页面或单组件
+- 简单 Bug 修复
+- 无复杂业务联动、无真实接口契约的轻量任务
+
+约束：
+
+- 仍然必须经过 `requirement-analyst -> frontend-implementer -> code-guardian`
+- `proposal/specs/design/tasks/checklist/iterations` 仍需真实落盘
+- 但产物采用短版 compact 规格
+- 机械交接优先由宿主层自动推进
+- 默认不保留运行历史文件
+
+### standard
+
+适用于：
+
+- 真实业务页面或模块
+- 多状态联动
+- 涉及真实接口或复杂业务规则
+- 需要完整审查和更强验收证据的交付
+
+约束：
+
+- 默认自动推进；需要人工审核时显式切换到 `main-flow-blocking（主流程阻塞审核）`
+- 使用完整 OpenSpec 产物
+- 允许更完整的设计、任务和审查说明

package/.agents/flows/common/requirement-to-observability.md

@@ -0,0 +1,97 @@
+---
+id: requirement-to-observability
+version: 1
+name: 需求到可观测
+status: active
+type: flow-template
+owner: task-orchestrator
+description: 面向埋点口径、错误追踪和真实用户监控设计的可观测治理模板。用于把需求边界继续沉淀成可分析、可追踪的观测方案。
+triggers:
+  - observability-plan
+  - event-instrumentation
+  - error-monitoring
+required_roles:
+  - requirement-analyst
+  - event-instrumentation-specialist
+optional_roles:
+  - error-tracker
+  - rum-analyst
+  - code-guardian
+approval_gates: []
+artifacts:
+  - openspec/changes/<change-id>/proposal.md
+  - openspec/changes/<change-id>/design.md
+  - openspec/changes/<change-id>/tasks.md
+  - event-plan
+  - tracking-schema-notes
+  - error-triage-notes
+  - rum-analysis-notes
+visibility: internal
+domains:
+  - demand-design
+  - observability
+  - governance
+---
+
+# requirement-to-observability
+
+## 模板定位
+
+这条模板服务于“需求已经明确，但还缺可观测设计”的场景。
+
+它重点回答：
+
+- 要追哪些关键事件
+- 事件字段和命名如何统一
+- 错误追踪与归因口径如何建立
+- 哪些真实用户数据值得持续关注
+
+## 适用场景
+
+- 新功能要补行为埋点
+- 现有埋点口径不统一，需要治理
+- 团队开始补错误追踪或 RUM 观察面
+
+## 不适用场景
+
+- 纯页面实现，没有观测需求
+- 只有单点 bug 修复，不涉及追踪设计
+- 没有任何需求边界，只有模糊“想看数据”
+
+## 基础骨架
+
+本模板的默认骨架如下：
+
+1. `requirement-analyst`
+2. `event-instrumentation-specialist`
+
+## 可选专家插入规则
+
+| 条件 | 建议插入专家 | 作用 |
+| --- | --- | --- |
+| 需要统一错误分层和归因口径 | `error-tracker` | 补高频错误与排查视角 |
+| 已有真实用户监控数据，需判断真实影响 | `rum-analyst` | 补用户侧风险判断 |
+| 需要形成阻断项和放行口径 | `code-guardian` | 审核观测方案是否可交付 |
+
+## 主要产物
+
+至少要沉淀以下内容：
+
+- `proposal.md`
+- `design.md`
+- `tasks.md`
+- `event-plan`
+- `tracking-schema-notes`
+
+## 完成标准
+
+当满足以下条件时，本模板可视为完成：
+
+- 观测目标已经和需求边界对齐
+- 事件命名、触发时机和字段口径已经清楚
+- 错误追踪或 RUM 观察面已有清晰建议
+- 后续实现和验收可以直接消费这些观测定义
+
+## 说明
+
+这条模板关注“把需求变成可观测方案”，不是直接替代埋点实现。

package/.agents/orchestration/README.md

@@ -0,0 +1,22 @@
+# 主代理协议目录
+
+本目录用于存放 `task-orchestrator` 的内部协议、运行时载荷、桥接说明与配套模板。
+
+目录约定：
+
+- `roles/`：谁来做
+- `skills/`：怎么做
+- `flows/`：按什么顺序做
+- `orchestration/`：主代理运行协议、载荷规范、桥接约定
+- `registry/`：安装与运行时索引
+
+放在这里的文件不是“专家角色”，而是给主代理、运行时适配层、抽取器和桥接层使用的支撑文档。
+
+当前包含的文件类型：
+
+- `*-spec.md`：协议与数据结构说明
+- `*-payload.md`：桥接/适配载荷规范
+- `*-template.md`：主代理输出模板
+- `*-hooks.md`：运行时钩子与调用约定
+
+新增主代理配套文件时，优先放在本目录，不再回写到 `.agents/roles/common/`。

package/.agents/orchestration/expert-dispatch-spec.md

@@ -0,0 +1,155 @@
+---
+id: expert-dispatch-spec
+name: 专家派发载荷规范
+status: active
+owner: task-orchestrator
+description: 定义当前运行态如何生成并更新当前专家执行载荷，使 run（运行编排） 能稳定衔接到专家实际执行。
+---
+
+# 专家派发载荷规范
+
+> **Profile 驱动说明（V1）**：本规范中的示例以 `frontend-implementer` 作为实现角色。实际派发时，`expert.id` 应根据当前 profile 的 `implementation_role` 动态填入（`frontend-implementer` / `backend-implementer` / `tooling-implementer`）。
+>
+> **多 profile 说明**：当 manifest 使用 `profiles` 数组时（如 `["vue", "nestjs"]`），`task-orchestrator` 须先通过"路径前缀匹配"确定本次变更属于哪个子包，再取对应 profile 的 `implementation_role` 作为 `expert.id`。
+
+## 1. 目的
+
+这份规范解决的问题是：
+
+> `run-state（运行状态）` 已经落盘，但系统还需要一份由 `task-orchestrator（任务主代理）` 明确产出的“当前专家可执行载荷”。
+
+因此当前推荐形态是：
+
+- `task-orchestrator（任务主代理）` 负责理解任务、选择角色、裁剪上下文、决定技能
+- 本地工具只负责校验和落盘 `expert-dispatch（专家派发载荷）`
+
+## 2. 推荐落盘位置
+
+当前阶段使用两处落盘：
+
+- `.ai-spec/internal/current-dispatch.json`
+- `.ai-spec/internal/dispatches/<run-id>/<dispatch-id>.json`
+
+其中：
+
+- `internal/current-dispatch.json`
+  - 始终表示“当前这一轮应该交给谁执行”
+- `internal/dispatches/<run-id>/`
+  - 记录本次运行历史上生成过哪些专家执行载荷
+
+## 3. 最小结构
+
+```json
+{
+  "schema_version": 1,
+  "kind": "expert-dispatch",
+  "dispatch_id": "2026-03-31T15-10-00-000Z__frontend-implementer",
+  "generated_at": "2026-03-31T15:10:00.000Z",
+  "run_id": "run_20260331_151000_abcd",
+  "status": "running",
+  "role": {
+    "id": "frontend-implementer",
+    "name": "前端实现专家",
+    "source": ".agents/roles/common/frontend-implementer.md",
+    "preferred_skills": ["execute-task", "create-component"]
+  },
+  "task": {
+    "raw_goal": "创建一个商品组件",
+    "change_id": "add-product-card"
+  },
+  "flow": {
+    "id": "prd-to-delivery"
+  },
+  "execution": {
+    "profile": "vue",
+    "current_role": "frontend-implementer",
+    "next_role": "code-guardian",
+    "pending_gate": null,
+    "expected_output": ["完成组件实现"],
+    "skills": [
+      {
+        "id": "create-component",
+        "installed": true,
+        "path": ".agents/skills/create-component/SKILL.md"
+      }
+    ]
+  },
+  "anchor": {
+    "kind": "task-anchor"
+  },
+  "instructions": {
+    "source": ".agents/roles/common/frontend-implementer.md",
+    "markdown": "# 前端实现专家 ..."
+  }
+}
+```
+
+## 4. 推荐接入方式
+
+当前最稳的接入方式是：
+
+```bash
+ai-spec-auto expert-dispatch apply --payload ./.ai-spec/internal/tmp/current-dispatch.json
+```
+
+或：
+
+```bash
+cat ./.ai-spec/internal/tmp/current-dispatch.json | ai-spec-auto expert-dispatch apply --stdin
+```
+
+也就是说：
+
+- `expert-dispatch（专家派发载荷）` 的内容由 `task-orchestrator（任务主代理）` 产出
+- `bin/` 只做校验、补齐时间戳和 ID、落盘
+- 对 `prd-to-delivery（需求到交付）`，`task.change_id` 必须随派发一起下发，不能丢
+- `requirement-analyst（需求解析专家）` 的 `expected_output` 必须显式包含 `proposal.md` 与 `tasks.md`
+- `code-guardian（规范守护者）` 的 `expected_output` 必须显式包含 `checklist.md` 与 `iterations.md`
+
+推荐在以下动作后由 `task-orchestrator（任务主代理）` 再次产出新的当前派发：
+
+- `bootstrap（首轮桥接）`
+- `handoff（交接）`
+- `approve（审批）`
+- `resume（恢复）`
+
+推荐在以下终态动作后清理当前派发：
+
+- `complete（完成）`
+- `fail（失败）`
+- `cancel（取消）`
+
+## 5. 一句话约束
+
+> `expert-dispatch（专家派发载荷）` 应由 `task-orchestrator（任务主代理）` 产出，本地只负责校验与落盘；不要让本地脚本替代 `task-orchestrator（任务主代理）` 做角色理解、技能选择和上下文裁剪。
+
+补充：
+
+- 若当前流程是 `prd-to-delivery（需求到交付）` 且目标角色是 `requirement-analyst / frontend-implementer / code-guardian`，则 `task.change_id` 缺失应视为非法派发
+
+## 6. 多 profile 下的角色选择规则
+
+当 `.ai-spec/manifest.json` 的 `profiles` 为数组时，`task-orchestrator` 按以下逻辑确定 `expert.id`：
+
+1. 检查本次任务涉及的文件路径列表
+2. 将路径与 `manifest.packages[].path` 逐一做**前缀匹配**
+3. 命中某子包 → 取该子包对应 profile 的 `implementation_role`（从 `profiles.json` 查询）
+4. 多个文件跨多个子包 → 按主体变更量所在子包决定，或拆成多轮派发
+5. 无法匹配任何子包（如根目录配置文件修改）→ 优先使用 `code-guardian` 角色处理，不要猜测技术栈
+
+**示例（vue + nestjs）**：
+
+```
+packages/front/src/components/Foo.vue  → profile: vue  → implementation_role: frontend-implementer
+packages/server/src/user/user.service.ts → profile: nestjs → implementation_role: backend-implementer
+```
+
+`execution.profile` 字段应填写本次实际生效的 profile（非数组，填具体值）：
+
+```json
+"execution": {
+  "profile": "nestjs",
+  "current_role": "backend-implementer",
+  ...
+}
+```

package/.agents/orchestration/expert-executor-spec.md

@@ -0,0 +1,84 @@
+---
+id: expert-executor-spec
+name: 单轮专家执行器规范
+status: active
+owner: task-orchestrator
+description: 定义如何消费 current-dispatch（当前专家派发载荷），为当前专家生成单轮执行载荷，不自动递归推进下一轮。
+---
+
+# 单轮专家执行器规范
+
+## 1. 目的
+
+这份规范解决的问题是：
+
+> 当前系统已经有 `run-state（运行状态）` 和 `expert-dispatch（专家派发载荷）`，但还需要一份由“当前专家”明确产出的“本轮执行输入”。
+
+因此当前阶段的最小实现是：
+
+- 当前专家负责产出 `expert-execution（专家执行载荷）`
+- 本地工具默认负责校验和落盘
+- 当显式启用 `--advance-runtime` 时，本地工具还会把本轮执行稳定映射到运行态更新
+- Phase A（第一步） 只到执行载荷
+- Phase B（第二步） 可额外落盘 `runtime-action（运行动作）` 草案
+- 不自动递归跑完整链
+
+## 2. 当前支持角色
+
+Phase A（第一步） 当前只要求支持 3 个角色：
+
+- `requirement-analyst（需求解析专家）`
+- `frontend-implementer（前端实现专家）`
+- `code-guardian（规范守护者）`
+
+## 3. 推荐落盘位置
+
+- `.ai-spec/internal/current-execution.json`
+- `.ai-spec/internal/current-execution.md`
+- `.ai-spec/internal/executions/<run-id>/<execution-id>.json`
+- `.ai-spec/internal/executions/<run-id>/<execution-id>.md`
+
+## 4. 推荐接入方式
+
+当前最稳的接入方式是：
+
+```bash
+ai-spec-auto expert-executor apply --payload ./.ai-spec/internal/tmp/current-execution.json
+```
+
+或：
+
+```bash
+cat ./.ai-spec/internal/tmp/current-execution.json | ai-spec-auto expert-executor apply --stdin
+```
+
+如果当前环境希望把执行语义和运行态直接接通，可显式启用：
+
+```bash
+ai-spec-auto expert-executor apply --payload ./.ai-spec/internal/tmp/current-execution.json --advance-runtime
+```
+
+此时工具会：
+
+- 识别 `requirement-analyst -> propose`
+- 识别 `frontend-implementer -> apply`
+- 识别 `code-guardian -> verify`
+- 优先读取 `.agents/registry/roles.json` 中的动作与交接约定，代码内置映射只作保底
+- 校验对应 OpenSpec 产物
+- 在确定的流转场景下生成并应用最小 `runtime-action（运行动作）`
+
+Phase B（第二步） 仍支持继续落盘 `runtime-action（运行动作）` 草案：
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json
+```
+
+如需直接提交到运行态：
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json --advance-runtime
+```
+
+## 5. 一句话约束
+
+> `expert-executor（专家执行器）` 不应替当前专家做技能选择、执行推理和下一步动作判断；它可以在显式授权下推进最小运行态，但仍不负责自动生成下一轮 `expert-dispatch（专家派发载荷）`。

package/.agents/orchestration/expert-runtime-action-spec.md

@@ -0,0 +1,73 @@
+---
+id: expert-runtime-action-spec
+name: 单轮专家运行动作产出规范
+status: active
+owner: task-orchestrator
+description: 定义如何把 task-orchestrator（任务主代理） 产出的 task-orchestrator-runtime-action（主代理运行动作载荷）稳定落到 .ai-spec/，但不自动推进到下一轮。
+---
+
+# 单轮专家运行动作产出规范
+
+## 1. 目的
+
+这份规范约束的是 Phase B（第二步）：
+
+> 当 `task-orchestrator（任务主代理）` 已经明确给出“当前专家这一轮结束后建议做什么”时，本地需要一层稳定工具把这份 `runtime-action（运行动作）` 落到 `.ai-spec/`。
+
+这一步只负责：
+
+- 校验 `task-orchestrator-runtime-action（主代理运行动作载荷）`
+- 落盘到 `.ai-spec/internal/current-runtime-action.json`
+
+这一步不负责：
+
+- 自动推理该动作
+- 默认不自动执行该动作
+- 自动递归推进下一轮
+
+## 2. 推荐落盘位置
+
+- `.ai-spec/internal/current-runtime-action.json`
+- `.ai-spec/internal/current-runtime-action.md`
+- `.ai-spec/internal/runtime-actions/<run-id>/<action-id>.json`
+- `.ai-spec/internal/runtime-actions/<run-id>/<action-id>.md`
+
+## 3. 当前最小命令
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json
+```
+
+或：
+
+```bash
+cat ./.ai-spec/internal/tmp/current-runtime-action.json | ai-spec-auto expert-executor apply-action --stdin
+```
+
+如果当前环境已经确认由 `expert-executor（专家执行器）` 负责把动作提交到运行态，可显式启用：
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json --advance-runtime
+```
+
+补充约束：
+
+- `run_id` 缺省时允许从 `.ai-spec/current-run.json` 自动补齐
+- `complete` 会被视作 OpenSpec 的 `archive` 语义收尾，但运行态仍落为 `complete`
+
+## 4. 与 Phase C（第三步） 的边界
+
+当前这一步只做：
+
+- 记录标准 `task-orchestrator-runtime-action（主代理运行动作载荷）`
+
+当前这一步不做：
+
+- 默认不自动调用 `task-orchestrator-adapter（自动执行适配层）`
+- 不自动递归推进下一轮
+- 不自动连跑完整专家链
+- 不自动生成下一轮 `expert-dispatch（专家派发载荷）`
+
+## 5. 一句话要求
+
+> Phase B（第二步） 允许系统记录“下一步动作草案”，也允许在显式授权下把它提交到运行态；但动作本身仍必须由 `task-orchestrator（任务主代理）` 明确产出，不能由本地脚本代替 `task-orchestrator（任务主代理）` 推理。