handofflisted
Install: claude install-skill Xsxdot/handoff
<!--
职责:
- 教会「协调者」角色如何用 handoff CLI 驱动一个派发任务的完整生命周期。
不叫审核者:用户把审核者理解成 code review,协调者才是派发与盯任务的那一端。
- 固化那些一旦搞错就会卡住任务的硬约束:ID 形态、状态机前置条件、事件分诊、失败出口。
边界:
- 不讲 agentd 的部署与配置(config.yaml 各段、approver 审批链、env 注入)——见仓库 README。
- 不讲各 executor 的内部差异与协议实现——见 README「各 executor 须知」与 docs/superpowers/specs/。
- 不替协调者做审批判断:批不批、改不改由协调者(必要时升级给人)决定。
-->
# handoff:以协调者身份驱动派发任务
## 心智模型
handoff 把「写计划的人」和「干活的人」拆成两个进程:
- **agentd** 跑在 executor 所在机器上,持有**全部**状态——任务、事件、工单、executor 生命周期,落 SQLite。
- **你(协���者)**只是一个客户端。你不持有任何状态,随时可以崩溃、断网、换一台机器接管。
- 你和 agentd 之间只有一条通道:`handoff` CLI。
这条架构直接决定了三件事,后面所有纪律都是它的推论:
1. **你的会话不是权威**。「我记得这个任务已经批过了」不作数,`handoff show` 说了算。
2. **断网不丢事件**。事件在 agentd 侧持久化并带 cursor,`wait` 重连后从断点续拉。所以你没必要一直挂着。
3. **绕过 CLI 就会失配**。ssh 到执行机去杀 executor 进程、手删任务目录、直接进工作区改代码——这些 agentd 全都不知道,它记的运行态和真实存活性会当场对不上,任务卡成孤儿。
### 铁律:一切经 CLI
需要看 executor 在干什么,用 `handoff attach`(经 agentd 的 render 流,远程也不需要 ssh)。需要看代码,用 `handoff diff` / `fetch` / `run`。需要回收,用 `handoff done` / `stop`;归档后残留的 managed worktree 用 `handoff reclaim` 清;终态任务的 tmp/gocache 叶子和残留 managed 树用 `handoff gc`(默认预览,`--yes` 才删)。
**唯一例外**:任务已经彻底死了、CLI 三条路(`resume` / `continue` / `done`)全被拒,此时按任务目录 `proc.json` 里的 `handle.pid` 手工 kill shim 进程是兜底。但那是排障,不是日常。
## 任务 ID 必须是完整 UUID
所有接受 `<task>` 的子命令都是**精确匹配**,没有前缀补全。传 8 位短 id 一律 404「任务不存在」。
短 id(`id8`)只出现在 `--notify` 的通知文案里,不能当命令参数用。
拿完整 id 的办法:`dispatch` 的输出 JSON 里的 `.id`,或者 `handoff tasks | jq -r 'select(.name=="...") | .id'`。
## 状态机:先看状态,再敲命令
六个状态。**`continue` 和 `done`