Handoff

Handoff

Compact this conversation into a document that carries everything the next session needs to continue it. Judge the result by one question: reading only this file and the artifacts it links, could a fresh agent pick the work up without asking what was already agreed?

Capture what lives only in the chat — the open tasks, the user's exact requirements, the alternatives already rejected, the state of the working tree. Everything already written down elsewhere gets a link, never a retelling.

Where to save

Write one file to .yoke/handoff/<YYYYMMDD-HHMMSS>-<slug>.md.

Resolve the path against the root checkout, never the current worktree — /do works inside a worktree and /merge deletes it, taking any uncommitted file with it:

dirname "$(git rev-parse --path-format=absolute --git-common-dir)"

Outside a git repository the root is the working directory; say so in the final message. Take the timestamp from date '+%Y%m%d-%H%M%S' — never invent it.

Derive <slug> from the first source that answers: the active .yoke/ai/<slug>/ task, the current branch name, or a kebab-case summary of the conversation.

Create .yoke/handoff/ when it is missing. When .yoke/ itself was missing, suggest /yoke:bootstrap once the file is written.

What to write

Open with the goal — what this conversation set out to do — then cover:

• Tasks — every task raised, each marked done, in progress, or pending.
• Requirements — the user's constraints and prohibitions, quoted verbatim. A paraphrase loses exactly the wording the next agent then violates.
• State — what is done, what is left, and the next step.
• Decisions — what was settled and why.
• Rejected — the alternatives considered and the reason each was dropped, so nobody relitigates them.
• Git — branch, worktree, uncommitted files, open PR.
• Gotchas — blockers, traps, and anything that cost time to learn.
• Artifacts — paths and URLs. Yoke artifacts live under .yoke/: .yoke/ai/<slug>/, .yoke/adr/, .yoke/context.md, .yoke/journal.md.
• Suggested skills — which yoke skills the next agent should invoke, given where the work sits in the flow (unstarted → /yoke:do; implemented but unreviewed → /yoke:review; PR approved → /yoke:merge).

When .yoke/handoff/ already holds a handoff of this same conversation, link it as a prior handoff instead of restating it.

Never duplicate a PRD, plan, ADR, issue, commit, or diff — link it.

Redact secrets and PII — API keys, passwords, tokens — as [REDACTED]. The file is committed with the rest of .yoke/ unless the project ignores it, so a leaked secret lands in git history.

Treat $ARGUMENTS as the focus of the next session and tailor the document to it.

Finish by printing the absolute path, so the user can hand it to the next agent.

Rules

• Save under .yoke/handoff/ in the root checkout — never in a worktree, never outside .yoke/.
• Be exhaustive about what exists only in the conversation; link everything else.
• Quote the user's requirements verbatim.
• Redact secrets and PII.
• Delete nothing: handoffs accumulate.
• Language: match the conversation language, or follow the project-level definition in CLAUDE.md / AGENTS.md.