| name | cross-agent-handoff |
| description | Transfer context between AI agent sessions with structured handoff protocols, state serialization, and decision log preservation. Covers multi-agent coordination, context compression, and continuity patterns. Triggers on agent handoff, session transfer, or multi-agent continuity requests. |
| license | MIT |
| complexity | intermediate |
| time_to_learn | 30min |
| tags | ["agent-handoff","context-transfer","multi-agent","session-continuity","coordination"] |
| governance_phases | ["prove"] |
| organ_affinity | ["all"] |
| triggers | ["user-asks-about-agent-handoff","context:session-transfer","context:multi-agent","context:agent-continuity"] |
| complements | ["session-lifecycle-patterns","agent-swarm-orchestrator","prompt-engineering-patterns"] |
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
Context Compression
Summarization Levels
| Level | Token Budget | Content |
|---|
| Full | Unlimited | Complete handoff document |
| Standard | ~2000 tokens | State + Decisions + Next Actions |
| Minimal | ~500 tokens | Current state + Next action only |
| Emergency | ~100 tokens | "Continue from step X of plan Y" |
Compression Strategy
def compress_handoff(handoff: dict, target_tokens: int) -> str:
if target_tokens > 2000:
return format_full_handoff(handoff)
elif target_tokens > 500:
return format_standard_handoff(handoff)
elif target_tokens > 100:
return f"""
Continue {handoff['task']}. Phase: {handoff['phase']}.
Completed: {', '.join(handoff['completed'][:5])}.
Next: {handoff['next_actions'][0]}.
Key constraint: {handoff['constraints'][0]}.
"""
else:
return f"Continue {handoff['task']} from step {handoff['next_step']}. Plan: {handoff['plan_path']}"
Multi-Agent Coordination
Parallel Agent Handoff
When multiple agents work simultaneously:
coordination:
task: "Skill Fortification Campaign"
agents:
- id: agent-a
scope: "Stream A: Engineering Infrastructure"
owns: [skills/development/*-patterns/]
status: in_progress
- id: agent-b
scope: "Stream B: Governance & Process"
owns: [skills/tools/*, skills/documentation/*]
status: in_progress
shared_state:
completed_skills: ["A1", "A2", "A3"]
pending_skills: ["A4", "A5", "A6"]
conflict_zones:
- path: .build/skills-registry.json
rule: "Only one agent refreshes at a time"
- path: ecosystem.yaml
rule: "Coordinate updates"
Conflict Prevention
OWNERSHIP_RULES = {
"exclusive": "Only one agent modifies this path",
"append_only": "Multiple agents can add, none can modify existing",
"coordinator_only": "Only the coordinator agent modifies this",
}
def check_conflict(agent_id: str, file_path: str, agents: list[dict]) -> bool:
for agent in agents:
if agent["id"] != agent_id and file_path in agent.get("owns", []):
return True
return False
Handoff Triggers
| Trigger | Action |
|---|
| Context window 80% full | Start compression, prepare handoff |
| Task phase complete | Write handoff document at phase boundary |
| Error threshold exceeded | Handoff with error log and attempted fixes |
| Time limit approaching | Save state and produce next-actions list |
| Explicit user request | Full handoff with all context |
Recovery Patterns
From Incomplete Handoff
## Recovery Protocol
1. Read the last handoff document
2. Verify current file system state matches "Current State"
3. If mismatch: investigate git log for changes since handoff
4. Re-verify key decisions still hold
5. Continue from "Next Actions"
From Missing Handoff
## Cold Start Protocol
1. Read the plan file (.Codex/plans/*)
2. Check git log for recent session activity
3. Inventory what exists vs what the plan requires
4. Infer current progress from file existence
5. Ask user to confirm before continuing
Anti-Patterns
- No handoff document — Every session that might continue must produce one
- Handoff without decisions — Raw state is useless without rationale
- Over-compressed context — Better to have a verbose handoff than lose critical context
- Handoff to file only — Also summarize in conversation so user has visibility
- No conflict zones — Parallel agents will corrupt shared state without coordination
- Assuming continuous context — Always verify state at session start
