.pouch/skills/ack/references/kickoff.md

如何开始一个需求（Kickoff）

从零开一个需求的启动手册。本文件只覆盖确认前的产品文档、任务拆分与验收信号。 用户确认后的三角色闭环、飞书收件、启动 worker、交付和回归由 SKILL.md 按条件加载， 不要在本文件开头预读其它规范。

---

前提：谁是 Coordinator

你（发起编排的强模型会话）就是 Coordinator (PM) / 产品。 你负责写文档、拆任务、 编排、终检，不亲自写代码、不亲自跑测试。开发和测试是另起的 worker agent； 具体 CLI、模型、reasoning effort 和执行模式的机器事实源是 .pouch/ack/tasks.yaml 的 project.orchestration。.pouch/ack/project.md 只解释项目 差异，不能提供另一套启动命令。

---

第 0 步：给 Coordinator 的开场指令（复制改需求）

我要做一个新需求：<一句话需求>。
你作为 ack 的 Coordinator(PM)，按 ACK Skill 执行：

1. 先读 .pouch/ack/project.md，并用 `scripts/select_tasks.py .pouch/ack/tasks.yaml`
   读取有预算的 project、summary 和可工作任务；已知任务时传 `--task-id`，不要把
   完整 tasks.yaml 注入上下文。校验 .pouch/ack/knowledge.yaml 并用
   `scripts/select_knowledge.py` 只读取当前任务相关的 active 条目。
   本 kickoff 只做确认前的产品文档与任务拆分；用户确认后的闭环、飞书、启动
   worker、交付和回归按 ACK Skill 的模式路由按条件加载，不要在本步预读其它
   references。配置本身不是执行授权。
2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
3. 按任务 scope 从 knowledge.yaml 推荐 active 知识，确认后把固定 revision 的
   knowledgeRefs 写入任务；不要派发 candidate 或全量知识库。
4. 把任务写进 .pouch/ack/tasks.yaml（只有你写），校验 tasks.yaml 和 knowledge.yaml。
5. 先把「产品文档 + 任务拆分 + 验收信号 + 适用知识引用」给我确认；若启用了交付，
   同时列明本次 profile、目标、停止点与审批步骤。不要急着派发或交付。
6. 我确认后，按 ack 闭环循环：先用 `scripts/launch_worker.py` 校验结构化
   Developer/Test profile；优先选择同一轮内角色/profile/worktree 匹配的空闲 worker，
   只有历史消息已可信清理并取得新会话身份才复用，否则审阅 plan 后用 expected
   fingerprint 创建 fresh worker；
   dispatch 开发 → worker_done → 若 intents.testEnvironment 已启用则先用 deployer 拉起测试环境 →
   dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml；
   每个任务最多三轮有效产品复验，三轮不过记 leftover 并升级我复盘；环境失败单独
   记录、恢复并告诉我下一步，不占产品复验轮次。
7. 所选任务都 verified 后，按 SKILL.md「运行回归」给出新增/更新/退役/无回归，确认后写入
   .pouch/ack/regression.yaml。只有本次计划包含交付时才按 profile 顺序执行并写
   deliveryRuns；启用 delivery 时不能省略 defaultProfile，默认停在 validation_ready
   或 review_ready，stable/production 步骤再次向我确认。

---

第 1 步：Coordinator 产出（确认前）

1. 产品文档 → docs/PRD-<feature>.md 等（Coordinator R/W）。
2. 任务板 → .pouch/ack/tasks.yaml，每条任务带 expected + verification，验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
3. 项目知识 → 从 .pouch/ack/knowledge.yaml 按 component、path、dependency、version 和 tag 推荐 active 条目，Coordinator 确认后写入固定 revision 的显式 knowledgeRefs。candidate 不参与选择。
4. 校验结构与引用：

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

project.orchestration 是 worker profile 的机器 SSOT；未知字段、非 allowlist 模型、 不匹配的角色/档位和非安全权限必须在派发前 fail closed。

