| name | handoff |
| version | 1 |
| owner | compass-maintainers |
| last_verified | 2026-08-25T00:00:00.000Z |
| description | Compact the current conversation into a typed in-repo handoff so a fresh agent can continue the work. |
| argument-hint | What will the next session be used for? |
When
The user asks to hand off, or a gate needs a typed record.
Steps
Refuse if write-gate fields are missing. Write .agents/handoffs/<task_id>.md
and update .agents/ledger.md.
Output
A schema-valid handoff file. Not an OS temp path.
Pass
Write-gate fields present; task_id is issue/PR/WP-*.
Anti-patterns
Do not write OS-temp handoffs. See
_evals/anti-patterns.md.
Escalate
Unknown schema_version, or required fields cannot be filled.
Write a typed handoff so a fresh agent can continue without the producer
transcript. Follow .agents/handoffs/SCHEMA.md.
If the user passed arguments, treat them as the next session’s focus and
tailor to, artifact, and evidence accordingly.
Write path
- Collect required fields:
task_id, from, to, owner, status,
artifact, evidence. Also fill assumptions, open_risks,
next_deadline, retry, approval, waiting_on, escalation.
- If
task_id, owner, status, artifact, or evidence is missing,
stop. Request the missing field. Do not write a file. Do not fall
back to OS temp. Do not write status: waiting as a substitute for
missing evidence.
- Validate against the schema:
schema_version: 1, status enum, exactly
one owner, artifact pointers that exist, evidence commands/results
that are not invalid completions ("done", "looks good", and the rest
listed in the schema).
- If the workspace is not writable, escalate. Never write to OS temp.
- Write
.agents/handoffs/<task_id>.md with YAML frontmatter matching the
schema, then an optional short body. The body is not required to act.
- Update
.agents/ledger.md in the same turn (create
it if absent): one row per in-flight task_id. Default priority to
medium if unknown. Change the row; do not append a transcript.
- Optionally include a "suggested skills" section in the body (not required
to act).
- Do not duplicate PRDs, plans, ADRs, issues, commits, or diffs — link
them by path or URL.
- Redact secrets: API keys, passwords, tokens,
compass.yaml contents,
personal calendar data, and personally identifiable information.
- Delete the handoff file in the same commit that closes the task, except
the documented
issue-0 example.
Suggested skills
After the record is written, list skills the receiver should invoke
(for example /verify-change, /ship, /local-dev-bootstrap).
