.pouch/skills/ack/SKILL.md

name, description

name	description
ack	初始化、检查并运行 ACK 三角色协作闭环。仅在用户显式调用 /ack 或 $ack，并要求 初始化 ACK、检查 docs/ack 配置、按 ACK 规划需求、指挥 Coordinator/Developer/Test 工作，或配置并执行任务验证后的项目交付流程时使用。

ACK 项目协作入口

本 Skill 是 ACK 的完整能力包：references/ 保存通用规范，templates/ 保存项目 状态模板，scripts/ 保存校验工具。目标项目只在 docs/ack/ 保存 project.md、 tasks.yaml、knowledge.yaml 和默认关闭的 delivery.yaml，不要复制或链接 Skill 内容。

开始时解析当前 SKILL.md 所在目录，记为 <ack-skill-dir>。所有通用规范、模板和 脚本都相对此目录访问，不依赖固定的全局安装路径。

选择模式

• 用户要求初始化、接入或安装 ACK：执行“初始化”。
• 用户要求检查 ACK 是否可用、配置是否完整：执行“检查”。
• 用户要求用 ACK 做需求、修复问题或继续任务：执行“工作”。
• 用户用自然语言要求增加、修改或关闭项目交付流程：执行“交付配置维护”。

始终先解析真实项目根目录。优先使用 git rev-parse --show-toplevel；不是 Git 项目时使用用户指定目录或当前目录。不要修改项目的 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。

初始化

1. 确认 skiff 可执行，并检查 <project>/docs/ack 是否存在。

2. 不存在时执行：

   skiff init ack --project <project-root>
   

   该命令从本 Skill 的 templates/ 生成项目状态，不会在项目中创建 Skill 软链接或资源副本。

3. 如果 docs/ack 已存在，不重复初始化、不覆盖文件；转入“检查”。旧项目只有 project.md 与 tasks.yaml 时，先报告缺少 knowledge.yaml。用户授权后， 从 templates/knowledge.template.yaml 生成这个缺失文件并替换项目名和时间；若 tasks.yaml 尚无 project.knowledgeFile，同时只补 docs/ack/knowledge.yaml 这一项。不要重跑 skiff init，也不要改写其它已有 项目状态。

4. 读取项目的公开配置和文档，例如 README、语言清单、包管理清单、测试配置与 CI，确定项目名、技术栈、源码/规格/测试路径及真实可执行命令。

5. 完善 docs/ack/project.md：

   • 用实际项目值替换全部占位符。
   • 无服务地址时把 Base URL 写为 n/a，不要虚构端口。
   • 无法从项目证据确定的命令写为 n/a，并在结果中列为待配置项。
   • 只写项目差异，不复制 references/ 中的通用规范。

6. 完善 docs/ack/tasks.yaml 的项目信息。纯初始化且用户没有提供真实任务时， 删除模板示例任务并保留 tasks: []；不要虚构需求或缺陷。 项目状态固定从当前项目根的 docs/ack/ 推导，不写入 repoPath 或 devWorktree； worker 的绝对路径只保存在 project.orchestration.allowedWorktrees 并在派发时通过 --worktree 显式选择。旧任务板中的 repoPath、devWorktree 仅兼容读取。

7. 检查 docs/ack/knowledge.yaml。新项目没有已验证的项目经验时保留 verificationRegistry: {} 与 entries: []，不从聊天、README 或单次失败中 猜测并激活知识。

8. 检查 docs/ack/delivery.yaml。新项目保留 enabled: false、空能力表和空 profile； 不从 README 或 CI 猜测、启用交付。旧项目没有该文件时仍可继续使用原 ACK 闭环；只有用户明确要求配置交付时，才按“交付配置维护”补齐。

9. 更新 updatedAt，并运行：

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

10. 检查 project.md、tasks.yaml、knowledge.yaml 与 delivery.yaml 是否仍有 <...> 占位符。 结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”并列出 缺失值。

11. 报告创建的路径、检测到的命令、校验结果和下一步。除非用户明确要求，不提交、 不推送。

