Handoff Skill

Prerequisites

What Is a Handoff

Parsing Arguments

$ARGUMENTS

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

Provider Resolution

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

gpt-5.4

Worktree Resolution

--worktree

--base

git branch --show-current

Writing the Handoff Prompt

Must Include

1. Task description — What needs to be done, in clear imperative language
2. 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
3. Relevant files — List every file path that matters, with brief descriptions of what each contains
4. Current state — What has been done so far, what's working, what's not
5. What was tried — Any approaches attempted and why they failed or were abandoned
6. Decisions made — Anything you and the user agreed on (design choices, constraints, trade-offs)
7. Acceptance criteria — How the agent knows it's done
8. 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

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

2. Do not wait for the agent by default — the user can choose to wait or move on.
3. If the user wants to wait, run

   paseo wait <id>

   and then

   paseo logs <id>

   when done.