.pouch/kits/agent-collaboration-kit/adoption-checklist.md

Adoption Checklist

复制本工具包到新项目后，按这份清单接入。

1. 项目级规范

• 根目录存在 AGENTS.md。
• AGENTS.md 引用 docs/agent-collaboration-kit/。
• 写清项目简介和技术栈。
• 写清本地运行命令。
• 写清构建命令。
• 写清单元测试命令。
• 写清集成测试或浏览器测试命令。

2. 路径权限

• Product/Test 可写规格路径：<spec_paths>。
• Product/Test 可写集成测试路径：<integration_test_paths>。
• Developer 可写源码路径：<source_paths>。
• Developer 可写单元测试路径：<unit_test_paths>。
• 本地私有配置标记为只读或不提交。
• 明确 tasks.yaml 状态字段谁可以改。

3. 任务板

• 从 task-board-template.yaml 创建项目根目录 tasks.yaml。
• 替换 <project_name>、<repo_path>、<base_url>、<dev_worktree>。
• 至少添加一个示例任务，验证字段结构够用。
• 约定状态：open、dispatched、fixed_by_dev、retesting、verified、leftover。

4. Orca 编排

• orca status --json 可用。
• orca terminal list --json 能看到 Coordinator 终端。
• 能创建或复用 Developer Worker。
• 决定默认使用当前 worktree 还是隔离 worktree。
• 验证 worker_done 能发回 Coordinator。

5. 验证命令

• Product/Test 有黑盒验证命令。
• Developer 有白盒验证命令。
• 构建产物和服务启动命令写清楚。
• 浏览器测试的 BASE_URL 写清楚。
• 复测前能确认服务来自正确 worktree。

6. 三轮失败策略

• 每个任务记录 rounds 或等效 evidence。
• 三轮失败后标记 leftover。
• leftover 不阻塞继续处理其他任务。
• 最终报告列出所有 leftover 和最后失败证据。

7. 第一次试运行

推荐选择一个低风险 bug 跑完整流程：

1. Product/Test 写入 tasks.yaml。
2. 创建 Orca task。
3. 派发 Developer Worker。
4. 等待 worker_done。
5. Product/Test 复测。
6. 更新 tasks.yaml。
7. 输出总结。

试运行结束后，检查是否出现以下问题：

• Developer 修改了越权路径。
• worker_done 没有验证证据。
• Product/Test 复测到了旧服务。
• 任务板字段不够记录失败原因。
• 三轮失败策略没有被执行。

把发现的问题回写到项目 AGENTS.md 或本工具包的项目副本中。