.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: []；不要虚构需求或缺陷。

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（旧项目可无；存在或被任务板引用时必须校验）
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. 检查知识引用能解析到固定 revision，candidate 仍留在任务证据中，且 stale、superseded 和 archived 不会被当作可派发的 active 知识。
6. 若存在 project.orchestration，检查 profile、model allowlist、默认 profile、 允许 worktree、顶层 workerReceipts 与 dispatch.developer/test 的引用；receipt 必须绑定当前 ACK task、同一 role/profile/attempt，receiptId 与 attemptId 必须同时为空或同时填写。 缺少结构化路由的旧任务板只能使用手动模式，不能自动创建 worker。
7. 检查不会自动修复或覆盖现有配置；用户明确要求修复后再修改。

工作

1. 若 docs/ack 不存在，停止并建议先用 /ack 初始化；不要静默初始化。
2. 依次读取：
   • docs/ack/project.md
   • docs/ack/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 写入当前任务上下文； 不全量注入知识库。
4. 新需求先写产品文档、任务拆分与可观测验收信号，更新 tasks.yaml 并校验， 然后交给用户确认；若启用了交付，还要把本次 profile、目标、停止点和需要审批的 步骤放入同一份计划。确认前不派发实现，也不执行交付。
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 传入。v0.10 不根据持久化 receipt 自动 复用旧终端；每次自动派发都创建 fresh worker，receipt 只作审计与 dispatch 关联。
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 自报成功直接当作完成。每项最多三轮，仍失败则记录 leftover 并继续其它任务。
9. 关键的安全、正确性和兼容性约束应下沉为测试、lint、CI 或正式规范； knowledge.yaml 只保存触发条件、原因与证据引用，不能替代可执行控制。
10. 选定任务全部进入 verified 后，若 delivery.enabled: true 且用户确认的本次计划 包含交付，按 references/delivery.md 顺序执行 profile，并由 Coordinator 把证据 写入 tasks.yaml.deliveryRuns。任务状态保持 verified；交付失败只改变 delivery run，不回写成任务失败。默认 profile 最多到 review_ready，稳定发布和生产部署 必须在对应步骤再次取得明确批准。

交付配置维护

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； v0.10 不自动复用既有 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 指令文件。
• 项目只保存 docs/ack/project.md、docs/ack/tasks.yaml、 docs/ack/knowledge.yaml 和可选的 docs/ack/delivery.yaml；通用资源始终从当前 ACK Skill 目录读取。