refactor: fold ack kit into skill

2026-07-30 11:54:02 +08:00
parent e308d6a04c
commit 076d87e303
32 changed files with 592 additions and 619 deletions
@@ -0,0 +1,79 @@
+# <项目名> Agent 协作协议（项目覆盖层）
+
+> 本项目基于 ACK Skill v<ack_version>。通用规范由 `/ack` 从 Skill 自身的
+> `references/` 读取；本文件只保存项目差异。
+>
+> **本文件是「项目覆盖层」，文件名可配置。** 默认放 `docs/ack/project.md`，
+> 不占用 `AGENTS.md`，避免与团队已有的 `AGENTS.md` 约定冲突。
+> 若希望 Agent 自动加载，可在项目 `AGENTS.md` 里加一行指向本文件，或直接把本文件命名为 `AGENTS.md`。
+> 无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。
+> `docs/ack/` 只保存本项目的 `project.md` 与 `tasks.yaml`，不复制或链接 Skill。
+
+## 项目概览
+
+- 项目：`<project_name>`
+- 技术栈：`<tech_stack>`
+- 运行命令：`<run_command>`
+- Base URL：`<base_url>`
+- 任务板：`docs/ack/tasks.yaml`
+- 覆盖层文件：`<overlay_file_path>`（默认 `docs/ack/project.md`）
+
+## 通用规范（由 ACK Skill 按需读取）
+
+- 开始需求：`references/kickoff.md`
+- 角色、权限、状态机与完成定义：`references/roles-and-permissions.md`
+- 模型档位与升级规则：`references/model-routing.md`
+- 闭环流程与 worktree 对齐：`references/closed-loop.md`
+- 验收信号与三轮策略：`references/optimization-method.md`
+- 派发 prompt 模板：`references/prompt-templates.md`
+- Orca 编排命令（可选）：`references/orca-adapter.md`
+
+## 模型档位（项目可覆盖，默认见 references/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>
+```
+
+任务板校验由 `/ack` 使用 Skill 自带的 `scripts/validate_tasks.py` 执行。
+
+## 硬规则（其余见 references/）
+
+- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
+- 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 references/model-routing.md）。
+- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
+- 只有 Coordinator 写 `tasks.yaml`；Developer 与 Test 都只读，通过消息回报。
+- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
+- 不提交或推送，除非用户明确要求。