feat: modify ack

kits/ack/README.md

@@ -23,6 +23,7 @@ ack/
   README.md
   adoption-checklist.md
   core/                         # 稳定核心：跨项目通用，随 kit 升级，尽量别改
+    kickoff.md                  #   如何开始一个需求（启动手册 + 开场指令模板）
     roles-and-permissions.md    #   角色/权限/状态机/完成定义（SSOT）
     model-routing.md            #   三角色默认模型档位 + 升级规则（SSOT）
     closed-loop.md              #   编排无关闭环 + 手动模式 + worktree 对齐
@@ -94,6 +95,65 @@ ln -s <此框架绝对路径> <project>/docs/ack/kit
 
 ---
 
+## 常用使用方法
+
+### 开一个新需求（最常用）
+
+你（强模型会话）就是 Coordinator(PM)。完整手册见 `core/kickoff.md`，开场指令：
+
+```text
+我要做一个新需求：<一句话需求>。你作为 ack 的 Coordinator(PM)，按 docs/ack/kit/core 规范：
+先读 project.md 与 core/*；写产品文档到 docs/ 并把需求拆成带可观测验收信号的任务写进 docs/ack/tasks.yaml；
+先给我确认产品文档+任务拆分，再按闭环起 DEV/TEST worker（cursor-agent --model auto）循环派发/复测/终检；
+每个任务最多三轮，三轮不过记 leftover。
+```
+
+### 起 worker（模型固定为 auto）
+
+```bash
+orca terminal create --worktree active --command "cursor-agent --model auto" --title "DEV"  --json
+orca terminal create --worktree active --command "cursor-agent --model auto" --title "TEST" --json
+```
+
+需要隔离/并行时先建 worktree：`orca worktree create --name <feature> --base-branch <base> --json`（选择依据见 `core/closed-loop.md`）。
+
+### 派发与等待（Orca）
+
+```bash
+orca orchestration task-create --spec "<任务与验收>" --json
+orca orchestration dispatch --task <task_id> --to <dev_handle> --json
+orca orchestration check --terminal <coordinator_handle> --wait \
+  --types worker_done,retest_result,escalation,decision_gate --timeout-ms 900000 --json
+```
+
+不能 `--inject` 时手动投递 `core/prompt-templates.md` 的模板；命令细节见 `core/orca-adapter.md`。
+
+### 校验任务板结构
+
+```bash
+python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
+```
+
+### 只处理已有未通过项
+
+用「默认口令」（见下）让 Coordinator 直接扫 `tasks.yaml` 里的 `open` / `failed_retest` 继续闭环。
+
+### 速查：想做什么 → 看哪个文件
+
+| 想做的事 | 文件 |
+|----------|------|
+| 开一个新需求怎么起步 | `core/kickoff.md` |
+| 角色/权限/状态机/完成定义 | `core/roles-and-permissions.md` |
+| 三角色各自该怎么做（规划/写测试/复测能力清单） | `core/roles-and-permissions.md` §三角色能力清单 |
+| 用哪个模型、怎么固定、何时升级 | `core/model-routing.md` |
+| 闭环步骤、手动模式、worktree 决策与对齐 | `core/closed-loop.md` |
+| 验收信号写法、三轮失败策略 | `core/optimization-method.md` |
+| 派发/复测/回报的 prompt 文案 | `core/prompt-templates.md` |
+| Orca 具体命令 | `core/orca-adapter.md` |
+| 新项目接入步骤 | `adoption-checklist.md` |
+
+---
+
 ## 默认口令
 
 ```text

kits/ack/VERSION

@@ -1 +1 @@
-0.6.2
+0.8.0

kits/ack/core/kickoff.md

@@ -0,0 +1,85 @@
+# 如何开始一个需求（Kickoff）
+
+从零开一个需求的启动手册。角色/权限见 `roles-and-permissions.md`，闭环见 `closed-loop.md`，模型见 `model-routing.md`。
+
+---
+
+## 前提：谁是 Coordinator
+
+**你（发起编排的强模型会话）就是 Coordinator (PM) / 产品。** 你负责写文档、拆任务、编排、终检，**不亲自写代码、不亲自跑测试**。开发和测试是另起的 worker agent（`cursor-agent --model auto`）。
+
+---
+
+## 第 0 步：给 Coordinator 的开场指令（复制改需求）
+
+```text
+我要做一个新需求：<一句话需求>。
+你作为 ack 的 Coordinator(PM)，按 docs/ack/kit/core 的规范执行：
+
+1. 先读 docs/ack/project.md、docs/ack/kit/core/roles-and-permissions.md、closed-loop.md、optimization-method.md。
+2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
+3. 把任务写进 docs/ack/tasks.yaml（只有你写），跑 validate 校验结构。
+4. 先把「产品文档 + 任务拆分 + 验收信号」给我确认，不要急着派发。
+5. 我确认后，按 ack 闭环循环：为任务起 Developer/Test worker（cursor-agent --model auto），
+   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. 校验结构：
+
+```bash
+python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
+```
+
+4. **停下来给人确认**——这是强模型该花时间的地方，不要跳过。
+
+---
+
+## 第 2 步：决定 worktree
+
+见 `closed-loop.md` §「子任务放哪」：
+
+- 需求大 / 要并行 / 要保基线分支干净 → 新建隔离 worktree。
+- 小改动 / 串行修复 → 当前 worktree 起子 agent。
+
+---
+
+## 第 3 步：起 worker（模型固定 auto）
+
+```bash
+orca terminal create --worktree active --command "cursor-agent --model auto" --title "DEV"  --json
+orca terminal create --worktree active --command "cursor-agent --model auto" --title "TEST" --json
+```
+
+新 worktree 时先 `orca worktree create --name <feature> --base-branch <base>`，再在其中起终端。选型与升级见 `model-routing.md`。
+
+---
+
+## 第 4 步：跑闭环（每个任务）
+
+```text
+task-create → dispatch 给 DEV → 等 worker_done
+  → 回写 fixed_by_dev → dispatch 给 TEST 复测 → 等 retest_result
+  → Coordinator 读证据终检 → 过则 verified，不过则 failed_retest 再派 DEV（最多累计 3 轮）
+  → 三轮失败：leftover，升级复盘，继续下一个
+```
+
+具体命令见 `orca-adapter.md`（Orca）或 `closed-loop.md` §「手动模式」（无 Orca）；派发文案见 `prompt-templates.md`。
+
+---
+
+## 第 5 步：收尾
+
+一轮结束时 Coordinator 必须能回答 `optimization-method.md` §「结束条件」的问题：哪些 verified、哪些 leftover、各失败几轮、工作树是否干净、还有没有未处理项。
+
+---
+
+## 一句话
+
+产品文档 + 验收信号写在前（你，强模型）→ DEV/TEST 用 `--model auto` 起 worker → dispatch / 复测 / 终检循环 → 结论只落 `tasks.yaml`。

