Handoff without compaction

# AGENTS.md: hand off work without compaction

Long sessions end in one of three ways: the context fills and gets compacted, you `/clear`, or the work moves to another
agent or person. Compaction keeps what a summariser thought mattered. A handoff file keeps what the next session needs.

## When to write a handoff
- Before `/clear`, `/compact` or ending a long session with work unfinished.
- Before switching agents (for example Claude Code to Codex or Antigravity) or handing to a teammate.
- When the context is clearly getting long: answers slow down, you re-read files you already read, or you lose track
  of earlier decisions. Do not wait for automatic compaction.
- Use the `write-handoff` skill. It writes `HANDOFF.md` at the repo root and checks it.

## When to read one
- At the start of every session, if `HANDOFF.md` exists, use the `resume-from-handoff` skill before doing anything
  else. Confirm the goal and next step with the user in one or two sentences.

## Rules for the file
- Facts, not narrative: goal, current state, files touched, decisions with reasons, what still fails (exact error),
  the next step, and the commands that prove it works.
- Record the commit (`git rev-parse --short HEAD`) and branch. A handoff for a different commit is stale until checked.
- Short: under 120 lines. Link to files and line numbers instead of pasting code.
- No secrets, tokens or personal data. It may be committed or shared.
- One owner per open task. If something is unverified, say so; do not round "probably works" up to "done".
- Delete or archive the file (`git rm HANDOFF.md` or move it to `docs/handoffs/`) when the work is finished.

## MCP servers and tools
- Note which MCP servers and CLIs the work depended on. A new agent may not have them configured.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `write-handoff`, `resume-from-handoff`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Handoff without compaction" v1.0.0 — https://loadout.jnw-it.com/loadouts/agent-handoff/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `write-handoff`, `resume-from-handoff`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Handoff without compaction" v1.0.0 — https://loadout.jnw-it.com/loadouts/agent-handoff/ -->

---
name: write-handoff
description: Write HANDOFF.md so a fresh session or a different agent can continue without the old context. Use before clearing or compacting context, at the end of a long session, or when switching agents or people.
---

# Write a handoff

1. Gather facts, do not summarise from memory alone:
   - `git rev-parse --abbrev-ref HEAD` and `git rev-parse --short HEAD`
   - `git status --short` and `git diff --stat` for files touched
   - Run the project's test command once and copy the first failing test and its exact error line.
2. Fill in `references/HANDOFF.template.md` and save it as `HANDOFF.md` at the repository root. Keep every heading.
   Write "none" rather than deleting a section.
3. Check it: `python3 scripts/check_handoff.py HANDOFF.md`. Fix everything it reports. It checks the required
   sections, the recorded commit against `HEAD`, length, leftover placeholders and secret-shaped strings.
4. Tell the user where the file is and the single next step. Do not commit it unless the user asks.

## Writing well
- Goal: one sentence on what "done" means, in the user's words.
- Decisions: what you chose, the alternative you rejected, and why. These are what compaction loses first.
- Failing or open: exact test name, command and error. "Tests flaky" is not useful; `test_refund_rounding: expected
  10.00, got 9.99` is.
- Next step: one concrete action the next session can start on without asking.

# Handoff

- Branch: <branch>
- Commit: <short sha>
- Written: <YYYY-MM-DD HH:MM timezone>
- Owner: <who picks this up, or "unassigned">

## Goal
<one sentence: what done looks like>

## Current state
<what works now, what was verified and how>

## Files touched
- <path>: <what changed>

## Decisions
- <decision>: <why; alternative rejected>

## Failing or open
- <test or task>: <exact command and error, or "none">

## Next step
<one concrete action>

## Verify with
- <command that proves it works>

## Tools and MCP servers needed
- <name, or "none">

#!/usr/bin/env python3
"""Check a HANDOFF.md before a session ends or another agent picks it up.

Usage: python3 check_handoff.py [HANDOFF.md] [--max-lines 120]
Exit 0 when complete, 1 when something needs fixing. Standard library and git only; no network.
"""
import re
import subprocess
import sys
from pathlib import Path