读取任务上下文使用：

python3 <ack-skill-dir>/scripts/select_tasks.py .pouch/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/select_tasks.py .pouch/ack/tasks.yaml \
  --task-id <ack-task-id>

选择器解析并校验完整任务板，但只输出命中任务及其 receipt/delivery run；超过预算时 显式失败，不得改用 cat 或整文件 sed。

5. 停下来给人确认：这是强模型该花时间的地方，不要跳过。

如果 delivery.enabled: true，确认内容还必须列出：profile、关联 task IDs、构建产物、 发布 channel、部署环境、PR 是否创建/标 ready、停止点，以及哪些步骤会再次审批。

---

第 2 步：决定 worktree

• 需求大 / 要并行 / 要保基线分支干净 → 新建隔离 worktree。
• 小改动 / 串行修复 → 当前 worktree 起子 agent。 用户确认后的闭环步骤由 SKILL.md「工作」加载，不要在本步预读其它规范。

---

第 3 步：审阅并启动 worker

先读 tasks.yaml.project.orchestration 的结构化 profiles。历史 receipt 或既有 Orca terminal 不能单独授权复用。复用候选必须属于同一轮 ACK、处于空闲状态，且角色、 profile、worktree 与启动身份仍完全匹配；还必须通过受信后端清理历史消息并取得可核对 的新会话身份。当前 Orca 接口缺少该清理证明，所以 Orca 派发仍创建 fresh worker。 复用边界以 SKILL.md「启动 worker」为准，不要在本步预读其它规范。

先查看目标 profile hash，确认本次结构化配置。这个 hash 只用于审计和漂移比较， 不能用于匹配或复用旧 receipt / 既有终端：

python3 <ack-skill-dir>/scripts/launch_worker.py profile-hash \
  --project-root <project-root> --profile-id <profile-id>

生成只读计划：

python3 <ack-skill-dir>/scripts/launch_worker.py plan \
  --project-root <project-root> --task-id <task-id> \
  --attempt-id <task-id>-A<round> --role <developer-or-test> \
  --profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99>

审阅计划后执行唯一创建入口：

python3 <ack-skill-dir>/scripts/launch_worker.py launch \
  --project-root <project-root> --task-id <task-id> \
  --attempt-id <task-id>-A<round> --role <developer-or-test> \
  --profile-id <profile-id> --worktree <absolute-worktree> --slot <1..99> \
  --expected-launch-fingerprint <plan 中的 sha256:...>

launch 的 fingerprint 必须来自刚才审阅的 plan；若中间任何关键事实漂移，重新 plan，不得覆盖检查。标准输出是单一 JSON。Coordinator 校验其中的 receipt 后，把 receipt 原样追加到 tasks.yaml.workerReceipts，把 receipt.id 写入该任务 dispatch.<role>.receiptId、把 profileId 写入 dispatch.<role>.profileId，并把 本轮稳定 ID 写入 dispatch.<role>.attemptId。三者必须与 receipt 的当前 task/role/profile/attempt 完全绑定；不得把旧任务或旧轮次的 receipt 改挂到当前 dispatch。后续 紧随其后的本次 Orca dispatch 只使用这次 fresh receipt binding 中的 handle；持久化 receipt 仅用于审计，不能在后续轮次单独授权复用。不要自行拼装 Agent CLI 或 Orca 的 底层创建命令。

新 worktree 时可先运行 orca worktree create --name <feature> --base-branch <base> --json，再对返回的绝对 worktree 走同一套 plan -> 带 expected fingerprint 的 launch。在调用 launcher 前，确认新 worktree 与权威项目根同一 Git 仓库即可（v0.19 起不再需要登记 allowedWorktrees）。profile 只允许 read-only 或 workspace-write；v0.10 的 full-access 授权通道尚未实现， 任何 bypass、YOLO/force 或关闭 sandbox 的请求都必须失败，不能手写命令兜底。 选型与升级以 SKILL.md「启动 worker」为准。

---

