🤝 relay — 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.

Modes

Every invocation resolves to exactly one mode. Load only the matched reference:

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 updateagents 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

0. Triage + approval gate (source: obra/superpowers, skills/brainstorming/SKILL.md): map the task to one path — spike (throwaway probe), bounded (fixed scope), or architectural (multi-session design) — announce it aloud, then ratchet one way only (spike → bounded → architectural; never downgrade). On every path, get explicit human approval before ANY code is written or dispatched; a dispatch prompt without that approval is a procedure failure.
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.
   • Interfaces (source: obra/superpowers, skills/writing-plans/SKILL.md): every file in Target Scope gets a consumes/produces line — what it reads, what it returns or changes. Unlisted coupling is out of scope.
   • No placeholders (same source): TBD, "appropriate handling", and "etc." fail the packet — every section carries exact paths, verbatim code, or a concrete command.
   • If Blocked: Escalation fallback.
   • Assumptions-first + spec template (source: addyosmani/agent-skills spec-driven-development): every packet opens with an assumptions block (each assumption evidence-backed or flagged for the human gate), then fills the 6-area spec template — Objective / Commands / Structure / Style / Testing / 3-tier Boundaries. Human gate per phase: SPECIFY → PLAN → TASKS → IMPLEMENT never advances on an unapproved phase.
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.
6. Close the loop (#51): when the dispatched task returns and you are authorized, perform the delivery action programmatically via the available tools — commit + PR, merge, or issue/checklist update — rather than only describing it. Update the ticket/checklist to the real resulting state so the loop is closed, not narrated. Only describe-and-defer when the action itself requires a human (approval, merge to protected branch, secrets); leave ONE explicit ready-to-run command for that step.

🧭 Route: multi-mode batching & config (#52)

Before dispatching, map the incoming task to the combination of existing modes/references — not a single one — that should act on it in parallel. Decide per sub-task which of relay's own modes (Resume/Dispatch/Ambient) plus which other skills' references each worker runs, and whether the outputs are independent (parallel) or ordered (sequential pipeline). Record the mapping in the packet's Target Scope so workers never re-derive it.

Optional auto-trigger config: where the runtime supports it, document a project-level config (e.g. .agents/relay-config.yaml) that maps trigger keywords → the resolved mode/reference combination, so the same choreography fires without re-deciding each time. Tool-independent — it's a contract, not a tool. Skip the config unless a project runs the same handoff pattern frequently.

🗺️ Decision map: multi-session handoff artifact

For work spanning sessions, attach a wayfinder map to the timestamped packet (source: mattpocock/skills, skills/wayfinder/SKILL.md via abubakar collection) — five lines, refreshed per session: Destination (one-line goal) · Notes (live context) · Decisions (made, not re-litigated) · Not-yet-specified (fog) · Out-of-scope (never touch). Fog-of-war graduation rule: ticket the sharp edges only (research / prototype / task, each marked HITL vs AFK), leave fog as fog — never ticket what is not yet specified. One ticket per session; refer to decisions by name.

🌊 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.

🧠 Muse Memory Dual-Scope Architecture Hooks

Handoff integrates with Muse Memory's dual-scope architecture, without ever touching .memory/** raw files directly — that path is owned exclusively by musememory:

1. Global User Truth: On session start or workspace entry, query global identity and user preferences from ~/.memory/USER.md via get_context(query=...).
2. Local Project Constraints: Local project constraints and active in-flight boundaries read and write to ./.memory/ and CURRENT.md (or .agents/context/current.md).
3. No Direct YAML Mutation: Never read, write, or modify internal .memory/** YAML files directly by hand. Always invoke the MCP tools (memory_capture, search, get_context) or sovereign CLI commands (memory capture, memory search).
4. On outbound handoff or full flush: Push durable decisions only (not the file dump) through memory_capture(type="decision"|"constraint"). Ephemeral state stays in HANDOFF.md; durable rules and decisions go to memory.
5. On workspace entry (ladder rung 2): Memory recall is a lookup, filtered strictly to the current directory boundary.
6. 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.
• Ticketing Fog: Never write a ticket against a Not-yet-specified map item — fog graduates to tickets, never starts as one.

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.
• Mode B dispatch announced its triage path (spike / bounded / architectural) and carried explicit human approval before any code.
• Outbound packet carries an Interfaces consumes/produces block covering every file in scope.
• Outbound packet opens with an assumptions block and fills the 6-area spec template; no phase advanced without human approval.
• Multi-session work attached a decision map; fog items carry no tickets.
• 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