检查

1. 检查以下路径：
   • docs/ack/project.md
   • docs/ack/tasks.yaml
   • docs/ack/knowledge.yaml
   • docs/ack/delivery.yaml（旧项目可无；存在或被任务板引用时必须校验） 需要查看任务内容时，使用 <ack-skill-dir>/scripts/select_tasks.py 解析完整任务板并 只输出项目配置、摘要和可工作任务；不要用 cat、整文件 sed 或等价方式把完整 tasks.yaml 注入上下文。完整性仍由校验器检查。
2. 读取 <ack-skill-dir>/VERSION，对比 tasks.yaml 的 ackVersion。旧项目只有 kitVersion 时仍可读取，但建议迁移为 ackVersion。ackVersion 必须是合法 SemVer；从 0.10.0 起 project.orchestration 与顶层 workerReceipts 必须同时 存在。
3. 查找未替换占位符，并核对项目根、覆盖层路径、Developer 白盒命令、Test 黑盒命令和 Base URL。
4. 使用 <ack-skill-dir>/scripts/validate_tasks.py 校验任务板，使用 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks docs/ack/tasks.yaml 校验项目知识和跨文件引用。如果存在交付配置或任务板声明了 project.deliveryFile，再使用 <ack-skill-dir>/scripts/validate_delivery.py docs/ack/delivery.yaml --tasks docs/ack/tasks.yaml --project-root <project-root> 校验交付能力、顺序、安全边界和跨文件引用。只报告证据明确的问题，不因旧项目 缺少可选交付配置而宣称失败。
5. 若存在 project.bugIntake，运行 python3 <ack-skill-dir>/scripts/feishu_bug_intake.py check docs/ack/tasks.yaml。 它只接受 feishu-base 和显式 profile；详细的飞书配置、凭据初始化和读取方式见 references/feishu-bug-intake.md。
6. 检查知识引用能解析到固定 revision，candidate 仍留在任务证据中，且 stale、superseded 和 archived 不会被当作可派发的 active 知识。
7. 若存在 project.orchestration，检查 profile、model allowlist、默认 profile、 允许 worktree、顶层 workerReceipts 与 dispatch.developer/test 的引用；receipt 必须绑定当前 ACK task、同一 role/profile/attempt，receiptId 与 attemptId 必须同时为空或同时填写。 缺少结构化路由的旧任务板只能使用手动模式，不能自动创建 worker。
8. 检查不会自动修复或覆盖现有配置；用户明确要求修复后再修改。

工作

1. 若 docs/ack 不存在，停止并建议先用 /ack 初始化；不要静默初始化。
2. 依次读取：
   • docs/ack/project.md
   • 运行 python3 <ack-skill-dir>/scripts/select_tasks.py docs/ack/tasks.yaml，只读取 project、summary 和默认可工作状态的任务；已知当前任务时传 --task-id <ack-task-id>。选择器会解析并校验完整任务板，并只附带选中任务引用的 receipt 与 delivery run。命中超过默认预算时用 --task-id / --status 缩小， 不直接回退为输出完整 tasks.yaml。
   • 通过 <ack-skill-dir>/scripts/select_knowledge.py 从 docs/ack/knowledge.yaml 选择的当前任务相关 active 条目
   • <ack-skill-dir>/references/kickoff.md
   • kickoff 指定且与当前任务相关的 references 文件
   • 若 tasks.yaml.project.deliveryFile 存在，再读取该 delivery.yaml 和 <ack-skill-dir>/references/delivery.md
