如何开始一个需求（Kickoff）

从零开一个需求的启动手册。角色/权限见 roles-and-permissions.md，闭环见 closed-loop.md，模型见 model-routing.md。

前提：谁是 Coordinator

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

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

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

1. 先读 docs/ack/project.md、docs/ack/tasks.yaml（包括 project.orchestration），校验 docs/ack/knowledge.yaml 并
   用 `scripts/select_knowledge.py` 只读取当前任务相关的 active 条目，再读
   references/roles-and-permissions.md、closed-loop.md、optimization-method.md。
   如果 tasks.yaml 声明 project.deliveryFile，再读取 delivery.yaml 与
   references/delivery.md，但不要把配置本身当作执行授权。
2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
3. 按任务 scope 从 knowledge.yaml 推荐 active 知识，确认后把固定 revision 的
   knowledgeRefs 写入任务；不要派发 candidate 或全量知识库。
4. 把任务写进 docs/ack/tasks.yaml（只有你写），校验 tasks.yaml 和 knowledge.yaml。
5. 先把「产品文档 + 任务拆分 + 验收信号 + 适用知识引用」给我确认；若启用了交付，
   同时列明本次 profile、目标、停止点与审批步骤。不要急着派发或交付。
6. 我确认后，按 ack 闭环循环：先用 `scripts/launch_worker.py` 校验结构化
   Developer/Test profile，审阅 plan 后用 expected fingerprint 创建 fresh worker，
   dispatch 开发 → worker_done → dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml；
   每个任务最多三轮，三轮不过记 leftover 并升级我复盘。
7. 所选任务都 verified 后，只有本次计划包含交付时才按 profile 顺序执行并写
   deliveryRuns；默认停在 review_ready，stable/production 步骤再次向我确认。

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

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

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

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

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

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

第 2 步：决定 worktree

见 closed-loop.md §「子任务放哪」：

需求大 / 要并行 / 要保基线分支干净 → 新建隔离 worktree。
小改动 / 串行修复 → 当前 worktree 起子 agent。

第 3 步：审阅并启动 worker

先读 tasks.yaml.project.orchestration 的结构化 profiles。v0.10 不把历史 receipt 或既有 Orca terminal 当作自动复用授权；每次自动派发都创建 fresh worker。原因和边界见 model-routing.md §「Receipt、审计与复用边界」。

先查看目标 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 前，先把新路径加入 project.orchestration.allowedWorktrees 并重新运行任务板校验。profile 只允许 read-only 或 workspace-write；v0.10 的 full-access 授权通道尚未实现，任何 bypass、YOLO/force 或关闭 sandbox 的请求都必须失败，不能手写命令兜底。选型与升级见 model-routing.md。

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

task-create → dispatch 给 DEV → 等 worker_done
  → 每个角色都通过 plan + expected fingerprint launch fresh worker 并写回 receipt
  → 每轮使用 Coordinator 分配的稳定 <task-id>-A<round>
  → 回写 fixed_by_dev → dispatch 给 TEST 复测 → 等 retest_result
  → Developer 回 knowledgeApplied / knowledgeCandidates，Test 回 knowledgeChecks
  → Coordinator 读证据终检 → 过则 verified，不过则 failed_retest 再派 DEV（最多累计 3 轮）
  → 三轮失败：leftover，升级复盘，继续下一个

具体命令见 orca-adapter.md（Orca）或 closed-loop.md §「手动模式」（无 Orca）；派发文案见 prompt-templates.md。

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

第 5 步：可选交付

所选任务都由 Coordinator 标记为 verified 后，若用户确认的计划包含交付，按 delivery.md 执行所选 profile。先重新校验 delivery.yaml，固定当前 commit 和 config revision，然后按有序步骤调用项目入口与已安装的低层 skill。每一步证据写入 tasks.yaml.deliveryRuns；默认 profile 到 review_ready 即停止，stable 发布和 production 部署必须在 approval 步骤再次确认。失败时保留任务的 verified，把 delivery run 标为 blocked 或 failed。

第 6 步：收尾

一轮结束时 Coordinator 必须能回答 optimization-method.md §「结束条件」的问题：哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。

一句话

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

8.9 KiB Raw Permalink Blame History Unescape Escape