Handoff

Handoff — checkpoint the session into context.md

Your job: distill everything a brand-new agent would need to continue this work, and write it as a new dated entry at the TOP of context.md → §0 Current status (most recent first). The next agent reads context.md first (it's @-imported by CLAUDE.md), so this is the durable handoff channel — not your chat history, which is gone the moment the session ends.

Write for someone with zero context. If a fact lives only in your head right now, it must end up in the entry.

1. Gather the state (don't skip — read, don't guess)

Run these and read the output before writing:

git status --short            # uncommitted / untracked work
git log --oneline -8          # what landed this session
git branch --show-current     # are we off main?
git stash list                # anything parked?

Then assemble, from this session:

• What changed & why — the work done and the reasoning/decision behind it (the "why" is the part that's impossible to reconstruct from a diff).
• State of the work — committed+pushed? committed-not-pushed? uncommitted in the working tree? mid-refactor with the build red? Say exactly which.
• Where it stopped — if anything is half-done, name the file + the next edit.
• Next steps — the ordered TODO the fresh agent should start on.
• Open questions / blocked on the human — decisions awaiting the user, with the options on the table.
• New gotchas — traps you hit that aren't obvious from the code.
• Verification status — what you actually tested (build/lint/runtime/live) vs. what you only assumed. Be honest; an untested claim mislabeled as done is worse than no claim.

2. Write the entry

Prepend a new bullet as the first - item in §0 — directly after the line ending …these surfaces now exist: and above the current top bullet.

Match the existing house style exactly:

• Bold lead-in summarizing the change, then (newest, YYYY-MM-DD) using today's absolute date (convert any relative date; check the environment's current date — don't hardcode).
• Tight prose. Backtick file paths, ops, and identifiers.
• End with the relevant tags when they apply:
  • Touched: — comma-separated files you changed.
  • Next: — the ordered next steps.
  • ⚠️ — any new gotcha or "blocked on the human" note.
  • Supersedes — if this overrides something in §1–§7, say so (those sections aren't always updated in-place).

Then fix the (newest) marker: remove or downgrade it on the previous top entry so only one bullet is tagged newest.

Template:

- **<one-line summary of the change>** (newest, YYYY-MM-DD). <2–5 sentences:
  what changed, why, and the state of it (pushed / uncommitted / WIP-build-red).>
  Touched: `path/a.ts`, `path/b.tsx`. Next: <ordered steps>. ⚠️ <gotcha or
  what's blocked on the human, if any>.

3. Compact context.md (always check, act on thresholds)

context.md is a status board, not an archive — and it's re-read at every session start, so its size is a recurring cost. After writing the new entry, measure it:

wc -c context.md                 # bytes
grep -c '^- \*\*' context.md     # rough §0 entry count

If §0 has more than 8 entries, or the file exceeds 25 KB, compact now (don't defer it to a "later" that never comes):

• Keep the newest 3 entries verbatim.
• For each older entry that is fully landed or superseded:
  1. Move any still-true durable fact (architecture, gotcha, decision + its "why") into the right stable section (§1+).
  2. Then collapse the entry to a single line — or delete it outright if it carries nothing not already recorded elsewhere.
• Never drop: unresolved ⚠️ / blocked-on-human notes, claims still marked assumed (unverified), or the only record of why a decision was made.

Report the result in the end-of-handoff summary: context.md: 11 entries / 34 KB → 5 entries / 18 KB (or "no compaction needed").

4. Persist it

• Never write secrets, tokens, API keys, or .env values into the doc — secrets belong in the project's own secret store, not here.
• The handoff is only useful if it's committed (a fresh clone / new agent reads the committed file). Commit and push, ending the message with the Co-Authored-By trailer. Where to push: if the project auto-deploys its main branch (Vercel git integration — the default in this workflow), push main only when the session's work is verified and fit to be live; otherwise push a work-in-progress branch so the handoff is backed up without publishing unfinished work. Commit the context.md update plus any genuinely-finished work; for deliberately in-progress code, do not force a commit — instead make sure the entry describes its exact state so it can be resumed.
• After writing, show the user the new §0 entry and a one-line summary of what you committed/pushed vs. what's left in the working tree.