Skip to main content

Agent Handoff Protocol

This document defines the standard protocol for handing off work between agents in the development workflow.

Handoff Chain Overview

@chief-product-officer (Product Vision & Strategy)

@senior-product-manager (Requirements & PRD)

@marketer (Brand & Visual Identity) → @ux-designer (UX & Style Guide) → @product-designer (UI Designs)
  ↓                                     ↓                                   ↓
@software-architect (System Architecture & Linear Tickets)

@dba (Database Schema & Migrations)

┌─────────────────────────────────┐
│ @frontend-developer             │ ← → @backend-developer
│ (UI Implementation)             │     (API & Business Logic)
└─────────────────────────────────┘

@app-security-engineer (Security Scanning)

@senior-qa-engineer (QA Testing)

@devops-engineer (Infrastructure & Deployment)

✅ PRODUCTION LIVE

Handoff Requirements

Every handoff MUST include:

  1. Linear ticket updated with completion status
  2. Work summary posted as Linear comment
  3. All deliverables committed and pushed to branch
  4. Documentation updated (if applicable)
  5. Next agent tagged in Linear comment
  6. Clear instructions for next agent
  7. PROJECT_OVERVIEW.md updated with handoff status

Handoff Template

When handing off work, post this to Linear ticket:
## Work Complete ✓

**Linear Ticket**: LINEAR-[XXX] - [Title]
**Completed By**: @[agent-name]
**Completion Date**: [YYYY-MM-DD]

### Deliverables
- ✅ [Deliverable 1]
- ✅ [Deliverable 2]
- ✅ [Deliverable 3]

