@gong-ym/ai-spec-auto 0.2.3

package/.agents/flows/RUN_OUTPUT.md

@@ -0,0 +1,263 @@
+# ai-spec-auto run 最小解析器与输出约定
+
+本文件定义 `ai-spec-auto run` 在读取流程模板 frontmatter 后的最小输出结构。
+
+目标不是一次把整个执行引擎定义完，而是先保证：
+
+- CLI 可稳定输出
+- OpenClaw 可稳定读取
+- 后续主代理路由和状态机可以在此基础上扩展
+
+## 1. 为什么要有这个约定
+
+`ai-spec-auto run` 至少会经过两个阶段：
+
+1. 读取流程模板 frontmatter，得到结构化模板信息
+2. 结合任务输入，由主代理生成本次实际执行计划
+
+如果没有统一 JSON 输出：
+
+- CLI 只能打印文字
+- OpenClaw 只能靠日志猜当前状态
+- 后续很难做状态追踪、审批、恢复和审计
+
+因此建议把输出分成两类对象：
+
+- `flow-descriptor`
+- `run-plan`
+
+## 2. 阶段一：flow-descriptor
+
+这是“模板解析结果”，只依赖 frontmatter，不包含本次任务的动态路由结果。
+
+### 2.1 输出时机
+
+在 `ai-spec-auto run` 读取到模板文件并完成 frontmatter 校验后立即生成。
+
+### 2.2 最小 JSON 结构
+
+```json
+{
+  "schema_version": 1,
+  "kind": "flow-descriptor",
+  "flow": {
+    "id": "prd-to-delivery",
+    "version": 1,
+    "name": "PRD 到交付",
+    "status": "active",
+    "type": "flow-template",
+    "owner": "task-orchestrator",
+    "description": "面向新需求、设计还原和增量交付的基础协作模板。",
+    "visibility": "internal",
+    "domains": ["demand-design", "engineering", "testing"],
+    "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": ["before-implementation", "before-archive"],
+    "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"
+    ],
+    "source": ".agents/flows/common/prd-to-delivery.md"
+  },
+  "errors": [],
+  "warnings": []
+}
+```
+
+### 2.3 说明
+
+- `schema_version`
+  - 表示输出契约版本，不等于 flow frontmatter 的 `version`
+- `kind`
+  - 当前固定为 `flow-descriptor`
+- `flow.source`
+  - 为解析器补充字段，不来自 frontmatter
+- `errors`
+  - 仅用于模板解析层错误
+- `warnings`
+  - 用于提示非阻断问题
+
+## 3. 阶段二：run-plan
+
+这是“主代理生成的执行计划”，在 `flow-descriptor` 之上增加本次任务的动态路由结果。
+
+### 3.1 输出时机
+
+在主代理完成：
+
+- 模板选择
+- 必选专家确认
+- 可选专家激活
+- 审批点生成
+
+之后输出。
+
+### 3.2 最小 JSON 结构
+
+```json
+{
+  "schema_version": 1,
+  "kind": "run-plan",
+  "run_id": "run_20260326_001",
+  "mode": "auto",
+  "review_policy": "main-flow-blocking",
+  "status": "planned",
+  "task": {
+    "change_id": "add-user-center",
+    "input_kind": "prd-input",
+    "risk_level": "medium"
+  },
+  "flow": {
+    "id": "prd-to-delivery",
+    "name": "PRD 到交付",
+    "source": ".agents/flows/common/prd-to-delivery.md"
+  },
+  "plan": {
+    "required_roles": ["requirement-analyst", "frontend-implementer", "code-guardian"],
+    "activated_optional_roles": ["design-collaborator", "api-contract-specialist"],
+    "skipped_optional_roles": ["unit-test-specialist", "verification-reviewer", "performance-auditor"],
+    "approval_gates": ["before-implementation", "before-guardian", "before-archive"],
+    "first_handoff": "requirement-analyst",
+    "review_policy": "main-flow-blocking"
+  },
+  "artifacts": [
+    "openspec/changes/add-user-center/proposal.md",
+    "openspec/changes/add-user-center/specs/",
+    "openspec/changes/add-user-center/design.md",
+    "openspec/changes/add-user-center/tasks.md",
+    "openspec/changes/add-user-center/checklist.md",
+    "openspec/changes/add-user-center/iterations.md"
+  ],
+  "missing_inputs": [
+    "API 字段说明未确认"
+  ],
+  "warnings": [],
+  "errors": []
+}
+```
+
+## 4. 字段说明
+
+### 4.1 顶层字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `schema_version` | 输出契约版本，当前固定为 `1` |
+| `kind` | `flow-descriptor` 或 `run-plan` |
+| `run_id` | 仅 `run-plan` 需要，表示一次运行实例 ID |
+| `mode` | 主代理运行模式：`auto / suggest / manual` |
+| `review_policy` | 当前审核策略：`none / main-flow-blocking` |
+| `status` | 当前运行状态，如 `planned / waiting-confirm / waiting-approval / running / blocked` |
+
+### 4.2 `task`
+
+用于表达本次运行所面向的任务上下文。
+
+当前最小字段建议：
+
+- `change_id`
+- `input_kind`
+- `risk_level`
+
+### 4.3 `plan`
+
+这是 `run-plan` 最关键的部分。
+
+| 字段 | 说明 |
+| --- | --- |
+| `required_roles` | 本模板本次必须参与的专家 |
+| `activated_optional_roles` | 主代理动态激活的可选专家 |
+| `skipped_optional_roles` | 本次未激活的可选专家 |
+| `approval_gates` | 本次实际保留的审批点 |
+| `first_handoff` | 第一位要被启动的专家 |
+| `review_policy` | 本次计划对应的审核策略，便于运行时恢复默认门禁 |
+
+## 5. 最小实现建议
+
+当前阶段不要试图让 `ai-spec-auto run` 一次做完整状态机。
+
+建议分两步实现：
+
+### Step 1
+
+支持：
+
+- 读取流程模板
+- 输出 `flow-descriptor`
+- 校验流程元数据是否完整
+
+### Step 2
+
+支持：
+
+- 主代理根据输入生成 `run-plan`
+- 输出 `first_handoff`
+- 输出 `approval_gates`
+- 输出 `review_policy`
+- 输出 `missing_inputs`
+
+## 6. 错误处理约定
+
+### 6.1 模板解析错误
+
+若 frontmatter 无法解析，返回：
+
+```json
+{
+  "schema_version": 1,
+  "kind": "flow-descriptor",
+  "flow": null,
+  "errors": ["missing required field: required_roles"],
+  "warnings": []
+}
+```
+
+### 6.2 路由错误
+
+若模板能解析，但主代理无法生成可执行计划，返回：
+
+```json
+{
+  "schema_version": 1,
+  "kind": "run-plan",
+  "status": "blocked",
+  "errors": ["missing business goal", "input scope is ambiguous"],
+  "warnings": []
+}
+```
+
+## 7. 推荐输出方式
+
+为了兼容 CLI、本地脚本和 OpenClaw，建议：
+
+- 标准输出打印 `run-plan` JSON
+- 人类可读说明走标准错误输出或额外 `--pretty` 模式
+
+这样可以保证：
+
+- 机器人读 JSON
+- 人看可读文本
+
+两者互不干扰。
+
+## 8. 当前建议
+
+当前阶段，`ai-spec-auto run` 最重要的不是“真的把所有专家跑完”，而是先做到这三件事：
+
+1. 读模板
+2. 产出结构化执行计划
+3. 明确第一跳交接给谁
+
+只要这三件事稳定了，后面接 OpenClaw、审批、恢复、审计都会顺很多。
+
+补充当前默认语义：
+
+- `suggest（建议）` 模式下，`run-plan（运行计划）` 落盘后通常会进入 `waiting-confirm（等待确认）`
+- `manual（手动）` 模式下，必须显式指定 `flow（流程模板）`
+- `prd-to-delivery（需求到交付流程）` 在 `review_policy = main-flow-blocking（主流程阻塞审核）` 下，会把 `before-guardian（守护前门禁）` 注入到实际 `approval_gates（审批点）` 中

