Skip to content

damus-io/notedeck / .claude/skills/handoff

handoff

Verified

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 autowork <task>` also branches the new session off the `autowork` branch and has it land its commit there.

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 the session's title, so it's identifiable in agentium list, and set it with --title rather than letting it derive from the first message. If the task is a headway card, the title is the card's full ref, --title headway:<board>/<word-id>: Dave's session list draws a ref title as the card's inline chip, so the row shows the card's live title and a click on it opens the card. Otherwise, a terse summary of the task (a few words).
  • If the task is a headway card, link the session to it with --issue-url headway:<board>/<word-id> (the full ref, never a bare word-id — the CLI rejects one). The card is then recorded on the session itself, so agentium show names it and s on the session in Dave opens it.
  • If the invocation includes autowork (/handoff autowork <task>, or --autowork), the new session works on the autowork branch. Follow autowork: land on the autowork branch below. Don't put the word in the task prompt.
  • If the new session should investigate and get approval before writing code, pass --permission-mode plan. Writing "start in plan mode" in the prompt does not work: the session's backend has already launched in the host's default mode by the time it reads that first message. The flag is the only thing that actually sets it.

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.

Write the prompt to a file first, with the Write tool, in your scratchpad (e.g. <scratchpad>/handoff-prompt.md). Then spawn with --prompt-file <path>. --ref waits (bounded) for the host's answer and prints only the new session's agentium: ref, so a plain $(...) captures it:

ref=$(agentium spawn --successor --title "<title>" --prompt-file <scratchpad>/handoff-prompt.md --ref)
echo "$ref"

Never put a heredoc inside $(...), and never compose the prompt in the shell at all. macOS's /bin/bash is 3.2, which finds the end of a $(...) by matching parens and doesn't skip heredoc bodies, quoted delimiter or not. The first stray ) in the prompt (a 1) list item) or apostrophe (don't) ends the substitution. The new session gets the prompt cut there, and the rest of the prompt runs as shell: backticked commands in it really execute. A file read by agentium is never parsed by the shell.

When the task is a headway card, <title> is its ref and --issue-url headway:<board>/<word-id> links it too; add --permission-mode plan when the task should be investigated and approved before any code is written.

--successor records the new session as carrying this one's work on: its state names this session as parent-session with relation successor, which is how Dave's list and scene draw the handoff.

3. Check the whole prompt arrived

spawn prints a receipt on stderr, prompt: <n> bytes, <m> lines, last line: "…". Its last line must be your file's last line. Then confirm the session got it:

agentium log "$ref" --role user -n 1 --no-pager

The message it shows must end with your prompt's last line (the host delivers it when the session comes up, so give a fresh session a few seconds). If the end is missing, send the missing lines from the file. $(sed …) reading a file is safe; only a heredoc inside $(...) is not:

agentium send "$ref" "$(sed -n '<first missing line number>,$p' <scratchpad>/handoff-prompt.md)"

That's the whole handoff. Notes:

  • 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).
  • --ref fails, printing nothing on stdout, when the host doesn't answer in time. The spawn command and its prompt were still published, so run agentium list before spawning again; never re-run blind.
  • An agentium older than --ref rejects it as an unknown flag. Use --wait --json piped straight into jq -r .session instead (still with --prompt-file <path>, still no heredoc).

autowork: land on the autowork branch

/handoff autowork gives the new session the same branch discipline as an autowork chain lane: it starts from autowork and, when its commit is done, fast-forwards autowork onto it. The mechanics live in the autowork skill's Parallel chains section (~/.claude/skills/autowork/SKILL.md): autowork is never checked out, the main worktree's branch belongs to the user, and the Land block moves autowork with a compare-and-swap update-ref. Point at that block; don't copy it here or into the prompt.

Before spawning, in this session:

  1. Commit your own work first, and land it with that Land block. The new session's first step is a rebase of this worktree. A dirty tree makes that rebase fail. A commit you make after the rebase reaches autowork only when the next session lands.
  2. Check that autowork is free: git worktree list | grep -q '\[autowork\]' must find nothing. If the branch doesn't exist yet, the Land block creates it from the main worktree's branch.
  3. Check that the tree is clean: git status --porcelain prints nothing. If it prints anything that isn't yours, someone else has work in this worktree. Hand off into another worktree with --cwd, or ask the user. Never stash it.

Then append this paragraph to the task prompt, after the task itself:

Branch: this handoff works on `autowork`. Before you change anything, rebase this
worktree's branch onto it (`git rebase autowork`); if that fails, stop and report. When
your commit passes the repo's checks, land it on `autowork` with the *Land* block in the
*Parallel chains* section of ~/.claude/skills/autowork/SKILL.md. Read that block from
the file; do not invoke the `autowork` skill, since this is not a chain. Quote the landed
hash in the card's done comment and pass it to `headway review --commit`.

The spawned session doesn't load any skill, so this paragraph is the only way it learns about the branch. It names the block instead of restating it, so the rules stay in one place.

A --wait timeout does NOT mean nothing was created

spawn publishes the command before it starts waiting. So a timeout means "we didn't see the host's answer in time" — not "nothing happened". A slow host still materializes the session and still delivers the --prompt, because the prompt rides the command.

Never re-run the spawn on a timeout. Check first:

agentium list --cwd "$(pwd)"

If the session is there, the handoff worked — take its ref and report it. Only if nothing appeared is it worth suspecting no Dave host is running on the target host (or that --cwd is wrong).

Re-running is also guarded now, not just discouraged: an identical spawn within ten minutes is refused before publishing, naming the session it would have duplicated, and a host that does see a repeat answers it with the session it already made. --allow-duplicate overrides the guard when you genuinely want a second session in the same worktree. Treat the guard as a backstop, not a licence to retry blindly — check list first.

4. 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, build and publish the explainer (visual-explainer skill), headway review <card> --explainer <url>, then the done comment with the hash, title and explainer URL, and move the card. The handoff doesn't excuse leaving the current work half-done.

After an autowork handoff, your commit is already landed (step 1 above), and the new session may already have moved this worktree's HEAD. So pass your landed hash to headway review <card> --commit <hash> instead of relying on its HEAD default.

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.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall