.pouch/skills/ack/SKILL.md

name, description

name	description
ack	初始化、检查并运行 ACK 三角色闭环。仅在用户显式调用 /ack 或 $ack，并要求 初始化 ACK、检查 .pouch/ack、按 ACK 做需求或修 bug、指挥 Coordinator/Developer/Test、配置或运行测试环境与发版、或跑回归时使用。

ACK 项目协作入口

项目只在 .pouch/ack/ 保存 project.md、tasks.yaml、knowledge.yaml、 delivery.yaml、regression.yaml，以及可选的 agents.yaml 角色启动覆盖配置。 不要复制 Skill 内容，不要修改项目的 AGENTS.md、 CLAUDE.md。

固定状态文件为 .pouch/ack/project.md、.pouch/ack/tasks.yaml、 .pouch/ack/knowledge.yaml、.pouch/ack/delivery.yaml 和 .pouch/ack/regression.yaml。

开始时解析当前 SKILL.md 所在目录为 <ack-skill-dir>。优先 git rev-parse --show-toplevel 作为项目根。

选择模式

• 初始化、接入 ACK：执行「初始化」。
• 检查配置是否完整：执行「检查」。
• 临时调整 Developer/Test 的 CLI 或模型：执行「角色启动配置维护」。
• 做需求、修 bug 或继续任务：执行「工作」。修 bug 不写大 PRD。
• 增改关闭交付、说明怎么布测试环境或发版：执行「交付配置维护」。
• 部署或重布测试环境：执行「运行测试环境」（加载 deployer skill 的「初始化」或运行流程，不复制 compose）。
• 发布版本：执行「运行版本发布」。回归：执行「运行回归」。
• 任务板使用 Orca 时，编排命令见 orca-adapter.md。

边界

• 不覆盖已有 .pouch/ack；除用户确认的任务、agents profile 或 delivery profile 外，不擅自提交、推送、创建终端、新 worktree、发布或部署。
• 不猜测命令、地址、worker handle 或模型名；无法确定写 n/a。
• agents.yaml 是可选的临时角色启动覆盖；存在时优先于 tasks.yaml.project.orchestration，不存在时回退到任务板配置。
• agents.yaml 只能描述结构化 CLI、模型、reasoning effort 和权限，不能保存 command、argv、shell 或环境变量；Pi 的默认模型用 cli: pi、model: null 表示。
• 不把完整 tasks.yaml / knowledge.yaml / regression.yaml 注入上下文；用对应 select_*.py。写回前跑完整校验。
• 只有 Coordinator 写任务板、知识库、回归目录、deliveryRuns 和 regressionRuns。delivery.yaml 只在「交付配置维护」中改。见 roles-and-permissions.md。
• 知识检查只经 run_verification.py 的 registry ID；不把知识正文拼成 shell。
• 自动 worker 禁止 full-access、bypass、关闭 sandbox、Grok --yolo / bypassPermissions。OMP --approval-mode yolo 只用于 OMP 审批（workspace-write → yolo，read-only → always-ask），禁止 --auto-approve，不适用于其它 backend。
• 无清理证明不复用 worker；无密钥 receiptHash 或 Orca live metadata 不能授权复用。当前 Orca 走 fresh。只复用同轮、空闲且完成清理历史消息的 worker；无法确认清理成功时创建 fresh worker。indeterminate / reconcile required 不直接重试。
• 产品失败才占三轮；环境失败写 environmentIncidents，环境失败不占复验轮次。见 optimization-method.md §4。

初始化

1. 确认 pouch 可执行。.pouch/ack 不存在则 pouch init ack --project <project-root>；已存在则不覆盖、转入「检查」。
2. 按 init-new-project.md 完善项目状态。不从 README/CI 猜测并启用交付或知识；初始化 不 自动初始化 deployer 或 builder。
3. 运行：

python3 <ack-skill-dir>/scripts/validate_tasks.py .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_knowledge.py .pouch/ack/knowledge.yaml \
  --tasks .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/validate_delivery.py .pouch/ack/delivery.yaml \
  --tasks .pouch/ack/tasks.yaml --project-root <project-root>
python3 <ack-skill-dir>/scripts/validate_regression.py .pouch/ack/regression.yaml \
  --tasks .pouch/ack/tasks.yaml

# 仅在存在临时角色配置时运行
python3 <ack-skill-dir>/scripts/validate_agents.py .pouch/ack/agents.yaml

4. 检查上述文件是否仍有 <...> 占位符；没有真实任务时使用 tasks: []。结构校验通过且必填项目事实完整才称「完成」。除非用户明确要求，不提交、不推送。

## ack 初始化：完成 | 部分完成 | 阻塞

已具备: …
待配置: 路径 + 字段 + 可粘贴示例 + 缺了会挡住哪步
工具链: pouch …
下一步: 一句话

检查

只读，不自动修复。核对清单见 adoption-checklist.md。用 select_tasks.py 看配置；跑与「初始化」相同的四个校验器；存在 agents.yaml 时再跑 validate_agents.py。对比 VERSION 与 ackVersion（旧 kitVersion 仍可读）；从 0.10.0 起 project.orchestration 与 workerReceipts 必须同时存在。旧项目可无 delivery/regression，存在或被引用时必须校验。若有 bugIntake 再跑 feishu_bug_intake.py check。若测试环境走 deployer，只读跑其 check.py；未通过列入待配置，不要复制 compose 或静默初始化 deployer。用同一报告格式，标题改为 ## ack 检查：…。

工作

