# How Agent Handoffs Work in the Agency Coordination System: The NEXUS Protocol

> Discover how agent handoffs work in the agency coordination system. Learn about NEXUS Handoff Documents, deterministic loops, and retry policies for seamless AI agent transitions.

- Repository: [Michael Sitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents)
- Tags: internals
- Published: 2026-03-09

---

**Agent handoffs in the coordination system rely on standardized NEXUS Handoff Documents that preserve full context and quality gates as work moves between specialized AI agents, orchestrated by the Agents Orchestrator with a deterministic Dev↔QA loop and three-retry escalation policy.**

The `msitarzewski/agency-agents` repository implements a rigor-controlled coordination system that treats agent handoffs as deterministic state transitions rather than informal context dumps. By enforcing strict documentation standards and orchestrator oversight, the system eliminates "context loss"—the primary failure mode in multi-agent pipelines—ensuring that specialized agents can seamlessly continue work started by their predecessors.

## The NEXUS Handoff Document Structure

Every transfer of responsibility begins with a **NEXUS Handoff Document** defined in [`strategy/coordination/handoff-templates.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/handoff-templates.md). This standardized format ensures that receiving agents inherit complete situational awareness without requiring prior conversation history.

### Metadata and Context Preservation

The handoff captures essential routing information and project state to prevent discontinuity. According to the source templates, every document must include:

- **Identity fields**: Who is handing off (From) and who receives (To), including division (e.g., Engineering vs. Testing)
- **Tracking data**: Phase designation, task reference ID, priority level, and ISO timestamps
- **Project context**: Current state description, completed components, and relevant file paths
- **Dependencies and constraints**: Blocking issues, API requirements, and acceptance criteria such as WCAG 2.1 AA compliance

This metadata eliminates ambiguity about work status and prevents agents from re-discovering information already uncovered by predecessors.

### Deliverable Requests and Quality Gates

The **Deliverable Request** section specifies exactly what the next agent must produce, including:
- Functional requirements with checkboxes for verification
- Reference materials (design specs, brand guidelines)
- **Quality expectations**: Required evidence formats (screenshots, audit JSONs), performance thresholds (e.g., ≤2s first paint), and explicit handoff targets

## The Dev↔QA Loop and Orchestrator Role

The coordination system operates as a state machine where the **Agents Orchestrator** (defined in [`specialized/agents-orchestrator.md`](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md) and activated via prompts in [`strategy/coordination/agent-activation-prompts.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/agent-activation-prompts.md)) manages the handoff chain.

### Standard Development Handoffs

For regular development tasks, the workflow follows a strict sequence:

1. A developer agent completes implementation and generates a **Standard Handoff** directed to a QA agent (typically the **Evidence Collector** defined in testing agent files)
2. The orchestrator logs the handoff in the pipeline status report and assigns the next agent
3. The receiving agent consumes the context and produces either a deliverable or a verdict

### QA Verification and PASS/FAIL States

The **Evidence Collector** or specialized QA agents evaluate deliverables against the acceptance criteria specified in the original handoff. They respond using specific templates:

- **PASS handoff**: Indicates the task meets all criteria. The orchestrator marks the task complete and advances to the next backlog item.
- **FAIL handoff**: Lists specific defects and fix instructions, returning the task to the developer agent.

### Retry Logic and Escalation

The orchestrator enforces a **three-retry limit** for any task. If a QA agent returns a **FAIL** verdict:
1. The handoff returns to the original developer with explicit fix instructions
2. The attempt counter increments (e.g., "Attempt 2 of 3")
3. After three failed attempts, the orchestrator generates an **Escalation Report** using the template from [`strategy/coordination/handoff-templates.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/handoff-templates.md)

The escalation document includes failure history, root cause analysis, impact assessment, and recommended resolution strategies (reassignment, decomposition, or approach revision).

## Phase-Gate and Sprint Transitions

Beyond individual tasks, the coordination system handles aggregate state transfers. Specialized handoff templates exist for:
- **Phase Gate handoffs**: Transferring milestone completion states, metrics, and risks between major project phases
- **Sprint handoffs**: Moving sprint backlog status and retrospective findings to the next iteration's agents
- **Incident handoffs**: Routing critical issues to specialized response agents with full context

These transitions reference the coordination matrix defined in [`strategy/nexus-strategy.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/nexus-strategy.md) to ensure agents are wired correctly across the pipeline.

