handoff

name

handoff

description

Maintain `handoff.md` at the project meta-repo root ({{MAIN_REPO}}) as the single, curated, never-stale ROLLING MEMORY of the whole project — current development status AND every durable learned truth — so any brand-new agent with zero foreknowledge can fully take over. This is an ORCHESTRATOR-ONLY duty. Use it: (1) the moment a context compaction/summary/handoff is imminent — flush the live context window into handoff.md FIRST; (2) after any milestone, merge, decision, architecture change, or newly-learned gotcha that changes durable state; (3) at session start, to READ handoff.md before acting; (4) whenever asked to update/regenerate/fix the handoff. Core rule: ACCRETE + CURATE, never blind-overwrite — preserve durable truths, supersede only what is truly stale.

Handoff skill — curate handoff.md as the project's rolling memory

Origin-project note: extracted from a real multi-repo project (brand jerb). The specific repo/path names below (the {{MAIN_REPO}} meta-repo root, the jerb/backend/worker/web/harness/ MCP-server component list) are the concrete example from that origin project — keep the mechanics (accrete-not-overwrite, required sections, recovery-from-git), swap in your own project's shape.

{{MAIN_REPO}}/handoff.md is the defacto rolling memory of the entire project. It is the one artifact that lets a fresh agent (no chat history, no context) resume development completely. Treat it as a living document you continuously curate — not a one-off dump.

When to update (triggers)

• Compaction imminent (context is long / a summary is about to happen / user says "compact", "handoff", "update handoff") → update handoff.md FIRST, harvesting everything still-relevant from the live context window before it is lost.
• After milestones: a PR merged, an epic completed, a decision made, a bug's root cause learned, an architecture/env change, a new gotcha discovered, a subagent's important findings.
• On session start / after a crash: READ handoff.md first; then reconcile it against git status, open PRs/issues, and running processes before acting.
• On request: any "regenerate / fix / update the handoff".

The prime rule: ACCRETE + CURATE, do not blind-overwrite

handoff.md accumulates durable truth over the whole project. When updating:

1. READ the current handoff.md first (and, if it was recently overwritten, recover the prior version from git: git -C {{MAIN_REPO}} show <rev>:handoff.md). Never discard durable content you did not consciously decide is stale.
2. Merge, don't replace: keep every still-true durable fact; update the moving parts; delete only what is genuinely obsolete (and prefer moving obsolete-but-historical items to a short "superseded" note over deleting the lesson).
3. Curate for a stranger: write so an agent with NO foreknowledge can take over. Spell out repo layout, how to run things, secrets locations, and the why behind non-obvious decisions.
4. Keep it tight but complete: durable truths + current status. Don't let it bloat with dead detail, but never drop a hard-won lesson or a load-bearing fact.

Required contents (a fresh agent must be able to fully take over)

Keep these sections present and current:

1. READ-FIRST / crash recovery — what's in flight right now; if services/subagents died, exactly how to restart the stack (commands + env) and what to re-dispatch.
2. What the project IS — the product, the repos + their branches/roles, and the high-level architecture (example from the origin project: backend API + worker, web app, a CLI/agent harness, an MCP server, transactional email, SQLite/Postgres). Enough that a stranger understands the system.
3. Active goal(s) — the current Stop-hook/goal verbatim intent + acceptance criteria.
4. Current status — what's built/merged vs in-progress vs blocked; the epic map with per-child status; the migration head; what's proven vs pending.
5. Learned truths / load-bearing gotchas — the durable lessons that cost real time if forgotten (migration serialization, test-pinning, ff-locals, forward-slash worktree paths, fix-breaks-existing- tests, harness-main sync, merge-guard pitfalls, etc.). NEVER drop these.
6. Operating model — orchestrator vs executor roles, issue flags, git auth, commit trailer, merge style, secrets locations ({{SECRETS_DIR}}, never commit).
7. Env / how to run — how to start backend/worker/frontend + the exact env vars/keys; seeded users; feature flags (example from the origin project: JERB_AUTO_SUBMIT_ENABLED).
8. In-flight + ordered next steps — including any crashed/lost work to recover (branch names).

How to update from the context window before compaction

• Scan the live context for: merges/decisions/root-causes since the last handoff, any subagent's reported findings (extract from their transcript at ~/.claude/projects/<encoded-project-path>/<session>/subagents/agent-<id>.jsonl — Claude Code encodes the project's absolute path into that directory name — if their .output is empty (the harness .output can truncate on crash)), the current running-process/stack state, and the exact next action.
• Fold those into the relevant sections; refresh moving numbers (migration head, open PRs, epic child status); re-verify "gotchas" still apply and add any new one.

Persistence (the handoff must survive)

• handoff.md lives at the project meta-repo root and is committed + pushed to origin ({{GITHUB_OWNER}}/{{MAIN_REPO}}). Commit with the standard trailer and push after each meaningful update — do not rely on autosave alone (it has silently failed). In the origin project, session transcripts were separately backed up to a dedicated repo (see the project's own CLAUDE.md for that convention if you adopt it).

Guardrails

• Orchestrator-only; executors do their one issue and do not touch handoff.md.
• Secrets: never write real keys/tokens into handoff.md — reference the file in {{SECRETS_DIR}}.
• One canonical handoff.md — supersede in place; do not fork copies.