.pouch/skills/agent-collaboration-kit/roles-and-permissions.md

Roles And Permissions

本文件定义多 Agent 协作的责任边界。目标是让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。

角色模型

角色	主要职责	验证方式	不应做的事
Product/Test Coordinator	需求拆解、任务记录、黑盒测试、复测验收、调度开发	浏览器、API、集成脚本、用户可见行为	修改应用源码、凭 worker_done 直接标记完成
Developer Worker	实现修复、写单元测试、运行构建和白盒验证	单元测试、类型检查、构建、本地运行	修改产品规格、标记 verified、绕过测试声称完成
User / Decision Owner	决定范围、优先级、阻塞项是否继续	审阅报告和遗留清单	直接替代复测证据

路径权限模板

目标项目应在 AGENTS.md 中填入实际路径。

路径	Product/Test	Developer	说明
<spec_paths>	R/W	Read-only	PRD、API spec、设计文档
<integration_test_paths>	R/W	Read-only	浏览器用例、API smoke、回归清单
<test_records_path>	R/W	Read-only	复测记录，通常可 gitignore
<source_paths>	Read-only	R/W	应用源码
<unit_test_paths>	Read-only	R/W	单元测试
<shared_config_templates>	Read-only	R/W	可提交配置模板
<local_config>	Read-only	Read-only	本地私有配置，不提交
tasks.yaml	R/W	Limited R/W	任务事实源；Developer 可写实现状态和证据，Product/Test 写 verified

Product/Test Coordinator 工作流

1. 读取用户目标、项目规格、任务板。
2. 用黑盒方式复现问题或验证需求。
3. 在 tasks.yaml 写入任务：
   • 复现步骤
   • 预期结果
   • 实际结果
   • 证据
   • 验收命令或验收页面
4. 创建 Orca 编排任务并派发 Developer Worker。
5. 等待 worker_done / escalation / decision_gate。
6. 重新构建和复测。
7. 通过则标记 verified；失败则追加证据并继续派发，最多三轮。
8. 三轮失败则标记为遗留项，继续下一个任务。

Developer Worker 工作流

1. 读取 AGENTS.md、tasks.yaml 和相关规格。
2. 只修改 Developer 可写路径。
3. 做最小正确修改，避免顺手重构。
4. 为非平凡逻辑补充或更新单元测试。
5. 运行项目要求的验证命令。
6. 完成后发送一次 worker_done，包含：
   • 修改文件
   • 验证命令和结果
   • 剩余风险
7. 不标记 verified，也不提交或推送，除非用户明确要求。

状态机

推荐 tasks.yaml 使用以下状态：

open
  -> dispatched
  -> fixed_by_dev
  -> retesting
  -> verified

失败分支：

dispatched -> blocked
fixed_by_dev -> failed_retest -> dispatched
failed_retest x3 -> leftover

状态定义：

状态	写入者	含义
open	Product/Test	已发现，等待处理
dispatched	Product/Test	已派发给开发 Agent
blocked	Product/Test 或 Developer	需要用户决策或外部条件
fixed_by_dev	Developer	开发声称已修复并提供验证
retesting	Product/Test	正在复测
failed_retest	Product/Test	复测失败，可继续派发
verified	Product/Test	复测通过
leftover	Product/Test	三轮仍未通过，留给人工或专项处理

完成定义

一个任务只有同时满足以下条件，才能标记 verified：

• Developer 已提供修改文件和验证证据。
• Product/Test 在正确 worktree 和正确服务实例上复测。
• 相关单元测试、构建、集成或浏览器检查通过。
• tasks.yaml 中记录了复测证据。
• 用户可见行为符合验收标准。