From c4c68572c3d96fea7e669e112764319d3a6d34a7 Mon Sep 17 00:00:00 2001
From: laily <i@laily.net>
Date: Mon, 6 Jul 2026 09:24:22 +0800
Subject: [PATCH] feat: add agent-collaboration-kit

---
 .../AGENTS-template.md                        |  94 +++++++
 skills/agent-collaboration-kit/README.md      |  68 ++++++
 .../adoption-checklist.md                     |  74 ++++++
 .../optimization-method.md                    | 194 +++++++++++++++
 .../orca-closed-loop.md                       | 229 ++++++++++++++++++
 .../prompt-templates.md                       | 137 +++++++++++
 .../roles-and-permissions.md                  |  98 ++++++++
 .../task-board-template.yaml                  |  76 ++++++
 8 files changed, 970 insertions(+)
 create mode 100644 skills/agent-collaboration-kit/AGENTS-template.md
 create mode 100644 skills/agent-collaboration-kit/README.md
 create mode 100644 skills/agent-collaboration-kit/adoption-checklist.md
 create mode 100644 skills/agent-collaboration-kit/optimization-method.md
 create mode 100644 skills/agent-collaboration-kit/orca-closed-loop.md
 create mode 100644 skills/agent-collaboration-kit/prompt-templates.md
 create mode 100644 skills/agent-collaboration-kit/roles-and-permissions.md
 create mode 100644 skills/agent-collaboration-kit/task-board-template.yaml

