/handoff

name: handoff
description: 'Use when work reaches a session boundary or the user asks to hand off, delegate, or get a clipboard-ready prompt. Mode brief packages continuity; mode prompt builds the delegation prompt.'

Session continuity and handoff

Contract

| Field | Bound contract | |---|---| | Trigger | Substantive work starts, reaches a significant boundary, resumes after interruption, completes, or must move to another session, agent, harness, directory, repository, or person. An explicit handoff request selects the mode. | | Authority | Reversible local: mode brief writes only ignored repository-local continuity files and one brief under `.handoff/handoffs/` or stdout; mode prompt writes only the assembled prompt text and the clipboard. Rollback is version control or undo. No remote mutation. | | Side effect | Continuity files under `.handoff/continuity/`, portable briefs under `.handoff/handoffs/`, or clipboard text. No receiver launch, data-at-rest changes outside these artifacts, bulk mutation, or irreversible effects. | | Done | Continuity status (`fresh`, `resumed`, `interrupted`, or `completed`) with the death-point path. On explicit handoff: mode brief, one compliant brief path or stdout result; mode prompt, a path-free prompt on the clipboard or printed with a stated unavailability. |

Inputs

• Mode (required on explicit handoff): `brief` for a session continuity brief file or stdout, `prompt` for a clipboard-ready, path-free delegation prompt.
• Current repository identity, session handle, goal, scope, active files, and current time.
• Current tasks, decisions with rationale, blockers, evidence, and next action.
• Existing continuity artifacts, when present.
• Mode `brief`: optional source handle, destination path, and project exclude list.
• Mode `prompt`: the task the user names or clearly implies, plus optional repo or product identity, issue/PR/branch names or URLs, likely modules, constraints, known symptoms, and desired output shape, inferred from nearby context when the user gives only a short label.

Use `.handoff/continuity/` for `notes.md`, `graph.md`, and `death-point.md`. Use `.handoff/handoffs/` for portable briefs. Before the first write, prove `.handoff/` is ignored. If it is not, add the repository-local exclusion and prove it again. Do not stage these files.

Procedure

1. **Choose resume or fresh.** Follow [resume.md](references/resume.md). Resume only from the complete, readable, unfinished continuity set whose recorded repository identity matches the current repository. Start fresh when it is absent, completed, corrupt, stale, incomplete, or belongs to another project. A minimal emergency death point starts a fresh record with its available context. Preserve unusable files and report why they were rejected. Done when: the continuity mode is selected and the source is ready for resume or fresh initialization.

2. **Initialize continuity state.** In fresh mode, write `death-point.md` first with the available goal, repository identity, session handle, timestamp, status `active`, and next action `initialize continuity state`. Flush that minimal death point before creating `notes.md` and `graph.md`. Then write the goal, scope, repository identity, session handle, and initial rationale to `notes.md`; create a directed graph of task, decision, and blocker nodes with dependency, sequence, and resolution edges; and replace the death point with the last completed action, next action, blockers, timestamp, and status `active`. In resume mode, append a timestamped resumption record, mark the prior death-point node `resumed`, and reconcile current facts without rewriting prior decisions or rationale. Done when: the continuity set is consistent with current facts and the death point is up to date.

3. **Maintain one live record.** At each decision, discovery that changes the plan, task-state transition, blocker change, phase boundary, interruption risk, or scope change, update the rationale notes, graph, and death point before continuing. Record the changed fact and why it matters; omit tool chatter and intermediate noise. Flush all three artifacts after the update. Done when: the changed fact is recorded and the artifacts are flushed.

4. **Mark the ending.** On interruption or ordinary session exit, set the death point to `interrupted` with the last completed action, exact next action, active blockers, and timestamp. On goal completion, append the achieved result and residual work to the notes, resolve or classify every open graph node, and set the death point to `completed`. A later session always starts fresh after a `completed` marker. Done when: the session is correctly classified and the death point is flushed.

5. **Package only on explicit handoff.** Resolve the requested source by exact handle when supplied; otherwise use the current live state. Reject ambiguity and wrong-project matches. Before reading source content into a package, apply the exclude list to the canonical project identity and every candidate path. Refuse the package if any source is excluded; a stale index does not override the current exclude list. Then select the mode: `brief` packages a session continuity brief; `prompt` builds a path-free delegation prompt. Done when: the source is resolved, excluded items are refused, and the mode is selected.

6. **Mode brief: print the source receipt.** Show session or harness kind, canonical project identity, short session handle, source timestamp, and computed age. Treat future or invalid timestamps as unknown age. For work older than seven days, print a warning with its age before continuing. If policy withholds newer matching work, disclose that this is the newest visible source. Done when: the receipt is printed, age warnings are shown, and any visibility policy is disclosed.

7. **Mode brief: build one UTF-8 brief of at most 6,144 bytes.** Include typed sections for source receipt, goal and scope, active files, task/decisio