Park the current work as a draft PR and write the handoff into the PR description, so the next agent picks up the baton from GitHub with nothing else to go on.
The work is in progress by definition. Push it exactly as it stands — the feature stays unfinished, the failures stay failing, the diff stays untidy. Capture the state; completing it is the next agent's job.
Steps
- Get onto a branch. If HEAD is the default branch, create a descriptive one first. Push only ever to a non-default branch, and only ever as a new commit — no force-push, no rewriting what is already on the remote.
- Commit what's there. Stage the changes that belong to this work — tracked edits plus new files — and commit with a
wip: subject. Leave scratch files, local config, and credentials out. Done when git status shows nothing left that belongs to the work.
- Open the draft, or update it.
git push -u, then gh pr create --draft --title "..." --body-file <handoff>. If the branch already has a PR, write the new handoff over the old one with gh pr edit --body-file <handoff> rather than opening a second PR.
- Report. Print the PR URL, and say plainly whether the tree is green or red.
The handoff description
Written for an agent that will gh pr checkout this branch and continue — not for a human reviewer, so it reads as instructions rather than as a changelog. Every section below filled from the actual conversation and diff, with no placeholders:
- Goal — what this change is meant to achieve, in a sentence.
- State — what already works, and what is green or red right now: the failing test name or the exact error, verbatim.
- Resume point — the next concrete action, naming the file and function to start in.
- Verify — the exact commands that tell the next agent it is done.
- Landmines — decisions already taken, and approaches already tried and abandoned, so the next agent doesn't re-litigate them.
- Suggested skills — skills the next agent should invoke.
Reference specs, plans, ADRs, and issues by path or URL; don't restate what they already say. Redact API keys, passwords, and personal data — a PR description is readable by everyone with access to the repo.
If the user passed arguments, treat them as the next agent's brief and tailor the description to it.
1---2name: pr-handoff3description: Push the work in progress as a draft GitHub PR whose description is the handoff for the next agent.4---56Park the current work as a **draft** PR and write the handoff into the PR description, so the next agent picks up the baton from GitHub with nothing else to go on.78The work is in progress by definition. Push it exactly as it stands — the feature stays unfinished, the failures stay failing, the diff stays untidy. Capture the state; completing it is the next agent's job.910## Steps11121. **Get onto a branch.** If HEAD is the default branch, create a descriptive one first. Push only ever to a non-default branch, and only ever as a new commit — no force-push, no rewriting what is already on the remote.132. **Commit what's there.** Stage the changes that belong to this work — tracked edits plus new files — and commit with a `wip:` subject. Leave scratch files, local config, and credentials out. Done when `git status` shows nothing left that belongs to the work.143. **Open the draft, or update it.** `git push -u`, then `gh pr create --draft --title "..." --body-file <handoff>`. If the branch already has a PR, write the new handoff over the old one with `gh pr edit --body-file <handoff>` rather than opening a second PR.154. **Report.** Print the PR URL, and say plainly whether the tree is green or red.1617## The handoff description1819Written for an agent that will `gh pr checkout` this branch and continue — not for a human reviewer, so it reads as instructions rather than as a changelog. Every section below filled from the actual conversation and diff, with no placeholders:2021- **Goal** — what this change is meant to achieve, in a sentence.22- **State** — what already works, and what is green or red right now: the failing test name or the exact error, verbatim.23- **Resume point** — the next concrete action, naming the file and function to start in.24- **Verify** — the exact commands that tell the next agent it is done.25- **Landmines** — decisions already taken, and approaches already tried and abandoned, so the next agent doesn't re-litigate them.26- **Suggested skills** — skills the next agent should invoke.2728Reference specs, plans, ADRs, and issues by path or URL; don't restate what they already say. Redact API keys, passwords, and personal data — a PR description is readable by everyone with access to the repo.2930If the user passed arguments, treat them as the next agent's brief and tailor the description to it.
sunfmin