## Implementation Examples

The following examples demonstrate the actual handoff documents used in the coordination system:

### Standard Handoff (Developer to QA)

```markdown

# NEXUS Handoff Document

## Metadata

| Field | Value |
|-------|-------|
| **From** | Frontend Developer (Engineering Division) |
| **To**   | Evidence Collector (Testing Division) |
| **Phase** | Phase 2 — Build UI |
| **Task Reference** | T-1234 |
| **Priority** | High |
| **Timestamp** | 2026-03-09T14:32:00Z |

## Context

**Project**: Nexus Product Page  
**Current State**: Landing page UI component implemented, responsive layout completed.  
**Relevant Files**:
- `src/components/LandingPage.tsx` — React component with Tailwind classes  
- `src/styles/tokens.css` | CSS design‑system tokens  
**Dependencies**: API endpoint `/api/landing-data` must return JSON payload before final QA.  
**Constraints**: Must pass WCAG 2.1 AA contrast on both dark and light themes.

## Deliverable Request

**What is needed**: Fully functional LandingPage component with screenshots for desktop, tablet, mobile.  
**Acceptance criteria**:
- [ ] Component renders without console errors.  
- [ ] Layout matches design tokens (spacing, colors).  
- [ ] Accessibility checklist passes (keyboard navigation, aria labels).  

**Reference materials**:  
- Design spec: `design/specs/landing-page.md`  
- Brand guide: `design/brand-guidelines.md`

## Quality Expectations

**Must pass**: Visual verification, accessibility audit, performance ≤ 2 s first‑paint.  
**Evidence required**: Screenshots for three viewports, Lighthouse audit JSON.  
**Handoff to next**: Evidence Collector – provide QA verdict (PASS/FAIL).

```

*(Source: [`strategy/coordination/handoff-templates.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/handoff-templates.md))*

### QA PASS Verdict

```markdown

# NEXUS QA Verdict: PASS ✅

## Task

| Field | Value |
|-------|-------|
| **Task ID** | T-1234 |
| **Task Description** | Implement LandingPage UI |
| **Developer Agent** | Frontend Developer |
| **QA Agent** | Evidence Collector |
| **Attempt** | 1 of 3 |
| **Timestamp** | 2026-03-09T15:10:12Z |

## Verdict: PASS

## Evidence

**Screenshots**:
- Desktop (1920x1080): `evidence/landing-desktop.png`  
- Tablet (768x1024): `evidence/landing-tablet.png`  
- Mobile (375x667): `evidence/landing-mobile.png`

**Functional Verification**:
- [x] Component renders without errors.  
- [x] All design tokens applied correctly.  
- [x] Keyboard navigation works, aria labels present.

**Accessibility**: Verified contrast ratio ≥ 4.5:1 for all text.  
**Performance**: First Contentful Paint = 1.8 s (≤ 2 s target).

## Notes

No issues detected.  

## Next Action

→ Agents Orchestrator: Mark task complete, advance to next backlog item.

```

*(Source: [`strategy/coordination/handoff-templates.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/handoff-templates.md))*

### Escalation After Exhausted Retries

```markdown

# NEXUS Escalation Report 🚨

## Task

| Field | Value |
|-------|-------|
| **Task ID** | T-5678 |
| **Task Description** | API endpoint for order creation |
| **Developer Agent** | Backend Architect |
| **QA Agent** | API Tester |
| **Attempts Exhausted** | 3/3 |
| **Escalation To** | Agents Orchestrator |
| **Timestamp** | 2026-03-09T17:45:00Z |

## Failure History

### Attempt 1

- **Issues found**: 500 Internal Server Error on valid payload.  
- **Fixes applied**: Added missing input validation.  
- **Result**: FAIL — still 500.

### Attempt 2

- **Issues found**: Null pointer exception in order service.  
- **Fixes applied**: Guarded null reference.  
- **Result**: FAIL — response time > 1 s, still errors.

### Attempt 3

- **Issues found**: Rate limiting header missing, causing client retries.  
- **Fixes applied**: Implemented `Retry‑After` header.  
- **Result**: FAIL — specification compliance still unmet.

## Root Cause Analysis

The endpoint mixes synchronous DB writes with async event publishing, leading to race conditions under load.

## Recommended Resolution

- [ ] **Reassign** to a different Backend Architect with experience in event‑driven services.  
- [ ] **Decompose** the endpoint into two separate services (order creation + event publisher).  
- [ ] **Revise approach** – introduce transactional outbox pattern.

## Impact Assessment

- **Blocking**: Order creation feature in sprint backlog.  
- **Timeline Impact**: +2 weeks to redesign.  
- **Quality Impact**: Current implementation not production‑ready.

## Decision Required

**Decision maker**: Agents Orchestrator  
**Deadline**: 2026‑03‑12

```

*(Source: [`strategy/coordination/handoff-templates.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/handoff-templates.md))*

## Summary

- **Agent handoffs in the coordination system** use deterministic state transitions via the **NEXUS Handoff Document** to preserve full context and prevent information loss.
- The **Agents Orchestrator** manages the pipeline, creating handoffs, assigning specialized agents, and enforcing the three-retry limit defined in [`strategy/coordination/agent-activation-prompts.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/agent-activation-prompts.md).
- **Quality gates** are embedded in handoff templates, requiring the **Evidence Collector** and other QA agents to validate deliverables against specific acceptance criteria before issuing PASS/FAIL verdicts.
- **Escalation Reports** trigger automatically after three failed attempts, providing root cause analysis and resolution options to prevent pipeline stalls.
- **Continuity enforcement** ensures every agent receives the same context data as their predecessors, eliminating rework and maintaining audit trails across [`strategy/coordination/handoff-templates.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/handoff-templates.md).

## Frequently Asked Questions

### What prevents context loss when agents hand off work?

The **NEXUS Handoff Document** structure mandates explicit **Context** sections that capture project state, completed pieces, relevant file paths, dependencies, and constraints. According to the orchestration prompts in [`strategy/coordination/agent-activation-prompts.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/agent-activation-prompts.md), every handoff must carry full context, ensuring receiving agents have identical situational awareness to the handing-off agent without requiring conversation history.

### How does the system handle failed quality checks?

The **Dev↔QA loop** enforces a strict retry policy. When a QA agent (such as the **Evidence Collector**) returns a **FAIL** verdict, the **Agents Orchestrator** routes the handoff back to the developer with specific fix instructions. The system tracks attempts (e.g., "Attempt 2 of 3") and automatically generates an **Escalation Report** after three failures, requiring strategic intervention rather than repeated attempts.

### What triggers an escalation in the coordination system?

An **Escalation Report** triggers when a task exhausts its **three-retry limit** without achieving a **PASS** verdict from QA. The escalation document (defined in [`strategy/coordination/handoff-templates.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/coordination/handoff-templates.md)) includes failure history, root cause analysis, impact assessment, and recommended resolutions such as reassignment or architectural decomposition, requiring the **Agents Orchestrator** to make a strategic decision by a specified deadline.

### Can the handoff system manage large project phases or just individual tasks?

The coordination system supports both granular and aggregate handoffs. While individual tasks use the **Standard Handoff Template**, phase completions and sprint boundaries utilize specialized templates (Phase Gate, Sprint, Incident) that transfer aggregate states, metrics, and risks. These reference the coordination matrix in [`strategy/nexus-strategy.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/nexus-strategy.md) to ensure proper agent wiring across macro-level transitions.