Handoff

🤝 handoff — Bidirectional Handoff, Resumption & Ambient Continuity Engine

Aliases: agent-handoff | subagent-handoff | context-packet | resume | where-were-we

handoff provides context continuity across agent lifecycles in three modes:

1. Inbound Resumption: Resumes previous agent sessions with boundary-safe directory matching, leading with any unanswered open questions.
2. Outbound Dispatch: Generates lean, bounded context packets before dispatching subagents or stepping away.
3. Ambient Continuity (v2.1.0): Passively maintains a live state file and probes for it on every workspace entry, so work continues across conversations, agents, and runtimes — even after abrupt endings and even when no one asked for a handoff.

When to Use

Mode A: Inbound Session Resumption

• User asks: "where were we", "resume", "pick up where I left off", "what was I doing", or begins a session with no fresh prompt.
• Restoring state after an interruption or machine restart.

Mode B: Outbound Subagent Dispatch

• Before dispatching any subagent for backend, frontend, testing, or refactoring.
• Before spawning multi-agent teams or worker processes.
• Before stepping away from a long-running session (>30 minutes).
• Whenever a task prompt to another agent exceeds 3 sentences.

Mode C: Ambient Continuity (Default-On)

• Every workspace entry: probe for prior state before doing anything else.
• Every checkpoint: a milestone completes, a decision is made, a correction lands, a task is abandoned mid-flight.
• End of any working turn with work incomplete: session ending normally, crash imminent, or user walking away — no explicit handoff request required.
• A brand-new conversation opens in a working directory where prior work happened: the agent resumes context automatically instead of starting blind.

Quick Reference

Mode Comparison

Token Budgets (hard limits)

The State-Source Ladder (cold-start continuity)

On workspace entry, resolve prior state by climbing the ladder; stop at the first rung that yields state:

1. Live Handoff file — .agents/artifacts/HANDOFF.md exists → resume from it directly.
2. Memory recall — query the runtime's session-memory tool (e.g. memory_sessions / memory_recall), strictly filtered to this directory boundary.
3. Project context — .agents/context/current.md and .agents/context/index.md (maintained by updateagents conventions).
4. Git forensics — reconstruct from the repository itself (recipe in references/resumption-protocol.md); after reconstructing, write HANDOFF.md immediately so the next agent never digs again.
5. Cold start — declare honestly: No prior session history found for this project directory. Never invent history. Offer the ai-ready audit.

The Live Handoff File (.agents/artifacts/HANDOFF.md)

One fixed-name file, ≤30 lines, overwritten on every state change — the bridge from any session to any future conversation:

# HANDOFF — <ISO timestamp>
branch: <branch> | phase: <one-line state>

## Next Step
<Single atomic action: file + what to do>

## In-Flight
- <Unfinished item, if any>

## Ruled Out
- <Approach>: <why it failed — one line>

## Decisions
- <Durable choice made, not to be re-litigated>

## Verify
`<exact command>`

## Open Questions
- <Unanswered user question, if any — leads resumption>

Omit empty sections. Full schema and write-trigger contract: references/ambient-handoff.md.

Procedures

🔄 Mode A: Inbound Session Resumption Procedure

1. Resolve Workspace Directory: Normalize the current working directory. If a directory override argument is provided, resolve to an absolute path.
2. Retrieve Prior Session (via the State-Source Ladder above): Query session history (memory tools, .agents/artifacts/, .agents/context/current.md), enforcing directory-boundary isolation:

   // Prohibit raw prefix matching to prevent sibling repo bleed:
   session.cwd === projectPath || session.cwd.startsWith(projectPath + path.sep)
   

3. Surface Unanswered Questions FIRST: If the prior session ended on an unanswered user question (?), highlight it at the very top of your response. Do not guess the answer.
4. Format Resumption Summary (≤5 lines before the first productive action):

   Resuming [session_id] "[session_title]".
   
   ❓ Open Question from Last Session:
   [Unanswered question, if present]
   
   📌 State: [key decisions & modified files · active roadblocks]
   
   👉 Immediate Next Step:
   [Single concrete atomic action]
   

📦 Mode B: Outbound Subagent Dispatch Procedure

1. Extract Operational Facts:
   • Objective: Exact 1-sentence goal starting with an imperative verb.
   • Decisions Made: Irreversible choices not to be re-litigated.
   • Ruled-Out Paths: Approaches tried and eliminated with failure reasons.
   • Target Scope: Exact files to touch.
   • Hard Constraints: Forbidden files, libraries, or credentials (MUST NOT).
   • Deterministic Verification: Exact test or build command.
   • If Blocked: Escalation fallback.
