handoff

Handoff

Bank the current work's context so a fresh agent can continue it. Handoffs live in one of two backends — a beads issue when beads is available, a HANDOFF*.md file otherwise.

Backend preflight

command -v bd >/dev/null 2>&1 && [ -d .beads ] && echo "Backend: beads — read references/beads.md before writing" || echo "Backend: files — read references/files.md before writing"

If the preflight above didn't run, run the check yourself: command -v bd >/dev/null 2>&1 && [ -d .beads ] → beads. Read exactly one reference (references/beads.md or references/files.md) for where and how the handoff is stored, then fill the contract below.

Work name (both backends)

Name the handoff for the work, not just the branch. Default to git branch --show-current; when that doesn't describe the work — a generic default branch (main, master, develop, trunk), a bare ticket ID, or a branch carrying several unrelated tasks — pick a short kebab-case name from what this session is actually about (e.g. grafana-skill). Not in a git repo / detached HEAD with no obvious short name → no name.

Content contract (both backends)

Sections, in order:

1. Goal — what we're trying to accomplish. If it evolved from the original ask, note how and why.

2. Current Progress — what's been done so far.

3. Files Changed — files modified, created, or deleted this session.

4. What Worked — approaches that succeeded.

5. What Didn't Work — approaches that failed, so they're not repeated.

6. Next Steps — concrete, ordered action items for continuing.

7. Anchor — omit when not in a git repo. Exact shape (the HEAD: line is machine-parsed for drift detection):

   ## Anchor
   - Branch: <git branch --show-current>
   - HEAD: `<git rev-parse HEAD>`
   - Written: <date -u +%Y-%m-%dT%H:%M:%SZ>
   

8. Session — run:

   # Codex: this path resolves under Claude Code; substitute the directory containing this SKILL.md.
   SKILL_DIR="${CLAUDE_SKILL_DIR}"
   bash "$SKILL_DIR/scripts/session-info.sh"