command-center/agent/managed-skills/repo-agent-handoff-doc/SKILL.md

name, description

name	description
repo-agent-handoff-doc	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:

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.