package/.agents/flows/common/README.md

@@ -0,0 +1,29 @@
+# 流程目录说明
+
+本目录用于定义“专家协同流程”。
+
+当前阶段已落地 5 条流程：
+
+- `prd-to-delivery.md`
+- `bugfix-to-verification.md`
+- `change-to-release.md`
+- `requirement-to-observability.md`
+- `change-to-architecture-review.md`
+
+这里的“流程”不再理解成写死所有步骤的刚性链路，而应理解成：
+
+- 基础协作模板
+- 必选专家骨架
+- 可选专家插入条件
+- 审批点和产物约束
+
+当前阶段的目标不是把流程做复杂，而是先把“大需求主链”“小需求快修链”和“发布/可观测/架构评审补充链”都收口稳定，后续再按相同结构继续新增。
+
+## Frontmatter 约定
+
+流程模板的结构化元数据统一约定见：
+
+- [../FRONTMATTER.md](../FRONTMATTER.md)
+- [../RUN_OUTPUT.md](../RUN_OUTPUT.md)
+
+后续 CLI、插件页面、OpenClaw 调度层都应优先解析 frontmatter，而不是依赖正文做关键路由判断。

package/.agents/flows/common/bugfix-to-verification.md

@@ -0,0 +1,95 @@
+---
+id: bugfix-to-verification
+version: 1
+name: 缺陷修复到验证
+status: active
+type: flow-template
+owner: task-orchestrator
+description: 面向全新、低风险、小范围 bug 修复或样式/文案/小交互调整的轻量协作模板。默认不进入 OpenSpec change 目录，而是在 .ai-spec/history/<run-id>/ 下保留最小留痕。
+triggers:
+  - bugfix-routing
+  - small-change
+  - style-adjustment
+required_roles:
+  - frontend-implementer
+  - code-guardian
+optional_roles:
+  - unit-test-specialist
+  - verification-reviewer
+  - performance-auditor
+approval_gates: []
+artifacts:
+  - code
+  - .ai-spec/history/<run-id>/bugfix.md
+  - .ai-spec/history/<run-id>/implementation-notes.md
+  - .ai-spec/history/<run-id>/checklist.md
+  - .ai-spec/history/<run-id>/iterations.md
+visibility: internal
+domains:
+  - engineering
+  - testing
+---
+
+# bugfix-to-verification
+
+## 模板定位
+
+这条模板服务于“小而明确”的修复型需求，不替代 `prd-to-delivery`，也不把小修正偷偷升级成完整需求流程。
+
+它适用于：
+
+- 单页面、单组件、单模块的 bug 修复
+- 样式微调、文案调整、小交互修正
+- 风险等级低、无需长期 OpenSpec 规范沉淀的修正
+
+## 不适用场景
+
+以下情况应升级回 `prd-to-delivery`：
+
+- 新增真实 API、路由或全局状态
+- 影响需求范围、验收边界或方案决策
+- 涉及权限、支付、风控、合规等高风险逻辑
+- 需要长期归档、评审或显式 spec 留痕
+
+## 基础骨架
+
+本模板固定骨架为：
+
+1. `frontend-implementer`
+2. `code-guardian`
+
+默认不进入 `requirement-analyst`，也不经过 `archive-change`。
+
+## 可选专家插入规则
+
+| 条件 | 建议插入专家 | 作用 |
+| --- | --- | --- |
+| 修复涉及复杂逻辑、store、明显回归风险 | `unit-test-specialist` | 补关键测试策略 |
+| 需要更强验收证据或复核 | `verification-reviewer` | 补强验证结论 |
+| 修复指向性能问题 | `performance-auditor` | 给出性能风险判断 |
+
+## 主要产物
+
+至少要沉淀以下内容：
+
+- 与本次修复相关的代码实现
+- `.ai-spec/history/<run-id>/bugfix.md`
+- `.ai-spec/history/<run-id>/implementation-notes.md`
+- `.ai-spec/history/<run-id>/checklist.md`
+- `.ai-spec/history/<run-id>/iterations.md`
+
+## 完成标准
+
+当满足以下条件时，本模板可视为完成：
+
+- 修复范围仍然限定在低风险小需求边界内
+- `bugfix.md` 说明了问题、影响范围、复现和限制
+- `implementation-notes.md` 说明了修复动作、验证结果和残留风险
+- `checklist.md` 给出通过 / 未通过 / 阻断项 / 证据 / 是否放行
+- `iterations.md` 记录问题、修正动作、残留风险和后续提醒
+
+## 说明
+
+这条模板的目标是“更轻”，不是“更随意”。
+
+一旦守护阶段发现范围已经越出小修正边界，应立即阻断并升级到 `prd-to-delivery`。

