# <项目名> Agent 协作协议（项目覆盖层）

> 本项目基于 ack v<kit_version>（见 `docs/ack/kit/VERSION`）。
> 稳定规范引用 `docs/ack/kit/core/`，不复制其内容；本文件只填项目自己的差异。
>
> **本文件是「项目覆盖层」，文件名可配置。** 默认放 `docs/ack/project.md`，
> 不占用 `AGENTS.md`，避免与团队已有的 `AGENTS.md` 约定冲突。
> 若希望 Agent 自动加载，可在项目 `AGENTS.md` 里加一行指向本文件，或直接把本文件命名为 `AGENTS.md`。
> 无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。
>
> 目录约定：`docs/ack/` 下只有一个软链接 `kit/`（指向共享框架），加本项目 `project.md` + `tasks.yaml`。

## 项目概览

- 项目：`<project_name>`
- 技术栈：`<tech_stack>`
- 运行命令：`<run_command>`
- Base URL：`<base_url>`
- 任务板：`docs/ack/tasks.yaml`
- 覆盖层文件：`<overlay_file_path>`（默认 `docs/ack/project.md`）

## 稳定规范（不在此重复，直接引用）

- 角色模型 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md`
- 模型档位与升级规则：`docs/ack/kit/core/model-routing.md`
- 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md`
- 优化方法（验收信号、三轮策略）：`docs/ack/kit/core/optimization-method.md`
- 派发 prompt 模板：`docs/ack/kit/core/prompt-templates.md`
- Orca 编排命令（可选）：`docs/ack/kit/core/orca-adapter.md`

## 模型档位（项目可覆盖，默认见 core/model-routing.md）

| 角色 | 默认档位 | 本项目实际 |
|------|----------|------------|
| Coordinator (PM) | 强模型 | `<model_or_default>` |
| Test | 中低模型 | `<model_or_default>` |
| Developer | 中低模型 | `<model_or_default>` |

## 路径权限（项目覆盖层，必须填实际路径）

| 路径 | Coordinator | Test | Developer | 说明 |
|------|:-----------:|:----:|:---------:|------|
| `<spec_paths>` | R/W | Read-only | Read-only | 产品规格、API 文档、计划（PM 拥有） |
| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器/API 回归（Test 拥有） |
| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录 |
| `<source_paths>` | Read-only | Read-only | R/W | 应用源码 |
| `<unit_test_paths>` | Read-only | Read-only | R/W | 单元测试 |
| `<shared_config_templates>` | Read-only | Read-only | R/W | 可提交配置模板 |
| `<local_config_paths>` | Read-only | Read-only | Read-only | 本地私有配置 |
| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |

## 命令（项目覆盖层）

Developer 白盒验证：

```bash
<unit_test_command>
<build_command>
<local_run_command>
```

Test 黑盒复测：

```bash
<preflight_command>
<api_smoke_command>
<browser_regression_command>
```

任务板校验：

```bash
python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
```

## 硬规则（其余见 kit/core/）

- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
- 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 kit/core/model-routing.md）。
- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
- 只有 Coordinator 写 `tasks.yaml`；Developer 与 Test 都只读，通过消息回报。
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
- 不提交或推送，除非用户明确要求。