kits/ack/core/prompt-templates.md

@@ -4,6 +4,20 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
 
 角色分工见 `roles-and-permissions.md`；闭环顺序见 `closed-loop.md`。
 
+派发时除了具体任务，Coordinator 应把对应角色的**能力要求**一并带上（`roles-and-permissions.md` §「三角色能力清单」的 Must Do / Must Not）。下面模板已内置关键条目，复制即可。
+
+---
+
+## 0. 可选 skills 路由（装了才用，不阻塞）
+
+如果 worker 所在环境已安装以下 skill，可在对应环节调用以获得更强 playbook；未安装则按 `roles-and-permissions.md` 的能力清单执行：
+
+- Coordinator 规划复杂需求：`/think` 或 `superpowers:brainstorming` / `writing-plans`。
+- Developer 排查缺陷：`/hunt` 或 `superpowers:systematic-debugging`；行为变更：`superpowers:test-driven-development`。
+- Test 复测 / 合并前检查：`/check` 或 `superpowers:verification-before-completion`。
+
+派发时可加一行：「若已安装 <skill>，本环节可用它；未安装按 ack 角色能力清单执行。」
+
 ---
 
 ## 1. 初始派发给 Developer
@@ -27,12 +41,18 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
 2. <expected behavior 2>
 3. <expected behavior 3>
 
