Handoff Protocol

Part of Ydun AI Workflow

This guide is part of the complete AI workflow toolkit.

Get the toolkit Installation guide

AI instances do not share context. Every handoff is a fresh start for the receiver. The quality of the handoff determines the quality of the next step. A good handoff gives the receiver everything they need to continue without asking questions. A bad handoff wastes context window on clarification.

The core principle

Summarise the state, not the journey.

Context windows are finite. The receiver does not need to know every decision you considered, every approach you tried, or every file you read. They need to know:

1. What was done
2. What remains
3. What questions are open
4. What the next step is

Everything else is noise.

Handoff template

Use this template for every handoff between instances. Copy it, fill it in, attach it to the work.

## Handoff: [Task Name]

**From:** [Your role]
**To:** [Recipient role]
**Date:** [ISO date, e.g., 2026-03-06]
**File:** [Filename if applicable]

### Summary
[Current state of the work. What exists now. Not how you got here.]

### Status
- [x] [Completed item]
- [x] [Completed item]
- [ ] [Remaining item]
- [ ] [Remaining item]

### Open Questions
- [Uncertainty that needs resolution]
- [Decision that needs human input]

### Next Steps
- [What the recipient should do first]
- [What the recipient should do second]

What makes a good summary

Bad summary (journey)	Good summary (state)
“I started by reading the auth module, then tried three approaches to the token validation, eventually settling on JWT verification with RS256…"	"Auth module uses JWT with RS256. Token validation is implemented and tested. Refresh token flow is not yet built."
"After investigating the performance issue, I profiled the database queries and found that the N+1 problem was causing slowdowns…"	"Database queries have N+1 problem on the user endpoint. Fix: add eager loading for the roles association. Not yet implemented.”

The first column wastes tokens on narrative. The second column gives the receiver everything they need.

File naming convention

For file-based handoffs (specifications, research, status updates), use a structured naming convention that makes priority, sender, and recipient immediately visible.

Format: [PRIORITY]-[FROM]-[TO]-[PROJECT]-[DESCRIPTION].[ext]

Priority levels

Priority	Meaning	Expected response time
P1	Urgent — blocks other work	Immediate
P2	Normal — standard workflow	Within current work cycle
P3	Low — informational, no urgency	Next convenient opportunity

Role abbreviations

Define short abbreviations for each team role. Keep them consistent across all handoffs.

Example role	Abbreviation
Lead / Human	LEAD
Coordinator	COORD
Developer	DEV
Infrastructure	INFRA
Security	SEC
Researcher	RESEARCH

Examples

P1-DEV-INFRA-api-deploy-hotfix.md
P2-RESEARCH-DEV-auth-security-spec.md
P2-DEV-COORD-status-update.md
P3-SEC-COORD-weekly-scan-report.md
P1-LEAD-DEV-payment-critical-bug.md

The naming convention means you can sort a handoff directory and immediately see:

• What is urgent (P1 items first)
• Who sent it and who should receive it
• What project and topic it concerns

Status update template

For periodic status reporting rather than task-specific handoffs:

## Status: [Role Name]

**Date:** [ISO date]

### Currently Working On
- [Active task with brief context]
- [Active task with brief context]

### Completed Since Last Update
- [Item with date completed]
- [Item with date completed]

### Blocked / Waiting
- [Item]: [What it's waiting on]
- [Item]: [Who needs to act]

### Needs Attention
- [Escalation with priority level]

When to send status updates

Team size	Frequency	Trigger
2 instances	As needed	When completing a handoff
3-4 instances	Daily	End of work cycle
5+ instances	Daily + on-demand	Scheduled plus any P1 events

Escalation protocol

Not every issue should be handled at the same level. The escalation protocol defines how problems move up the chain.

Priority	Action	Example
P3	Include in next status update	”Dependency X has a minor version mismatch”
P2	Direct handoff to coordinator	”Build fails on the compute server — needs investigation”
P1	Flag to the human lead directly	”Credentials exposed in public repository”

Escalation rules

1. When in doubt, escalate. It is better to flag something unnecessarily than to miss a real problem.
2. Include context. Never escalate with just “something is wrong”. State what, where, and what you have already tried.
3. Suggest next steps. Even if you cannot fix it, propose what should happen.
4. Do not skip levels. P2 goes to the coordinator. P1 goes to the lead. Do not send P3 items directly to the lead.

External sync rule

When your team includes external members (different AI services, human collaborators outside the internal network), significant internal work must be summarised for them.

Rule: Any significant internal iteration — merged pull request, specification change, architectural decision — must generate a handoff summary to the coordinator within 24 hours for relay to the external team.

The external team cannot review what it cannot see. If a major decision happens internally and the external research team does not learn about it, they will continue working with stale assumptions.

Internal event	Required external sync
Merged PR with architectural changes	Summary of what changed and why
Specification updated	New spec or diff of changes
Blocker encountered	Description of blocker and impact
Direction change	Rationale and implications for ongoing work
Milestone completed	Status update with what is now possible

Dead drop pattern

For teams with a strict boundary between external and internal systems (e.g., an air-gapped internal network, or a shared folder between environments), the dead drop pattern provides file-based coordination.

External Environment
      │
      ▼ (file placed in shared location)
  Shared Folder [Dead Drop]
      │
      ▼ (file picked up by coordinator)
  Coordinator → routes to internal team
      │
      ▼ (results placed back in shared location)
  Shared Folder [Dead Drop]
      │
      ▼ (results picked up externally)
External Environment

Flow:

Direction	Action
Inbound	External party places file in shared folder. Coordinator picks up and routes internally.
Outbound	Internal team returns results to coordinator. Coordinator places in shared folder. External party retrieves.

The dead drop pattern works when direct network connectivity between external and internal is not available or not desirable. The shared folder is the only point of contact.

Putting it together

A complete coordination setup combines these elements:

Element	Purpose	Reference
Handoff template	Structured task transfers	This page
File naming convention	Sortable, scannable handoff files	This page
Status updates	Periodic team-wide visibility	This page
Escalation protocol	Problems reach the right level	This page
External sync rule	External team stays informed	This page
Role cards	Each instance knows its job and relationships	Writing Role Cards
Communication norms	Consistent give/receive behaviour	Team Orchestration
Machine specialisation	Right work on right hardware	Multi-Agent Setup

Further reading

• Team Orchestration — The system-level pattern that makes handoffs effective
• Writing Role Cards — How relationship tables drive handoff quality
• Multi-Agent Setup — Architecture patterns for the machines that exchange handoffs