Agent Handoff Protocol
This document defines the standard protocol for handing off work between agents in the development workflow.Handoff Chain Overview
Handoff Requirements
Every handoff MUST include:
- ✅ Linear ticket updated with completion status
- ✅ Work summary posted as Linear comment
- ✅ All deliverables committed and pushed to branch
- ✅ Documentation updated (if applicable)
- ✅ Next agent tagged in Linear comment
- ✅ Clear instructions for next agent
- ✅ PROJECT_OVERVIEW.md updated with handoff status
Handoff Template
When handing off work, post this to Linear ticket:Agent-Specific Handoff Protocols
1. Chief Product Officer → Senior Product Manager
CPO Completes:- Product vision document
- Market research
- High-level product strategy
- OKRs and success metrics
2. Senior Product Manager → UX Designer & Software Architect
PM Completes:- Comprehensive PRD
- User stories
- Acceptance criteria
- Feature specifications
3. UX Designer → Product Designer
UX Designer Completes:- Style guide
- Component library specs
- UX patterns
- Interaction guidelines
4. Software Architect → DBA
Architect Completes:- System design document
- API contracts
- Data model requirements
- Linear tickets created
5. DBA → Backend Developer
DBA Completes:- Database schema
- Migrations
- Seed data
- Connection documentation
6. Backend Developer → Frontend Developer (Parallel) → Security Engineer
Backend Developer Completes:- API endpoints
- Business logic
- Database integration
- API documentation
7. Frontend Developer → Security Engineer
Frontend Developer Completes:- UI implementation
- API integration
- State management
- Component library
8. Security Engineer → QA Engineer
Security Engineer Completes:- Security scan
- Vulnerability assessment
- Code review for security issues
- Security report
9. QA Engineer → DevOps Engineer
QA Engineer Completes:- Test execution
- Bug reports
- Regression testing
- QA sign-off
10. DevOps Engineer → PRODUCTION
DevOps Engineer Completes:- Infrastructure setup
- CI/CD pipeline
- Staging deployment
- Production deployment
Handoff Checklist
Before handing off, verify:- All work committed and pushed to branch
- Linear ticket updated with completion status
- Comprehensive handoff comment posted
- All deliverables documented
- Next agent tagged
- Clear instructions provided
- PROJECT_OVERVIEW.md updated
- Documentation links included
- Quality checks passed
- No blockers for next agent
Handling Blockers During Handoff
If you cannot complete handoff due to blocker:-
Update Linear ticket immediately:
- Notify dependent agent via Linear mention
- Update PROJECT_OVERVIEW.md with blocker status
- Continue with non-blocked work if possible
Emergency Handoff
For urgent issues requiring immediate handoff:- Use priority: Urgent in Linear ticket
- Add 🚨 URGENT to handoff comment
- Tag next agent with mention
- Provide immediate action items
- Include emergency contact if needed
Handoff Best Practices
DO ✅
- Be thorough - Include all relevant information
- Be clear - Make instructions explicit
- Be proactive - Anticipate next agent’s questions
- Link extensively - Connect all related work
- Document decisions - Explain the “why”
- Update promptly - Don’t delay handoffs
- Test before handoff - Ensure quality
DON’T ❌
- Hand off broken work - Fix issues first
- Skip documentation - Always document
- Leave ambiguity - Be specific
- Forget to update Linear - Always update
- Rush - Take time to handoff properly
- Assume knowledge - Explain context
Measuring Handoff Quality
Good handoffs have:- ✅ Complete deliverables
- ✅ Clear documentation
- ✅ No blocking issues
- ✅ Comprehensive testing
- ✅ Detailed instructions
- ✅ All links working
- ✅ Next agent can start immediately
- ❌ Confusion and delays
- ❌ Back-and-forth questions
- ❌ Rework required
- ❌ Missed requirements
- ❌ Quality issues
- ❌ Timeline delays
Questions?
Refer to:- Linear Integration Guide
- Project Overview
- Individual agent documentation in
.claude/agents/