docs(ai-workflow): 补充多agent协作治理入口

- 新增 gframework-multi-agent-batch skill 及其公开入口说明 - 更新 AGENTS.md 中主 Agent 协调多 worker 的职责与停机约束 - 补充 ai-plan-governance 主题的 public recovery 入口与验证记录
2026-05-10 02:59:02 +08:00 · 2026-05-09 15:56:15 +08:00 · 2026-05-09 15:56:15 +08:00 · 228e954d2d
commit 228e954d2d
parent d4735aec25
9 changed files with 303 additions and 2 deletions
--- a/.agents/skills/README.md
+++ b/.agents/skills/README.md
@ -1,6 +1,6 @@
 # GFramework Skills

-公开入口目前包含 `gframework-doc-refresh` 与 `gframework-batch-boot`。
+公开入口目前包含 `gframework-doc-refresh`、`gframework-batch-boot` 与 `gframework-multi-agent-batch`。

 ## 公开入口

@ -66,6 +66,30 @@
 /gframework-batch-boot keep refactoring repetitive source-generator tests in bounded batches
 ```

+### `gframework-multi-agent-batch`
+
+当用户希望主 Agent 负责拆分任务、派发互不冲突的 subagent 切片、核对进度、维护 `ai-plan`、验收结果并持续推进时，使用该入口。
+
+适用场景：
+
+- 复杂任务已经明确可以拆成多个互不冲突的写面
+- 主 Agent 需要持续 review / integrate，而不是把执行权完全交给单个 worker
+- 需要把 delegated scope、验证结果与下一恢复点同步写回 `ai-plan`
+- 任务仍要受 branch diff、context budget 与 reviewability 边界约束
+
+推荐调用：
+
+```bash
+/gframework-multi-agent-batch <task>
+```
+
+示例：
+
+```bash
+/gframework-multi-agent-batch continue the current cqrs optimization by delegating non-conflicting benchmark and runtime slices
+/gframework-multi-agent-batch coordinate parallel subagents, keep ai-plan updated, and stop when reviewability starts to degrade
+```
+
 ## 共享资源

 - `_shared/DOCUMENTATION_STANDARDS.md`
--- a/.agents/skills/gframework-batch-boot/SKILL.md
+++ b/.agents/skills/gframework-batch-boot/SKILL.md
@ -11,6 +11,9 @@ Use this skill when `gframework-boot` is necessary but not sufficient because th
 batches until a clear stop condition is met.

 Treat `AGENTS.md` as the source of truth. This skill extends `gframework-boot`; it does not replace it.
+If the task's defining requirement is that the main agent must keep acting as dispatcher, reviewer, `ai-plan` owner,
+and final integrator for multiple parallel workers, prefer `gframework-multi-agent-batch` and use this skill's stop
+condition guidance as a secondary reference.

 Context budget is a first-class stop signal. Do not keep batching merely because a file-count threshold still has
 headroom if the active conversation, loaded repo artifacts, validation output, and pending recovery updates suggest the
@ -27,6 +30,7 @@ agent is approaching its safe working-context limit.
   - the work is repetitive, sliceable, or likely to require multiple similar iterations
   - each batch can be given an explicit ownership boundary
   - a stop condition can be measured locally
+   - the task does not primarily need the orchestration-heavy main-agent workflow captured by `gframework-multi-agent-batch`
 3. Before any delegation, define the batch objective in one sentence:
   - warning family reduction
   - repeated test refactor pattern
--- a/.agents/skills/gframework-boot/SKILL.md
+++ b/.agents/skills/gframework-boot/SKILL.md
@ -9,6 +9,8 @@ description: Repository-specific boot workflow for the GFramework repo. Use when

 Use this skill to bootstrap work in the GFramework repository with minimal user prompting.
 Treat `AGENTS.md` as the source of truth. Use this skill to enforce a startup sequence, not to replace repository rules.
+If the task clearly requires the main agent to keep coordinating multiple parallel subagents while maintaining
+`ai-plan` and reviewing each result, switch to `gframework-multi-agent-batch` after the boot context is established.

 ## Startup Workflow

@ -45,6 +47,8 @@ Treat `AGENTS.md` as the source of truth. Use this skill to enforce a startup se
   - Use `explorer` with `gpt-5.1-codex-mini` for narrow read-only questions, tracing, inventory, and comparisons
   - Use `worker` with `gpt-5.4` only for bounded implementation tasks with explicit ownership
   - Do not delegate purely for ceremony; delegate only when it materially shortens the task or controls context growth
+   - If the user explicitly wants the main agent to keep orchestrating multiple workers through several review/integration
+     cycles, prefer `gframework-multi-agent-batch` over ad-hoc delegation
 13. Before editing files, tell the user what you read, how you classified the task, whether subagents will be used,
    and the first implementation step.
 14. Proceed with execution, validation, and documentation updates required by `AGENTS.md`.
--- a/.agents/skills/gframework-multi-agent-batch/SKILL.md
+++ b/.agents/skills/gframework-multi-agent-batch/SKILL.md
@ -0,0 +1,114 @@
+---
+name: gframework-multi-agent-batch
+description: Repository-specific multi-agent orchestration workflow for the GFramework repo. Use when the main agent should keep coordinating multiple parallel subagents, maintain ai-plan recovery artifacts, review subagent results, and continue bounded multi-agent waves until reviewability, context budget, or branch-diff limits say to stop.
+---
+
+# GFramework Multi-Agent Batch
+
+## Overview
+
+Use this skill when `gframework-boot` has already established repository context, and the task now benefits from the
+main agent acting as the persistent coordinator for multiple parallel subagents.
+
+Treat `AGENTS.md` as the source of truth. This skill expands the repository's multi-agent coordination rules; it does
+not replace them.
+
+This skill is for orchestration-heavy work, not for every task that merely happens to use one subagent. Prefer it when
+the main agent must keep splitting bounded write slices, monitoring progress, updating `ai-plan`, validating accepted
+results, and deciding whether another delegation wave is still safe.
+
+## Use When
+
+Adopt this workflow only when all of the following are true:
+
+1. The task is complex enough that multiple parallel slices materially shorten the work.
+2. The candidate write sets can be kept disjoint.
+3. The main agent still needs to own review, validation, integration, and `ai-plan` updates.
+4. Another wave is still likely to fit the branch-diff, context-budget, and reviewability budget.
+
+Prefer `gframework-batch-boot` instead when the task is mainly repetitive bulk progress with a single obvious slice
+pattern and little need for continuous multi-worker orchestration.
+
+## Startup Workflow
+
+1. Execute the normal `gframework-boot` startup sequence first:
+   - read `AGENTS.md`
+   - read `.ai/environment/tools.ai.yaml`
+   - read `ai-plan/public/README.md`
+   - read the mapped active topic `todos/` and `traces/`
+2. Confirm that the active topic and current branch still match the work you are about to delegate.
+3. Define the current wave in one sentence:
+   - benchmark-host alignment
+   - runtime hotspot reduction
+   - documentation synchronization
+   - other bounded multi-slice work
+4. Identify the critical path and keep it local.
+5. Split only the non-blocking work into disjoint ownership slices.
+6. Estimate whether one more delegation wave is still safe:
+   - include current branch diff vs baseline
+   - loaded `ai-plan` context
+   - expected validation output
+   - expected integration overhead
+
+## Worker Design Rules
+
+For each `worker` subagent, specify:
+
+- the concrete objective
+- the exact owned files or subsystem
+- files or areas the worker must not touch
+- required validation commands
+- expected output format
+- a reminder that other agents may be editing the repo
+
+Prefer `explorer` subagents when the result is read-only ranking, tracing, or candidate discovery.
+
+Do not launch two workers whose write sets overlap unless the overlap is trivial and the main agent has already decided
+how to serialize or reconcile that overlap.
+
+## Main-Agent Loop
+
+While workers run, the main agent should only do non-overlapping work:
+
+- inspect the next candidate slices
+- recompute branch-diff and context-budget posture
+- review finished worker output
+- queue follow-up validation
+- keep `ai-plan/public/**` current when accepted scope or next steps change
+
+After each completed worker task:
+
+1. Review the reported ownership, validation, and changed files.
+2. Confirm the worker stayed inside its boundary.
+3. Run or rerun the required validation locally if the slice is accepted.
+4. Record accepted delegated scope, validation milestones, and the next recovery point in the active `ai-plan` files.
+5. Reassess whether another wave is still reviewable and safe.
+
+## Stop Conditions
+
+Stop the current multi-agent wave when any of the following becomes true:
+
+- the next wave would likely push the main agent near or beyond a safe context budget
+- the remaining work no longer splits into clean disjoint ownership slices
+- branch diff vs baseline is approaching the current reviewability budget
+- integrating another worker would degrade clarity more than it would save time
+- validation failures show that the next step belongs on the critical path and should stay local
+
+If a branch-size threshold is also in play, treat it as a coarse repository-scope signal, not the sole decision rule.
+
+## Task Tracking
+
+When this workflow is active, the main agent must keep the active `ai-plan` topic current with:
+
+- delegated scope that has been accepted
+- validation results
+- current branch-diff posture if it affects stop decisions
+- the next recommended resume step
+
+The main agent should keep active entries concise enough that `boot` can still recover the current wave quickly.
+
+## Example Triggers
+
+- `Use $gframework-multi-agent-batch to coordinate non-conflicting subagents for this complex CQRS task.`
+- `Keep delegating bounded parallel slices, update ai-plan, and verify each worker result before continuing.`
+- `Run a multi-agent wave where the main agent owns review, validation, and integration.`
--- a/.agents/skills/gframework-multi-agent-batch/agents/openai.yaml
+++ b/.agents/skills/gframework-multi-agent-batch/agents/openai.yaml
@ -0,0 +1,4 @@
+interface:
+  display_name: "GFramework Multi-Agent Batch"
+  short_description: "Coordinate bounded parallel subagents with ai-plan tracking"
+  default_prompt: "Use $gframework-multi-agent-batch to coordinate multiple bounded parallel subagents in this GFramework repository while the main agent owns ai-plan updates, validation, review, and integration."
--- a/AGENTS.md
+++ b/AGENTS.md
@ -102,9 +102,13 @@ All AI agents and contributors must follow these rules when writing, reviewing,

 ## Repository Boot Skill

- The repository-maintained Codex boot skill lives at `.codex/skills/gframework-boot/`.
+- The repository-maintained Codex boot skill lives at `.agents/skills/gframework-boot/`.
+- The repository-maintained multi-agent coordination skill lives at `.agents/skills/gframework-multi-agent-batch/`.
 - Prefer invoking `$gframework-boot` when the user uses short startup prompts such as `boot`、`continue`、`next step`、
  `按 boot 开始`、`先看 AGENTS`、`继续当前任务`.
+- Prefer invoking `$gframework-multi-agent-batch` when the user explicitly wants the main agent to delegate bounded
+  parallel work, track subagent progress, maintain `ai-plan`, verify subagent output, and keep coordinating until the
+  current multi-agent batch reaches a natural stop boundary.
 - The boot skill is a startup convenience layer, not a replacement for this document. If the skill and `AGENTS.md`
  diverge, follow `AGENTS.md` first and update the skill in the same change.
 - The boot skill MUST read `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md` and the relevant
@ -131,6 +135,39 @@ All AI agents and contributors must follow these rules when writing, reviewing,
 - The main agent remains responsible for reviewing and integrating subagent output. Unreviewed subagent conclusions do
  not count as final results.

+### Multi-Agent Coordination Rules
+
+- Prefer the repository's multi-agent coordination mode when the user explicitly wants the main agent to keep
+  orchestrating parallel subagents, or when the work naturally splits into `2+` disjoint write slices that can proceed
+  in parallel without blocking the next local step.
+- In that mode, the main agent MUST keep ownership of:
+  - critical-path selection
+  - baseline and stop-condition tracking
+  - `ai-plan` updates
+  - validation planning and final validation
+  - review and acceptance of every subagent result
+  - the final integration and completion decision
+- Before spawning any `worker` subagent, the main agent MUST:
+  - identify the immediate blocking step and keep it local
+  - define disjoint file or subsystem ownership for each worker
+  - state the required validation commands and expected output format
+  - check that the expected write set still fits the current branch-diff and reviewability budget
+- While workers run, the main agent MUST avoid overlapping edits and focus on non-conflicting work such as:
+  - ranking the next candidate slices
+  - reviewing completed worker output
+  - recomputing branch-diff and context-budget posture
+  - keeping `ai-plan/public/**` recovery artifacts current
+- Before accepting a worker result, the main agent MUST confirm:
+  - the worker stayed within its owned files or subsystem
+  - the reported validation is sufficient for that slice
+  - any accepted findings or follow-up scope are recorded in the active `ai-plan` todo or trace when the task is
+    complex or multi-step
+- Do not continue launching workers merely because a file-count threshold still has room. Stop the current wave when
+  ownership boundaries start to overlap, reviewability materially degrades, or the context-budget signal says the main
+  agent should close the batch.
+- When a complex task uses multiple workers, the main agent SHOULD prefer the public workflow documented by
+  `$gframework-multi-agent-batch` unless a more task-specific skill already provides stricter rules.
+
 ## Commenting Rules (MUST)

 All generated or modified code MUST include clear and meaningful comments where required by the rules below.
--- a/ai-plan/public/README.md
+++ b/ai-plan/public/README.md
@ -21,6 +21,10 @@ help the current worktree land on the right recovery documents without scanning
    API-reference alignment baseline.
  - Tracking: `ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md`
  - Trace: `ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md`
+- `ai-plan-governance`
+  - Purpose: govern repository AI workflow rules, recovery entrypoints, and multi-agent coordination conventions.
+  - Tracking: `ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md`
+  - Trace: `ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md`
 - `coroutine-optimization`
  - Purpose: continue the coroutine semantics, host integration, observability, regression coverage, and migration-doc
    follow-up work.
--- a/ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md
+++ b/ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md
@ -0,0 +1,67 @@
+# AI-Plan Governance 跟踪
+
+## 目标
+
+保持仓库级 AI 工作流规则、公开恢复入口与多 Agent 协作约定在 `AGENTS.md`、`.agents/skills/**` 与
+`ai-plan/public/**` 之间一致，并让 `boot` 能稳定恢复这类治理主题。
+
+## 当前恢复点
+
+- 恢复点编号：`AI-PLAN-GOVERNANCE-RP-002`
+- 当前阶段：`Phase 2`
+- 当前焦点：
+  - 已补齐 `ai-plan/public/README.md` 的 active-topic 暴露，使 `feat/cqrs-optimization` 映射到
+    `ai-plan-governance` 时，`boot` 能落到真实的 public tracking / trace 入口。
+  - 已在 `AGENTS.md` 增补主 Agent 协调多 worker wave 时的强约束，明确 critical path、`ai-plan`、
+    review、validation 与 final integration 归主 Agent 所有。
+  - 已新增 `.agents/skills/gframework-multi-agent-batch/`，把“主 Agent 负责派发、核对、更新 `ai-plan`、
+    验收并决定是否继续下一波”的流程沉淀为可复用 skill。
+  - 已轻量更新 `gframework-boot`、`gframework-batch-boot` 与 `.agents/skills/README.md`，把该模式接入既有
+    boot / batch 入口而不重复定义规则。
+  - 当前变更面仍限定在 `AGENTS.md`、`.agents/skills/**` 与 `ai-plan/public/**`，没有扩散到运行时代码或产品
+    模块。
+
+## 当前状态摘要
+
+- 已落地“`AGENTS.md` 负责强治理约束，skill 负责可执行流程”的混合方案。
+- 已修复本 worktree 的一个恢复入口缺口：topic 映射存在，但 active-topic 列表和 public recovery 文件此前缺失。
+- 当前主题已经具备后续继续演进 AI workflow 规则所需的 public tracking / trace 基线。
+
+## 当前活跃事实
+
+- 当前分支：`feat/cqrs-optimization`
+- `AGENTS.md` 的 `Repository Boot Skill` 现已与仓库实际目录对齐，使用 `.agents/skills/gframework-boot/`
+  而不是失效的 `.codex/skills/gframework-boot/` 路径。
+- `AGENTS.md` 新增 `Multi-Agent Coordination Rules`，用于约束主 Agent 的职责边界、worker ownership、
+  acceptance gate 与 stop condition。
+- `.agents/skills/gframework-multi-agent-batch/` 现已包含：
+  - `SKILL.md`
+  - `agents/openai.yaml`
+- `.agents/skills/gframework-boot/SKILL.md` 与 `.agents/skills/gframework-batch-boot/SKILL.md` 现已明确在
+  orchestration-heavy 场景下切换或让位给 `gframework-multi-agent-batch`。
+- `.agents/skills/README.md` 已把 `gframework-multi-agent-batch` 纳入公开入口说明。
+- `ai-plan/public/ai-plan-governance/` 已建立 public tracking / trace 入口，可供后续治理任务继续复用。
+
+## 当前风险
+
+- 漂移风险：若后续只改 `AGENTS.md` 或只改 skill，主 Agent 职责定义可能再次分叉。
+- 入口重叠风险：若 `gframework-batch-boot` 与 `gframework-multi-agent-batch` 的边界被继续模糊，公开入口会变得难以选择。
+- 恢复噪音风险：若该 topic 后续把每一轮治理细节都堆进 active 文件，`boot` 的默认恢复效率会下降。
+
+## 验证说明
+
+- `python3 scripts/license-header.py --check --paths AGENTS.md ai-plan/public/README.md ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md`
+  - 结果：通过
+  - 备注：本轮受 license-header 规则约束的 public 文档文件均已具备 Apache-2.0 头
+- `git diff --check`
+  - 结果：通过
+  - 备注：本轮治理变更未引入 trailing whitespace 或 patch 格式问题
+- `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release`
+  - 结果：通过
+  - 备注：`0 warning / 0 error`；满足仓库“完成任务前至少通过一条 build validation”的要求
+
+## 下一步
+
+1. 后续如再次出现“主 Agent 持续派发并验收多个 worker”的任务，优先直接用真实任务验证 `gframework-multi-agent-batch`
+   的可恢复性与边界清晰度
+2. 若该 skill 的 stop condition、ownership 或 `ai-plan` 记录格式在实战中出现歧义，再回到本 topic 做下一轮治理收口
--- a/ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md
+++ b/ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md
@ -0,0 +1,43 @@
+# AI-Plan Governance 追踪
+
+## 2026-05-09
+
+### 阶段：多 Agent 协作治理入口落地（AI-PLAN-GOVERNANCE-RP-002）
+
+- 确认本轮目标采用混合方案，而不是只写 skill 或只写 `AGENTS.md`：
+  - `AGENTS.md` 承载仓库级强约束
+  - `.agents/skills/gframework-multi-agent-batch/` 承载主 Agent 持续派发 / review / `ai-plan` / validation 的执行流程
+- 修复 repository boot 入口的一处一致性问题：
+  - `AGENTS.md` 先前仍引用 `.codex/skills/gframework-boot/`
+  - 仓库实际技能目录是 `.agents/skills/`
+  - 本轮已对齐为 `.agents/skills/gframework-boot/`，并补入新的多 Agent skill 路径
+- 本轮已落地的治理变更：
+  - 在 `AGENTS.md` 增加 `Multi-Agent Coordination Rules`
+  - 在 `.agents/skills/README.md` 新增 `gframework-multi-agent-batch` 公开入口说明
+  - 在 `.agents/skills/gframework-boot/SKILL.md` 增加 orchestration-heavy 场景切换说明
+  - 在 `.agents/skills/gframework-batch-boot/SKILL.md` 增加与新 skill 的边界说明
+  - 新建 `.agents/skills/gframework-multi-agent-batch/`
+  - 在 `ai-plan/public/README.md` 补入 `ai-plan-governance` active topic
+  - 新建 `ai-plan/public/ai-plan-governance/` 的 tracking / trace 入口
+- 关键约束决策：
+  - 主 Agent 负责 critical path、stop condition、`ai-plan`、validation、review、final integration
+  - worker 只能拿到显式且互不冲突的 ownership slice
+  - 继续派发下一波前，主 Agent 必须重算 reviewability、branch diff 与 context budget
+- 当前收尾目标：
+  - 运行校验
+  - 把验证结果回填到 active tracking / trace
+  - 以 Conventional Commit 提交本轮治理变更
+
+### 验证里程碑
+
+- `python3 scripts/license-header.py --check --paths AGENTS.md ai-plan/public/README.md ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md`
+  - 结果：通过
+- `git diff --check`
+  - 结果：通过
+- `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release`
+  - 结果：通过（`0 warning / 0 error`）
+
+### 下一步
+
+1. 提交本轮多 Agent 协作治理变更
+2. 未来若有真实的 orchestration-heavy 任务进入该 worktree，优先直接用新 skill 驱动并据实补充下一恢复点