---
name: repo-agent-handoff-doc
description: "Use when asked to write or refresh a standing handoff/status doc so agents landing in a repo can continue work isolated from other directories; sections that code cannot reveal, plus moving untracked docs onto a branch without dirtying a shared checkout."
---

# Standing agent handoff doc for a repo

"Put a complete handoff on project X in its directory so agents there can work
isolated" is not a changelog request. The value is the knowledge the code cannot
reveal. Discover the repo's own conventions first, then write one **living** file.

## 0. Fit the repo, do not invent a layout

`ls -a` + `grep -n '^##' README.md` + `find docs -maxdepth 2` before writing:
- existing `docs/` conventions (dated `docs/decisions/*.md` records vs flat pages),
- whether an `AGENTS.md`/`CLAUDE.md` auto-loads (if not, the README is the only
  entry point → the handoff MUST be linked from it, same commit),
- the exact numbers you will quote: per-file `grep -c '^@test'`, `package.json`
  `scripts`, module list from `ls src/`. Never write a test count or command from
  memory.

## 1. Section checklist (point of use — each answers a question the next agent hits)

1. **State line**: the commit it describes (`main` at `<sha>`, "after PRs #N") +
   the rule that whoever leaves work updates it in the same commit. A stale
   handoff is worse than none: it gets believed.
2. **Commands** — build/typecheck/test with real runtime, plus concurrency
   hazards (e.g. a suite that rebuilds `dist/` in `setup()` → two `bats` runs
   corrupt each other's byte-identical pin).
3. **Test seam and how to add a test** — where the harness mock lives, scenario
   names, how scripted UI answers are consumed, env dials that are *ignored*
   (a `setup()` that clobbers your override), and the red-first rule with the
   one exception (a characterization test that says so in a comment).
4. **The laws, each with the test that holds it** — table form. Distinguish
   load-bearing invariants from incidental behaviour; this is the section that
   stops a confident agent "fixing" a chosen design.
5. **Worktree/dev-dir recipe** — symlinked deps, gitignore rule that keeps the
   symlink untracked, why the shared checkout stays clean.
6. **Ship path** — branch → tests → rebuild committed artifact → PR → merge on the
   owner's OK → land with `--ff-only` → deploy (the gotcha that the upgrade target
   is the PACKAGE name, not the directory alias) → `cmp` the live artifact against
   the merged build → prune. Include the auth traps of the forge (token via a
   600 curl `-K` file, empty token answering 404 not 401, form-encoded merge).
7. **Live verification** — the instrument that produces evidence (stub player,
   log line counts, pty submit semantics), and explicitly what is NOT a check
   (print-mode invocation, screen reads of transient toasts, single-take audio
   comparisons).
8. **Environment reality not visible from this code** — the live endpoints,
   measured limits, refusals; crosslink the README if it owns the table.
9. **Open items** — numbered, each actionable alone, each saying who decides if a
   human must; name the repo a fix belongs in when it is NOT this one.
10. **History** — one line per issue/PR. No tables of metrics.

One owner per fact: link the README/decision records instead of restating knob
tables or rationale.

## 2. Tree hygiene (the costly step)

Writing straight into a shared checkout leaves an untracked file on `main` — a
half-deployed state where the checkout is the deployment, and a dirty tree for
everyone else. Move it onto a branch without switching anyone's HEAD:

```bash
mv <repo>/docs/handoff.md /tmp/handoff.md
git -C <repo> fetch -q origin
git -C <repo> worktree add -q -b docs/<slug> ~/Projects/wt-<topic> origin/main
ln -s <repo>/node_modules ~/Projects/wt-<topic>/node_modules   # if deps are needed
mv /tmp/handoff.md ~/Projects/wt-<topic>/docs/handoff.md
git -C <repo> status --porcelain                              # shared checkout clean again
```

README pointer edit happens **in the worktree** (an edit there is a separate
checkout; editing the shared one dirties a tracked file). Then commit, run the
suite, push, open the PR, and merge only on the owner's explicit OK.

## 3. Voice rules

Prose in the repo's own style (match an existing decision record). State reasons
and consequences, not bookkeeping. No measured numbers for things that drift;
keep the law, drop the figure.