agency-coordination-handoffs

name	agency-coordination-handoffs
description	The Agency Multi-Agent Handoff & QA Verdict Templates: Standardized agent-to-agent work transfers and quality gate checklists.
metadata	{"origin":"TheAgency","division":"strategy"}

Strategy & Runbook Note

Harmonized with ECC Rules: All implementations triggered by this runbook MUST strictly obey the Modular Architecture Hard Rule (5-level decomposition) and Documentation-First Sequential Execution (one micro-task at a time).

---

📋 NEXUS Handoff Templates

Standardized templates for every type of agent-to-agent handoff in the NEXUS pipeline. Consistent handoffs prevent context loss — the #1 cause of multi-agent coordination failure.

---

1. Standard Handoff Template

Use for any agent-to-agent work transfer.

# NEXUS Handoff Document

## Metadata
| Field | Value |
|-------|-------|
| **From** | [Agent Name] ([Division]) |
| **To** | [Agent Name] ([Division]) |
| **Phase** | Phase [N] — [Phase Name] |
| **Task Reference** | [Task ID from Sprint Prioritizer backlog] |
| **Priority** | [Critical / High / Medium / Low] |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Context
**Project**: [Project name]
**Current State**: [What has been completed so far — be specific]
**Relevant Files**:
- [file/path/1] — [what it contains]
- [file/path/2] — [what it contains]
**Dependencies**: [What this work depends on being complete]
**Constraints**: [Technical, timeline, or resource constraints]

## Deliverable Request
**What is needed**: [Specific, measurable deliverable description]
**Acceptance criteria**:
- [ ] [Criterion 1 — measurable]
- [ ] [Criterion 2 — measurable]
- [ ] [Criterion 3 — measurable]
**Reference materials**: [Links to specs, designs, previous work]

## Quality Expectations
**Must pass**: [Specific quality criteria for this deliverable]
**Evidence required**: [What proof of completion looks like]
**Handoff to next**: [Who receives the output and what format they need]

---

2. QA Feedback Loop — PASS

Use when Evidence Collector or other QA agent approves a task.

# NEXUS QA Verdict: PASS ✅

## Task
| Field | Value |
|-------|-------|
| **Task ID** | [ID] |
| **Task Description** | [Description] |
| **Developer Agent** | [Agent Name] |
| **QA Agent** | [Agent Name] |
| **Attempt** | [N] of 3 |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Verdict: PASS

## Evidence
**Screenshots**:
- Desktop (1920x1080): [filename/path]
- Tablet (768x1024): [filename/path]
- Mobile (375x667): [filename/path]

**Functional Verification**:
- [x] [Acceptance criterion 1] — verified
- [x] [Acceptance criterion 2] — verified
- [x] [Acceptance criterion 3] — verified

**Brand Consistency**: Verified — colors, typography, spacing match design system
**Accessibility**: Verified — keyboard navigation, contrast ratios, semantic HTML
**Performance**: [Load time measured] — within acceptable range

## Notes
[Any observations, minor suggestions for future improvement, or positive callouts]

## Next Action
→ Agents Orchestrator: Mark task complete, advance to next task in backlog

---

3. QA Feedback Loop — FAIL

Use when Evidence Collector or other QA agent rejects a task.

# NEXUS QA Verdict: FAIL ❌

## Task
| Field | Value |
|-------|-------|
| **Task ID** | [ID] |
| **Task Description** | [Description] |
| **Developer Agent** | [Agent Name] |
| **QA Agent** | [Agent Name] |
| **Attempt** | [N] of 3 |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Verdict: FAIL

## Issues Found

### Issue 1: [Category] — [Severity: Critical/High/Medium/Low]
**Description**: [Exact description of the problem]
**Expected**: [What should happen according to acceptance criteria]
**Actual**: [What actually happens]
**Evidence**: [Screenshot filename or test output]
**Fix instruction**: [Specific, actionable instruction to resolve]
**File(s) to modify**: [Exact file paths]

### Issue 2: [Category] — [Severity]
**Description**: [...]
**Expected**: [...]
**Actual**: [...]
**Evidence**: [...]
**Fix instruction**: [...]
**File(s) to modify**: [...]

[Continue for all issues found]

## Acceptance Criteria Status
- [x] [Criterion 1] — passed
- [ ] [Criterion 2] — FAILED (see Issue 1)
- [ ] [Criterion 3] — FAILED (see Issue 2)

## Retry Instructions
**For Developer Agent**:
1. Fix ONLY the issues listed above
2. Do NOT introduce new features or changes
3. Re-submit for QA when all issues are addressed
4. This is attempt [N] of 3 maximum

**If attempt 3 fails**: Task will be escalated to Agents Orchestrator

---

4. Escalation Report

Use when a task exceeds 3 retry attempts.

# NEXUS Escalation Report 🚨

## Task
| Field | Value |
|-------|-------|
| **Task ID** | [ID] |
| **Task Description** | [Description] |
| **Developer Agent** | [Agent Name] |
| **QA Agent** | [Agent Name] |
| **Attempts Exhausted** | 3/3 |
| **Escalation To** | [Agents Orchestrator / Studio Producer] |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Failure History

### Attempt 1
- **Issues found**: [Summary]
- **Fixes applied**: [What the developer changed]
- **Result**: FAIL — [Why it still failed]

### Attempt 2
- **Issues found**: [Summary]
- **Fixes applied**: [What the developer changed]
- **Result**: FAIL — [Why it still failed]

