/handoff

name: handoff
description: "Prepare reliable, role-typed cross-session handoffs for any project. Use when the user runs /handoff, asks to create, update, improve, or use a handoff / transition file / context bridge; pass work to a new Claude Code session, thread, agent, owner, or executor; spin up parallel sessions on a project; close or archive a source session before compaction; preserve project context; generate a kickoff prompt; or evaluate a new session's Verification Report. Always perform a pre-handoff documentation/state audit, reconcile stale docs with facts when safe, ground-verify commands, preserve dirty-tree boundaries, make the next session read and verify context, and when it reports back, judge whether it understood the context accurately rather than assigning its next work."
allowed-tools: Read Write Edit Glob Grep Bash
disable-model-invocation: false

Skill: Handoff

Core Rule

Create a handoff only after the project state and documentation have been reconciled. A handoff is not a chat summary; it is the final transfer artifact after audit, consistency cleanup, verification, and scoped git handling. The handoff is the control surface between the owner and a session.

Do not trust memory files, old handoffs, README/status files, SNAPSHOT, or prior chat as current truth without checking the workspace.

When the source session receives a Verification Report from the target session, its job is acceptance, not command-and-control. Confirm whether the target session accurately understood the handoff, boundaries and readiness state so the source session can be safely archived. Do not turn that response into a new task brief unless the user explicitly asks for new instructions.

Control Model — what gets a handoff, and why

OWNER     decides which modules = sessions exist; reviews each session's output      (coarse control)
SESSION   owns its module/role; decides HOW, including spawning subagents             (fine control — the agent)
SUBAGENT  ephemeral legwork inside a session; invisible to the owner; gets NO handoff (the session's own call)

boundary owner↔session    = the module CONTRACT  (enforced via handoff → report → consensus → output review)
boundary session↔subagent = the session's internal task spec (Agent tool: researcher / implementer / reviewer)

• **A session is the owner's unit of control** — launchable, observable, correctable, reviewable. **Each module → its own session.**
• **A subagent is internal delegation** via the Agent tool — the session decides it; the owner does not see or steer it. **Subagents get NO handoff.**
• Therefore **handoffs are for SESSIONS only.** This skill produces session handoffs.
• Module=session control only holds when the module's **seam contracts are clean** — otherwise correcting one session ripples into others. Define seams before parallelizing.

Handoff TYPES — pick by what the new session will DO

`TYPE: orchestrator | executor | reviewer | owner | general`

The two primary types have opposite failure modes; a session onboarded to the wrong type fails in a characteristic way:

| | **Orchestrator** | **Executor** | |---|---|---| | Scope | global: roadmap, module map, all seams, all module states | ONE module (its folder-root) + its named contracts | | Focus | coordination + architecture | implementation | | Does | decompose work, define/maintain seam contracts, write executor handoffs, review their reports, integrate, sequence | build the module's pipeline/console/store/fixtures/reference; debug against its own metrics | | NEVER | implements module internals by hand; reads deep into one module to build | touches other modules; redefines contracts; edits the roadmap; climbs into global context | | May | use subagents (Agent tool) for legwork it owns end-to-end (stays in the loop) | use its own subagents internally | | Output | coordination artifacts: contracts, executor handoffs, roadmap/state updates, decisions | module code + its verification report + commits within its contract | | Mis-onboard failure | "grabs the work and starts implementing" — loses coordination altitude | "climbs into the whole project" — loses focus |

Other TYPE values, when neither fits:

• **reviewer** — audits/reviews a defined scope; reports findings; does not implement.
• **owner** — transfer of ownership/decision context to a human or lead session.
• **general** — continuation of the same role in a fresh session (e.g. pre-compaction archive); state the scope explicitly anyway.

Parallelizing a project typically means **one orchestrator handoff + N executor handoffs** (one per module). Slugs disambiguate.

Grounding Discipline — all handoffs (hard-won)

• **Ground claims in territory, not metafiles.** Verify each load-bearing fact (counts, file/store states, what's done) by running the command BEFORE writing it. Stale metafile claims make the new session repeat or break work.
• **Never pin a moving "last/current commit" hash** — it goes stale on your own next commit. Give a STABLE ref (the commit holding the key work) + "check `git log` for live HEAD".
• **Honest done-vs-pending.** Work finished THIS session is done — say so; never label it "to do" (or the reverse).
• **Include the verification commands** so the new session can re-confirm the facts itself.
• **Scope discipline.** Each handoff confines its session to its scope — a focused worker, not "everyone at every meeting."

Workflow

1. Establish The Target

• Identify the project root, current working directory, branch, owner intent,

and the role expected in the next session → that fixes the TYPE.

• If the target is a git worktree, inspect current status and recent history.
• Respect dirty-tree boundaries: never revert or stage unrelated user changes.
• If the user gives stop rules, ownership boundaries, or "do not commit/push"

instructions, obey them over this generic workflow.

2. Audit Documentation Before Handoff

Read the docs that define curren