A handoff is a dated doc plus, when the repo uses beads, an epic. The doc is the brief. A
session or agent starts only when the user says to start it. scripts/handoff does every
mechanical step; the agent's job is to write a good doc and report what the script prints.
Commands
scripts/handoff new "Report importer" # docs/YYYY-MM-DD-report-importer-handoff.md
scripts/handoff start DOC # epic + worktree + launch, detached
scripts/handoff start DOC --supervise # wait for the agent, then collect
scripts/handoff start DOC --here # worktree, branch, brief and epic; no agent
scripts/handoff start DOC --agent "codex-acp" # any ACP agent command
scripts/handoff status ID # commits, dirty files, agent exit, log tail
scripts/handoff collect ID # verify and record the result on the epic
scripts/handoff close ID [--discard] # remove the worktree once merged
scripts/handoff list
Run them from inside the target repository. State is kept in <git-common-dir>/handoff/<id>/
(state.json, brief.md, run.log), so nothing is added to the working tree.
Workflow
- Write the doc. Use
handoff new "<title>"or the project's own convention: look at existing handoff or spec docs first and match their folder and naming. Fill in problem, scope, what is out of scope and "done when". Put verification commands in a fenced block under a heading namedChecks(orVerify):collectruns each line in the worktree. - Stop and wait until the user says to start it. Writing the doc is not consent to launch.
- Start.
handoff start DOCprints the base branch and commit it cuts from; relay that line, and any note that the source checkout has uncommitted changes the worktree won't have. Withoutbdor a.beads/folder the epic is skipped with a one-line note. - Check in with
handoff status ID. Don't poll in a loop; use--supervisewhen the user wants to wait for it. - Collect.
handoff collect IDchecks that the agent finished, the branch has commits, the worktree is clean, nothing new changed in the source checkout, and each brief check passes. It records the result as a comment on the epic and exits non-zero on any failure. - Merge is the user's call. Report the verdict and the branch name, then stop.
- Close after the merge:
handoff close IDremoves the worktree and workspace, deletes the merged branch and closes the epic. It refuses an unmerged branch unless--discard, which removes the worktree but always keeps the branch.
What the agent is told
The doc is sent as the prompt with fixed rules appended: stay in the worktree, commit on the
handoff branch with explicit paths only, never merge, rebase, push or open a PR, don't touch
files outside the worktree, report blockers instead of working around them, and end with a short
report. acp-run enforces the path rule for permission requests and file reads and writes.
Requirements and limits
- git, Python 3, a running herdr, and herdr's
acp-runscript. The script looks foracp-runonPATH, next to this skill in a siblingherdrskill, and in the usual skill folders; setHANDOFF_ACP_RUNto override. - Only ACP agents. The script never falls back to a TUI agent.
- The worktree is cut from committed history. Uncommitted changes, including an uncommitted doc, aren't in it; the brief still reaches the agent because it is passed as a file.
- "Nothing changed outside the worktree" compares the source checkout's
git statuswith a snapshot from start time. In a checkout shared with other sessions a change there may be theirs, socollectnames the files instead of guessing.