.pouch/skills/ack/templates/project.template.md

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

本项目基于 ACK Skill v<ack_version>。通用规范由 /ack 从 Skill 自身的 references/ 读取；本文件只保存项目差异。

本文件是「项目覆盖层」，文件名可配置。 默认放 docs/ack/project.md， 不占用 AGENTS.md，避免与团队已有的 AGENTS.md 约定冲突。 若希望 Agent 自动加载，可由项目维护者自行在 AGENTS.md 中引用本文件；ACK 不会自动修改 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。 无论叫什么，都在 tasks.yaml 的 project.overlayFile 记录实际路径。 docs/ack/ 只保存本项目的 project.md、tasks.yaml、knowledge.yaml 与默认关闭的 delivery.yaml， 不复制或链接 Skill。

项目概览

• 项目：<project_name>
• 技术栈：<tech_stack>
• 运行命令：<run_command>
• Base URL：<base_url>
• 任务板：docs/ack/tasks.yaml
• 项目知识：docs/ack/knowledge.yaml
• 交付契约：docs/ack/delivery.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/delivery.md

Worker 路由

机器可校验的模型、reasoning effort、权限模式、默认 profile、允许 worktree 和启动 receipt 全部以 docs/ack/tasks.yaml 的 project.orchestration 与顶层 workerReceipts 为准。本文件不保存可执行 worker 命令。

默认 profile：

角色	profile ID	档位
Developer	codex-dev-standard	standard
Test	codex-test-standard	standard
Developer 升级	codex-dev-strong	strong

项目如改用 Cursor 或 Grok，应修改结构化 profile、allowlist 和 defaults，再运行任务板 校验；不能在这里粘贴 orca --command、Agent CLI 参数或自由 shell。 每次自动派发必须先审阅 launcher plan，再把其中的 launchFingerprint 作为 --expected-launch-fingerprint 启动 fresh worker。receiptHash 只作审计 checksum， 不授权自动复用旧终端；只有同轮空闲、身份匹配且历史消息可信清理后才可复用。

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

路径	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 写
knowledge.yaml	R/W	Read-only	Read-only	只有 Coordinator 写；Developer/Test 通过回报提名或验证
delivery.yaml	仅显式维护时 R/W	Read-only	Read-only	项目交付能力，不是执行授权

命令（项目覆盖层）

Developer 白盒验证：

<unit_test_command>
<build_command>
<local_run_command>

Test 黑盒复测（服务启动以 delivery.yaml 的 intents.testEnvironment 为准）：

<preflight_command>
<api_smoke_command>
<browser_regression_command>

知识项的 verification.ref 只能引用 knowledge.yaml.verificationRegistry 中已 审查的检查入口。Registry 只保存仓库内相对 path 和结构化 args，不保存或执行自由 shell 命令；新项目没有知识时保持空对象。Developer/Test 只能把 registry ID 交给 Skill 的 scripts/run_verification.py 执行，不直接拼接 path/args。检查脚本从项目 根 cwd 或 ACK_PROJECT_ROOT 定位资源，不能依赖自身文件路径。 ACK_PROJECT_ROOT 是 runner 固定的根目录 fd 路径；仅用于日志的原始路径位于 ACK_PROJECT_ROOT_DISPLAY。

项目状态校验由 /ack 使用 Skill 自带的 scripts/validate_tasks.py、 scripts/validate_knowledge.py 和 scripts/validate_delivery.py 执行。 构建、测试环境部署和版本发布的机器入口以 delivery.yaml 的 intents 为准； 本文件不维护第二套交付命令。

硬规则（其余见 references/）

• 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
• 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 references/model-routing.md）。
• 自动 worker 只能由 ACK 的 scripts/launch_worker.py 按结构化 profile 启动； 禁止直接拼 orca terminal create --command，禁止 command、extraArgs、env 等第二配置面。
• v0.10 自动 launcher 只支持 read-only 和 workspace-write。full-access、 bypass、YOLO/force 与关闭 sandbox 均 fail closed；需要可信平台审批通道后再开放。
• 复用仅限同轮空闲、身份匹配且历史消息可信清理的 worker；否则重新 plan/launch。
• 整轮结束后回收只属于 verified 任务的终端；blocked/failed/leftover 终端保留且不设 TTL。
• worker_done 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 verified。
• 只有 Coordinator 写 tasks.yaml 和 knowledge.yaml；Developer 与 Test 都只读， 通过消息回报。
• Coordinator 只派发按 scope 命中并显式写入 knowledgeRefs 的 active 知识； candidate 不派发，知识库不全量注入。
• Developer 回报 knowledgeApplied 与 knowledgeCandidates，Test 回报 knowledgeChecks。关键约束应下沉为测试、lint、CI 或正式规范。
• ACK 不自动修改 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。
• delivery.yaml 默认关闭，只描述能力，不自动授权提交、推送、发布或部署。测试环境 与发版都写在这份契约的 intents 里；用户明确要求重新部署测试环境或发布版本时 才执行对应 intent。常规交付仍在任务 verified 且本次 profile 得到确认后运行。
• 默认交付 profile 最多到 validation_ready 或 review_ready；stable 发布或 production 部署必须有 approval 步骤并再次获得明确批准。配置变更只影响下一次 run。
• 每个任务最多派发 3 轮，仍不过标记 leftover 并继续下一个。
• 不提交、推送、发布或部署，除非用户确认的 ACK 任务或 delivery profile 明确包含。