handoff

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

1. Identify trigger -- Determine why a handoff is needed (see trigger table)
2. Write file -- Create .agents/handoffs/YYYYMMDD-slug.md using the template
3. Update index -- Append to .agents/handoffs/INDEX.md
4. Report -- Show the handoff flag in chat
5. 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