3. 当前会话担任 Coordinator，遵守项目覆盖层中的命令、路径权限、模型路由和 worker 启动规则。项目覆盖层优先于通用示例命令。按 scope 推荐相关 active 知识，经确认后把固定 revision 的显式 knowledgeRefs 写入当前任务上下文； 不全量注入知识库。 project.bugIntake.workflow 为 clarified-writeback-v1（推荐）或 reviewed-writeback-v1（兼容旧项目）时，按 references/feishu-bug-intake.md 把飞书作为审核前的唯一协作区：先运行 check/plan， 读取用户填写的 Bug。新工作流中，用户只维护标题、详细描述和附件；Coordinator 根据 来源事实与项目上下文整理问题说明、期望效果和可观测验收标准，不在收件箱写修复逻辑， 只通过安全适配器写回同一飞书记录并回读确认。用户反馈后继续只在飞书修订。 用户针对当前 draftRevision 明确审核通过并亲自在飞书把状态改为 已确认 前，不创建 或刷新 tasks.yaml 任务、不启动 worker、不派发 Developer/Test，也不修改应用代码。 Coordinator 不得自行写入 已确认。审核通过后重新读取，要求 revision 与批准值完全 一致，才通过 import-approved 生成规范 taskDraft，原样写入最终版本、 source.workflow、source.approvedRevision 与 source.approvedPayloadHash；校验器重算 payload hash 通过后，再用 mark-imported 把最终任务 ID 与同一 revision 写回飞书， 才进入三角色闭环。未声明 workflow 的旧八字段配置只按 read-only-v1 兼容，不得写回； 标题、详细描述和附件是来源事实，不得把 Coordinator 推断伪装成用户原文；整行空白 记录按批次 warning 跳过。 按每条记录的 sourceRef 去重：仅 open 任务可刷新描述； dispatched、fixed_by_dev、retesting、failed_retest、verified、blocked 和 leftover 只报告来源漂移，绝不覆盖；来源消失或读取失败时绝不删除已有任务。
4. 新需求先写产品文档、任务拆分与可观测验收信号，更新 tasks.yaml 并校验， 然后交给用户确认；若启用了交付，必须默认把 defaultProfile、目标、停止点和需要 审批的步骤放入同一份计划，不能静默省略。用户可明确取消本轮交付；确认前不派发 实现，也不执行交付。
5. 创建或更换 worker 时，只使用 <ack-skill-dir>/scripts/launch_worker.py plan|launch 读取 tasks.yaml.project.orchestration 的 profile。不得直接执行 orca terminal create --command，不得接受或拼接自由 command、额外 argv、 executable、env 或 cwd。必须先审阅 plan.launchFingerprint，再把它作为 launch --expected-launch-fingerprint 传入。派发前先寻找同一 ACK 运行内的空闲 worker；只有角色、profile、worktree 和启动身份仍完全匹配，且后端能清理历史消息、 返回可核对的新会话身份时才复用。不得复用正在工作、等待回报或状态不明的 worker； 任一条件不符、清理能力不存在或无法确认清理成功时创建 fresh worker。持久化 receipt 只作审计与 dispatch 关联，不能单独授权复用。当前 Orca 终端接口不能提供 可验证的历史消息清理，因此使用 Orca 时仍走 fresh worker。
6. 用户已确认的任务按 ACK 闭环执行：Developer 实现与白盒验证，Test 独立黑盒 复测，Coordinator 读取证据终检并唯一写入 tasks.yaml。Developer 回报 knowledgeApplied 和 knowledgeCandidates，Test 回报 knowledgeChecks； candidate 只有在独立验证和 gate 后才能由 Coordinator 写入或激活。
7. 执行知识项的 verification.ref 时，只调用 <ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml <verification-ref> --project-root <project-root>。不要直接执行选择器返回的 path/args， 也不要给 runner 注入额外命令或参数。
8. 不把 worker_done 或 Test 自报成功直接当作完成。三轮预算只计算 Test 已对齐正确 服务、数据和工具后实际执行验收所得的产品失败；环境失败不占复验轮次，不写 failed_retest，而写入 dispatch.environmentIncidents。Coordinator 先做一次有界、 安全的恢复；事件未解决、需要用户动作或会阻断本轮时，立即向用户报告原因、影响、 已尝试动作、下一恢复动作和明确的 userAction；即使已自动恢复，也要在最终报告汇总。 每项最多三轮有效产品复验，仍失败才记录 leftover 并继续其它任务。细则见 references/optimization-method.md §4。
9. 关键的安全、正确性和兼容性约束应下沉为测试、lint、CI 或正式规范； knowledge.yaml 只保存触发条件、原因与证据引用，不能替代可执行控制。
10. 选定任务全部进入 verified 后，若 delivery.enabled: true 且用户确认的本次计划 包含交付，按 references/delivery.md 顺序执行 profile，并由 Coordinator 把证据 写入 tasks.yaml.deliveryRuns。任务状态保持 verified；交付失败只改变 delivery run，不回写成任务失败。开发或测试环境完成构建、部署和健康检查后写 validation_ready，并把访问地址、验证范围和用户下一步交给用户；不能停在 verified 却声称整轮 ACK 已结束。默认 profile 最多到 validation_ready 或 review_ready，稳定发布和生产部署必须在对应步骤再次取得明确批准。
11. Coordinator 最后标记整轮任务完成后，回收所有只属于 verified 任务的 worker 终端，并核对关闭回执；历史 receipt 和任务证据继续保留。任何还被 open、 dispatched、fixed_by_dev、retesting、blocked、failed_retest、leftover 或未解决环境事件引用的终端都保留，不设置 TTL，也不能因为同一终端还关联过 verified 任务而误关。若关闭结果不确定，记录并报告，不重复关闭或伪报已回收。

