@gong-ym/ai-spec-auto 0.2.3

package/.agents/orchestration/task-orchestrator-runtime-hooks.md

@@ -0,0 +1,214 @@
+---
+id: task-orchestrator-runtime-hooks
+name: 主代理运行态钩子规范
+status: active
+owner: task-orchestrator
+description: 定义 task-orchestrator 在首轮规划、审批阻断、审批放行、专家交接、恢复、完成、失败、取消时应如何把最小 scratch 交给宿主 Runner 或回退桥接层消费。
+---
+
+# 主代理运行态钩子规范
+
+> **Profile 驱动说明（V1）**：本规范中的示例以 `frontend-implementer` 作为实现角色。实际运行时，应从 `.ai-spec/manifest.json` 读取 `profile`，再从 `.agents/registry/profiles.json` 查询 `implementation_role`，动态决定交接的实现角色（`frontend-implementer` / `backend-implementer` / `tooling-implementer`）。
+
+## 1. 目的
+
+这份规范不直接替代真正的运行器代码，它解决的是：
+
+> 当 `task-orchestrator（任务主代理）` 真的开始驱动一条任务链时，每个关键节点应优先把哪类最小 scratch 交给宿主 `Runner（运行器）` 消费；如果 `Runner` 不可用，再回退到哪条 `adapter/runtime-state` 命令。
+
+也就是说，它是：
+
+- 自动执行链的调用约定
+- 未来 Runner（运行器）或 IDE（开发工具）插件的接线图
+
+## 2. 最小钩子映射
+
+### 2.1 首轮计划生成后
+
+当主代理已经拿到：
+
+- `run-plan（运行计划）`
+- 首轮 `task-anchor（任务锚点）`
+
+推荐优先方式：
+
+```text
+由宿主层调用内部 Runner：
+task-orchestrator-runner.advanceRunner({ target })
+```
+
+其中默认输入应来自：
+
+- `./.ai-spec/internal/tmp/task-orchestrator-turn.json`
+
+如果当前环境尚未接 `Runner（运行器）`，且当前主代理已经直接产出了结构化 bootstrap JSON，可回退为：
+
+```bash
+ai-spec-auto task-orchestrator-adapter apply --payload ./.ai-spec/internal/tmp/task-orchestrator-bootstrap.json
+```
+
+如果当前环境尚未接抽取层和适配层，再回退为：
+
+```bash
+ai-spec-auto runtime-state bootstrap --payload ./.ai-spec/internal/tmp/task-orchestrator-bootstrap.json
+```
+
+### 2.2 进入审批等待或被阻断
+
+如果当前节点不能继续，需要卡在审批点或阻断点：
+
+```bash
+ai-spec-auto task-orchestrator-adapter apply --payload ./.ai-spec/internal/tmp/current-runtime-action.json
+```
+
+如果只是一般阻断，没有审批点：
+
+```bash
+ai-spec-auto runtime-state gate-blocked --status blocked --message "缺少设计稿，无法继续"
+```
+
+### 2.3 审批通过
+
+优先由宿主 `Runner（运行器）` 或内部工具消费结构化动作载荷；未接时回退为：
+
+```bash
+ai-spec-auto runtime-state approve \
+  --gate before-implementation \
+  --to-role frontend-implementer
+```
+
+### 2.4 专家交接
+
+优先由宿主 `Runner（运行器）` 或内部工具消费结构化动作载荷；未接时回退为：
+
+```bash
+ai-spec-auto runtime-state handoff \
+  --to-role frontend-implementer \
+  --next-role code-guardian \
+  --task-anchor ./.ai-spec/internal/tmp/frontend-implementer-anchor.json \
+  --status running
+```
+
+当前阶段若已接内部桥接层，则在状态更新成功后，会自动清理旧的：
+
+- `.ai-spec/internal/current-dispatch.json`
+- `.ai-spec/internal/current-execution.json`
+- `.ai-spec/internal/current-runtime-action.json`
+
+随后应由 `task-orchestrator（任务主代理）` 根据新的 `run-state（运行状态）` 明确重新产出下一轮：
+
+- `expert-dispatch（专家派发载荷）`
+- `expert-execution（专家执行载荷）`
+
+如果已经接 `Runner（运行器）`，则推荐下一轮统一走：
+
+```text
+task-orchestrator-runner.advanceRunner({ target })
+```
+
+### 2.4.1 单轮专家执行结束后
+
+当前阶段不要求专家自己递归推进下一轮；建议在当前专家完成本轮后，由 `task-orchestrator（任务主代理）` 明确生成标准 `runtime-action（运行动作）` 草案，再由宿主 `Runner（运行器）` 或内部工具落盘：
+
+```text
+task-orchestrator-runner.advanceRunner({ target })
+```
+
+其中默认输入可来自：
+
+- `./.ai-spec/internal/tmp/current-runtime-action.json`
+- 或新的 `./.ai-spec/internal/tmp/task-orchestrator-turn.json`
+
+如果暂未接 `Runner（运行器）`，再回退为：
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json --advance-runtime
+```
+
+若当前环境仍坚持旧的“两步桥接”模式，则继续使用：
+
+```bash
+ai-spec-auto expert-executor apply-action --payload ./.ai-spec/internal/tmp/current-runtime-action.json
+ai-spec-auto task-orchestrator-adapter apply --payload ./.ai-spec/internal/current-runtime-action.json
+```
+
+### 2.5 恢复执行
+
+优先由宿主 `Runner（运行器）` 或内部工具消费结构化动作载荷；未接时回退为：
+
+```bash
+ai-spec-auto runtime-state resume --to-role frontend-implementer --status running
+```
+
+### 2.6 运行完成
+
+优先由宿主 `Runner（运行器）` 或内部工具消费结构化动作载荷；未接时回退为：
+
+```bash
+ai-spec-auto runtime-state complete
+```
+
+### 2.7 运行失败
+
+优先由宿主 `Runner（运行器）` 或内部工具消费结构化动作载荷；未接时回退为：
+
+```bash
+ai-spec-auto runtime-state fail --error "组件规范检查未通过"
+```
+
+### 2.8 用户取消
+
+优先由宿主 `Runner（运行器）` 或内部工具消费结构化动作载荷；未接时回退为：
+
+```bash
+ai-spec-auto runtime-state cancel --message "用户主动取消当前任务"
+```
+
+### 2.9 查询当前状态
+
+优先由宿主 `Runner（运行器）` 或内部工具消费结构化动作载荷；未接时回退为：
+
+```bash
+ai-spec-auto runtime-state status
+```
+
+## 3. 推荐自动链顺序
+
+```text
+task-orchestrator（任务主代理）
+  -> 生成 run-plan（运行计划） + task-anchor（任务锚点） / runtime-action（运行动作）
+  -> 宿主 Runner（运行器）或内部桥接层
+  -> bootstrap（首轮桥接）
+  -> 如需等待审批：gate-blocked（阻断）
+  -> 审批通过：approve（审批）
+  -> 交给下一位专家：handoff（交接）
+  -> 如执行中断：resume（恢复）
+  -> 成功结束：complete（完成）
+  -> 失败结束：fail（失败）
+  -> 用户放弃：cancel（取消）
+```
+
+## 4. 当前阶段边界
+
+当前仓库里已经有：
+
+- 最小 `runtime-state（运行状态）` 命令
+- 最小钩子映射规范
+- 最小 `task-orchestrator-adapter（自动执行适配层）` 回退桥接
+- 最小 `task-orchestrator-runner（运行器）` inbox（收件箱） 消费器
+
+但还没有：
+
+- 自动从 `AI（智能体）` 会话本身拉取输出的宿主层集成
+- 自动生成所有中间 `task-anchor（任务锚点）` 文件的执行器
+- 由本地脚本替代 `task-orchestrator（任务主代理）` 产出 `expert-dispatch（专家派发载荷） / runtime-action（运行动作）`
+- 由本地脚本替当前专家产出 `expert-execution（专家执行载荷）`
+- 由 `expert-executor（专家执行器）` 自动补下一轮 `expert-dispatch（专家派发载荷）`
+
+所以这份规范当前的意义是：
+
+> 先把自动执行链的调用协议定稳，再把真正的运行器接上。
+
+## 5. 一句话要求
+
+> `task-orchestrator（任务主代理）` 不应只负责“说下一步做什么”，还应优先输出最小结构化 scratch；其中 `expert-dispatch（专家派发载荷） / runtime-action（运行动作）` 由 `task-orchestrator（任务主代理）` 产出，`expert-execution（专家执行载荷）` 由当前专家产出，宿主 `Runner（运行器）` 优先负责消费，本地 adapter/runtime-state 只做回退桥接。

package/.agents/registry/README.md

@@ -0,0 +1,63 @@
+---
+name: sync-registry-index
+description: sync（同步）本地求解使用的最小注册表目录。用于维护场景方案、规则映射和技能能力域标签，避免把安装求解数据硬编码在执行脚本里。
+---
+
+# sync（同步）注册表目录
+
+本目录用于承载 `ai-spec-auto sync（同步）` 的本地静态注册表。
+
+当前阶段放 5 类数据：
+
+- `scenario-packages.json`
+  - 兼容保留的 `scenario_package（场景方案包） metadata`，用于导出追踪与展示分析
+  - 不再参与 `sync（同步）` 的安装求解；未知场景包不应阻断安装
+- `rules.json`
+  - 定义 `rule（规则） id` 到实际文件的映射，以及它们的 `domains（能力域）`
+  - `task-orchestrator` 优先通过它解析规则文件，不再在执行器中硬编码规则路径
+- `skills.json`
+  - 定义 `skill（技能）` 的 `domains（能力域）` 标签
+  - `task-orchestrator` 优先通过它解析技能文件，不再在执行器中硬编码技能路径
+- `roles.json`
+  - 定义 `role（专家角色）` 的安装元数据，以及角色侧公共支持文件
+  - 同时承载 `rule_ids / skill_priority / micro_skill_allowlist / rule_contract_profiles / openspec_actions / runtime_transition` 等运行时约束
+- `flows.json`
+  - 定义 `flow（流程模板）` 的安装元数据，以及流程侧公共支持文件
+
+当前原则：
+
+- 运行逻辑写在 `bin/sync.js`
+- 安装求解数据沉淀在 `.agents/registry/`
+- 后续新增或调整 `rules（规则） / skills（技能） / roles（专家角色） / flows（流程模板）` 时，优先改注册表，不优先改执行器
+- `scenario_packages（场景方案包）` 作为 metadata，允许存在于导出快照中，但不再作为本地安装求解的强依赖
+
+## 校验方式
+
+为避免 `registry（注册表）` 数据文件写坏，当前项目提供了专门的校验命令：
+
+```bash
+ai-spec-auto validate-registry
+ai-spec-auto validate-registry --json
+```
+
+校验范围包括：
+
+- `rules.json`
+- `skills.json`
+- `roles.json`
+- `flows.json`
+- `scenario-packages.json`
+
+当前会检查：
+
+- `JSON（结构化数据）` 是否可解析
+- 根字段是否存在
+- `version（版本号）` 是否合法
+- `source（源文件） / sourceByProfile（按技术栈源文件） / support_files（支持文件）` 是否真实存在
+- `domains（能力域）` 是否为字符串数组
+- `roles.json / flows.json` 对 `rules / skills / roles` 的引用是否都能在注册表中找到
+- 若存在 `scenario-packages.json`，其引用关系会继续校验；若不存在，不影响主流程校验
+- `roles.json.rule_contract_profiles` 的 profile key 与数组字段是否合法
+- `scenario_package（场景方案包）` 引用的 `roles（专家角色） / skills（技能） / rules（规则）` 是否都能在注册表中找到
+
+`ai-spec-auto sync（同步）` 在执行前也会先跑一次注册表校验；若校验失败，会直接中断并提示先执行 `ai-spec-auto validate-registry` 查看详情。

package/.agents/registry/flows.json

@@ -0,0 +1,125 @@
+{
+  "version": 1,
+  "support_files": [
+    ".agents/flows/FRONTMATTER.md",
+    ".agents/flows/RUN_OUTPUT.md",
+    ".agents/flows/common/README.md"
+  ],
+  "flows": {
+    "prd-to-delivery": {
+      "name": "PRD 到交付",
+      "status": "active",
+      "source": ".agents/flows/common/prd-to-delivery.md",
+      "default_schema": "expert-delivery",
+      "artifact_profile": "full",
+      "required_roles": ["requirement-analyst", "frontend-implementer", "code-guardian"],
+      "optional_roles": ["design-collaborator", "api-contract-specialist", "unit-test-specialist", "verification-reviewer", "performance-auditor"],
+      "first_handoff": "requirement-analyst",
+      "approval_gates": [],
+      "handoff_gate_policy": {
+        "requirement-analyst->frontend-implementer": "silent",
+        "frontend-implementer->code-guardian": "silent",
+        "code-guardian->archive-change": "silent"
+      },
+      "core_artifacts": ["proposal", "specs", "design", "tasks", "checklist", "iterations"],
+      "required_artifacts": ["proposal.md", "specs", "design.md", "tasks.md", "checklist.md", "iterations.md"],
+      "handoff_policy": "task-orchestrator -> requirement-analyst -> frontend-implementer -> code-guardian -> archive-change(可选) -> terminal",
+      "completion_policy": "proposal.md、specs/、design.md、tasks.md、checklist.md、iterations.md 缺一不可；默认自动进入 archive-change，如需人工审核可切换到 main-flow-blocking"
+    },
+    "bugfix-to-verification": {
+      "name": "缺陷修复到验证",
+      "status": "active",
+      "source": ".agents/flows/common/bugfix-to-verification.md",
+      "default_schema": "expert-delivery",
+      "artifact_profile": "compact",
+      "required_roles": ["frontend-implementer", "code-guardian"],
+      "optional_roles": ["unit-test-specialist", "verification-reviewer", "performance-auditor"],
+      "first_handoff": "frontend-implementer",
+      "approval_gates": [],
+      "handoff_gate_policy": {
+        "frontend-implementer->code-guardian": "silent"
+      },
+      "runtime_transitions": {
+        "frontend-implementer": {
+          "action": "handoff",
+          "to_role": "code-guardian",
+          "next_role": null,
+          "message": "handoff to code-guardian after lightweight bugfix delivery"
+        },
+        "unit-test-specialist": {
+          "action": "handoff",
+          "to_role": "code-guardian",
+          "next_role": null,
+          "message": "handoff to code-guardian after lightweight test supplementation"
+        },
+        "verification-reviewer": {
+          "action": "handoff",
+          "to_role": "code-guardian",
+          "next_role": null,
+          "message": "handoff to code-guardian after lightweight verification review"
+        },
+        "performance-auditor": {
+          "action": "handoff",
+          "to_role": "code-guardian",
+          "next_role": null,
+          "message": "handoff to code-guardian after lightweight performance review"
+        },
+        "code-guardian": {
+          "action": "complete",
+          "to_role": "code-guardian",
+          "next_role": null,
+          "message": "run completed after lightweight verification closeout"
+        }
+      },
+      "core_artifacts": ["bugfix", "implementation-notes", "checklist", "iterations"],
+      "required_artifacts": ["bugfix.md", "implementation-notes.md", "checklist.md", "iterations.md"],
+      "handoff_policy": "task-orchestrator -> frontend-implementer -> code-guardian -> terminal",
+      "completion_policy": "bugfix.md、implementation-notes.md、checklist.md、iterations.md 缺一不可；若守护阶段发现范围升级，则转回 prd-to-delivery"
+    },
+    "change-to-release": {
+      "name": "变更到发布",
+      "status": "active",
+      "source": ".agents/flows/common/change-to-release.md",
+      "default_schema": "expert-delivery",
+      "artifact_profile": "compact",
+      "required_roles": ["build-specialist", "pipeline-specialist", "deployment-specialist"],
+      "optional_roles": ["e2e-test-specialist", "code-guardian"],
+      "first_handoff": "build-specialist",
+      "approval_gates": [],
+      "core_artifacts": ["build-analysis", "pipeline-plan", "deployment-plan", "release-checklist"],
+      "required_artifacts": ["build-analysis", "pipeline-plan", "deployment-plan"],
+      "handoff_policy": "task-orchestrator -> build-specialist -> pipeline-specialist -> deployment-specialist -> code-guardian(可选) -> terminal",
+      "completion_policy": "构建、流水线与部署风险已经收口；若启用 E2E 或守护专家，则需补齐对应验证结论"
+    },
+    "requirement-to-observability": {
+      "name": "需求到可观测",
+      "status": "active",
+      "source": ".agents/flows/common/requirement-to-observability.md",
+      "default_schema": "expert-delivery",
+      "artifact_profile": "full",
+      "required_roles": ["requirement-analyst", "event-instrumentation-specialist"],
+      "optional_roles": ["error-tracker", "rum-analyst", "code-guardian"],
+      "first_handoff": "requirement-analyst",
+      "approval_gates": [],
+      "core_artifacts": ["proposal", "design", "tasks", "event-plan", "tracking-schema-notes"],
+      "required_artifacts": ["proposal.md", "design.md", "tasks.md", "event-plan"],
+      "handoff_policy": "task-orchestrator -> requirement-analyst -> event-instrumentation-specialist -> error-tracker/rum-analyst(可选) -> code-guardian(可选) -> terminal",
+      "completion_policy": "观测目标、事件口径与追踪建议已收口；若启用附加专家，则需补齐错误或 RUM 观察结论"
+    },
+    "change-to-architecture-review": {
+      "name": "变更到架构评审",
+      "status": "active",
+      "source": ".agents/flows/common/change-to-architecture-review.md",
+      "default_schema": "expert-delivery",
+      "artifact_profile": "compact",
+      "required_roles": ["architecture-advisor", "dependency-governor"],
+      "optional_roles": ["requirement-analyst", "code-guardian"],
+      "first_handoff": "architecture-advisor",
+      "approval_gates": [],
+      "core_artifacts": ["architecture-notes", "module-boundary-suggestions", "dependency-audit-notes", "upgrade-plan"],
+      "required_artifacts": ["architecture-notes", "dependency-audit-notes"],
+      "handoff_policy": "task-orchestrator -> architecture-advisor -> dependency-governor -> requirement-analyst/code-guardian(可选) -> terminal",
+      "completion_policy": "模块边界、依赖影响与后续实现拆分建议已经清楚，足以支撑下一轮实现或评审"
+    }
+  }
+}

package/.agents/registry/profiles.json

@@ -0,0 +1,101 @@
+{
+  "version": 1,
+  "profiles": {
+    "vue": {
+      "status": "active",
+      "label": "Vue",
+      "project_type": "frontend",
+      "implementation_role": "frontend-implementer",
+      "rules_dir": ".agents/rules/profiles/vue",
+      "skills_dir": ".agents/skills/profiles/vue",
+      "configs_dir": "configs/profiles/vue",
+      "project_init_rule_ids": [
+        "component-standard",
+        "api-standard",
+        "route-standard",
+        "store-standard",
+        "style-standard",
+        "test-standard-web",
+        "format-check-standard-web"
+      ],
+      "aliases": []
+    },
+    "react": {
+      "status": "active",
+      "label": "React",
+      "project_type": "frontend",
+      "implementation_role": "frontend-implementer",
+      "rules_dir": ".agents/rules/profiles/react",
+      "skills_dir": ".agents/skills/profiles/react",
+      "configs_dir": "configs/profiles/react",
+      "project_init_rule_ids": [
+        "component-standard",
+        "api-standard",
+        "route-standard",
+        "store-standard",
+        "style-standard",
+        "test-standard-web",
+        "format-check-standard-web"
+      ],
+      "aliases": []
+    },
+    "springboot": {
+      "status": "active",
+      "label": "Spring Boot",
+      "project_type": "backend",
+      "implementation_role": "backend-implementer",
+      "rules_dir": ".agents/rules/profiles/springboot",
+      "skills_dir": ".agents/skills/profiles/springboot",
+      "configs_dir": "configs/profiles/springboot",
+      "project_init_rule_ids": [
+        "layering-standard",
+        "api-contract-standard",
+        "persistence-standard",
+        "runtime-config-standard",
+        "exception-standard",
+        "test-standard-jvm",
+        "format-check-standard-jvm"
+      ],
+      "aliases": []
+    },
+    "node-tooling": {
+      "status": "active",
+      "label": "Node.js Tooling",
+      "project_type": "tooling",
+      "implementation_role": "tooling-implementer",
+      "rules_dir": ".agents/rules/profiles/node-tooling",
+      "skills_dir": ".agents/skills/profiles/node-tooling",
+      "configs_dir": "configs/profiles/node-tooling",
+      "project_init_rule_ids": [
+        "cli-standard",
+        "contract-standard",
+        "runtime-files-standard",
+        "logging-standard",
+        "script-entry-standard",
+        "test-standard-node",
+        "format-check-standard-node"
+      ],
+      "aliases": []
+    },
+    "nestjs": {
+      "status": "active",
+      "label": "NestJS",
+      "project_type": "backend",
+      "implementation_role": "backend-implementer",
+      "rules_dir": ".agents/rules/profiles/nestjs",
+      "skills_dir": ".agents/skills/profiles/nestjs",
+      "configs_dir": "configs/profiles/nestjs",
+      "project_init_rule_ids": [
+        "module-structure-standard",
+        "api-contract-standard",
+        "persistence-standard",
+        "config-standard",
+        "exception-standard",
+        "test-standard-node",
+        "format-check-standard-node"
+      ],
+      "aliases": ["nest"]
+    }
+  },
+  "_multi_profile_note": "当 manifest.json 使用 profiles 数组时（如 [\"vue\",\"nestjs\"]），表示同一仓库同时激活多个 profile。规则统一写入根目录 .agents/rules/，文件名需区分领域避免冲突；context/ 下使用单一 PROJECT.md 覆盖整个项目。"
+}