dylanpulver handoff
A core meta-workflow: plan in one chat → handoff → execute in a fresh chat. Without a standard, the same handoff-request template gets retyped over and over and orphaned HANDOFF-*.md files litter repo roots. This standardizes both directions.
Write mode (/handoff <topic> or "make a handoff")
- Write to
.claude/handoffs/<topic>-YYYY-MM-DD.md(create dir; never the repo root). - Sections, in order — self-contained enough that a cold session needs nothing else:
- Goal — what we're trying to achieve, in one paragraph
- Architecture / how it works — only what the executor must know, with real file paths
- Decisions made (and why) — so they don't get re-litigated
- Current status — done / in-flight / not started
- Exact next steps — numbered, concrete, in order
- Open questions — decisions the executor should surface, not make
- Artifacts — files, PRs, URLs, commands that matter
- Gotchas — anything that already bit us once
- Append one line to
.claude/handoffs/INDEX.md: date, topic, path, status: open. - Tell the user the one-liner to start the new chat with:
read .claude/handoffs/<file> and continue.
Consume mode (session opens with a handoff path, or consume <path>)
- Read it fully; confirm understanding in 3 lines (goal, next step, first action) — then start.
- Mark it consumed in INDEX.md with today's date and the new session's purpose.
- Do not maintain the handoff during execution — it's a launch document, not a status file
(standing instruction: "handoff was a 1-time thing"). Ongoing state belongs in
.claude/state.md(whereami skill).
Hygiene
If you notice stale HANDOFF-*.md files in a repo root, offer to move them into .claude/handoffs/
and index them — once.