+能力要求（见 roles-and-permissions.md §三角色能力清单 · Developer）：
+- 动手前先复现失败现象，或先写一个会失败的测试再修。
+- bug 修复配可复现的失败用例；行为变更配单元测试。
+- 完成前亲自走一遍验收路径，不只满足静态文案。
+- 若是网站 / 常驻服务，改完重启服务并确认生效，别让 Test 测到旧进程或旧构建。
+
 约束：
 - 只修改 Developer 可写路径（见覆盖层文件的权限表）。
 - 不要修改产品规格和集成测试文件（分别由 Coordinator 与 Test 拥有），除非任务明确要求。
 - 不要写 tasks.yaml，不要标记 verified。
 - 不要提交或推送，除非用户明确要求。
-- 最小 diff，避免无关重构。
+- 最小 diff，只改本任务根因，避免无关重构；若必须先重构请停下说明并请示。
 
 完成前必须运行：
 - <test command 1>
@@ -86,8 +106,9 @@ Developer 本轮声称（仅供参考，不作数）：
 - 改动文件：<files>
 - 自测命令：<commands>
 
-复测要求：
+复测要求（见 roles-and-permissions.md §三角色能力清单 · Test）：
-- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md）。
+- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
+- 网站类任务优先用浏览器复测真实交互，其次才是 API / 脚本。
 - 逐条验证下列验收信号，不要只看静态文案，要验证交互后的真实状态：
   1. <observable signal 1>
   2. <observable signal 2>

kits/ack/core/roles-and-permissions.md

@@ -23,6 +23,57 @@
 
 ---
 
