Skill: Agent Handoff

Purpose

Transfer work and context between agents with complete information for seamless continuity.

When to Use

• Workflow requires different agent expertise
• Task moves to next phase
• Specialist input needed
• Review or validation required

---

Handoff Types

Type	From	To	Example
Sequential	Agent A	Agent B	BA → PO → Architect
Review	Implementer	Reviewer	Jr Dev → Sr Dev
Specialist	Generalist	Specialist	Orchestrator → QA
Escalation	Any Agent	Orchestrator	Agent → Orchestrator → Stakeholder
Parallel	Orchestrator	Multiple	Orchestrator → BA + Architect

---

Handoff Protocol

1. Complete Current Work

Before handoff:

• Finish in-progress tasks
• Document what was done
• Log in Jira comment

2. Package Context

Prepare handoff package:

• Work completed
• Decisions made
• Open questions
• Relevant links
• Next expected action

3. Log Handoff

Document in Jira:

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "{{issueKey}}",
  commentBody: `🤖 **{{fromAgent}} Agent** → **{{toAgent}} Agent**

**Handoff:** {{handoffType}}

**Completed:**
{{#each completed}}
- ✅ {{item}}
{{/each}}

**Context:**
{{context}}

**For {{toAgent}}:**
{{instructions}}

**Open Questions:**
{{#each questions}}
- {{question}}
{{/each}}

**Relevant Links:**
- {{links}}`
})

4. Transfer Control

Orchestrator routes to next agent with context.

---

Handoff Templates

Requirements → Technical Review

BA → Architect:

🤖 **Business Analyst Agent** → **Software Architect Agent**

**Handoff:** Technical feasibility review

**Completed:**
- ✅ Requirements analysis
- ✅ User stories created (MDDEV-101, 102, 103)
- ✅ Acceptance criteria defined
- ✅ BRD drafted

**Context:**
New authentication feature for user registration and login. Stories are drafted with acceptance criteria pending technical validation.

**For Architect:**
1. Review technical feasibility of each story
2. Identify dependencies and risks
3. Add complexity estimates
4. Note any architectural considerations
5. Create ADR if significant technical decisions

**Open Questions:**
- Is JWT the right approach for our scale?
- Any concerns with the session management AC?

**Relevant Links:**
- Epic: MDDEV-100
- BRD: [Confluence Link]

Technical Review → QA Review

Architect → QA:

🤖 **Software Architect Agent** → **QA Engineer Agent**

**Handoff:** Testability review

**Completed:**
- ✅ Technical feasibility confirmed
- ✅ Architecture approach documented
- ✅ ADR-015 created
- ✅ Technical notes added to stories

**Context:**
Authentication feature technically reviewed. JWT-based approach selected. Stories need testability validation before refinement complete.

**For QA:**
1. Review acceptance criteria for testability
2. Identify edge cases not covered
3. Add test considerations to stories
4. Flag any unclear or untestable criteria

**Technical Notes:**
- JWT tokens with 24hr expiry
- bcrypt password hashing
- Rate limiting on auth endpoints

**Relevant Links:**
- Stories: MDDEV-101, 102, 103
- ADR: [Confluence Link]

Implementation → Code Review

Jr Dev → Sr Dev:

🤖 **Junior Developer Agent** → **Senior Developer Agent**

**Handoff:** Code review

**Completed:**
- ✅ Feature implemented per spec
- ✅ Unit tests written (85% coverage)
- ✅ PR created: #123
- ✅ Manual testing passed locally

**Context:**
Password reset feature implementation complete. Follows the JWT approach from ADR-015. Ready for code review.

**For Senior Developer:**
1. Review code quality and patterns
2. Validate error handling
3. Check security considerations
4. Verify test coverage
5. Approve or request changes

**Implementation Notes:**
- Used existing auth service pattern
- Added rate limiting middleware
- Email template in `/templates/password-reset.html`

**Test Coverage:**
- Unit: 85%
- Key scenarios covered in tests

**Relevant Links:**
- PR: #123
- Story: MDDEV-103
- Tech Spec: [Confluence Link]

Testing → Acceptance

QA → PO:

🤖 **QA Engineer Agent** → **Product Owner Agent**

**Handoff:** Story acceptance

**Completed:**
- ✅ Test plan executed
- ✅ 12/12 test cases passed
- ✅ No critical bugs found
- ✅ 2 minor bugs logged and fixed

**Context:**
Password reset feature fully tested. All acceptance criteria validated. Ready for product owner acceptance.

**For Product Owner:**
1. Review completed functionality
2. Validate against acceptance criteria
3. Accept or reject story
4. Note any follow-up items

**Test Summary:**
- Functional: All pass
- Edge cases: All pass
- Security: Validated
- Performance: Within targets

**Relevant Links:**
- Story: MDDEV-103
- Test Results: [Confluence Link]
- Demo Environment: [URL]

---

Parallel Handoff

When multiple agents needed simultaneously:

🤖 **Orchestrator Agent** → **Multiple Agents**

**Parallel Handoff:** Feature analysis

**Task:** Analyze new "Dark Mode" feature request

**Assignments:**

**→ Business Analyst:**
- Break down requirements
- Create user stories
- Draft acceptance criteria

**→ Software Architect:**
- Assess technical approach
- Identify dependencies
- Document architecture considerations

**→ UI/UX Designer:**
- Design dark mode palette
- Create component specifications
- Document accessibility requirements

**Sync Point:** All agents report back to Orchestrator when complete

**Deadline:** [Date/Time]

**Shared Context:**
- Stakeholder request: [Link/Summary]
- Existing design system: [Link]

---

Escalation Handoff

When escalating to stakeholder:

🤖 **{{Agent}} Agent** → **Orchestrator Agent**

**Handoff:** Stakeholder escalation needed

**Issue:** {{issue}}

**Why Escalation:**
- Decision type: Business/Scope/Priority
- Outside agent authority
- Stakeholder input required

**Context:**
{{context}}

**Prepared For Stakeholder:**
- Question: {{question}}
- Options: {{options}}
- Recommendation: {{recommendation}}

**Request:**
Please escalate to stakeholder using stakeholder communication protocol.

**Blocking:**
- {{blockedItems}}

---

Handoff Acknowledgment

Receiving agent acknowledges:

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "{{issueKey}}",
  commentBody: `🤖 **{{toAgent}} Agent**

**Handoff Received** from {{fromAgent}}

**Acknowledged:**
- Context reviewed
- {{#if questions}}Questions noted{{/if}}
- Beginning {{task}}

**Estimated Completion:** {{estimate}}

**Will Deliver:**
{{#each deliverables}}
- {{deliverable}}
{{/each}}`
})

---

Used By Agents

Agent	Typical Handoffs
Orchestrator	Routes all handoffs, parallel coordination
Business Analyst	To: PO, Architect, QA
Product Owner	To: BA, Orchestrator
Software Architect	To: Sr Dev, QA, DevOps
Senior Developer	To: Jr Dev, QA, DevOps
Junior Developer	To: Sr Dev (review)
QA Engineer	To: PO, Dev (bugs)

Best Practices

1. Complete before handoff - Don't hand off incomplete work
2. Be specific - Clear instructions prevent confusion
3. Include context - Receiving agent needs background
4. Link everything - Jira, Confluence, PRs, etc.
5. Set expectations - What's needed and by when
6. Acknowledge receipt - Confirm handoff received