paseo-handoff

A user-invocable procedure for handing the current task off to a fresh agent with a complete, self-contained briefing. Because the receiving agent starts with zero context, the skill's core deliverable is a handoff prompt that captures everything needed to continue the work. It triggers on phrases like handoff, hand off, or hand this to.

As prerequisites, it reads the companion paseo skill and, unless the user names a provider explicitly, consults ~/.paseo/orchestration-preferences.json before choosing where to send the work. Argument parsing resolves three things: the provider (explicit request first, otherwise the impl preference, or ui for styling-only tasks), whether to create a worktree (a short branch name derived from the task, branched off the current branch), and the free-text task description.

The handoff prompt follows a fixed template with sections for Task (imperative), Context, Relevant files (each annotated with why it matters), Current state, What was tried (and why it failed), Decisions with rationale, Acceptance criteria, and Constraints. A key rule is preserving task semantics: an investigate-only task must instruct not to edit files, a fix must say to implement the fix, and a refactor must remain a refactor, carrying the user's exact intent.

Launch happens through Paseo with a [Handoff] title, the briefing as the initial prompt, and a detached relationship. Workspace placement varies: current for no worktree, a create/worktree form for a new branch-off, or existing for a pre-created worktree, with a caution against using current with a worktree cwd. Handoff agents are siblings or root agents, not subagents, so they survive the caller being archived; notifyOnFinish is left off unless requested, and the skill returns the new agent's ID and how to follow along rather than waiting.