cross-agent-handoff

Cross-Agent Handoff

Transfer work between agent sessions without losing context, decisions, or progress.

The Handoff Problem

When an agent session ends (context limit, task change, timeout), work must continue. Without a structured handoff, the next agent:

• Re-explores already-understood code
• Re-makes already-decided decisions
• Contradicts previous agent's approach
• Misses critical constraints discovered earlier

Handoff Document Structure

# Agent Handoff: {task-name}

**From:** Session {id} | **Date:** {date} | **Phase:** {current-phase}

## Current State
{What exists right now — files created, branches, test status}

## Completed Work
{What was accomplished, with evidence}
- [x] Created skills/development/python-packaging-patterns/SKILL.md
- [x] Created skills/development/cli-tool-design/SKILL.md
- [ ] Wave 1 skills (not started)

## Key Decisions
{Decisions made and WHY — so next agent doesn't re-litigate}
| Decision | Rationale |
|----------|-----------|
| Used governance_norm_group: repo-hygiene for packaging skills | Packaging is infrastructure hygiene, not quality-gate |
| Put data-backup-patterns in development/ not security/ | It's an engineering pattern, security-baseline applies via norm_group |

## Critical Context
{Non-obvious information the next agent needs}
- The ecosystem.yaml shows 130+ skills target, currently at 101
- Governance metadata format: governance_phases, governance_norm_group, organ_affinity, triggers, complements
- Bundle skills use `includes:` field listing constituent skill names

## Next Actions
{Exactly what to do next, no ambiguity}
1. Create Wave 1 skills: fastapi-patterns, database-migration-patterns, ...
2. After all waves: run refresh_skill_collections.py
3. Then validate with validate_skills.py --collection example --unique

## Risks & Warnings
{Things that could go wrong}
- Skill name must match directory name exactly
- .build/ artifacts must be refreshed after skill changes
- 16GB RAM constraint: max 4-6 concurrent agents