REQUIRED = ["Goal", "Current state", "Files touched", "Decisions", "Failing or open", "Next step", "Verify with"]
SECRET = re.compile(r"\b(?:sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9]{30,}|AKIA[0-9A-Z]{16}|xox[abposr]-[A-Za-z0-9-]{10,})"
                    r"|-----BEGIN [A-Z ]*PRIVATE" r" KEY-----|\b(?:password|passwd|token|secret)\s*[:=]\s*\S{8,}", re.I)
PLACEHOLDER = re.compile(r"<[A-Za-z][A-Za-z0-9 ,/:\"'-]*>")


def git(*args):
    try:
        return subprocess.run(["git", *args], capture_output=True, text=True, check=True).stdout.strip()
    except (OSError, subprocess.CalledProcessError):
        return None


def main(argv):
    path = Path(next((a for a in argv[1:] if not a.startswith("--")), "HANDOFF.md"))
    max_lines = int(argv[argv.index("--max-lines") + 1]) if "--max-lines" in argv else 120
    if not path.is_file():
        print(f"FAIL {path} not found")
        return 1
    text = path.read_text(encoding="utf-8")
    lines = text.splitlines()
    problems = []
    headings = {m.group(1).strip().lower(): i for i, l in enumerate(lines) if (m := re.match(r"^##\s+(.+)$", l))}
    for name in REQUIRED:
        if name.lower() not in headings:
            problems.append(f"missing section: ## {name}")
            continue
        start = headings[name.lower()] + 1
        body = []
        for l in lines[start:]:
            if l.startswith("## "):
                break
            if l.strip():
                body.append(l)
        if not body:
            problems.append(f"empty section: ## {name} (write 'none' if there is nothing)")
    if len(lines) > max_lines:
        problems.append(f"too long: {len(lines)} lines (max {max_lines}); link to files instead of pasting")
    for n, l in enumerate(lines, 1):
        if PLACEHOLDER.search(l):
            problems.append(f"line {n}: template placeholder left in: {PLACEHOLDER.search(l).group(0)}")
        if SECRET.search(l):
            problems.append(f"line {n}: looks like a secret; remove it")
    m = re.search(r"^- Commit:\s*([0-9a-f]{7,40})\b", text, re.M)
    head = git("rev-parse", "HEAD")
    if not m:
        problems.append("no '- Commit: <sha>' line")
    elif head and not head.startswith(m.group(1)):
        ahead = git("rev-list", "--count", f"{m.group(1)}..HEAD")
        problems.append(f"stale: written at {m.group(1)}, HEAD is {head[:7]}" + (f" ({ahead} commits later)" if ahead else "")
                        + "; re-check the state before trusting it")
    b = re.search(r"^- Branch:\s*(\S+)", text, re.M)
    branch = git("rev-parse", "--abbrev-ref", "HEAD")
    if b and branch and b.group(1) != branch:
        problems.append(f"branch mismatch: handoff says {b.group(1)}, checkout is {branch}")
    for p in problems:
        print(f"FAIL {p}")
    if not problems:
        print(f"OK {path}: {len(REQUIRED)} sections, {len(lines)} lines, commit matches HEAD")
    return 1 if problems else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

---
name: resume-from-handoff
description: Pick up work from HANDOFF.md at the start of a session. Checks the handoff is current, re-runs its verify commands and confirms the next step before changing anything.
---

# Resume from a handoff

1. Read `HANDOFF.md` in full before opening other files.
2. Check it is current: `python3 .agents/skills/write-handoff/scripts/check_handoff.py HANDOFF.md` (or the same script
   under `.claude/skills/`). If it reports "stale", run `git log --oneline <recorded commit>..HEAD` and read what
   changed before trusting the "Current state" section.
3. Re-run the "Verify with" commands. Compare the result with "Failing or open". Note any difference.
4. Check the "Tools and MCP servers needed" are available in this agent. If one is missing, say so; do not guess.
5. Reply to the user in two or three sentences: the goal, what you found when you re-ran the checks, and the next step
   you propose. Wait for a yes if anything differs from the handoff.
6. As you work, keep `HANDOFF.md` updated at natural stopping points, using the `write-handoff` skill.