tomevault-io Agent Handoff Protocol
Ensure smooth transitions when passing work between AI agents.
Why Handoffs Matter
When one agent hands off to another, context can be lost. This skill ensures:
- The receiving agent understands what was done
- Important decisions are preserved
- Work isn't duplicated or contradicted
Handoff Checklist
When handing off to another agent, always include:
1. Summary of Work Done
What: Brief description of completed work Why: The reasoning behind decisions made Where: Files and locations modified
## Work Completed
- Implemented user authentication in src/auth/
- Added JWT token generation and validation
- Created middleware for protected routes
## Key Decisions
- Chose JWT over sessions for stateless scaling
- Set token expiry to 24 hours (configurable)
- Used bcrypt for password hashing (cost factor 12)
2. Files Changed
List all modified files with brief descriptions:
## Files Modified
- src/auth/jwt.js - Token generation/validation
- src/auth/middleware.js - Auth middleware
- src/routes/auth.js - Login/logout endpoints
- src/models/user.js - Added password field
## New Files Created
- src/auth/config.js - Auth configuration
- tests/auth.test.js - Authentication tests
3. Open Issues and Concerns
What the next agent should be aware of:
## Open Issues
- [ ] Rate limiting not implemented yet
- [ ] Password reset flow pending
- [ ] Need to add refresh token logic
## Concerns
- JWT secret is currently hardcoded - needs env var
- No input validation on login endpoint
- Error messages might leak user existence
4. Next Steps
Clear instructions for the receiving agent:
## For Next Agent
1. Review security of current implementation
2. Add rate limiting to login endpoint
3. Implement password reset via email
4. Add refresh token rotation
Priority: Security review is most critical
Handoff Template
# Agent Handoff: [Task Name]
## Context
[Brief description of the task and current state]
## Work Completed
- [List of completed items]
## Key Decisions
| Decision | Rationale |
|----------|-----------|
| [Choice] | [Why] |
## Files Modified
- path/to/file.js - [what changed]
## Open Issues
- [ ] [Issue description]
## For Next Agent
1. [First action]
2. [Second action]
## Shared Artifacts
- artifact-key: [description]
- finding-ids: [list]
Using cliagents Tools
Store Artifacts for Handoff
store_artifact taskId="task-123" key="implementation-plan" type="plan" content="..."
store_artifact taskId="task-123" key="code-changes" type="code" content="..."
Share Findings
share_finding taskId="task-123" type="info" content="JWT implementation notes..."
share_finding taskId="task-123" type="security" severity="medium" content="Rate limiting needed"
Retrieve Previous Work
get_shared_findings taskId="task-123"
Anti-Patterns
- No context: Starting fresh without reviewing previous work
- Duplicated effort: Redoing what another agent already did
- Lost decisions: Not documenting why choices were made
- Silent failures: Not reporting issues encountered
- Vague handoffs: "Finish the implementation" without specifics
Receiving a Handoff
When you receive a handoff:
- Read the full context: Don't skim
- Check shared artifacts: Use
get_shared_findings - Validate understanding: Summarize back if unclear
- Build on existing work: Don't start over
- Continue the documentation: Add your own handoff notes
Converted and distributed by TomeVault — claim your Tome and manage your conversions.