package/.agents/flows/common/change-to-architecture-review.md

@@ -0,0 +1,89 @@
+---
+id: change-to-architecture-review
+version: 1
+name: 变更到架构评审
+status: active
+type: flow-template
+owner: task-orchestrator
+description: 面向跨模块改动、依赖调整和结构性演进的架构评审模板。用于在实现前或实现中期补一轮边界与影响分析。
+triggers:
+  - architecture-review
+  - module-boundary-design
+  - dependency-audit
+required_roles:
+  - architecture-advisor
+  - dependency-governor
+optional_roles:
+  - requirement-analyst
+  - code-guardian
+approval_gates: []
+artifacts:
+  - architecture-notes
+  - module-boundary-suggestions
+  - dependency-audit-notes
+  - upgrade-plan
+visibility: internal
+domains:
+  - engineering
+  - governance
+---
+
+# change-to-architecture-review
+
+## 模板定位
+
+这条模板服务于“改动已经超出单点实现，需要先看结构和影响面”的场景。
+
+它重点处理：
+
+- 模块边界是否清楚
+- 依赖引入或升级是否值得
+- 结构性改动会影响谁
+- 后续实现应如何拆分和回滚
+
+## 适用场景
+
+- 涉及多个模块或多个包的改动
+- 需要新增、升级或替换关键依赖
+- 目录边界、职责拆分或架构走向存在争议
+
+## 不适用场景
+
+- 纯样式或文案微调
+- 已经明确是低风险小修正
+- 仅需执行既定 tasks，不再涉及结构判断
+
+## 基础骨架
+
+本模板的默认骨架如下：
+
+1. `architecture-advisor`
+2. `dependency-governor`
+
+## 可选专家插入规则
+
+| 条件 | 建议插入专家 | 作用 |
+| --- | --- | --- |
+| 需求边界仍需再收敛 | `requirement-analyst` | 补需求和实现范围约束 |
+| 需要形成阻断项与放行结论 | `code-guardian` | 输出规范一致性检查 |
+
+## 主要产物
+
+至少要沉淀以下内容：
+
+- `architecture-notes`
+- `module-boundary-suggestions`
+- `dependency-audit-notes`
+- `upgrade-plan`
+
+## 完成标准
+
+当满足以下条件时，本模板可视为完成：
+
+- 结构性风险已经被识别并记录
+- 依赖引入、升级或移除的影响面已经清楚
+- 后续实现拆分、验证路径和回滚关注点已经明确
+
+## 说明
+
+这条模板关注“先把结构问题看清”，不是替代最终实现。

