How to Hand a Task to Another Coding Agent

Quick answer
A handoff is a new agent session continuing work another session started, and it works only if the state lives outside the old context.
Write a handoff file with the goal, accepted decisions, current diff status, open questions, and the next command.
Commit or stash the work before handing off, so the next agent starts from a known tree rather than uncommitted changes.
Point the new session at the handoff file and the spec, not at a summary of the conversation.
Verify the first action of the new agent, because a confident handoff can still be read wrongly.

What must a handoff contain?

The goal in one sentence, the decisions that are already settled, the state of the working tree, the open questions, and the next concrete action. Everything else is optional; those five are what stops the next agent from re-litigating the work.

Write it as a file in the repository, not as a chat message. A file can be committed, reviewed, diffed, and read by a human who joins later. Chat context dies with the session.

# Handoff: session expiry check

Goal: reject expired sessions in requireUser middleware.
Decisions: keep refresh tokens valid; do not touch the login flow.
State: middleware change is applied and passing locally; tests not yet added.
Open: whether expired refresh tokens should also return 401.
Next: add the expired-session test in test/auth.test.ts, then run npm test -- auth.

How do you prevent the new agent from undoing the old work?

Commit the work in progress, even on a scratch branch. A clean tree plus a written decision list is a boundary the next agent can respect. Uncommitted changes mixed with a handoff note invite a rewrite.

State the decisions as constraints: “keep the refresh-token path unchanged” is actionable, while “mostly done” is not. Constraints are what the next agent needs in order to not improve the design you already rejected.

When should you hand off rather than continue?

When the context is nearly full, when the task moves to a different specialism, or when a second opinion is worth more than continuity. A fresh session with a tight brief often performs better than a long session carrying irrelevant history.

The opposite is also true: a small correction does not need a handoff. If the next step is one edit, steering the current agent is cheaper than rebuilding context.

How do you check the handoff worked?

Read the new agent’s first plan or first diff against the handoff file. If it starts by refactoring something marked as decided, the constraints were not clear enough — fix the file and restart rather than correcting in chat.

Keep the handoff file in the branch until the work merges. It is a useful record of why the change looks the way it does, and it becomes the description for the pull request.

Where this bites vibecoders
A generated handoff summary tends to describe the conversation rather than the repository: what was discussed, what the assistant suggested, what felt finished. The next agent needs the diff and the decisions. Replace narrative with state.

Where AI coding assistants get this wrong

Writing a handoff that summarises the conversation instead of the tree.
Handing off with uncommitted changes the next agent must guess about.
Omitting the decisions that were explicitly rejected.
Leaving the next action implicit.
Passing a chat transcript instead of a file.
Skipping verification of the new agent’s first step.

Checklist

Write the goal in one sentence.
List settled decisions and rejected options.
Commit or stash the working tree.
Name the next action and its verification command.
Point the new session at the handoff file and the spec.
Review the first plan before letting it run.

FAQ

Can two agents work at the same time?

Yes, but not on the same files. Concurrent sessions need separate worktrees or branches and an agreed file ownership boundary. A handoff is the sequential version of the same problem: state must live outside the session.

Where should the handoff file live?

Somewhere in the repository that is obviously temporary, such as a notes directory on the working branch. Do not merge it into the main branch unless the project wants a decision log; the pull request description is usually the durable artefact.

Does the next agent need the whole spec again?

It needs the spec section for the current task and the handoff. Pasting the entire specification wastes context and invites the agent to re-plan work that is already done. Link to the file and quote the relevant acceptance criteria.

What if the handoff is wrong?

That is the signal to fix the process, not the agent. A wrong handoff usually means the working tree or the decisions were not recorded. Correct the file, reset the branch, and start the new session again.