Handoff Skill

You are handing off the current task to another agent. Your job is to write a comprehensive handoff prompt and launch the agent via Paseo CLI.

User's arguments: $ARGUMENTS

Prerequisites

Load the Paseo skill first — it contains the CLI reference for all agent commands.

What Is a Handoff

A handoff transfers your current task — including all context, decisions, failed attempts, and constraints — to a fresh agent that will carry it to completion. The handoff prompt is the most important part: the receiving agent starts with zero context, so everything it needs must be in the prompt.

Parsing Arguments

Parse $ARGUMENTS to determine:

Provider and model — who to hand off to
Worktree — whether to run in an isolated git worktree
Task description — any additional context the user provided

Provider Resolution

User says	Provider	Model	Mode
(nothing)	`codex`	`gpt-5.4`	`full-access`
`codex`	`codex`	`gpt-5.4`	`full-access`
`claude`	`claude`	`opus`	`bypass`
`opus`	`claude`	`opus`	`bypass`
`sonnet`	`claude`	`sonnet`	`bypass`

Default is Codex with gpt-5.4.

Worktree Resolution

If the user says "in a worktree" or "worktree", add --worktree with a short descriptive branch name derived from the task. Worktrees require a --base branch — use the current branch in the working directory (run git branch --show-current to get it).

Writing the Handoff Prompt

This is the critical step. The receiving agent has zero context about your conversation. The handoff prompt must be a self-contained briefing document.

Must Include

Task description — What needs to be done, in clear imperative language
Task qualifiers — Preserve the semantics of what the user asked for:
- If the user asked to investigate without editing, say "DO NOT edit any files"
- If the user asked to fix, say "implement the fix"
- If the user asked to refactor, say "refactor" not "rewrite"
- Carry forward the exact intent
Relevant files — List every file path that matters, with brief descriptions of what each contains
Current state — What has been done so far, what's working, what's not
What was tried — Any approaches attempted and why they failed or were abandoned
Decisions made — Anything you and the user agreed on (design choices, constraints, trade-offs)
Acceptance criteria — How the agent knows it's done
Constraints — Anything the agent must NOT do

Template

## Task

[Clear, imperative description of what to do]

## Context

[Why this task exists, background the agent needs]

## Relevant Files

- `path/to/file.ts` — [what it does and why it matters]
- `path/to/other.ts` — [what it does and why it matters]

## Current State

[What's been done, what works, what doesn't]

## What Was Tried

- [Approach 1] — [why it failed/was abandoned]
- [Approach 2] — [partial success, but...]

## Decisions

- [Decision 1 — rationale]
- [Decision 2 — rationale]

## Acceptance Criteria

- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Constraints

- [Do not do X]
- [Must preserve Y]

Launching the Agent

Default (Codex, no worktree)

paseo run -d --mode full-access --provider codex --name "[Handoff] Task description" "$prompt"

Claude (Opus, no worktree)

paseo run -d --mode bypass --model opus --name "[Handoff] Task description" "$prompt"

Codex in a worktree

base=$(git branch --show-current)
paseo run -d --mode full-access --provider codex --worktree task-branch-name --base "$base" --name "[Handoff] Task description" "$prompt"

Claude in a worktree

base=$(git branch --show-current)
paseo run -d --mode bypass --model opus --worktree task-branch-name --base "$base" --name "[Handoff] Task description" "$prompt"

After Launch

Print the agent ID and the command to follow along:

Handed off to [provider] ([model]). Agent ID: <id>
Follow along: paseo logs <id> -f
Wait for completion: paseo wait <id>

Do not wait for the agent by default — the user can choose to wait or move on.
If the user wants to wait, run paseo wait <id> and then paseo logs <id> when done.

paseo-handoff