### Files Created/Modified
\`\`\`
path/to/file1.ext
path/to/file2.ext
path/to/file3.ext
\`\`\`

### Git Information
- **Branch**: feature/LINEAR-XXX-description
- **Commits**: [Count] commits
- **Lines**: +[X] -[Y]
- **Key Commits**: [commit-sha1], [commit-sha2]

### Documentation
- [Document 1](link-to-doc)
- [Document 2](link-to-doc)

### Quality Checks
- [x] All acceptance criteria met
- [x] Code follows style guidelines
- [x] Tests passing (if applicable)
- [x] Documentation updated
- [x] Committed and pushed to branch

### Handoff Notes
[Any specific information the next agent needs to know]

### Next Steps
**Ready for handoff to: @[next-agent-name]**

**Instructions for next agent:**
1. [Step 1]
2. [Step 2]
3. [Step 3]

**To invoke next agent:**
`@[next-agent-name]` - [What they need to do]

### References
- Related tickets: LINEAR-XXX, LINEAR-YYY
- Dependencies: [Any dependencies or blockers]

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
CPO Hands Off:
## Product Vision Complete ✅

**Vision Document**: docs/product/vision/product-vision-YYYY-MM.md

### Key Deliverables
- ✅ Product vision and mission
- ✅ Target market analysis
- ✅ Competitive landscape
- ✅ Success metrics and KPIs
- ✅ Product roadmap (high-level)

### Next Steps
**Ready for: @senior-product-manager**

**Instructions:**
1. Read product vision document
2. Create detailed PRD based on vision
3. Break down features into user stories
4. Define acceptance criteria for each feature

**Linear Tickets Created:**
- LINEAR-XXX: Create PRD for [Feature]

2. Senior Product Manager → UX Designer & Software Architect

PM Completes:
  • Comprehensive PRD
  • User stories
  • Acceptance criteria
  • Feature specifications
PM Hands Off:
## PRD Complete ✅

**PRD Document**: docs/product/prds/[feature]-prd.md

### Key Deliverables
- ✅ Comprehensive PRD with all features
- ✅ User stories with acceptance criteria
- ✅ Feature prioritization
- ✅ Technical requirements
- ✅ Success metrics defined

### Next Steps - Parallel Handoffs

**Ready for: @ux-designer AND @software-architect**

#### For @ux-designer:
1. Review PRD user flows section
2. Create style guide based on brand guidelines
3. Design user interface components
4. Linear ticket: LINEAR-XXX

#### For @software-architect:
1. Review PRD technical requirements
2. Design system architecture
3. Create Linear tickets for implementation
4. Document: LINEAR-YYY

3. UX Designer → Product Designer

UX Designer Completes:
  • Style guide
  • Component library specs
  • UX patterns
  • Interaction guidelines
UX Designer Hands Off:
## Style Guide Complete ✅

**Style Guide**: docs/design/style-guide/style-guide.md

### Key Deliverables
- ✅ Color palette with usage guidelines
- ✅ Typography system (6 levels)
- ✅ Spacing scale and grid system
- ✅ Component specifications
- ✅ Interaction patterns
- ✅ Accessibility guidelines

### Design System Overview
- Primary colors: [List]
- Typography: [Font families and scales]
- Components: [Count] components specified
- Responsive: Mobile-first breakpoints defined

### Next Steps
**Ready for: @product-designer**

**Instructions:**
1. Use style guide as foundation
2. Create high-fidelity UI designs
3. Design all screens and components
4. Provide specs for developers

**Linear Ticket**: LINEAR-XXX

4. Software Architect → DBA

Architect Completes:
  • System design document
  • API contracts
  • Data model requirements
  • Linear tickets created
Architect Hands Off:
## Architecture Design Complete ✅

**System Design**: docs/architecture/system-design.md

### Key Deliverables
- ✅ System architecture diagram
- ✅ API contract definitions
- ✅ Data model requirements
- ✅ Technology stack decisions
- ✅ Linear tickets created for all implementation work

### Architecture Overview
- **Frontend**: [Framework]
- **Backend**: [Framework]
- **Database**: [Database system]
- **Infrastructure**: [Cloud provider]

### Linear Tickets Created
- LINEAR-XXX: Database schema implementation
- LINEAR-YYY: Backend API implementation
- LINEAR-ZZZ: Frontend implementation

### Next Steps
**Ready for: @dba**

**Instructions:**
1. Review data model requirements in system design doc
2. Design database schema based on requirements
3. Create migration scripts
4. Document schema for backend developers

**Linear Ticket**: LINEAR-XXX
**Priority**: High (blocking backend development)

5. DBA → Backend Developer

DBA Completes:
  • Database schema
  • Migrations
  • Seed data
  • Connection documentation
DBA Hands Off:
## Database Schema Complete ✅

**Schema Docs**: docs/database/schemas/schema-v1.md

### Key Deliverables
- ✅ All tables/collections created
- ✅ Indexes optimized for query patterns
- ✅ Migration scripts tested
- ✅ Seed data for development
- ✅ RLS policies (if Supabase)
- ✅ Connection documentation

### Database Information
- **Platform**: [MongoDB/PostgreSQL/etc.]
- **Tables**: [Count] tables created
- **Indexes**: [Count] indexes
- **Migrations**: [Count] migration files

### Schema Overview
- Users table with authentication fields
- [Entity] tables with relationships
- Composite indexes for performance

### Next Steps
**Ready for: @backend-developer**

**Instructions:**
1. Review schema documentation
2. Set up database connection in backend
3. Implement repositories/data access layer
4. Use schema for API implementation

**Connection Info**:
- Guide: docs/database/connection/setup-guide.md
- Migration tool: [Tool name]

**Linear Ticket**: LINEAR-YYY

6. Backend Developer → Frontend Developer (Parallel) → Security Engineer

Backend Developer Completes:
  • API endpoints
  • Business logic
  • Database integration
  • API documentation
Backend Developer Hands Off:
## Backend APIs Complete ✅

**Linear Ticket**: LINEAR-YYY

### Key Deliverables
- ✅ All API endpoints implemented per contracts
- ✅ Service layer with business logic
- ✅ Database integration complete
- ✅ Authentication/authorization implemented
- ✅ Input validation on all endpoints
- ✅ Error handling comprehensive
- ✅ API documentation generated

### API Endpoints
- POST   /api/v1/[resource] - Create
- GET    /api/v1/[resource] - List
- GET    /api/v1/[resource]/:id - Get
- PUT    /api/v1/[resource]/:id - Update
- DELETE /api/v1/[resource]/:id - Delete

### Testing
- Unit tests: [X] tests passing
- Integration tests: [Y] tests passing
- Coverage: [Z%]

### Next Steps - Parallel Handoffs

**Ready for: @frontend-developer**
**Instructions:**
1. Review API documentation
2. Integrate API endpoints in UI
3. Handle API errors gracefully
4. Linear ticket: LINEAR-ZZZ

**Also ready for: @app-security-engineer**
**Instructions:**
1. Run security scan on backend code
2. Check for vulnerabilities
3. Verify security best practices
4. Linear ticket: LINEAR-AAA

7. Frontend Developer → Security Engineer

Frontend Developer Completes:
  • UI implementation
  • API integration
  • State management
  • Component library
Frontend Developer Hands Off:
## Frontend UI Complete ✅

**Linear Ticket**: LINEAR-ZZZ

### Key Deliverables
- ✅ All UI screens implemented per designs
- ✅ Component library created
- ✅ API integration complete
- ✅ State management implemented
- ✅ Responsive design (mobile/tablet/desktop)
- ✅ Accessibility standards met (WCAG 2.1 AA)
- ✅ Cross-browser testing complete

### Implementation Details
- **Components**: [Count] components created
- **Pages**: [Count] pages implemented
- **State Management**: [Redux/Context/etc.]
- **API Calls**: All endpoints integrated

### Testing
- Unit tests: [X] tests passing
- Component tests: [Y] tests passing
- E2E tests: [Z] scenarios covered
- Coverage: [W%]

### Next Steps
**Ready for: @app-security-engineer**

**Instructions:**
1. Run security scan on frontend code
2. Check for XSS vulnerabilities
3. Verify CSP policies
4. Test authentication flows

**Linear Ticket**: LINEAR-AAA
**Note**: Backend security scan may already be complete

8. Security Engineer → QA Engineer

Security Engineer Completes:
  • Security scan
  • Vulnerability assessment
  • Code review for security issues
  • Security report
Security Engineer Hands Off:
## Security Scan Complete ✅

**Linear Ticket**: LINEAR-AAA

### Key Deliverables
- ✅ Secret scanning (Gitleaks): No secrets found
- ✅ SAST analysis (Semgrep): No critical/high issues
- ✅ Dependency scan (Trivy): No known CVEs
- ✅ Code review: Security best practices verified
- ✅ Security report generated

### Scan Results
- **Secrets**: 0 issues ✅
- **Security Issues**: 0 critical, 0 high, 2 medium, 5 low
- **Dependencies**: All up to date, no CVEs

### Medium Severity Issues (Addressed)
1. Missing rate limiting on endpoint - FIXED
2. Weak password validation - FIXED

### Low Severity Issues (Documented)
1. [Issue 1] - Accepted risk, documented
2. [Issue 2] - Future enhancement

### Security Verification
- [x] Input validation on all endpoints
- [x] Authentication properly implemented
- [x] Authorization checks in place
- [x] SQL injection prevention verified
- [x] XSS prevention verified
- [x] CSRF protection implemented
- [x] Secrets in environment variables

### Next Steps
**Ready for: @senior-qa-engineer**

**Instructions:**
1. Execute comprehensive test plan
2. Verify all features work as expected
3. Test edge cases and error scenarios
4. Document any bugs found

**Linear Ticket**: LINEAR-BBB
**Test Plan**: docs/testing/test-plan.md

9. QA Engineer → DevOps Engineer

QA Engineer Completes:
  • Test execution
  • Bug reports
  • Regression testing
  • QA sign-off
QA Engineer Hands Off:
## QA Testing Complete ✅

**Linear Ticket**: LINEAR-BBB

### Key Deliverables
- ✅ All test cases executed
- ✅ Functional testing complete
- ✅ Integration testing complete
- ✅ E2E testing complete
- ✅ Performance testing complete
- ✅ Regression testing passed
- ✅ All critical/high bugs fixed
- ✅ QA approval granted

### Test Results
- **Test Cases**: [X] total, [Y] passed, [Z] failed
- **Pass Rate**: [W%]
- **Critical Bugs**: 0
- **High Bugs**: 0
- **Medium Bugs**: 2 (documented, accepted)
- **Low Bugs**: 5 (documented, future fixes)

### Performance Metrics
- Page load time: [X]ms (target: <3s) ✅
- API response time: [Y]ms (target: <500ms) ✅
- Time to interactive: [Z]ms (target: <5s) ✅

### Browser Compatibility
- ✅ Chrome (latest 2 versions)
- ✅ Firefox (latest 2 versions)
- ✅ Safari (latest 2 versions)
- ✅ Edge (latest 2 versions)

### Mobile Testing
- ✅ iOS Safari (iOS 15+)
- ✅ Android Chrome (Android 10+)

### Accessibility
- ✅ WCAG 2.1 AA compliance verified
- ✅ Screen reader testing passed
- ✅ Keyboard navigation working

### Known Issues (Accepted)
1. [Medium] - [Description] - LINEAR-CCC
2. [Low] - [Description] - LINEAR-DDD

### Next Steps
**Ready for: @devops-engineer**

**Instructions:**
1. Deploy to staging environment
2. Run smoke tests
3. If staging passes, deploy to production
4. Monitor post-deployment

**Linear Ticket**: LINEAR-EEE
**Approval**: ✅ QA APPROVED FOR PRODUCTION DEPLOYMENT

10. DevOps Engineer → PRODUCTION

DevOps Engineer Completes:
  • Infrastructure setup
  • CI/CD pipeline
  • Staging deployment
  • Production deployment
DevOps Engineer Completes:
## Production Deployment Complete ✅

**Linear Ticket**: LINEAR-EEE

### Deployment Status: 🎉 LIVE IN PRODUCTION

### Key Deliverables
- ✅ Infrastructure as code (Terraform)
- ✅ CI/CD pipeline configured
- ✅ Staging environment deployed and tested
- ✅ Production environment deployed
- ✅ Monitoring and alerting active
- ✅ Rollback procedures documented

### Deployment Details
- **Environment**: Production
- **Version**: v1.2.0
- **Deployed**: 2025-01-10 14:30 UTC
- **Deployment Time**: 8 minutes
- **Downtime**: 0 seconds (blue-green deployment)

### Production URLs
- **Frontend**: https://app.example.com
- **API**: https://api.example.com
- **Monitoring**: https://monitoring.example.com

### Infrastructure
- **Cloud Provider**: AWS
- **Region**: us-east-1
- **Compute**: 3 EC2 instances (t3.medium)
- **Database**: RDS PostgreSQL (db.t3.medium)
- **CDN**: CloudFront
- **Load Balancer**: ALB

### Monitoring
- **Error Rate**: 0.02% ✅
- **Response Time P95**: 250ms ✅
- **Uptime**: 100% ✅
- **Active Users**: Monitoring...

### Health Checks
- ✅ Frontend: Responding
- ✅ API: Responding
- ✅ Database: Connected
- ✅ CDN: Distributing

### Post-Deployment Tasks
- [x] Smoke tests passed
- [x] Monitoring dashboards active
- [x] Alerts configured
- [x] Team notified
- [x] Stakeholders informed
- [x] Documentation updated
- [x] Linear tickets updated

### Rollback Plan
If issues arise:
\`\`\`bash
gh workflow run deploy-production.yml -f version=v1.1.0
\`\`\`

### Next Steps
- Monitor for 24 hours
- Track error rates and performance
- Address any production issues immediately
- Plan next sprint work

---

## 🎉 PROJECT SUCCESSFULLY DEPLOYED!

**Thank you to the entire agent team:**
- @chief-product-officer - Vision and strategy
- @senior-product-manager - Requirements and PRD
- @marketer - Brand guidelines
- @ux-designer - Style guide and UX
- @product-designer - UI designs
- @software-architect - Architecture
- @dba - Database implementation
- @backend-developer - API implementation
- @frontend-developer - UI implementation
- @app-security-engineer - Security verification
- @senior-qa-engineer - Quality assurance
- @devops-engineer - Infrastructure and deployment

**Product is now live and serving users! 🚀**

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:
  1. Update Linear ticket immediately:
    ## ⚠️ HANDOFF BLOCKED
    
    Unable to complete handoff to @[next-agent] due to blocker.
    
    ### Blocker Details
    [Description]
    
    ### Dependency
    Waiting on: LINEAR-XXX
    Assigned to: @[agent]
    
    ### Impact
    [Impact description]
    
    ### Next Steps
    1. Resolve LINEAR-XXX
    2. Resume current work
    3. Complete handoff to @[next-agent]
    
  2. Notify dependent agent via Linear mention
  3. Update PROJECT_OVERVIEW.md with blocker status
  4. Continue with non-blocked work if possible

Emergency Handoff

For urgent issues requiring immediate handoff:
  1. Use priority: Urgent in Linear ticket
  2. Add 🚨 URGENT to handoff comment
  3. Tag next agent with mention
  4. Provide immediate action items
  5. 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
Poor handoffs result in:
  • ❌ Confusion and delays
  • ❌ Back-and-forth questions
  • ❌ Rework required
  • ❌ Missed requirements
  • ❌ Quality issues
  • ❌ Timeline delays

Questions?

Refer to: