---
name: handoff
description: Hand off to a fresh Dave session — ask the user what to work on next, spawn a new session in the current worktree, and send it the task as its first message. Use when the user wants to delegate the next unit of work to a brand-new agentic session rather than continue in this one — e.g. "/handoff", "hand this off", "spawn a session to do X next", "start a fresh session on the next task".
---

# Handoff to a fresh Dave session

`/handoff` starts a **new** Dave agentic session in the *current worktree* and
seeds it with the next task, so this session can wrap up while a fresh one picks
up with clean context. It's a single `agentium spawn` call (see the `agentium`
skill): one command spawns a sibling on this host + cwd, waits for it to come up,
and delivers the task as its first message.

## 1. Decide the task

The new session inherits **zero context** from this conversation, so the task has
to be a self-contained prompt: what to build, the full `headway:board/word-id`
card ref if there is one, and any constraint the fresh agent can't infer from the
repo. Treat it like the prompt *you* were handed at the start of this session.
(The new session will read the card itself, so the prompt only needs the ref plus
a short TL;DR — not the card's full text.)

- If the user already gave the task in the `/handoff` invocation, expand it into
  that self-contained prompt.
- Otherwise **ask the user what the next session should work on**, then show them
  the exact prompt you're about to send and get their OK — it's the only thing
  the new agent will see.
- Also pick a **short title** (a few words) for the session, so it's identifiable
  in `agentium list` — e.g. the headway card's title or a terse summary of the
  task. Set it with `--title` rather than letting it derive from the first
  message.

## 2. Write the prompt to a file, then spawn

**Write the prompt to a file with the Write tool and pass its path to
`--prompt-file`. Never build the prompt inside the shell command** — not with a
heredoc, not with an inline `--prompt`, not with `echo` or `printf`. A handoff
prompt is exactly the kind of text that breaks shells: it names flags in
backticks, quotes code fences, and contains apostrophes and `$`. Inside a
`$( … )` capture, bash parses the backticks as legacy command substitution and
then trips over the apostrophes, and it does that *even with* a quoted heredoc
delimiter (`<<'EOF'`). The failure is a `unexpected EOF while looking for
matching` syntax error before `agentium` ever runs. A file has no such rules:
write the bytes, hand over the path.

`agentium spawn` already defaults `--host`/`--cwd`/`--backend` to *this*
session's own state (`$AGENTIUM_SESSION`), so a bare spawn starts a sibling in
the same worktree on the same host — no need to look them up. `--wait` blocks
(bounded) until the host answers with the new session's kind-31988 state;
`.session` in the JSON is its durable `agentium:` ref.

1. Write the self-contained prompt to your scratchpad, e.g.
   `<scratchpad>/handoff-prompt.md`.
2. Spawn with that path:

```bash
agentium spawn --title "<short title>" --wait --json \
  --prompt-file <scratchpad>/handoff-prompt.md | jq -r .session
```

That prints the new session's ref. Capturing it in a variable is safe now that
no prompt text is in the command line:

```bash
ref=$(agentium spawn --title "<short title>" --wait --json \
  --prompt-file <scratchpad>/handoff-prompt.md | jq -r .session)
```

That's the whole handoff. Notes:

- `--prompt-file` also accepts `-` for stdin, but **don't** use it — reaching for
  stdin is what puts a heredoc back in the command. Use a path.
- `--prompt-file` is mutually exclusive with `--prompt`. Reserve `--prompt` for a
  genuine one-liner with no backticks, quotes, or `$` in it; when in doubt, file.
- The prompt rides the spawn command, so the host delivers it even if a slow host
  outlasts `--wait`.
- To hand off into a **different worktree**, add `--cwd /path/to/worktree` (a Dave
  host must be running on the target host to pick up the spawn).
- If you're **not inside a Dave session** (`$AGENTIUM_SESSION` unset), there's
  nothing to inherit — pass `--host` and `--cwd` explicitly (fall back to
  `hostname` / `pwd`).

If `spawn --wait` times out, no Dave host is running on the target host (or the
cwd is wrong) — report that; nothing was created.

## 3. Report back

Tell the user the new session's ref and how to watch it:

    handed off to <ref> — follow it with `agentium log <ref> -f`

Then finish wrapping up *this* session per CLAUDE.md (commit, headway comment +
move, etc.). The handoff doesn't excuse leaving the current work half-done.

## Notes

- `agentium` needs a signing key; inside a Dave session it's already configured.
  If a command complains you're not logged in, see the `agentium` skill's
  "Logging in" section.
- One handoff = one new session. To fan out several tasks, repeat `/handoff` (or
  spawn once per task); don't cram multiple unrelated tasks into one prompt.