# Handoff

> 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".

- Skill: `damus-io/handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add damus-io/handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/damus-io/handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: damus-io (https://skillmd.com/u/damus-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/damus-io/handoff

---


# 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. Spawn + send, in one command

`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. `--prompt-file -` reads the
first message from stdin, so a heredoc carries a long, multi-line prompt with
**zero shell-escaping** (no wrestling with quotes, `$`, or newlines). `--wait`
blocks (bounded) until the host answers with the new session's kind-31988 state;
`.session` is its durable `agentium:` ref.

```bash
ref=$(agentium spawn --title "<short title>" --wait --json --prompt-file - <<'EOF' | jq -r .session
<the self-contained task prompt — as many lines as you like, no escaping>
EOF
)
echo "$ref"
```

That's the whole handoff. Notes:

- Use a **quoted** heredoc delimiter (`<<'EOF'`) so the shell doesn't expand `$`
  in the prompt body.
- 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`).
- `--prompt-file <path>` also takes a real file if you'd rather write the prompt
  to your scratchpad first; it's mutually exclusive with `--prompt`.

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.