第 4 步：跑闭环（每个任务）

task-create → dispatch 给 DEV → 先确认 DEV 已开始执行（read/probe；未开始按环境失败处理）→ 滚动 wait 等 worker_done
  → 每个角色先检查可安全重置的空闲 worker；不符合即通过 plan + expected fingerprint launch fresh worker
  → 每轮使用 Coordinator 分配的稳定 <task-id>-A<round>
  → 回写 fixed_by_dev → 若 intents.testEnvironment 已启用则先用 deployer 拉起测试环境 → dispatch 给 TEST 复测 → 等 retest_result
  → Developer 回 knowledgeApplied / knowledgeCandidates，Test 回 knowledgeChecks
  → 环境无法完成：记录 environmentIncidents，报告影响与用户下一步，恢复后重新复验（不计轮次）
  → Coordinator 读证据终检 → 过则 verified，产品失败则 failed_retest 再派 DEV（最多累计 3 轮）
  → 三轮有效产品失败：leftover，升级复盘，继续下一个

Orca / 手动命令与派发文案由 SKILL.md「启动 worker」按条件加载。

Coordinator 只内联本轮 knowledgeRefs 指向的少量知识，不要求 worker 全量读取 知识库。知识正文不得作为自由 shell 执行；需要命令时只能引用项目已审查的检查 入口，并把它的 registry ID 交给 <ack-skill-dir>/scripts/run_verification.py， 不自行拼接 path/args。Test 独立验证且 gate 通过后，Coordinator 才能把 candidate 写成 active 知识；关键约束应继续下沉为测试、lint、CI 或正式规范。

---

第 5 步：可选交付

用户说「重新布测试环境」或「发布一个版本」时，转入 SKILL.md 对应模式，不要在本步预读交付规范。intent 为 null 时先做交付配置维护。

所选任务 verified 后，转入 SKILL.md「运行回归」给出新增/更新/退役/无回归四选一，用户确认后写入 .pouch/ack/regression.yaml。用户说「回归」时先布测试环境，再派 Test 按目录执行。

所选任务都由 Coordinator 标记为 verified 后，若用户确认的计划包含交付，转入 SKILL.md 对应交付模式。启用交付时必须在计划中默认列出 defaultProfile，用户可明确取消，Coordinator 不能静默省略。先重新校验 delivery.yaml，固定当前 commit 和 config revision，然后按有序步骤调用项目入口与已安装的低层 skill。每一步证据写入 tasks.yaml.deliveryRuns；默认 profile 到 validation_ready 或 review_ready 即停止。前者必须把测试环境地址和用户下一步交付出来；stable 发布和 production 部署必须在 approval 步骤再次确认。失败时保留任务的 verified，把 delivery run 标为 blocked 或 failed。

第 6 步：收尾

一轮结束时 Coordinator 必须能回答：哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。复验轮次争议以 SKILL.md「边界」为准。 Coordinator 最后标记整轮任务完成后，用 scripts/reclaim_workers.py 先 dry-run 审阅决策、再 --apply 关闭所有只关联 verified 任务的 Developer/Test 终端并核对 回执；receipt 和落盘证据继续保留。仍关联 blocked、failed_retest、leftover 或其它未完成任务/未解决环境事件的终端保留，不设置 TTL。一个终端只要仍被任一这类 任务引用，就不能因为同时关联了 verified 任务而关闭。

---

一句话

产品文档 + 验收信号写在前（你，强模型）→ 确认显式 knowledgeRefs → 从 tasks.yaml.project.orchestration 解析安全 profile → 审阅 plan 并用 expected fingerprint 启动 fresh DEV/TEST → dispatch / 复测 / 终检循环 → 任务结论落 tasks.yaml → 可选收获回归用例到 regression.yaml → 可选 delivery profile 到审核点，验证后的跨任务知识由 Coordinator 落 knowledge.yaml → 整轮完成后回收 仅属于 verified 任务的 worker，保留 blocked/failed/leftover worker。