ack（Agent Collaboration Kit）是一套可复用到其它项目的多 Agent 协作规范，默认三个独立角色：Coordinator (PM) 拆解需求并调度闭环，Developer 实现与白盒验证，Test 独立黑盒复测。关键属性是验证者 ≠ 实现者。角色默认按成本分层：Coordinator 用强模型（且不亲自跑测试），Test/Developer 用中低模型（见 core/model-routing.md）。

当前版本见 VERSION。这不是 Agent Skill（无 SKILL.md），不由 skiff 安装，而是复制/引用到目标项目。

适用场景

多个 Agent 分工协作，而非单个 Agent 从需求写到代码。
需要区分规格、测试、实现、复测的责任边界（Coordinator / Test / Developer 三角色）。
需要把失败项派发给 Developer，worker_done 后由独立的 Test 复测、Coordinator 终检。
需要连续修复多个问题，并把三轮仍未修好的问题留档。

目录结构

ack/
  VERSION                       # kit 版本，接入时记入项目
  README.md
  adoption-checklist.md
  core/                         # 稳定核心：跨项目通用，随 kit 升级，尽量别改
    roles-and-permissions.md    #   角色/权限/状态机/完成定义（SSOT）
    model-routing.md            #   三角色默认模型档位 + 升级规则（SSOT）
    closed-loop.md              #   编排无关闭环 + 手动模式 + worktree 对齐
    optimization-method.md      #   验收信号 + 三轮失败策略（SSOT）
    prompt-templates.md         #   派发 prompt 模板
    orca-adapter.md             #   Orca 具体命令（一种编排实现，可选）
  templates/                    # 项目覆盖层：复制一次并填空
    project.template.md         #   项目覆盖层模板（文件名可配置，默认不占用 AGENTS.md）
    tasks.template.yaml
    tasks.schema.json           #   任务板权威结构（跨语言）
  examples/                     # 填好的最小可跑示例
    project.example.md
    tasks.example.yaml
  scripts/
    validate_tasks.py           # 校验 tasks.yaml（参考实现）

核心原则：core/ 是稳定核心，每个概念只定义一次；templates/ 是项目覆盖层。二者分离，让 kit 升级和项目定制互不干扰。

项目目录布局（推荐）

每个项目在 docs/ack/ 下只放一个软链接加两个项目文件，稳定核心全部走软链接：

<project>/docs/ack/
  kit -> <此框架目录>     # 唯一软链接：core/templates/examples/scripts 全在里面
  project.md              # 项目覆盖层（差异），可改名，见下
  tasks.yaml             # 项目任务板

引用稳定核心时统一走 kit/ 前缀，例如 docs/ack/kit/core/roles-and-permissions.md。这样「一个项目一个软链接」，kit 升级自动生效，项目定制（project.md + tasks.yaml）互不干扰。

分发方式（二选一）

方式 A：单软链接引用（推荐，可升级）

把本框架目录整体 symlink 成项目的 docs/ack/kit：

mkdir -p <project>/docs/ack
ln -s <此框架绝对路径> <project>/docs/ack/kit

也可用 git submodule / sparse checkout 达到同样效果。项目只维护 project.md 与 tasks.yaml。

方式 B：整份复制（简单，手动升级）

把本框架整目录复制成 docs/ack/kit/（或直接铺平到 docs/ack/，此时引用去掉 kit/ 前缀）。务必在 project.md 与 tasks.yaml 的 kitVersion 记录来源版本，日后照 VERSION diff 升级。

覆盖层文件名（重要）

项目差异（路径、命令、handle、模型档位）写在项目覆盖层文件里，默认 docs/ack/project.md，不占用 AGENTS.md，以免与团队已有的 AGENTS.md 约定冲突。文件名可配置：想让 Agent 自动加载，可在 AGENTS.md 加一行指向它，或直接命名为 AGENTS.md。无论叫什么，都在 tasks.yaml 的 project.overlayFile 记录实际路径。覆盖层只填差异，不复制 core/ 内容。

快速接入

建 docs/ack/，按方式 A 建单软链接 kit。
复制 kit/templates/project.template.md → docs/ack/project.md，填项目差异与模型档位，记 kitVersion。
复制 kit/templates/tasks.template.yaml → docs/ack/tasks.yaml，填 project（含 overlayFile）与首个任务。
跑 python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml 确认结构。
按 kit/core/closed-loop.md 跑闭环（Orca 见 kit/core/orca-adapter.md，无 Orca 用手动模式）。
逐项对照 kit/adoption-checklist.md。

参考 examples/ 里填好的 project.example.md 与 tasks.example.yaml。

默认口令

用三角色协作闭环处理 docs/ack/tasks.yaml 里的未通过项：Coordinator 派发给 Developer 修复，再交给 Test 独立复测并终检；每个问题最多修三轮，三轮仍不过就记录为遗留，然后继续下一个。

README.md Unescape Escape

ack — Agent Collaboration Kit