+## 三角色能力清单（SSOT）
+
+上面的表定义了**边界**（谁能碰什么），这一节定义**能力**（每个角色到底该怎么做好自己的事）。每个角色用同一骨架描述：`Outcome`（产出什么）/ `Must Do`（必须做）/ `Must Not`（不能做）/ `Evidence`（拿什么证明）/ `Output`（交付格式）。派发 prompt 会引用这里，见 `prompt-templates.md`。
+
+这些是**通用工程习惯**，不含项目命令与路径；项目差异写在覆盖层文件（默认 `docs/ack/project.md`）。装了外部 skill 的环境可按每个角色末尾的「可选 skills」加速，未装则照本清单执行，不阻塞。
+
+### Coordinator (PM) —— 拆解与终检
+
+- **Outcome**：把一句话需求变成可执行、验收可观测的任务集，并跑完闭环得到明确结论（verified / leftover）。
+- **Must Do**
+  - 先澄清意图再动手：目标、成功标准、约束、明确「不做什么」。歧义有多解或多来源冲突时，先问清再拆。
+  - 每个任务写**可观测验收信号**（可见文本 / API 结果 / 交互结果，见 `optimization-method.md` §1），而不是「功能正常」。
+  - 拆任务时点明最脆弱的假设：「本任务假设 X，若 X 不成立则 Y」；列出被否掉的方案与原因。
+  - 拆分/验收先给用户确认，再派发（`kickoff.md` 第 1 步的停顿点）。
+  - 一次派发只针对一个明确问题（`optimization-method.md` §6）；每任务最多三轮。
+  - 终检：读 Test 证据，逐条对齐原始意图后才落 `verified`，不亲自复测。
+- **Must Not**：改源码、亲自跑测试、凭 `worker_done` 直接标 `verified`、把多个无关失败塞进一次派发。
+- **Evidence**：产品文档、`tasks.yaml` 里的 `expected` + `verification`、Test 回传的复测证据。
+- **Output**：确认前给「产品文档 + 任务拆分 + 验收信号」；闭环结束给最终报告（`prompt-templates.md` §6）。
+- **可选 skills**：复杂需求可先用 `/think` 或 `superpowers:brainstorming` / `writing-plans` 收敛设计与计划。
+
+### Developer —— 实现与白盒验证
+
+- **Outcome**：在授权路径内做出满足验收信号的最小改动，并用白盒证据证明它可复现。
+- **Must Do**
+  - 动手前先读覆盖层文件、`tasks.yaml` 对应任务、相关规格；复现失败现象或先写会失败的测试。
+  - 最小 diff，只改一个明确问题的根因，不顺手重构无关代码。
+  - 行为变更配单元测试；bug 修复先有一个能复现的失败用例再修。
+  - 完成前跑覆盖层里规定的命令（构建 / 单测 / 本地运行），亲自走一遍验收路径。
+  - **网站 / 常驻服务**：改完重启服务（或触发热更并确认生效），保证运行实例跑的是新代码，避免 Test 测到旧进程 / 旧构建。
+- **Must Not**：改产品规格与集成测试、写 `tasks.yaml`、标 `verified`、绕过测试声称完成、把 bug 修复扩成大重构（需要就先停下说明并请示）。
+- **Evidence**：改了哪些文件、跑了哪些命令及结果、如何复现验收路径、残留风险。
+- **Output**：一次 `worker_done`，字段见 `prompt-templates.md` §4（只报证据，不下最终结论）。
+- **可选 skills**：排查用 `/hunt` 或 `superpowers:systematic-debugging`（先根因后修）；实现行为变更用 `superpowers:test-driven-development`。
+
+### Test —— 独立黑盒复测
+
+- **Outcome**：以独立视角复现验收路径，逐条给出通过/失败的可观测证据，供 Coordinator 终检。
+- **Must Do**
+  - 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 `closed-loop.md`），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
+  - 逐条验证验收信号，验证交互后的真实状态，而不是只看静态文案。
+  - **网站类任务优先用浏览器复测**真实交互（点击 / 跳转 / 渲染），其次才是 API / 脚本；纯后端 / CLI 则以 API smoke 或脚本为主。
+  - 把最容易反复误判的路径沉淀成可执行测试（`optimization-method.md` §8）。
+  - 只回传证据 + 逐条结论，最终判定留给 Coordinator。
+- **Must Not**：改应用源码、改产品规格、写 `tasks.yaml`、凭 Developer 的 `worker_done` 直接下结论。
+- **Evidence**：运行环境快照、命令结果、每条信号 pass/fail + 证据（snapshot / DOM / API 结果）。
+- **Output**：一次复测报告，字段见 `prompt-templates.md` §5。
+- **可选 skills**：合并 / 发版前检查可用 `/check` 或 `superpowers:verification-before-completion`（证据先于结论）。
+
+---
+
 ## 路径权限模板
 
 目标项目在自己的**覆盖层文件**中填入实际路径（模板见 `templates/project.template.md`；覆盖层默认 `docs/ack/project.md`，路径记在 `tasks.yaml` 的 `project.overlayFile`）。

kits/ack/examples/project.example.md

@@ -1,6 +1,6 @@
 # notes-web Agent 协作协议（示例，项目覆盖层）
 
-> 本项目基于 ack v0.6.0。
+> 本项目基于 ack v0.8.0。
 > 稳定规范引用 `docs/ack/kit/core/`，本文件只填项目差异。
 > 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。
 > 目录下只有一个软链接 `kit/` + `project.md` + `tasks.yaml`。
@@ -16,6 +16,7 @@
 
 ## 稳定规范（引用，不重复）
 
+- 开始一个需求（启动手册）：`docs/ack/kit/core/kickoff.md`
 - 角色 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md`
 - 模型档位与升级规则：`docs/ack/kit/core/model-routing.md`
 - 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md`

kits/ack/templates/project.template.md

@@ -21,6 +21,7 @@
 
 ## 稳定规范（不在此重复，直接引用）
 
+- 开始一个需求（启动手册）：`docs/ack/kit/core/kickoff.md`
 - 角色模型 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md`
 - 模型档位与升级规则：`docs/ack/kit/core/model-routing.md`
 - 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md`