1. .pouch/ack 不存在：停止并建议先 /ack 初始化；不要静默初始化。
2. 读 project.md；若存在 agents.yaml，先用 validate_agents.py 校验并读取其 defaults；用 select_tasks.py（已知任务加 --task-id）和 select_knowledge.py 取当前任务相关 active 条目。超预算时缩小选择，不回退为完整 yaml。
3. 新需求或尚未确认的计划：读 kickoff.md。修 bug 写短问题说明、复现和可观测验收，不写大 PRD。
4. 用户已确认后，先读取并按 closed-loop.md 执行；使用 Orca 时同时读取 orca-adapter.md。当前会话担任 Coordinator，不亲自写代码或跑测试；worker profile 按 agents.yaml（若存在）否则按任务板配置选择。 这不是 fire-and-forget：Coordinator 不得在 launch / dispatch 后只回复“已派发”并结束当前会话。每个任务都必须在同一轮持续执行默认 60 秒窗口的 check --wait，并按 60–120 秒节奏运行 worker_probe.py，直到 Developer 回报 worker_done 或 escalation；随后写回 fixed_by_dev，主动派发 Test，并继续等待 retest_result。只有完成 Test 终检、重试/leftover 决策、回归决定和 worker 回收后，才可以结束本轮 ACK。
5. 存在 project.bugIntake 时先完成「飞书收件」。创建或更换 worker 走「启动 worker」。若 intents.testEnvironment 已启用，派 Test 前先走「运行测试环境」。
6. 知识 verification.ref 只经 run_verification.py。不把 worker_done 或 Test 自报成功当作完成。环境失败先有界恢复并报告 userAction；三轮产品失败记 leftover。
7. 任务 verified 且改了可见行为或 API 后，转入「运行回归」收获用例。若本次计划含交付，再走对应交付模式；默认最多到 validation_ready 或 review_ready。
8. 整轮任务完成后 reclaim_workers.py 先 dry-run 再 --apply，回收所有只属于 verified 任务的 worker 终端，并核对关闭回执；仍关联未完成任务的 worker 不设置 TTL。关闭结果不确定则记录，不伪报。

不能停在“任务已 verified 却声称整轮 ACK 已结束”：必须完成回归决定和 worker 回收。

角色启动配置维护

用户明确说「让这个项目的 dev agent 用 pi 默认模型、test agent 用 cursor-agent auto」等临时调整时，创建或更新 .pouch/ack/agents.yaml。配置文件形状见 agents.template.yaml 和 agents.example.yaml，只写结构化 profile，不写自由命令。

存在 agents.yaml 时，ACK 的 profile-hash、plan、launch 和 receipt 全部绑定该文件的 hash；修改配置后必须重新 plan，旧 fingerprint 不能继续启动。删除该文件即可回退到 tasks.yaml.project.orchestration。配置本身不代表提交、推送、发布或部署授权。

飞书收件

若存在 project.bugIntake，读 feishu-bug-intake.md。用户针对当前 draftRevision 明确审核通过并亲自把飞书状态改为 已确认 前：不创建或刷新任务、不启动 worker、不派发、不改应用代码。Coordinator 不得自行写入 已确认。未声明 workflow 的旧配置只按 read-only-v1，不得写回。来源消失或读取失败时不删除已有任务。

启动 worker

只使用 scripts/launch_worker.py plan|launch。不得直接 orca terminal create --command，不得拼接自由 command、argv、executable、env 或 cwd。读 model-routing.md。先审阅 plan.launchFingerprint，再作为 launch --expected-launch-fingerprint 传入。派发文案用 prompt-templates.md。派发后 terminal read 确认已开始；卡在审批、未回车或额度限制按环境失败处理。等待期间用 scripts/worker_probe.py，不盲等 worker_done。

交付配置维护

读 delivery.md。测试环境写成 {via: deployer, env: <env>}；.pouch/deployer/<env> 未就绪则停止并加载 deployer「初始化」，不在 ACK 里复制 compose。发版写在同一份 delivery.yaml，不保存 shell。本地 npm run dev / go run 不算测试环境。旧项目首次启用只补文件指针与 deliveryRuns: []，保持 enabled: false，用户确认后才启用。进行中的 run 使用开始时的 commit/config 快照。

运行测试环境

读 delivery.yaml 与 delivery.md，并加载 deployer。enabled 非 true 或 intent 为 null：停止，转入交付配置维护。intent 必须是 {via: deployer, env: <env>}；旧 profile ID 字符串要先迁移。不要用 ACK delivery profile 布环境，不猜测启动命令。不要求任务已 verified。对 .pouch/deployer/<env> 按 deployer：list → 按服务 sync+up → 健康检查。证据写入 deliveryRuns（intent: testEnvironment，profile: deployer-<env>）。未安装、缺目录、check.py 失败或健康检查失败：fail closed，报告 userAction，不记产品失败。

运行回归

读 regression.md。缺目录则停止；用户授权后从模板生成空文件并只补指针与 regressionRuns: []。用 select_regression.py 读 active 用例（默认 --suite smoke）；无命中则停止。先执行「运行测试环境」，再派独立 Test worker。Coordinator 不亲自点浏览器或打 API；browser 不得改成只打 API。终检写入 regressionRuns。失败不自动派 Developer，不占三轮预算。任务 verified 后给出新增/更新/退役/无回归四选一，用户确认后写入；Test 只提名。

运行版本发布

1. 读同一份 delivery.yaml 与 delivery.md。
2. enabled 不为 true，或 intents.release 为 null：停止，先做交付配置维护。
3. 按该 profile 顺序执行。stable 发布和生产部署的 approval 不能用口头「发版」代替。
4. 证据写入 deliveryRuns，intent: release；绑定了任务时 taskIds 仍只能引用 verified 任务。