handoff

Files (1)

• SKILL.md

SKILL.md (first lines)

# Handoff

`.agent/state.json` and the map carry what has been *settled*. Neither
carries the **live thread** — what is in flight right now, why this
approach and not the other one, what was just tried and rejected. That is
what compaction loses and what this document preserves.

Write it at a ticket boundary before `/clear`, or any time the context
window has grown large enough that the next step deserves a fresh one.

## Where it goes

The OS temporary directory — `$TMPDIR` on macOS, `/tmp` otherwise. Never
the workspace.

A handoff is scaffolding for one session gap, not a project artifact. In
the workspace it would become a third thing to keep in sync with the map
and `state.json`, and would go stale the moment it was read.

Name it `handoff-<ticket-or-topic>.md` and give the user the full path so
the next session can be pointed at it.

## What it carries

- **The live thread** — what is in flight and why, in the conversation's
  own terms. What was tried, what was ruled out, what the next concrete
  step is.
- **Suggested skills** — which skills the next session should reach for.
- **References, not copies** — link the map, spec, ADRs, tickets, commits,
  and diffs by path or URL. Everything already written down stays where it
  is; the handoff points at it.
- **Open questions** — anything the user still owes an answer on.

Anything already captured in the map, a spec, an ADR, a ticket, a commit
message, or a diff belongs in the references list, not the body. Copying it
in creates a second copy that immediately starts drifting from the first.

## Redaction

Strip API keys, tokens, passwords, connection strings, and personal data
before writing. The temp directory is not a secret store.

## Process

1. Identify the current ticket and phase from `.agent/state.json`.
2. Write the live thread — the reasoning that exists only in this
   conversation.
3. List references by path or URL.
4. Name the suggested skills for the next session.
5. Redact secrets.
6. Write to the temp dir and report the full path to the user.

## Relationship to state.json

Complementary, not a replacement. `state.json` stays the machine-readable
resume point the SessionStart hook reads automatically; the handoff is the
human- and agent-readable thread that sits alongside it. Persist
`state.json` as normal — a handoff never substitutes for it.

## Scope

Keep the document to the live thread. When it starts restating the map or
the spec, stop and link instead — a handoff that grows into a full project
summary has become the artifact it was written to avoid.

From lynchypin/project-onboard, MIT.

More from lynchypin/project-onboard