diff --git a/skills/agent-collaboration-kit/AGENTS-template.md b/skills/agent-collaboration-kit/AGENTS-template.md
new file mode 100644
index 0000000..346411e
--- /dev/null
+++ b/skills/agent-collaboration-kit/AGENTS-template.md
@@ -0,0 +1,94 @@
+# <Project Name> Agent Protocol
+
+本项目使用 `docs/agent-collaboration-kit/` 中的多 Agent 协作规范。本文填入本项目自己的路径、命令和权限边界。
+
+## Project Overview
+
+- Project: `<project_name>`
+- Stack: `<tech_stack>`
+- Main app command: `<run_command>`
+- Base URL: `<base_url>`
+- Task board: `tasks.yaml`
+
+## Roles
+
+| Role | Responsibility | Validation |
+|------|----------------|------------|
+| Product/Test Coordinator | Defines requirements, writes task evidence, runs black-box retest, marks verified | Browser/API/integration tests |
+| Developer Worker | Implements fixes/features, writes unit tests, runs build and white-box tests | Unit tests/build/local run |
+
+## Path Scoping
+
+| Path | Product/Test | Developer | Notes |
+|------|:------------:|:---------:|------|
+| `<spec_paths>` | R/W | Read-only | Product specs, API docs, plans |
+| `<integration_test_paths>` | R/W | Read-only | Browser/API regression |
+| `<test_records_path>` | R/W | Read-only | Run records |
+| `<source_paths>` | Read-only | R/W | Application source |
+| `<unit_test_paths>` | Read-only | R/W | Unit tests |
+| `<shared_config_templates>` | Read-only | R/W | Committable config templates |
+| `<local_config_paths>` | Read-only | Read-only | Local secrets/overrides |
+| `tasks.yaml` | R/W | Limited R/W | Product/Test owns `verified`; Developer may write implementation status/evidence |
+
+## Commands
+
+Developer verification:
+
+```bash
+<unit_test_command>
+<build_command>
+<local_run_command>
+```
+
+Product/Test verification:
+
+```bash
+<preflight_command>
+<api_smoke_command>
+<browser_regression_command>
+```
+
+## Task Status Lifecycle
+
+```text
+open -> dispatched -> fixed_by_dev -> retesting -> verified
+```
+
+Failure states:
+
+```text
+blocked
+failed_retest
+leftover
+```
+
+Rules:
+
+- `worker_done` is not completion. Product/Test must retest before `verified`.
+- Each task can be dispatched to Developer at most 3 rounds.
+- If still failing after 3 rounds, mark `leftover`, record evidence, and continue the next task.
+- Do not commit or push unless the user explicitly asks.
+
+## Orca Closed Loop
+
+Use `docs/agent-collaboration-kit/orca-closed-loop.md` when the user asks for supervised implementation/retest loops.
+
+Default loop:
+
+```text
+Product/Test records failure in tasks.yaml
+  -> Orca task-create
+  -> dispatch Developer Worker
+  -> wait worker_done/escalation/decision_gate
+  -> Product/Test retests
+  -> verified / failed_retest / leftover
+```
+
+## Definition Of Done
+
+A task is done only when:
+
+- Developer reports files modified and verification commands.
+- Product/Test verifies in the correct worktree/service.
+- Relevant build/test/browser/API checks pass.
+- `tasks.yaml` contains final evidence.
diff --git a/skills/agent-collaboration-kit/README.md b/skills/agent-collaboration-kit/README.md
new file mode 100644
index 0000000..fba5999
--- /dev/null
+++ b/skills/agent-collaboration-kit/README.md
@@ -0,0 +1,68 @@
+# Agent Collaboration Kit
+
+这是一套可复制到其他项目的多 Agent 协作规范。它把“产品/测试负责定义与验收，开发负责实现与白盒验证，协调者用 Orca 做闭环调度”的经验抽成项目无关模板。
+
+## 适用场景
+
+- 项目需要多个 Agent 分工协作，而不是单个 Agent 从需求写到代码。
+- 需要明确区分规格、测试、实现、复测的责任边界。
+- 需要把测试失败项派发给开发 Agent，等 `worker_done` 后再由测试 Agent 复测。
+- 需要连续修复多个问题，并把三次仍未修好的问题留档。
+
+## 推荐目录
+
+把本目录复制到目标项目：
+
+```text
+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` 执行三轮失败留档和节奏优化。
+
+## 建议的默认口令
+
+```text
+用 Agent 协作闭环处理 tasks.yaml 里的未通过项；每个问题最多派发开发 Agent 修三轮，三轮仍不过就记录为遗留，然后继续下一个。
+```
+
+## 与具体项目解耦
+
+本工具包使用占位符表达项目差异：
+
+- `<repo_path>`：仓库根目录
+- `<dev_worktree>`：开发 Agent 工作树
+- `<base_url>`：待测服务地址
+- `<test_commands>`：项目测试命令
+- `<source_paths>`：开发可改源码路径
+- `<spec_paths>`：产品/测试可改规格与测试路径
+
+复制到新项目后，应先替换这些占位符，再开始调度。
diff --git a/skills/agent-collaboration-kit/adoption-checklist.md b/skills/agent-collaboration-kit/adoption-checklist.md
new file mode 100644
index 0000000..2abf5c4
--- /dev/null
+++ b/skills/agent-collaboration-kit/adoption-checklist.md
@@ -0,0 +1,74 @@
+# 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` 或本工具包的项目副本中。
diff --git a/skills/agent-collaboration-kit/optimization-method.md b/skills/agent-collaboration-kit/optimization-method.md
new file mode 100644
index 0000000..3945894
--- /dev/null
+++ b/skills/agent-collaboration-kit/optimization-method.md
@@ -0,0 +1,194 @@
+# Optimization Method
+
+本文件记录更稳的多 Agent 协作方法，目标是减少“开发声称完成但复测不过”的循环成本。
+
+## 1. 先把验收写成可观测信号
+
+不要只写“页面可用”“体验更好”。每个任务至少写三类信号：
+
+| 类型 | 示例 |
+|------|------|
+| 可见文本 | 页面出现 `确认应用标签`、`取消`、`将修改` |
+| API 结果 | `POST /api/...` 返回 `code=0` 且字段存在 |
+| 交互结果 | 点击按钮后出现确认区；取消后不触发写入 |
+
+好的验收：
+
+```text
+点击“预览变更”后，页面必须出现 API 返回的 diff 行：
+- title
+- 修改前值
+- 修改后值
+- coverChanged 提示
+```
+
+不好的验收：
+
+```text
+预览功能正常。
+```
+
+## 2. worker_done 必须带证据，不带结论
+
+Developer Worker 的 `worker_done` 应该报告：
+
+- 改了哪些文件。
+- 跑了哪些命令。
+- 自己如何复现验收路径。
+- 仍可能有的风险。
+
+不要让 Developer Worker 写：
+
+```text
+已完成，应该可以了。
+```
+
+要写：
+
+```text
+修改 web/app/fix/page.tsx。已运行 npm run build、go test ./...。
+手测 /fix?fileId=1：搜索、选择候选、预览、确认区都可见。
+风险：未执行真实写文件 apply。
+```
+
+## 3. Product/Test 只信自己的复测
+
+即使 worker_done 写了“全部通过”，Coordinator 仍必须重新：
+
+1. 确认 worktree。
+2. 构建或重启服务。
+3. 执行验收命令。
+4. 浏览器或 API 复测。
+5. 更新任务板。
+
+这可以避免三类假通过：
+
+- 测错服务实例。
+- 测到旧构建产物。
+- 开发只验证静态文本，没有验证真实交互。
+
+## 4. 三轮失败策略
+
+每个任务最多自动派发三轮。
+
+```text
+round 1: 常规修复
+round 2: 带复测失败证据的定向修复
+round 3: 明确指出重复失败点，要求 worker 自己复现完整路径
+failed after round 3: 标记 leftover，继续下一个任务
+```
+
+三轮失败后不要继续消耗同一个 worker。常见原因是：
+
+- 验收标准需要重新设计。
+- Worker 对问题模型理解错了。
+- UI 自动化与实际浏览器状态有差异。
+- 需要人工观察或调试工具介入。
+
+留档字段建议：
+
+```yaml
+status: leftover
+leftoverReason: "failed after 3 supervised developer rounds"
+attempts:
+  - round: 1
+    result: failed
+    evidence: "<why failed>"
+  - round: 2
+    result: failed
+    evidence: "<why failed>"
+  - round: 3
+    result: failed
+    evidence: "<why failed>"
+```
+
+## 5. 任务排序
+
+推荐排序：
+
+1. P0 阻塞主流程。
+2. P1 高频用户路径。
+3. P1/P2 体验改进。
+4. 重构和内部质量。
+
+三轮失败的 P0 可以留档，但最终发布前需要人工决策：
+
+- 降级范围。
+- 改验收标准。
+- 换新 Agent / 新 worktree 重做。
+- 人工修复。
+
+## 6. 每轮派发只修一个明确问题
+
+不要一次让 Developer Worker 修太多失败项，除非它们共享同一根因。推荐：
+
+```text
+one dispatch = one bug = one acceptance path
+```
+
+优点：
+
+- 复测更快。
+- 失败原因更清楚。
+- 三轮失败留档更准确。
+
+## 7. 复测前强制记录运行环境
+
+每轮复测前记录：
+
+```text
+repo:
+worktree:
+branch:
+commit:
+server command:
+BASE_URL:
+frontendDir:
+test commands:
+```
+
+如果服务是长跑进程，确认它加载的是最新构建产物。静态前端项目尤其要注意是否重新 `build`。
+
+## 8. 把失败证据写给下一轮 worker
+
+第二轮以后，派发 prompt 不应重复原始描述为主，而应突出“上一轮为什么没过”。
+
+模板：
+
+```text
+上一轮不是完全失败，以下部分已通过：
+- <passed checks>
+
+仍失败：
+- <missing checks>
+
+直接 API/底层验证：
+- <api result>
+
+请重点排查：
+- <suspected area>
+```
+
+## 9. 优先让测试可执行化
+
+如果某个问题需要多轮修复，说明它值得沉淀成自动化检查。优先级：
+
+1. API smoke。
+2. 浏览器脚本或 case 文档。
+3. 单元测试。
+4. 人工检查清单。
+
+目标不是所有东西都自动化，而是把最容易反复误判的路径自动化。
+
+## 10. 结束条件
+
+一轮闭环结束时，必须能回答：
+
+- 哪些任务 verified？
+- 哪些任务 leftover？
+- 每个 leftover 失败了几轮？
+- 最后一轮失败证据是什么？
+- 当前工作树有哪些未提交改动？
+- 是否还有 open / failed_retest 未处理？
+
+如果这些问题答不清楚，闭环还没有结束。
diff --git a/skills/agent-collaboration-kit/orca-closed-loop.md b/skills/agent-collaboration-kit/orca-closed-loop.md
new file mode 100644
index 0000000..fc89573
--- /dev/null
+++ b/skills/agent-collaboration-kit/orca-closed-loop.md
@@ -0,0 +1,229 @@
+# Orca Closed Loop Workflow
+
+Orca orchestration 是运行时调度层，`tasks.yaml` 是持久事实源。不要把 Orca 消息当成最终记录；所有结论都要回写任务板。
+
+## 什么时候使用 Orca 编排
+
+使用：
+
+- 用户要求监督、等待结果、闭环修复、三轮重试。
+- 有多个 bug 或多个可独立派发的任务。
+- Product/Test 与 Developer 需要明确分工。
+- 需要 `worker_done` 后再复测。
+
+不使用：
+
+- 单次问答。
+- 用户只是要求完整 handoff，不需要你监督。
+- 不需要测试和复测的小改动。
+
+## 标准闭环
+
+```text
+Product/Test 发现或读取 open 任务
+  -> 写入/补全 tasks.yaml 验收标准
+  -> 创建 Orca task
+  -> dispatch 给 Developer Worker
+  -> 等待 worker_done / escalation / decision_gate
+  -> Product/Test 构建并复测
+  -> 通过：verified
+  -> 失败：failed_retest，追加证据，最多再派发两轮
+  -> 三轮失败：leftover，继续下一个任务
+```
+
+## 运行前检查
+
+```bash
+orca status --json
+orca terminal list --json
+orca orchestration task-list --json
+orca orchestration inbox --limit 20 --json
+```
+
+确认：
+
+- Orca runtime 可达。
+- Coordinator 终端和 Developer Worker 终端都存在。
+- Developer Worker 在正确 worktree。
+- 当前没有会冲突的活跃编排任务。
+
+## 创建父任务
+
+```bash
+orca orchestration task-create --spec "$(cat <<'EOF'
+Goal: Complete <release_or_feature> with supervised Product/Test -> Developer loop.
+
+Coordinator:
+- Owns task board, black-box tests, retest, final verification.
+
+Developer:
+- Owns implementation and white-box verification.
+
+Policy:
+- Each issue can be dispatched at most 3 rounds.
+- If still failing after 3 rounds, record as leftover and continue next issue.
+- worker_done is not final completion.
+EOF
+)" --json
+```
+
+## 创建子任务
+
+```bash
+orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
+Fix <task_id>: <title>
+
+Repository:
+- Path: <repo_path>
+- Worktree: <dev_worktree>
+
+Read:
+- AGENTS.md
+- tasks.yaml
+- <relevant_spec_or_test_doc>
+
+Failure evidence:
+- <copy latest Product/Test evidence>
+
+Acceptance:
+- <copy expected behavior>
+- <copy verification commands>
+
+Constraints:
+- Follow AGENTS.md path scope.
+- Do not mark verified.
+- Do not commit or push unless user asks.
+EOF
+)" --json
+```
+
+## 派发给 Developer Worker
+
+如果终端是 Orca 可识别的 Agent CLI：
+
+```bash
+orca orchestration dispatch \
+  --task <task_id> \
+  --to <developer_handle> \
+  --inject \
+  --json
+```
+
+如果不能 `--inject`，先登记 dispatch，再手动发送带上下文的 prompt：
+
+```bash
+orca orchestration dispatch \
+  --task <task_id> \
+  --to <developer_handle> \
+  --json
+```
+
+```bash
+orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
+You are receiving a supervised Orca task.
+
+taskId: <task_id>
+dispatchId: <dispatch_id>
+coordinator: <coordinator_handle>
+
+Task:
+- Fix <task_id>: <title>
+
+Acceptance:
+- <expected behavior>
+
+Verification:
+- <test_commands>
+
+When done, send exactly one worker_done:
+orca orchestration send --to <coordinator_handle> --type worker_done --subject "<task_id> fixed" --body "<summary>" --payload '{"taskId":"<task_id>","dispatchId":"<dispatch_id>","filesModified":["<paths>"],"verification":["<commands>"]}' --json
+EOF
+)" --enter --json
+```
+
+## 等待结果
+
+```bash
+orca orchestration check \
+  --terminal <coordinator_handle> \
+  --wait \
+  --types worker_done,escalation,decision_gate \
+  --timeout-ms 900000 \
+  --json
+```
+
+等待超时不等于失败。长任务可以继续等待，或检查 worker 终端活性。
+
+## worker_done 后复测
+
+Product/Test 必须自己验证：
+
+```bash
+git status --short
+<test_commands>
+curl -s <base_url>/health-or-summary
+```
+
+浏览器复测建议记录：
+
+```text
+BASE_URL:
+page:
+steps:
+expected:
+actual:
+snapshot evidence:
+```
+
+## 服务与 worktree 对齐
+
+复测前记录：
+
+```bash
+pwd
+git rev-parse --abbrev-ref HEAD
+git rev-parse --short HEAD
+```
+
+记录服务：
+
+```text
+serverPid:
+serverCommand:
+BASE_URL:
+frontendDir:
+worktreePath:
+```
+
+如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须停止并重启正确服务后再测。
+
+## 结果回写
+
+通过：
+
+```yaml
+status: verified
+verifiedAt: "<timestamp>"
+evidence:
+  verification: "<commands passed>"
+  browser: "<snapshot or API evidence>"
+```
+
+失败但未满三轮：
+
+```yaml
+status: failed_retest
+attempts:
+  - round: 1
+    result: failed
+    evidence: "<latest evidence>"
+```
+
+三轮失败：
+
+```yaml
+status: leftover
+leftoverReason: "failed after 3 supervised developer rounds"
+evidence:
+  final: "<latest failing evidence>"
+```
diff --git a/skills/agent-collaboration-kit/prompt-templates.md b/skills/agent-collaboration-kit/prompt-templates.md
new file mode 100644
index 0000000..e63f620
--- /dev/null
+++ b/skills/agent-collaboration-kit/prompt-templates.md
@@ -0,0 +1,137 @@
+# Prompt Templates
+
+这些模板用于 Coordinator 给 Developer Worker 派发任务。复制时替换尖括号占位符。
+
+## 1. 初始派发模板
+
+```text
+你现在接到一个受监督的 Orca 编排任务。请在 <dev_worktree> 开发工作树内完成。
+
+编排上下文：
+- taskId: <orca_task_id>
+- dispatchId: <orca_dispatch_id>
+- coordinator: <coordinator_handle>
+
+任务：
+- 修复 <task_id>: <task_title>
+
+请先读取：
+- AGENTS.md
+- tasks.yaml
+- <relevant_spec_or_test_doc>
+
+当前失败证据：
+<copy latest Product/Test evidence>
+
+验收标准：
+1. <expected behavior 1>
+2. <expected behavior 2>
+3. <expected behavior 3>
+
+约束：
+- 只修改 Developer 可写路径。
+- 不要修改 Product/Test 负责的规格和集成测试文件，除非任务明确要求。
+- 不要标记 verified。
+- 不要提交或推送，除非用户明确要求。
+- 最小 diff，避免无关重构。
+
+完成前必须运行：
+- <test command 1>
+- <test command 2>
+- <test command 3>
+
+完成后发送一次 worker_done：
+orca orchestration send --to <coordinator_handle> --type worker_done --subject "<task_id> fix ready round <n>" --body "<三句话内：修了什么、验证、风险>" --payload '{"taskId":"<orca_task_id>","dispatchId":"<orca_dispatch_id>","filesModified":["<paths>"],"verification":["<commands>"]}' --json
+
+如果阻塞，请发送 escalation 或 ask。
+```
+
+## 2. 复测失败再派发模板
+
+```text
+第 <n> 轮 QA 未通过，请继续修 <task_id>。
+
+上一轮开发声称：
+<worker_done summary>
+
+Product/Test 独立复测结果：
+- 运行命令：<commands>
+- 失败页面/API：<page or endpoint>
+- 仍缺失：<missing expected checks>
+- 实际观察：<actual evidence>
+
+关键提示：
+- 不要只满足静态文案，必须满足交互后的真实状态。
+- 如果后端/API 正常而 UI 不更新，请优先排查事件链、状态重置、异步请求、构建产物和服务 worktree。
+- 修复后请自己用浏览器或脚本复现 Product/Test 的完整步骤。
+
+验收不变：
+<copy acceptance criteria>
+
+完成后发送 worker_done，subject 使用：
+"<task_id> fix ready round <n>"
+```
+
+## 3. 三轮失败留档模板
+
+```text
+<task_id> 已完成 3 轮受监督修复，但仍未通过 Product/Test 复测。
+
+最终状态：
+- status: leftover
+- reason: failed after 3 supervised developer rounds
+
+保留证据：
+- round 1: <summary>
+- round 2: <summary>
+- round 3: <summary>
+- final failing evidence: <latest evidence>
+
+处理策略：
+- 不再自动派发同一问题。
+- 继续处理下一个 open / failed_retest 任务。
+- 该问题留给人工专项检查或后续重新设计。
+```
+
+## 4. Developer Worker worker_done 模板
+
+```bash
+orca orchestration send \
+  --to <coordinator_handle> \
+  --type worker_done \
+  --subject "<task_id> fix ready round <n>" \
+  --body "<修了什么。跑了哪些验证。还有什么风险。>" \
+  --payload '{
+    "taskId": "<orca_task_id>",
+    "dispatchId": "<orca_dispatch_id>",
+    "filesModified": [
+      "<file_a>",
+      "<file_b>"
+    ],
+    "verification": [
+      "<command_a>: passed",
+      "<command_b>: passed"
+    ],
+    "risk": "<remaining risk or none>"
+  }' \
+  --json
+```
+
+## 5. Coordinator 最终报告模板
+
+```text
+本轮闭环完成。
+
+已验证：
+- <task_id>: <what passed>
+
+遗留：
+- <task_id>: 三轮仍未通过，已记录为 leftover。最后失败证据：<evidence>
+
+验证命令：
+- <command>: passed
+
+工作树状态：
+- <repo_path>: <git status summary>
+- <dev_worktree>: <git status summary>
+```
diff --git a/skills/agent-collaboration-kit/roles-and-permissions.md b/skills/agent-collaboration-kit/roles-and-permissions.md
new file mode 100644
index 0000000..093d118
--- /dev/null
+++ b/skills/agent-collaboration-kit/roles-and-permissions.md
@@ -0,0 +1,98 @@
+# 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` 使用以下状态：
+
+```text
+open
+  -> dispatched
+  -> fixed_by_dev
+  -> retesting
+  -> verified
+```
+
+失败分支：
+
+```text
+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` 中记录了复测证据。
+- 用户可见行为符合验收标准。
diff --git a/skills/agent-collaboration-kit/task-board-template.yaml b/skills/agent-collaboration-kit/task-board-template.yaml
new file mode 100644
index 0000000..dc6b623
--- /dev/null
+++ b/skills/agent-collaboration-kit/task-board-template.yaml
@@ -0,0 +1,76 @@
+version: 1
+updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
+source: "Product/Test Agent"
+project:
+  name: "<project_name>"
+  repoPath: "<repo_path>"
+  baseUrl: "<base_url>"
+  devWorktree: "<dev_worktree>"
+
+summary:
+  verified: []
+  open: []
+  failedRetest: []
+  leftovers: []
+
+tasks:
+  - id: "BUG-001"
+    type: "bug"
+    title: "<short title>"
+    priority: "P0"
+    status: "open"
+    assignee: "developer"
+    component: "<source file or module>"
+    specRefs:
+      - "<docs/spec.md#section>"
+    testRefs:
+      - "<tests/browser/cases/01-case.md>"
+
+    description: >
+      <What is wrong, in user-visible terms.>
+
+    stepsToReproduce:
+      - "<step 1>"
+      - "<step 2>"
+      - "<step 3>"
+
+    expected: >
+      <Expected behavior.>
+
+    actual: >
+      <Actual behavior observed by Product/Test.>
+
+    evidence:
+      browser: "<snapshot text, screenshot path, or UI finding>"
+      api: "<curl result or API mismatch>"
+      logs: "<relevant log line if any>"
+
+    verification:
+      commands:
+        - "<unit/build command>"
+        - "<browser/API smoke command>"
+      browser:
+        page: "<page path>"
+        checks:
+          - "<visible text or interaction expected>"
+
+    dispatch:
+      taskId: null
+      dispatchId: null
+      worker: null
+      rounds: []
+
+    resolution:
+      fixedBy: null
+      verifiedAt: null
+      leftoverReason: null
+
+statusReference:
+  open: "Product/Test found issue; not dispatched yet"
+  dispatched: "Sent to Developer Worker"
+  fixed_by_dev: "Developer claims fixed and provides verification"
+  retesting: "Product/Test is verifying"
+  failed_retest: "Product/Test verification failed"
+  verified: "Product/Test verification passed"
+  blocked: "Needs user or external decision"
+  leftover: "Failed after 3 developer rounds; preserved for later manual review"