### Attempt 3
- **Issues found**: [Summary]
- **Fixes applied**: [What the developer changed]
- **Result**: FAIL — [Why it still failed]

## Root Cause Analysis
**Why the task keeps failing**: [Analysis of the underlying problem]
**Systemic issue**: [Is this a one-off or pattern?]
**Complexity assessment**: [Was the task properly scoped?]

## Recommended Resolution
- [ ] **Reassign** to different developer agent ([recommended agent])
- [ ] **Decompose** into smaller sub-tasks ([proposed breakdown])
- [ ] **Revise approach** — architecture/design change needed
 [ ]  current state with documented limitations
 [ ]  to future sprint


: [What other tasks are blocked by this]
: [How this affects the overall schedule]
: [What quality compromises exist if we accept current state]


: [Agents Orchestrator / Studio Producer]
: [When decision is needed to avoid further delays]

---

5. Phase Gate Handoff

Use when transitioning between NEXUS phases.

# NEXUS Phase Gate Handoff

## Transition
| Field | Value |
|-------|-------|
| **From Phase** | Phase [N] — [Name] |
| **To Phase** | Phase [N+1] — [Name] |
| **Gate Keeper(s)** | [Agent Name(s)] |
| **Gate Result** | [PASSED / FAILED] |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Gate Criteria Results
| # | Criterion | Threshold | Result | Evidence |
|---|-----------|-----------|--------|----------|
| 1 | [Criterion] | [Threshold] | ✅ PASS / ❌ FAIL | [Evidence reference] |
| 2 | [Criterion] | [Threshold] | ✅ PASS / ❌ FAIL | [Evidence reference] |
| 3 | [Criterion] | [Threshold] | ✅ PASS / ❌ FAIL | [Evidence reference] |

## Documents Carried Forward
1. [Document name] — [Purpose for next phase]
2. [Document name] — [Purpose for next phase]
3. [Document name] — [Purpose for next phase]

## Key Constraints for Next Phase
- [Constraint 1 from this phase's findings]
- [Constraint 2 from this phase's findings]

## Agent Activation for Next Phase
| Agent | Role | Priority |
|-------|------|----------|
| [Agent 1] | [Role in next phase] | [Immediate / Day 2 / As needed] |
| [Agent 2] | [Role in next phase] | [Immediate / Day 2 / As needed] |

## Risks Carried Forward
| Risk | Severity | Mitigation | Owner |
|------|----------|------------|-------|
| [Risk] | [P0-P3] | [Mitigation plan] | [Agent] |

---

6. Sprint Handoff

Use at sprint boundaries.

# NEXUS Sprint Handoff

## Sprint Summary
| Field | Value |
|-------|-------|
| **Sprint** | [Number] |
| **Duration** | [Start date] → [End date] |
| **Sprint Goal** | [Goal statement] |
| **Velocity** | [Planned] / [Actual] story points |

## Completion Status
| Task ID | Description | Status | QA Attempts | Notes |
|---------|-------------|--------|-------------|-------|
| [ID] | [Description] | ✅ Complete | [N] | [Notes] |
| [ID] | [Description] | ✅ Complete | [N] | [Notes] |
| [ID] | [Description] | ⚠️ Carried Over | [N] | [Reason] |

## Quality Metrics
- **First-pass QA rate**: [X]%
- **Average retries**: [N]
- **Tasks completed**: [X/Y]
- **Story points delivered**: [N]

## Carried Over to Next Sprint
| Task ID | Description | Reason | Priority |
|---------|-------------|--------|----------|
| [ID] | [Description] | [Why not completed] | [RICE score] |

## Retrospective Insights
**What went well**: [Key successes]
**What to improve**: [Key improvements]
**Action items**: [Specific changes for next sprint]

## Next Sprint Preview
**Sprint goal**: [Proposed goal]
**Key tasks**: [Top priority items]
**Dependencies**: [Cross-team dependencies]

---

7. Incident Handoff

Use during incident response.

# NEXUS Incident Handoff

## Incident
| Field | Value |
|-------|-------|
| **Severity** | [P0 / P1 / P2 / P3] |
| **Detected by** | [Agent or system] |
| **Detection time** | [Timestamp] |
| **Assigned to** | [Agent Name] |
| **Status** | [Investigating / Mitigating / Resolved / Post-mortem] |

## Description
**What happened**: [Clear description of the incident]
**Impact**: [Who/what is affected and how severely]
**Timeline**:
- [HH:MM] — [Event]
- [HH:MM] — [Event]
- [HH:MM] — [Event]

## Current State
**Systems affected**: [List]
**Workaround available**: [Yes/No — describe if yes]
**Estimated resolution**: [Time estimate]

## Actions Taken
1. [Action taken and result]
2. [Action taken and result]

## Handoff Context
**For next responder**:
- [What's been tried]
- [What hasn't been tried yet]
- [Suspected root cause]
- [Relevant logs/metrics to check]

## Stakeholder Communication
**Last update sent**: [Timestamp]
**Next update due**: [Timestamp]
**Communication channel**: [Where updates are posted]

---

Usage Guide

Situation	Template to Use
Assigning work to another agent	Standard Handoff (#1)
QA approves a task	QA PASS (#2)
QA rejects a task	QA FAIL (#3)
Task exceeds 3 retries	Escalation Report (#4)
Moving between phases	Phase Gate Handoff (#5)
End of sprint	Sprint Handoff (#6)
System incident	Incident Handoff (#7)