baton-handoff

Files (3)

• SKILL.md
• SKILL.md.bundle
• SKILL.md.sig

SKILL.md (first lines)

# Baton Handoff

> Implements Principle 6 of the DevOPs Constitution.
> Sessions are short. Projects are long. The baton bridges the gap.

**Tradeoff:** ~500 bytes of structured state per session-end. Worth it: zero
context loss across tool boundaries.

---

## When to invoke

1. **User types `/checkpoint`** — explicit handoff request.
2. **Session limit approaching** — proactively, when 80%+ of session budget is used.
3. **Natural task boundary** — completed unit of work, no obvious next move.
4. **Before tool switch** — user mentions opening another agent.

---

## What goes in the baton

`.workflow/state/baton.md` holds the fields below. Where the host tool wires
`hooks/universal/session-end/write-baton.sh`, that hook rewrites the file at
session end, filling its `## Next action` and `## Open questions for the user`
sections from `.workflow/state/next-action.txt` and
`.workflow/state/open-questions.txt`, so put them there; where it is not wired,
write the baton yourself. It contains:

- `last_updated` timestamp
- `session_id` and originating tool
- Active `lifecycle_phase` and `active_mode`
- Git state (branch, HEAD, dirty file count)
- Count of verified claims this session
- List of open blockers
- **`## Next action` section** — the literal next instruction for the next agent
- Open questions for the user
- Files modified this session
- Recently completed claim refs

---

## How to write the Next action well

The single most important section. Be specific. Keep one `## Next action`
heading and replace its text each session, rather than adding a second one or
a `next_action:` field: the Stratum session-start recall
(`runtime/scripts/session-start-context.ts`), where it runs, reads its query
only from the first `## Next action` section, up to the next `## ` heading.

**Bad** (forces the next agent to re-explore):
> Continue working on auth.

**Good** (the next agent knows exactly what to do):
> Resume task T-014 (refresh-token rotation). The spec is at
> `specs/auth/tokens.md#ac-3`. AC-3, AC-4, AC-5 are implemented and verified
> (see `.workflow/proofs/claim-2026-05-22-018.yml` through `-020.yml`).
> AC-6 (clock-skew tolerance) is next.
>
> First action: read AC-6, write the failing test in `src/auth/clock-skew.test.ts`,
> then implement. Use the existing `addClockSkew` helper from
> `src/auth/util.ts` line 47.

---

## How to write open_questions

Anything the agent couldn't resolve alone. The user reads this when starting the
next session, answers, and the answers go into `specs/` or `decisions.md`.

```markdown
1. Should refresh tokens be invalidated on password change? (Currently they
   are NOT. AC-7 implies yes but doesn't say explicitly. Spec ambiguous.)

2. Rate limit on /refresh? Current setting: 30/min/IP. The compliance doc
   suggests 5/min/IP for OAuth-style refresh. Confirm which applies.
```

---

## Where the baton lives

- File: `.workflow/state/baton.md`
- Committed to git where the project tracks `.workflow/state/`. Where
  `.gitignore` excludes it (as the DevOPs repository itself does), the baton
  stays a local file; leave it untracked.
- Checked by: `hooks/universal/session-start/load-baton.sh` on every session start.
  It reports whether the baton exists and how old it is; it does not read the
  contents for the agent.
- Max age before "stale": 24 hours (configurable). After that it's informational only.

---

## What NOT to put in the baton

- Code (the next agent has the repo)
- Lengthy reasoning (link to a doc instead)
- Anything secret (PII, keys) — not in the baton even where it stays
  untracked, and never in committed files
- Past completed work in detail (link to proofs)

---

## Reading the baton

On session start, `load-baton.sh` already prints status. The agent must still
explicitly:

1. Open `.workflow/state/baton.md`
2. Read its `## Next action` section and the open questions
3. Address blockers first
4. Then resume

---

**This skill is working when:** the user can type `continue` in any tool and
the agent picks up correctly. Target: resume success > 0.95. The
intended record is `governance/telemetry/resume-success.jsonl`. Nothing writes it yet, so check by hand.

From MILTONADINA/DevOPs, MIT.

More from MILTONADINA/DevOPs