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:

```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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

```markdown
# 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