Agent Operations Templates

Session hygiene. Context windows die; these notes are what the next session (or next agent) actually needs. Pair with Coordination and Recovery.

Agent handoff note

Use at the end of a productive session when work continues later or by someone else. Write for a competent engineer with amnesia — not a diary.

# Handoff — <task / branch>

Date: `<YYYY-MM-DD>` · From: `<human / tool / model>` · Branch: `<name>` · Spec: `docs/specs/<file>`

## Goal (unchanged)
`<one sentence from the spec>`

## Done this session
- `<concrete commits / PRs / files>`
- Tests: `<commands run + pass/fail>`

## Not done
- [ ] `<next concrete step>`
- [ ] `<…>`

## Decisions made (not yet in ADR / DECISIONS.md)
- `<decision>` — why: `<…>` — promote to ADR? `<y/n>`

## Landmines
- `<file / behavior that looks wrong but is intentional>`
- `<command that hangs / flaky test>`
- `<do not touch: path>`

## Exact next prompt
```text
Continue <task> per spec docs/specs/<file>.
Already done: <bullets>.
Do next: <single next step only>.
Constraints: <blast radius / never-dos>.
Verify with: <commands>.
```

Context reset note

Use when the session is thrashing, contradicting itself, or burning tokens on a stuck loop. Compact truth; start a new session with this as the only history.

# Context reset — <task>

Reason for reset: `<thrash / wrong approach / context pollution / tool crash>`
Spec (source of truth): `docs/specs/<file>` · Branch: `<name>` · HEAD: `<sha>`

## What is true right now
- Working tree: `<clean | describe dirty files>`
- Passing: `<commands>`
- Failing: `<commands + error one-liner>`

## Approach to abandon
`<what we tried and why it failed — 2–4 lines max>`

## Approach to take next
`<the plan — constrained, single direction>`

## Files that matter (only)
- `<path>` — `<why>`
- `<path>` — `<why>`

## Hard constraints (repeat)
- `<from CLAUDE.md / spec>`

## First message in new session
```text
Fresh session. Ignore prior chat.
Spec: docs/specs/<file>. Branch: <name> @ <sha>.
Reality: <passing/failing one-liners>.
Abandoned approach: <one line>.
Do only: <next step>.
Do not: <scope creep / rewrite>.
Verify: <commands>.
```

Repository onboarding note

Use for the first serious agent session in an unfamiliar repo — human fills this once, or has the agent draft it then verifies. Prefer lasting docs over repeating this forever.

# Repo onboarding — <repo name>

Filled: `<date>` · Verified by: `<human>`

## Purpose
`<what the system does — 2 sentences>`

## How to run
- Install: `<…>`
- Dev: `<…>`
- Test (exiting): `<…>`
- Gotchas: `<Docker, direnv, VPN>`

## Where truth lives
| Artifact | Path |
|---|---|
| Agent orders | `CLAUDE.md` / `AGENTS.md` |
| Architecture | `docs/ARCHITECTURE.md` |
| Specs | `docs/specs/` |
| ADRs | `docs/adr/` |

## Map (high level)
- Entrypoints: `<paths>`
- Domain core: `<paths>`
- Do not edit: `<generated / vendored>`

## First safe task
`<small verified change to prove the loop>` — verify: `<command>`

## Open risks for agents
- `<area agents routinely break>`

Multi-agent task split

Use before parallel agents. Non-overlapping ownership is the whole game — see Multi-Agent Patterns.

# Multi-agent split — <feature / milestone>

Spec: `docs/specs/<file>` · Coordinator (human): `<name>` · Date: `<…>`

## Shared source of truth
- Spec + ADRs linked above
- Integration branch / main: `<…>`
- Interface contracts frozen: `<API / types / OpenAPI path>`

## Agents

### Agent A — `<role name>`
- Owns paths: `<glob / packages>`
- Tasks: `<T1, T2 from breakdown>`
- Must not touch: `<Agent B paths>`
- Verify: `<commands>`
- Handoff artifact: `<PR / note path>`

### Agent B — `<role name>`
- Owns paths: `<…>`
- Tasks: `<…>`
- Must not touch: `<…>`
- Verify: `<…>`
- Handoff artifact: `<…>`

### Agent C — `<optional>`
- …

## Integration plan
1. Merge order: `<A then B | …>`
2. Integration owner (human): `<name>`
3. Conflict rule: `<interfaces win; re-implement callers>`
4. Final verify: `<commands / checklist>`

## Sync points
| When | Who | Artifact |
|---|---|---|
| Contracts frozen | human | `<path>` |
| Each agent done | agent → human | handoff note |
| Integration | human | green CI on integration branch |

Related

• Agent Roles — what to assign to whom
• Coordination — avoiding parallel chaos
• Multi-Agent Patterns — proven splits
• Recovery — when a session goes bad
• Large Tasks — when one agent isn't enough
• Templates index