package/.agents/flows/common/change-to-release.md

@@ -0,0 +1,94 @@
+---
+id: change-to-release
+version: 1
+name: 变更到发布
+status: active
+type: flow-template
+owner: task-orchestrator
+description: 面向构建、回归验证、流水线与部署上线准备的发布型协作模板。用于把“代码已改完”继续推进到“可上线、可回滚、可复验”。
+triggers:
+  - release-readiness
+  - ci-release
+  - deployment-change
+required_roles:
+  - build-specialist
+  - pipeline-specialist
+  - deployment-specialist
+optional_roles:
+  - e2e-test-specialist
+  - code-guardian
+approval_gates: []
+artifacts:
+  - code
+  - build-analysis
+  - pipeline-plan
+  - deployment-plan
+  - release-checklist
+visibility: internal
+domains:
+  - engineering
+  - testing
+  - delivery
+---
+
+# change-to-release
+
+## 模板定位
+
+这条模板服务于“实现已经基本完成，但发布链还没收口”的场景。
+
+它不替代 `prd-to-delivery`，而是聚焦：
+
+- 构建入口是否稳定
+- 回归验证是否足够
+- 流水线是否可复用
+- 部署与回滚风险是否清楚
+
+## 适用场景
+
+- 新增或调整构建脚本、产物结构、发布流水线
+- 上线链路依赖人工步骤较多，需要收口
+- 需要把回归验证、部署配置和发布策略统一整理
+
+## 不适用场景
+
+- 纯业务需求分析
+- 只涉及页面或接口实现、尚未进入发布准备
+- 纯线上故障排查且不涉及发布链路调整
+
+## 基础骨架
+
+本模板的默认骨架如下：
+
+1. `build-specialist`
+2. `pipeline-specialist`
+3. `deployment-specialist`
+
+## 可选专家插入规则
+
+| 条件 | 建议插入专家 | 作用 |
+| --- | --- | --- |
+| 需要更强的端到端回归证据 | `e2e-test-specialist` | 补关键发布前验证路径 |
+| 需要统一阻断项和放行结论 | `code-guardian` | 输出发布前检查结论 |
+
+## 主要产物
+
+至少要沉淀以下内容：
+
+- `build-analysis`
+- `pipeline-plan`
+- `deployment-plan`
+- `release-checklist`
+
+## 完成标准
+
+当满足以下条件时，本模板可视为完成：
+
+- 构建入口、产物和校验步骤已经清楚
+- 流水线中的自动化步骤、人工步骤与失败处理路径已经收口
+- 部署差异、环境依赖和回滚关注点已经明确
+- 若启用验证专家，关键回归路径已有可执行证据
+
+## 说明
+
+这条模板关注的是“怎么稳定发布”，不是重新定义业务范围。