.pouch/kits/agent-collaboration-kit/README.md

Agent Collaboration Kit

这是一套可复制到其他项目的多 Agent 协作规范。它把“产品/测试负责定义与验收，开发负责实现与白盒验证，协调者用 Orca 做闭环调度”的经验抽成项目无关模板。

适用场景

• 项目需要多个 Agent 分工协作，而不是单个 Agent 从需求写到代码。
• 需要明确区分规格、测试、实现、复测的责任边界。
• 需要把测试失败项派发给开发 Agent，等 worker_done 后再由测试 Agent 复测。
• 需要连续修复多个问题，并把三次仍未修好的问题留档。

推荐目录

把本目录复制到目标项目：

docs/agent-collaboration-kit/
  README.md
  roles-and-permissions.md
  orca-closed-loop.md
  task-board-template.yaml
  prompt-templates.md
  optimization-method.md
  adoption-checklist.md

目标项目还应在根目录保留一个项目级 AGENTS.md，引用本目录并填入项目自己的路径、测试命令和运行方式。

核心原则

1. 事实源持久化：任务、bug、验收证据写入任务板文件，不依赖聊天上下文。
2. 角色隔离：Product/Test Agent 只定义和验证；Developer Agent 只实现和自测。
3. worker_done 不等于完成：开发 Agent 声称修好后，必须由 Product/Test Agent 黑盒复测。
4. 最多三轮自动修复：同一问题三轮仍未通过，记录为遗留项，然后继续处理下一个问题。
5. 服务与 worktree 对齐：复测前确认服务、构建产物、分支和工作树一致，避免假通过或假失败。

快速接入步骤

1. 复制本目录到目标项目。
2. 基于 roles-and-permissions.md 在目标项目根目录创建或更新 AGENTS.md。
3. 基于 task-board-template.yaml 创建 tasks.yaml。
4. 在 AGENTS.md 中写清：
   • 项目运行命令
   • 单元测试命令
   • 构建命令
   • 集成/浏览器测试命令
   • Product/Test 与 Developer 的路径权限
5. 使用 orca-closed-loop.md 的流程派发修复。
6. 按 optimization-method.md 执行三轮失败留档和节奏优化。

建议的默认口令

用 Agent 协作闭环处理 tasks.yaml 里的未通过项；每个问题最多派发开发 Agent 修三轮，三轮仍不过就记录为遗留，然后继续下一个。

与具体项目解耦

本工具包使用占位符表达项目差异：

• <repo_path>：仓库根目录
• <dev_worktree>：开发 Agent 工作树
• <base_url>：待测服务地址
• <test_commands>：项目测试命令
• <source_paths>：开发可改源码路径
• <spec_paths>：产品/测试可改规格与测试路径

复制到新项目后，应先替换这些占位符，再开始调度。