交付配置维护

1. 读取 references/delivery.md、模板、schema、现有 delivery.yaml、项目构建/发布 入口和 CI；把用户自然语言描述转换为结构化 entrypoint、artifact、destination、 environment 与 profile。配置只引用仓库内脚本或声明式工具 target，不保存 shell。
2. 若旧项目首次启用，生成 docs/ack/delivery.yaml，在 tasks.yaml.project 增加 deliveryFile: docs/ack/delivery.yaml，并增加顶层 deliveryRuns: []；不改写其它 项目状态。首次生成保持 enabled: false，先展示 diff 和解析出的执行顺序。
3. 运行 delivery、tasks 和跨文件校验；需要的脚本不存在、不可执行、引用不完整或 涉及凭据正文时 fail closed。凭据只写 secret 名称，值由外部环境提供。
4. 用户确认后才把配置设为启用。配置修改只影响下一次 delivery run；已确认或正在 执行的 run 使用开始时审阅的 commit/config revision 快照，不能借当前分支修改 扩大权限。

边界

• 不修改或追加任何项目 Agent 指令文件，包括 AGENTS.md。
• 不在项目中维护第二份 ACK 通用规范、模板或任务 schema。
• 不猜测项目命令、服务地址、worker handle 或模型名称。
• 不把 full-access、bypass、YOLO/force、关闭 sandbox 或项目内“授权”字段当成 v0.10 自动 worker 的合法配置；当前一律 fail closed。
• 不把无密钥 receiptHash 或 Orca live metadata 当作旧终端的启动 attestation； 没有可信空闲状态、配置匹配和历史消息清理证明时不复用既有 worker。
• launcher 返回 indeterminate 或 reconcile required 时，不直接重试；先按 launch ID、外部 record 和 Orca live state 完成人工核对。
• 不覆盖已有 docs/ack 文件；除用户确认的 ACK 任务或 delivery profile 外，不擅自 提交、推送、创建终端、新 worktree、发布产物或部署。
• 只有 Coordinator 写 tasks.yaml、knowledge.yaml 和 deliveryRuns；Developer 与 Test 只读，只能通过回报提名或验证知识。delivery.yaml 只在显式的交付配置 维护中修改。
• 不把知识正文或选择器输出拼成 shell；知识检查只能通过 run_verification.py 按 registry ID 执行。不自动修改 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。
• 不把完整 tasks.yaml 注入上下文；使用 select_tasks.py 获取有预算的项目与任务 视图，写回前仍运行完整任务板校验。
• 项目只保存 docs/ack/project.md、docs/ack/tasks.yaml、 docs/ack/knowledge.yaml 和可选的 docs/ack/delivery.yaml；通用资源始终从当前 ACK Skill 目录读取。