handoff-protocol

Handoff Protocol — Interaction Records

The unified canonical artifact for all consequential agent exchanges. Every handoff, consultation, escalation, review, or capability request produces an Interaction Record.

Rule: Peer messages that don't produce a record are ephemeral and cannot be relied upon for decisions. If two agents agree on something that affects the system, it MUST be written into an Interaction Record before the change is committed.

The Interaction Record (canonical)

Use the same template regardless of transport (Agent Teams or orchestrator-mediated).

## Interaction Record
| Task ID       | [DEPT-NNN, e.g., ENG-042] |
| Type          | [consultation \| handoff \| review \| escalation \| capability-request] |
| From          | [sender agent name] |
| To            | [receiver agent name or orchestrator] |
| Transport     | [agent-teams \| orchestrator-mediated] |
| Risk Class    | [low \| medium \| high] |
| Timestamp     | [ISO 8601] |

### Context
[What's been done, relevant files, current state. Be specific — the receiver cold-reads this.]

### Request
[Specific ask — what the sender needs from the receiver. One sentence if possible.]

### Constraints
[Timeline, technical limits, dependencies, files that must not be touched.]

### Evidence Bundle
[Risk-class-appropriate evidence — see Evidence Bundles section below.]

### Decision
[Filled by the receiver: what was decided, rationale, next steps. Left blank when sending.]

Interaction Types

1. handoff — transfer of work between agents

Use when work is being passed forward. Include complete context, deliverable request, and acceptance criteria in the Context and Request sections.

2. consultation — peer asking for input without transferring ownership

Use when an agent wants a peer's opinion on an approach, API contract, or design choice. Ownership stays with the sender. Peer may propose, not commit.

## Interaction Record
| Task ID | ENG-042 |
| Type | consultation |
| From | backend-engineer |
| To | security-engineer |
| Transport | agent-teams |

### Context
Implementing OAuth2 PKCE flow for the /auth endpoint. JWT session currently in place.

### Request
Is the code_verifier length of 43 chars sufficient, or should I use the 128-char max?

### My Proposal
43 chars (minimum per RFC 7636) — keeps URL shorter, still entropic.

3. review — formal review of completed work

Use when submitting work for QA or reality-check. Must include Evidence Bundle matching the risk class.

4. escalation — agent stuck, needs reroute

Use when the agent has hit a wall. Must classify the failure type:

| Failure Type | Meaning | Orchestrator Action | |---|---|---| | wrong-capability | Agent needed different expertise | Reroute to matching capability | | task-too-large | Scope expanded beyond assignment | Decompose into subtasks | | conflicting-requirements | Spec contradicts code or other spec | Escalate to product/PM for clarity | | environment-issue | Infra/tooling broken, not task logic | Route to devops/sre | | insufficient-context | Agent needs info only another agent has | Route to knowledge holder | | unknown | Can't classify — describe symptoms | Orchestrator investigates |

## Interaction Record
| Task ID | ENG-042 |
| Type | escalation |
| From | backend-engineer |
| To | enterprise-orchestrator |

### Context
Attempted OAuth2 PKCE implementation. Blocked on Supabase JWT signing key rotation strategy.

### Request
Failure Type: wrong-capability
Need: security-engineer with auth+oauth2+supabase qualifiers

### Evidence Bundle
- Files attempted: src/auth/middleware.ts, src/auth/oauth.ts
- Error: "JWT signature verification failed after key rotation"
- What I tried: (1) single static key — works but rotates fail (2) kid-based lookup — key not found in JWKS

5. capability-request — agent needs a peer with specific expertise

Use when the agent doesn't need escalation but does need a specific capability. Lighter weight than an escalation — typically same-priority routing.

## Interaction Record
| Task ID | ENG-042 |
| Type | capability-request |
| From | backend-engineer |
| To | enterprise-orchestrator |

### Request
Capability needed: design-system + [tokens, dark-theme]
Reason: Need hex values for error state background in dark mode to render in email templates.
Urgency: non-blocking

Evidence Bundles by Risk Class

Evidence requirements are conjunctive (AND, not OR). Each risk class lists the minimum items that MUST be present. "Or" is not allowed — every listed item is required.

Low Risk

Triggers: docs, comments, config tweaks, typo fixes, small internal refactors. No reviewer required — orchestrator accepts on evidence completeness alone.

Required evidence (ALL of):

• File paths changed
• Brief description of change (≤3 sentences)

Medium Risk

Triggers: new features, refactors, API changes, schema additions. Reviewer: qa-engineer by default. If qa-engineer authored the work, use reality-checker. If both unavailable, orchestrator reviews directly.

Required evidence (ALL of):

• File paths changed
• Test output mapped to acceptance criteria (which test verifies which criterion)
• Before/after behavior description
• Any migrations or breaking-change notes

High Risk

Triggers: security changes, auth/session code, payments, data mutations at scale, database migrations, RLS policy changes, external API credentials, env var changes. Reviewer: reality-checker by default. Backup: security-engineer (if reality-checker authored the work or is unavailable). Cannot be auto-approved — if no reviewer available, task blocks and orchestrator reports to user. Waiver only by explicit user instruction ("ship it without review").

Required evidence (ALL of):

• File paths changed
• Test output mapped to acceptance criteria
• Security implications analysis (what attack surface is affected)
• Rollback plan (exact commands or steps to revert)
• Reviewer sign-off (the reviewer's Interaction Record Decision section filled)
• Before/after behavior description

Risk Reclassification

Risk is classified at dispatch AND re-evaluated on completion.

Upgrade LOW → MEDIUM if:

• More than 3 files changed
• Any test file modified
• Any API route modified

Upgrade MEDIUM → HIGH if:

• Any auth/security file touched (middleware, permissions, RLS)
• Any database migration created
• Any payment/billing code modified
• Any env var added or changed
• Any external credential reference added

If reclassified:

1. Apply the higher risk class's evidence requirements retroactively
2. If evidence is insufficient for new risk class → send back for additional evidence
3. Document the reclassification in the Interaction Record's Decision section

File Scope Declaration (Task ID Gating)

Every task receives a file scope from the orchestrator at dispatch:

## Task Assignment
| Task ID | ENG-042 |
| Assigned to | backend-engineer |
| Expected file scope | [src/auth/middleware.ts, src/auth/oauth.ts, tests/auth/*.test.ts] |
| Risk Class | medium |

Rules:

• The agent MAY modify files in the declared scope
• The agent MUST file a scope-expansion Interaction Record before touching any undeclared file
• On completion, orchestrator verifies every changed file was either declared OR had an approved scope-expansion record
• Undeclared changes → work rejected, agent must revert or file the expansion record

Scope expansion record:

## Interaction Record
| Task ID | ENG-042 |
| Type | consultation |
| From | backend-engineer |
| To | enterprise-orchestrator |

### Request
Scope expansion: need to also modify src/middleware/cors.ts because OAuth redirect URI changed.
This is a 3-line config update, not logic.

Agent Teams Authority Boundaries

When `CLAUDE_CODE_EX