Baton

Baton

Overview

A relay only works if the baton is passed cleanly. When you hand work to another agent — a fresh window, a future session, a different model — that runner starts with zero of your context. A baton is a single markdown file that lets them grab the work and sprint, instead of re-deriving everything you already know.

Core principle: capture what the next runner can't reconstruct from the code or git history — your intent, the dead ends you already ruled out, and the exact next step — grounded in verified repo state, not your chat narrative.

Two sides to this skill: Drop a baton (you're handing off) and Grab a baton (you're picking one up).

When to Use

Drop a baton when:

• A session ends with work unfinished and someone/something will continue it.
• The user says "hand this off", "pick up later", "pass this to another agent".
• You're running low on context and want to checkpoint before it's summarized away.
• You're about to dispatch the rest of the work to a separate agent/session.

Grab a baton when:

• Starting work in a repo where a prior session may have left one (check first).

Don't use for: a finished task (no handoff needed), or durable architecture rationale (that belongs in a long-lived design doc, not a baton).

Where the Baton Lives

Default destination: .baton/ at the repo root — a dedicated folder for handoffs, created if it doesn't exist. It works in any repo, so there's no other location to choose.

.baton/ is local scratch, not committed. The first time you drop a baton, ensure it's git-ignored — if .gitignore doesn't already cover it, add a .baton/ line.

Filename: -.md (e.g. .baton/2026-06-13-formula-eval-rounding.md).

The next agent finds the latest with ls -t .baton/.

The Iron Rule: Verify Before You Write

A baton built from the chat story instead of repo reality is worse than none — it sends the next runner the wrong way with false confidence. Before writing, run git status and git branch --show-current and confirm what is actually committed vs. uncommitted. The "State of play" section must reflect runtime truth. If reality contradicts the narrative, the baton documents reality and flags the gap.

Baton Format

Fill every section. If one is genuinely empty, write "none" — don't delete it (the next runner relies on the shape being consistent).

# Baton: 

**TL;DR:** 

## Intent & Goal
Why this work exists and the desired end state. Include the acceptance
criteria — ideally the exact command/test that must go green.

## State of Play (verified against git)
- Branch:  — confirmed via `git branch --show-current`
- Committed: 
- Uncommitted / in flight: 
- Verified working: 
- Assumed / unverified: 

## Learnings & Landmines
The highest-value section — what the next runner can't get from the code:
- Non-obvious discoveries.
- **Dead ends already ruled out** (so they don't repeat them) and *why*.
- **Do NOT touch** zones and the reason.

## Pointers
- Key anchors: `path/to/file.ts:123` — what's there.
- Relevant docs / prior batons / PRs.
- Commands to get oriented or reproduce: ``.

## Next Steps
Ordered, concrete, immediate action first. Not "finish the feature" — the
literal next move.

## Open Questions
Unresolved decisions + your current lean (so they can proceed if no one answers).

Grabbing a Baton (resuming)

1. Find it: ls -t .baton/ — read the newest.
2. Trust but verify: re-check "State of play" against real git status before

acting; the repo may have moved since the baton was dropped.

1. Continue from Next Steps.
2. Retire it when the work lands: delete it if it was only scratch, or fold

durable learnings into a canonical doc and then delete. Don't let stale batons pile up in .baton/.

Common Mistakes

| Mistake | Fix | |---------|-----| | Baton restates the diff | The diff is already in git. Capture intent, dead ends, next step. | | Built from chat, not git status | Verify first — a confidently-wrong baton is worse than none. | | Vague next step ("continue the work") | Write the literal next action. | | Dead ends omitted | Naming what didn't work is the highest-value content — it saves a full re-derivation. | | Scattered handoff location | Always .baton/ at repo root — never elsewhere, or the next agent can't find it. | | Stale batons pile up | Retire it when the work lands: delete, or fold learnings into a canonical doc. |

Response Behavior

After dropping a baton, state the exact path written and a one-line summary of what's in it.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: blader
• Source: blader/baton
• License: MIT

Install and usage instructions live in the source repository linked above.