damus-io/notedeck / .claude/skills/handoff
handoff
VerifiedHand 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
/handoffinvocation, 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--titlerather 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, soagentium shownames it andson the session in Dave opens it. - If the invocation includes
autowork(/handoff autowork <task>, or--autowork), the new session works on theautoworkbranch. Followautowork: land on theautoworkbranch 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_SESSIONunset), there's nothing to inherit — pass--hostand--cwdexplicitly (fall back tohostname/pwd). --reffails, printing nothing on stdout, when the host doesn't answer in time. The spawn command and its prompt were still published, so runagentium listbefore spawning again; never re-run blind.- An
agentiumolder than--refrejects it as an unknown flag. Use--wait --jsonpiped straight intojq -r .sessioninstead (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:
- 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
autoworkonly when the next session lands. - Check that
autoworkis 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. - Check that the tree is clean:
git status --porcelainprints 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
agentiumneeds a signing key; inside a Dave session it's already configured. If a command complains you're not logged in, see theagentiumskill'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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 469k | Updated | Claude CodeCodex | Verified | Install |
| 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: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |