# Hand off long-running work between agents

A long project should not depend on one agent's context window, quota, or terminal session. Solo gives the project a durable memory layer so you can stop an agent, launch a different configured tool, or return tomorrow without rebuilding the plan from chat scrollback.

The basic pattern is: keep durable facts in one scratchpad, keep actionable work in todos, and require an explicit handoff before changing agents.

## Create the project memory first

At the beginning of substantial work, ask the lead agent to create or reuse one canonical scratchpad. It should describe the project state well enough that a new agent can orient itself without reading the old conversation.

```text
Treat this as work that may outlive this session. Create or reuse one Solo
scratchpad as the source of truth, then create todos for the actionable slices.
Keep the scratchpad current with the goal, decisions, relevant files, verified
commands and tests, risks, and next action. Use todo comments for per-slice
handoffs. Do not rely on chat history for anything the next agent must know.
```

A useful scratchpad includes:

- Goal and non-goals.
- Repository, branch, and expected worktree state.
- Current design or diagnosis.
- Decisions already made and why.
- Relevant files, commands, and process names.
- Tests and verification already run.
- Open questions, risks, and external blockers.
- The next bounded action.

Keep detailed task activity out of the main narrative. Put it in the related todo comments so the scratchpad remains readable.

## Track slices with todos

Create one todo per meaningful piece of work. Include ownership, acceptance checks, the related scratchpad section, and blockers. The active agent should lock only the todo it is working on and release it after writing its handoff.

This gives the next agent two levels of context:

- The scratchpad explains the project and decisions.
- The todo and comments explain what happened on this slice.

When the plan changes, update both. A stale scratchpad with accurate todos is confusing; an accurate scratchpad with stale todo statuses makes the lead dispatch the wrong work.

## Require a handoff before switching

Before stopping, closing, or replacing an agent, ask it to leave a bounded handoff:

```text
Prepare this slice for handoff. Re-read the current diff and project state, update
the canonical scratchpad only where durable context changed, and comment on the
todo with: what changed, files touched, exact checks run and results, current
worktree state, unresolved risk, and the next concrete action. Release the todo
lock when the handoff is complete. Do not start another slice.
```

The handoff should say what is verified, not merely what the agent remembers doing. If a test was not run, say so. If the worktree contains unrelated changes, name the intended files without claiming the whole tree is clean.

[Agent summaries](../agents/auto-summarization.md) are useful for triage, but they are not the durable handoff. They can lag or omit the detail another worker needs.

## Launch the replacement from durable state

Give the new agent the scratchpad and exact todo, then ask it to verify the current repository state before editing.

```text
Continue the active slice from the Solo scratchpad and todo I linked. Read the
scratchpad sections and todo comments first. Verify the branch, worktree, relevant
files, and last reported test result against the repository. Tell me if the handoff
is stale or contradictory. Otherwise lock the todo, continue only its next action,
and keep the same acceptance checks and ownership boundary.
```

This works whether the replacement uses the same agent tool, a different model, or a different configured provider. The state belongs to the Solo project, not to the agent that created it.

Do not paste the entire old conversation into the new prompt. It often contains abandoned theories and transient instructions. Point the agent to the curated scratchpad and task history instead.

## Hand off while other work is still running

Sometimes the lead changes while worker agents or commands are still active. The outgoing lead should record their Solo process IDs, assigned todos, and expected outputs in the scratchpad. It should also cancel its pending timers before stopping so wake-ups are not delivered to a lead that is no longer responsible for the run.

The incoming lead should:

1. Inspect only the named processes first.
2. Compare their actual status and output with the handoff.
3. Reuse productive workers rather than spawning duplicates.
4. Set one new consolidated idle timer owned by the incoming lead if workers remain active.
5. Close completed or superseded agents after their output is captured.

Timer messages arrive as fresh user turns, so make them self-contained. Include the process IDs, scratchpad or todo IDs, and the exact action the lead should take when it wakes.

## Recover from an incomplete handoff

An agent can stop before it writes a clean handoff. When that happens, reconstruct state from the narrowest reliable sources:

1. Inspect git status and the actual diff.
2. Read the todo and its comments.
3. Read the relevant scratchpad sections.
4. Inspect the stopped agent's saved output when it is still available.
5. Re-run the smallest verification needed to establish the current state.

Write the recovered facts back to the scratchpad and todo before continuing. Do not turn an incomplete handoff into permission to recover every old session or artifact in the project.

## Finish with a smaller surface

At the end of a long run, refresh the scratchpad summary, mark todo states honestly, remove stale blockers, and leave final comments on anything another agent may pick up. Then [close agents](../agents/closing-agents.md) whose useful context has been captured and cancel timers that no longer have work to watch.

The goal is not a perfect transcript. The goal is a small, trustworthy set of project records that lets the next agent answer three questions quickly: What are we doing? What has been verified? What should happen next?

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/workflows/handoff-long-running-work