go-agent/claude/agentic/patterns/handoff-protocol.md

Handoff Protocol Pattern

Standardized format for agent-to-agent task handoffs, ensuring complete context transfer and clear success criteria.

Handoff Message Structure

Required Sections

Every handoff must include these four sections:

## Task Summary
[One paragraph describing what needs to be done]

## Current Context
[State of the work, relevant files, environment]

## Constraints
[Limitations, requirements, boundaries]

## Success Criteria
[Specific, measurable conditions for completion]

Section Details

Task Summary

A clear, actionable description of the work to be done.

Include:

• Primary objective
• Why this task matters
• Expected deliverable

Example:

## Task Summary

Implement pagination for the /api/users endpoint. Currently returns all users
which causes timeouts with large datasets. The endpoint should support limit/offset
query parameters and return pagination metadata in the response.

Current Context

The state of work and environment the receiving agent needs to understand.

Include:

• Working directory and relevant files
• Current branch and commit
• Related code or dependencies
• Work already completed
• Open questions or decisions made

Example:

## Current Context

- **Directory:** /home/claude/api-service
- **Branch:** feature/pagination (branched from main at abc123)
- **Files modified:**
  - `pkg/api/handlers/users.go` - Added limit/offset parsing
  - `pkg/api/models/pagination.go` - Created (new file)
- **Dependencies:** Using existing `pkg/db/query.go` for offset queries
- **Decision:** Using offset pagination over cursor-based (simpler, meets requirements)
- **Tests:** None written yet

Constraints

Non-negotiable requirements and limitations.

Include:

• Technical constraints
• Security requirements
• Scope boundaries
• Time constraints
• External dependencies

Example:

## Constraints

- **Technical:**
  - Maximum limit: 100 (prevent abuse)
  - Default limit: 20
  - Must work with existing SQL queries
- **Security:**
  - Validate limit/offset are positive integers
  - No SQL injection vulnerabilities
- **Scope:**
  - Only /api/users endpoint for now
  - Do not modify database schema
- **Time:**
  - Must be ready for code review by EOD

Success Criteria

Specific, verifiable conditions that indicate the task is complete.

Include:

• Functional requirements
• Test coverage requirements
• Documentation requirements
• Review requirements

Example:

## Success Criteria

- [ ] GET /api/users?limit=10&offset=0 returns paginated results
- [ ] Response includes total_count, limit, offset, has_more fields
- [ ] Invalid limit/offset returns 400 Bad Request
- [ ] Unit tests cover happy path and error cases
- [ ] All existing tests still pass
- [ ] Code reviewed by senior engineer

Complete Handoff Example

# Handoff: Pagination Implementation

## Task Summary

Complete the pagination implementation for /api/users. The basic structure is in
place but needs test coverage and error handling before it can be merged.

## Current Context

- **Directory:** /home/claude/api-service
- **Branch:** feature/pagination
- **Commit:** def456 "Add basic pagination to users endpoint"
- **Files:**
  - `pkg/api/handlers/users.go` - Pagination logic implemented
  - `pkg/api/models/pagination.go` - Response struct defined
- **State:** Implementation complete, tests needed
- **Blocked:** None

## Constraints

- Do not change the pagination approach (offset-based)
- Tests must not require database connection (use mocks)
- Follow existing test patterns in handlers_test.go
- Keep PR under 500 lines

## Success Criteria

- [ ] 90%+ test coverage on new code
- [ ] Tests for: valid params, missing params, invalid params, boundary cases
- [ ] golangci-lint passes
- [ ] PR description includes API documentation

Handoff Validation Checklist

Before sending a handoff:

1. Task Summary - Is the objective clear to someone unfamiliar with the project?
2. Context - Can the receiving agent start work immediately?
3. Constraints - Are all limitations explicitly stated?
4. Success Criteria - Are all conditions testable/verifiable?
5. Files - Do all referenced paths exist?
6. Branch - Is the branch pushed and accessible?

Anti-Patterns

• Vague tasks: "Fix the bug" instead of "Fix null pointer in user.GetName()"
• Missing context: Assuming the receiver knows the codebase
• Implicit constraints: Not mentioning time limits or scope boundaries
• Untestable criteria: "Code should be clean" instead of "Pass linting"
• Stale references: Pointing to branches or commits that don't exist