| name | handoff |
| description | Creates structured handoff documents when a task needs different capability or has failed after retries. Use when flagging tasks for another session or model, after 2 failed fix attempts, or when architecture decisions are needed. Invoke for handoff, escalation, blocked task, failed attempts, or capability mismatch. |
| license | MIT |
| metadata | {"author":"local","version":"1.0.0","domain":"workflow","triggers":"handoff, escalation, blocked, failed attempts, needs different model, architecture decision","role":"coordinator","scope":"workflow","output-format":"markdown","related-skills":"execute, kickoff"} |
Handoff
Packages a task for another session or model when current capability is insufficient.
Core Workflow
- Identify trigger -- Determine why a handoff is needed (see trigger table)
- Write file -- Create
.agents/handoffs/YYYYMMDD-slug.md using the template
- Update index -- Append to
.agents/handoffs/INDEX.md
- Report -- Show the handoff flag in chat
- Continue -- If non-blocking, keep working on next available task
Trigger Conditions
| Condition | Type | Blocking |
|---|
| 2 failed fix attempts | ANALYSIS | YES |
| Architecture/design decision needed | PLANNING | NO |
| New feature not in blueprint | PLANNING | NO |
| Next tasks are pure boilerplate | EXECUTION | NO |
| No blueprint yet | PLANNING | YES |
Handoff File Template
# HANDOFF: [title]
Date: [DATE] | Type: [PLANNING/ANALYSIS/EXECUTION] | Blocking: [Y/N] | Status: PENDING
## Why
[One paragraph: what was hit, why it needs different capability]
## Context
- Blueprint phase: [N], task: [N.X]
- Branch/worktree: [X]
- Key files: [list]
## Prompt (copy-paste to next session)
---
Read AGENTS.md and .agents/CONTEXT.md first.
[Exact task. Be specific: files, functions, constraints, expected output.]
When done: mark this handoff RESOLVED and write resume point.
---
## What's Done / What to Protect
- Done: [list]
- Don't touch: [list]
## Resolution
Resolved by: -- | Date: -- | Summary: -- | Resume at: --
Constraints
MUST DO
- Be specific about files, functions, and constraints in the prompt
- Update the handoff INDEX.md
- Continue working on non-blocking tasks after writing handoff
MUST NOT DO
- Prescribe which model should handle the handoff
- Stop working entirely for non-blocking handoffs
- Write vague or incomplete prompts
