# 如何开始一个需求（Kickoff）

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

---

## 前提：谁是 Coordinator

**你（发起编排的强模型会话）就是 Coordinator (PM) / 产品。** 你负责写文档、拆任务、编排、终检，**不亲自写代码、不亲自跑测试**。开发和测试是另起的 worker agent；具体 CLI、模型、reasoning effort 和执行模式必须先读项目覆盖层 `docs/ack/project.md`，禁止照抄未核对的默认命令。

---

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

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

1. 先读 docs/ack/project.md、docs/ack/tasks.yaml，校验 docs/ack/knowledge.yaml 并
   用 `scripts/select_knowledge.py` 只读取当前任务相关的 active 条目，再读
   references/roles-and-permissions.md、closed-loop.md、optimization-method.md。
2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
3. 按任务 scope 从 knowledge.yaml 推荐 active 知识，确认后把固定 revision 的
   knowledgeRefs 写入任务；不要派发 candidate 或全量知识库。
4. 把任务写进 docs/ack/tasks.yaml（只有你写），校验 tasks.yaml 和 knowledge.yaml。
5. 先把「产品文档 + 任务拆分 + 验收信号 + 适用知识引用」给我确认，不要急着派发。
6. 我确认后，按 ack 闭环循环：先按 docs/ack/project.md 校验 Developer/Test worker 启动命令，
   dispatch 开发 → worker_done → dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml；
   每个任务最多三轮，三轮不过记 leftover 并升级我复盘。
```

---

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

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

```bash
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
```

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

---

## 第 2 步：决定 worktree

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

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

---

## 第 3 步：复用或启动 worker

先读 `docs/ack/project.md` 的项目覆盖规则，再按 `orca-adapter.md` §「解析并复用 worker」执行：先列出现有终端和活跃任务，优先复用同 worktree、同角色、配置兼容且空闲的 worker。只有没有可复用项时才创建新终端；如果项目提供 `validate_worker_command.py`，校验未通过时不得创建。

```bash
# Codex 示例（模型与执行模式以项目覆盖层为准）
DEV_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-terra -c model_reasoning_effort=medium'
TEST_CMD='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.6-luna -c model_reasoning_effort=low'
python3 <ack-skill-dir>/scripts/validate_worker_command.py --role developer --command "$DEV_CMD"
python3 <ack-skill-dir>/scripts/validate_worker_command.py --role test --command "$TEST_CMD"
orca terminal create --worktree active --command "$DEV_CMD" --title "ACK-DEV-CODEX-TERRA-1" --json
orca terminal create --worktree active --command "$TEST_CMD" --title "ACK-TEST-CODEX-LUNA-1" --json

# Cursor 示例
CURSOR_CMD='cursor-agent --yolo --model auto'
python3 <ack-skill-dir>/scripts/validate_worker_command.py --role developer --command "$CURSOR_CMD"
orca terminal create --worktree active --command "$CURSOR_CMD" --title "ACK-DEV-CURSOR-AUTO-1" --json
```

上面的 `terminal create` 都是“没有空闲兼容 worker”时的兜底，不是每次 kickoff 的固定动作。新 worktree 时先 `orca worktree create --name <feature> --base-branch <base>`，再解析该 worktree 的 worker。选型与升级见 `model-routing.md`。新建终端后、dispatch 前必须读取启动信息，确认实际 CLI、模型和 reasoning effort；派发后把实际 handle 写入对应任务的 `dispatch.worker`。

---

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

```text
task-create → dispatch 给 DEV → 等 worker_done
  → 每轮使用 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 必须能回答 `optimization-method.md` §「结束条件」的问题：哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。

---

## 一句话

产品文档 + 验收信号写在前（你，强模型）→ 确认显式 `knowledgeRefs` → 按项目
覆盖层校验并启动 DEV/TEST → 核对实际模型 → dispatch / 复测 / 终检循环 → 任务
结论落 `tasks.yaml`，验证后的跨任务知识由 Coordinator 落 `knowledge.yaml`。