81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
---
|
|
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.
|