| name | upaseo-handoff |
| description | Hand off the current task to another agent with full context. Use when the user says "handoff", "hand off", "hand this to", or wants to pass work to another agent. |
Handoff Skill
Transfer the current task — context, decisions, failed attempts, constraints — to a fresh agent. The receiving agent starts with zero context, so the handoff prompt must be a self-contained briefing.
User's arguments: $ARGUMENTS
Prerequisites
Read the upaseo skill — provider for the receiving agent comes from orchestration preferences unless the user names one.
前置避障读取
执行标准避障前置读取，见 upaseo/references/learnings-precheck.md。本技能相关 category 为 command_error|tool_misuse。若提炼出避障规则，注入到 handoff prompt 的 ## 避障规则 段落中(格式见 reference §1);无规则则省略该段落。
上下文移交文档
启动接收 Agent 前，必须先创建一份上下文移交文档，作为本次 handoff 的 Source of Truth。
- 路径：
<项目根目录>/.paseo/handoffs/<YYYYMMDD-HHMM>-<short-task-slug>.md
- 若
.paseo/handoffs/ 不存在，先创建目录。
- 文档内容必须使用下方
The handoff prompt 的同一结构，完整记录任务、上下文、相关文件、当前状态、已尝试方案、决策、验收标准和约束。
- 文档头部必须声明
Priority: handoff（见 upaseo/SKILL.md "Source-of-Truth Priority Chain"），表示本文件在 SoT 链中位列 handoff 层：现场状态/任务语义以本文件为准，但 goal 边界与验收约束不可被覆盖；若同时存在 compact 文档，compact 优先。
- 创建接收 Agent 时，handoff prompt 必须包含该文档绝对路径，并要求接收 Agent 第一步读取它。
- 对话里的简短说明不能替代该文档；文档才是交接事实源。
Parsing arguments
- Provider — explicit user request first; otherwise resolve from
impl preference (or ui if the task is styling-only). UI/styling 任务的 provider 从 orchestration-preferences.json 的 ui 分类解析；本项目 ui 已 pin 到 codex/gpt-5.5（未配置时回退 codex/gpt-5.5，详见 upaseo/SKILL.md）。
- Worktree — "in a worktree" / "worktree" → use or create a worktree via Paseo.
- If the caller already supplied a concrete worktree path, or the current cwd is already the target worktree, do not create another worktree. Use that path as the receiving agent cwd.
- Only create a new worktree when the user requested worktree isolation and no existing worktree path/cwd was provided.
- When creating a new worktree, use a short branch name derived from the task, based on the current branch.
- Task description — anything else the user said.
The handoff prompt
The receiving agent has zero context. Include:
Priority: handoff
## Task
[Imperative description.]
## Context
[Why this task exists, background needed.]
## 上下文文件（首步必须读取）
- Handoff 移交文档：`<项目根目录>/.paseo/handoffs/<handoff>.md` — 接收后第一步读取（用当前宿主的文件读取原语，见 `upaseo/SKILL.md` 宿主工具兼容小节）
- 迭代设计文档：`<绝对路径>` — 若存在，接收后第一步读取（同上）
- 主计划文件：`<绝对路径>` — 按需读取
- 避障学习记录：`<项目根目录>/.paseo/learnings.jsonl` — 按需读取
严禁跳过 Handoff 移交文档。若 handoff prompt 提供了迭代设计文档，严禁跳过该文档读取；若本次 handoff 没有迭代设计文档，必须在报告中明确“无迭代设计文档，按 handoff 文档执行”。严禁基于口头转述猜测行事。
## 避障规则（来自历史教训，必须严格遵守）
- <规则1>
- <规则2>
(若无 learnings.jsonl 则省略本段落)
## Relevant files
- `path/to/file.ts` — [what it is and why it matters]
## Current state
[What's done, what works, what doesn't.]
## What was tried
- [Approach] — [why it failed or was abandoned]
## Decisions
- [Decision — rationale]
## Acceptance criteria
- [ ] [Criterion]
## Constraints
- [Must-not / must-preserve]
Preserve task semantics. Investigate-only → "DO NOT edit files." Fix → "implement the fix." Refactor → "refactor, not rewrite." Carry the user's exact intent.
Launch
Create the agent via Paseo with a [Handoff] <task> title, the briefing as initial prompt, and cwd set to the worktree path if --worktree. Pass background: true and notifyOnFinish: true so the receiving agent reports back asynchronously.
Don't wait by default — the user decides whether to follow along or move on. Tell them the agent ID and how to follow along (the upaseo skill explains).
完工通知：handoff 完成后向 Orchestrator 汇报接收 Agent 的 agentId 及 status。
