Handoff

Handoff

Handoff turns the current state of work into a portable markdown brief that another session, agent, or collaborator can pick up quickly.

The goal is not "summarize everything." The goal is to capture only the information that would otherwise be expensive to rediscover.

When to Use

• You are ending a session but the work is not actually finished
• Another agent, model, or machine will continue the task
• The conversation contains decisions that are not yet reflected in committed files
• A reviewer or implementer needs a compact state-of-play document

When NOT to Use

Workflow

1. Clarify what the next session is for

Start with one sentence:

• what the next session should accomplish
• what is already done
• what remains uncertain

If the user gave a follow-up goal, tailor the handoff around that goal instead of the whole conversation.

2. Pick a portable file path

Prefer a temporary markdown file outside the repo unless the user explicitly wants a committed file.

Examples:

# PowerShell
$path = Join-Path $env:TEMP ("handoff-" + [System.Guid]::NewGuid().ToString("N") + ".md")

# POSIX shell
path="$(mktemp -t handoff-XXXXXX.md)"

If a path already exists, read it before overwriting.

3. Reference artifacts instead of duplicating them

Do not restate content that already lives in:

• a plan
• an issue
• a PR
• an ADR
• a committed file
• a benchmark result

Link to those artifacts by path, URL, or commit hash and explain only why they matter.

3-A. Redact sensitive data before saving

Before writing the handoff document, actively redact sensitive data in the captured context:

• API keys, tokens, or credentials -> [REDACTED]
• Passwords or secrets -> [REDACTED]
• PII in sensitive context -> [REDACTED]
• Internal-only URLs or endpoints -> [INTERNAL URL]

Do not simply omit the fact that something existed. Replace the value with a placeholder so the next session knows there was sensitive context without seeing the secret itself.

4. Capture only the load-bearing context

Good handoffs usually include:

• current objective
• work completed
• open questions
• key files and why they matter
• relevant commands, outputs, or result files
• concrete next step

Skip long narrative unless it changes the next decision.

4-A. Transfer tasks via file, not paste

When dispatching a task to a sub-agent in the same session or machine, write the task brief to a file and pass the file path — do not paste the full task text inline.

Why:

• Inlined task text inflates context immediately, even when the agent has not started
• File-based transfer lets multiple agents share the same brief without duplicating tokens
• The brief becomes inspectable and auditable

For cross-machine or cross-session handoff, store the brief in a committed repo location or a shared path both machines can access — not in $env:TEMP. See Section 2 for picking a portable file path.

Pattern (same-session sub-agent dispatch):

# Orchestrator writes the brief
$brief = "$env:TEMP\task-brief-$(New-Guid).md"
Set-Content $brief @"
## Objective
...

## Input files
...

## Expected output
...
"@

# Pass only the file path to the sub-agent
task(agent_type: "general-purpose",
     prompt: "Read the task brief at $brief and complete it.")

Keep the brief short (objective, inputs, expected outputs, constraints). Do not embed code diffs, full file contents, or conversation history into the brief file. Reference those by path instead.

4-B. Make delegated work resumable

If the handoff is crossing sessions, machines, or agents, capture the minimum task ledger needed to resume without guesswork:

• current owner and next owner
• branch or worktree path when one exists
• current status (ready, blocked, awaiting-review, needs-verification)
• exact resume trigger
• verifier or synthesizer step if the work fans out

For parallel work, list each active lane separately instead of flattening it into one vague status paragraph.

5. Recommend the next skill or workflow

If another skill would help the next session, name it explicitly and explain why.

Examples:

• implementation-review for "compare this delivered diff against the original ask"
• grill-me for "the plan still has unresolved assumptions"
• verification-before-completion for "prove the claim before reporting success"

6. Save the handoff and report the path

The handoff is only useful if the next person can find it quickly. End by giving the exact saved path.

Output Template

# Handoff

## Objective
- ...

## Current State
- ...

## Task Ledger
| Task | Owner | Status | Resume Trigger |
|------|-------|--------|----------------|
| ...  | ...   | ...    | ...            |

## Key Decisions
- ...

## Important Files and Refs
- path or URL - why it matters

## Open Questions
- ...

## Risks or Gotchas
- ...

## Suggested Skills
- ...

## First Next Step
- ...

Common Rationalizations

Red Flags

• The handoff repeats existing docs word-for-word
• The next step is still vague after reading the document
• Important files are named without saying why they matter
• Secrets, tokens, or private data are copied into the handoff

Verification

• The next objective is explicit
• Existing artifacts are referenced instead of duplicated
• Open questions and risks are called out separately
• The saved path is reported back to the user

See Also

• cross-session-memory - resume or search prior Copilot sessions
• knowledge-curator - promote repeated lessons into durable project guidance
• implementation-review - compare delivered work against the original request