2. Write Handoff Packet to .agents/artifacts/handoff-<timestamp>.md (structure in README and worked example in examples/sample-handoff.md).
3. Lease hand-off to workers (shared checkouts): if the packet's Target Scope includes git mutations (branch switches, stashes, commits to shared surfaces), embed the worktree-lease instruction in the dispatch prompt — the worker probes .agents/artifacts/WORKTREE-LEASE.md before its first git mutation and inherits or acquires per the lease protocol (coupling-router Step 0). Never dispatch two workers whose scopes overlap on one checkout.
4. Echo & Dispatch: Embed the packet directly into the subagent invocation prompt.
5. Refresh the live file: update HANDOFF.md to point at the dispatched task so an interrupting conversation still lands correctly.

🌊 Mode C: Ambient Continuity Procedure

Write side (passive, silent — no prose, no user interruption):

Read side:

• Workspace entry always probes for HANDOFF.md before any other work. If present and fresh (same branch, plausible timestamp), emit the ≤5-line resumption block and continue — even though nobody said "resume".
• If the user's first message is a fresh instruction, treat the resumption block as silent context: proceed with the instruction, informed by state.
• Lease check on entry (shared checkouts): if .agents/artifacts/WORKTREE-LEASE.md exists with a fresh heartbeat, another session is live — the ≤5-line resumption block notes this, and the entry session takes a separate worktree or stays read-only until the lease releases (decision rules: coupling-router Step 0).

Anti-noise guardrails:

• One file, overwritten — never append, never accumulate.
• Refresh only on real state change (checkpoint, decision, reversal); not on every tool call.
• Silent writes: ambient handoff never narrates itself.

🧠 Memory System Hooks

Handoff integrates with whatever memory system the runtime provides (e.g. musememory's write/recall tools), without ever touching .memory/** directly — that path is owned exclusively by musememory:

1. On outbound handoff or full flush: push durable decisions only (not the file dump) through the runtime's memory-write tool call when one exists. Ephemeral state stays in HANDOFF.md; durable rules and decisions go to memory.
2. On workspace entry (ladder rung 2): memory recall is a lookup, filtered strictly to the current directory boundary.
3. When no memory tool exists: durable findings are reported in the output and recorded in .agents/context/ via updateagents conventions — never written to .memory/ by hand.

Neighboring Skill Boundaries

• context-anchor → manual mid-session drift stop within one conversation. Ambient handoff → session-boundary continuity across conversations; the live file doubles as a rolling anchor.
• coupling-router → owns the shared-worktree lease. Handoff routes to it: dispatches embed the lease instruction (Mode B step 3) and workspace entry respects an active lease (Mode C read side). A session that died holding the lease is exactly the case handoff's ladder reconstructs — check its notes for preserved WIP.
• dead-letter → failure-path escape hatch. A blocked task lands in both: HANDOFF.md Next Step (continuity) + dead-letter packet (diagnosis).
• updateagents → owns durable .agents/context/ truth; ambient handoff reads it (ladder rung 3) and routes durable changes to it rather than editing governed context directly.

Pitfalls

• Raw Prefix Collisions: Never match session directories using raw startsWith(path); sibling directories like /project-staging will falsely match /project.
• Hiding Open Questions: Never bury an unanswered user question under a wall of status logs.
• Compound Objectives: Never combine multiple decoupled tasks into one outbound packet.
• Omitted Ruled-Out Paths: Subagents re-explore failed attempts unless explicitly forbidden.
• Journal Bloat: HANDOFF.md is a pointer, not a diary. If it exceeds ~30 lines it has become a session log — prune or demote detail to a timestamped packet.
• Ladder Skipping: Do not run deep analysis before the entry probe; the cheapest rung that yields state wins.
• Silent Cold Starts: Never invent prior context when the ladder returns nothing — say "cold start" and move.

Verification

• Inbound resumption surfaces any unanswered question before status text.
• Session matching strictly validates directory boundaries.
• Outbound handoff packet is written to .agents/artifacts/handoff-<timestamp>.md.
• Workspace entry performed the HANDOFF.md probe before other work.
• HANDOFF.md is ≤30 lines, overwritten (not appended), and carries an atomic Next Step.
• Resumption output stayed within the ≤5-line budget before the first productive action.
• Memory integration used the runtime's tool API (or reported the durable fact) — .memory/** never touched by hand.
• All 7 outbound packet sections are populated with zero placeholder text.
• In shared checkouts, dispatched workers carry the worktree-lease instruction, and entry respected any active lease before mutating.

References

• 🔄 Inbound Resumption & Boundary Protection Protocol
• 🌊 Ambient Continuity & Live Handoff File Contract
• 📄 Sample Handoff Packet
• 📄 Sample Live Handoff File