--- name: handoff-protocol description: >- How to hand off a task mid-flight — context summary, what's done, what's pending, where to find work-in-progress, and when to escalate instead. Use this skill when a worker needs to pass an unfinished task to a peer or back to the team lead — auto-compact pressure, scope shift, blocker outside the worker's tool set, end-of-shift, or running into the spawn-time context budget. Also load it when receiving a handoff so you know what shape to expect. scope: dev-team loaded_by_default: [] created_at: "2026-05-10" created_by: operator --- # Handoff Protocol A handoff transfers an in-flight task from one agent to another (peer worker, team lead, or a freshly-spawned replacement) without losing the work-in-progress context. Done well, the receiving agent picks up in one message. Done poorly, they re-investigate everything and the work effectively restarts. This skill is loaded by both senders and receivers so the message shape is canonical. --- ## 1. When to hand off vs. escalate vs. shut down | Situation | Action | |-----------|--------| | Approaching auto-compact threshold (>80% context) and the task is non-trivial | **Hand off** to a fresh worker — your context window is the bottleneck, not your knowledge | | Hit a blocker outside your tool set (e.g. need a Rust expert, you only know TS) | **Hand off** to a peer with the right tool affinities | | Task is complete | **Shut down** (`shutdown_response: approve`), don't hand off — there's nothing to transfer | | Hit a real judgment call the operator must make | **Escalate** via `plan_approval_request`, don't hand off — the next worker would face the same question | | Task scope was wrong / impossible / overlaps another worker | **Escalate** to lead, don't hand off — the plan needs revision | | End of shift / pane being closed | **Hand off** to lead with full state so they can re-dispatch | The cheapest handoff is the one you didn't need to do. Before handing off, ask: can I finish this in the next 5 tool calls? If yes, finish it. --- ## 2. The handoff message — canonical format Send via `SendMessage` to the next agent (peer name, or `team-lead` if the lead will re-dispatch). The message body is plain text with these labeled sections, in this order: ``` HANDOFF — GOAL STATUS DONE - - PENDING - - WORK-IN-PROGRESS LOCATIONS - Branch: - Worktree: - Uncommitted files: - Scratch notes: KEY DECISIONS MADE - - OPEN QUESTIONS - - CONSTRAINTS (do not touch) - - NEXT STEP ``` Required sections: `GOAL`, `STATUS`, `DONE`, `PENDING`, `WORK-IN-PROGRESS LOCATIONS`, `NEXT STEP`. The others are optional but recommended. If `DONE` is empty, you probably should not be handing off — you have not de-risked the task enough for someone else to pick it up. --- ## 3. Worktree / branch hygiene before handing off Before sending the handoff message, the outgoing worker MUST: 1. **Commit all in-progress work.** Even messy. The receiver needs to see your diff, not reconstruct it. Use a `wip(): handoff snapshot` commit message. Do NOT amend; create a new commit. 2. **Push the branch.** The receiver may be running in a different worktree. 3. **Record the SHA** in the handoff message under `WORK-IN-PROGRESS LOCATIONS`. 4. **Leave a `RESUME.md` at the repo root** if there are more than 3 PENDING items. Brief — same shape as the handoff message — so the next agent can re-read it if their context fills up mid-task. If you cannot commit (e.g. hook failure you couldn't fix), `git stash` with a message like `handoff-2026-05-13-001` and reference the stash in the handoff. Do not lose work to a force-push or reset. --- ## 4. Receiver-side checklist When you receive a handoff message: 1. **Acknowledge first.** Reply with `SendMessage` to confirm receipt — the sender's `shutdown_request` may be queued behind your ack. 2. **Read `RESUME.md` if it exists** before reading the worktree. It's the compressed form. 3. **Check out the branch** and inspect the latest commit. Do not start a fresh branch. 4. **Run the test suite once.** Confirms the baseline the handoff describes. 5. **Re-read the original task description** (lead's prompt to the original worker). Don't trust the handoff's `GOAL` summary alone — it may have drifted. 6. **Take the NEXT STEP.** If it doesn't make sense after step 5, ask the lead before doing anything else. --- ## 5. Lead-side responsibilities When a lead receives a handoff (because the original worker is done with their pane but the task isn't finished): 1. Verify the handoff message has all required sections. If not, ask the outgoing worker to re-send before they shut down. 2. Decide: re-dispatch to a fresh worker, or absorb into a running peer's scope, or queue. 3. The new worker's prompt MUST include the full handoff message verbatim under a `## Handoff context` heading, plus the original task description. Do not paraphrase — the receiver may catch nuances the lead missed. 4. Update `ORCHESTRATION.md` task ledger: original worker's task moves to `handed-off`; new task created for receiver with a `handoff_from: ` metadata field. --- ## 6. Escalation thresholds A handoff becomes an escalation when one of these is true: - The next worker would face the same blocker you faced. → Surface to lead. - The PENDING list is longer than the DONE list AND you haven't been working long. → Lead needs to re-decompose; not a handoff problem. - You discover the task overlaps another worker's scope. → Lead arbitrates. - The OPEN QUESTIONS list includes anything that requires an operator decision. → `plan_approval_request` to lead, who forwards. Handoffs are for "I can't finish this but someone else can." Escalations are for "this can't be finished as scoped." Don't dress an escalation up as a handoff — it wastes a pane. --- ## 7. Common pitfalls - **Handoff without committing.** The receiver inherits a clean tree and no idea what you actually wrote. Always commit first. - **`NEXT STEP` too vague.** "Continue the work" is not a next step. "Run `bun test components/master/__tests__/foo.test.ts` and fix the two failing cases at lines 47 and 89" is. - **Skipping `CONSTRAINTS`.** The receiver doesn't know which sibling workers are running. Always list scopes they must not touch. - **Handing off because you're tired of the task.** That's not a handoff reason. Either finish or escalate. --- ## 8. Related skills - `subctl-team-protocol` — the message-passing primitives this skill builds on - `spec-driven-dev` — the receiver's first job is to re-read the spec - `orchestrator-mode` — lead-side dispatch + verification rules ## References - Operator auto-memory `feedback_shutdown_idle_workers.md` — context for why shutdown is preferred over leaving panes parked - `ORCHESTRATION.md` template in `components/skills/orchestrator-mode/SKILL.md`