# Real-World Handoff Workflow Examples

**Last Updated**: November 20, 2025  
**Purpose**: Demonstrate `/handoff` custom command for intentional phase transitions

---

## Pattern 1: Research → Planning Handoff

**Scenario**: Complete research phase, hand off to planning

**Phase 1: Research (with @researcher)**

```
Work completed:
✅ Analyzed Redis clustering patterns
✅ Evaluated Master-Replica vs Cluster mode
✅ Determined AOF persistence is better for our use case
✅ Identified minimum 3-node requirement
✅ Documented failover strategies
```

**Create Handoff:**

```bash
/handoff "design the Redis cluster architecture based on research findings"
```

**Generated Handoff Bundle**

```
File: .opencode/memory/handoffs/2025-11-20-redis-cluster-design.md

Summary:
- Research phase complete: Redis clustering analysis
- Key finding: Cluster mode better for horizontal scaling
- Decision: Use Sentinel for auto-failover, AOF for durability
- Constraint: Minimum 3 nodes, dedicated network

Next Phase Instructions:
Design the Redis cluster architecture including:
1. Node configuration (master, replica, sentinel)
2. Network topology and communication patterns
3. Failover automation strategy
4. Monitoring and alerting plan
5. Backup/recovery procedures

Recommended agent: @plan
```

**Phase 2: Planning (with @plan)**

```
New thread with @plan agent:
@.opencode/memory/handoffs/2025-11-20-redis-cluster-design.md

Plan deliverables:
✅ Architecture diagram
✅ Configuration specifications
✅ Deployment checklist
✅ Monitoring strategy
✅ Disaster recovery plan
```

**Benefits**:

- Clean slate - no prior conversation history
- Focused context - only essential information
- Portable bundle - can share with team
- Clear transition - explicit phase boundaries

---

## Pattern 2: Planning → Implementation Handoff

**Scenario**: Architecture plan complete, hand off to implementation

**Phase 1: Planning**

```
Architecture deliverables:
✅ System design document
✅ Database schema
✅ API endpoint specifications
✅ Authentication flow diagram
✅ Error handling strategy
```

**Create Handoff:**

```bash
/handoff "implement the authentication system according to the architecture plan"
```

**Phase 2: Implementation (with @build)**

```
New thread with @build agent:
@.opencode/memory/handoffs/2025-11-20-auth-implementation.md

Implementation tasks:
✅ Create user database models
✅ Build login/signup endpoints
✅ Implement JWT token handling
✅ Add password validation
✅ Write unit tests
✅ Add rate limiting
```

**Handoff includes**:

- Reference to architecture decision document
- Specific API specs to implement
- Testing requirements
- Security constraints
- Performance budgets

---

## Pattern 3: Implementation → Review Handoff

**Scenario**: Feature implementation complete, hand off to code review

**Phase 1: Implementation**

```
Completed work:
✅ 450 lines of feature code
✅ 35 test cases (85% coverage)
✅ Updated documentation
✅ Added error handling
✅ Integrated with existing systems
```

**Create Handoff:**

```bash
/handoff "review the completed authentication feature for security, performance, and code quality"
```

**Phase 2: Review (with @code-auditor)**

```
New thread with @code-auditor agent:
@.opencode/memory/handoffs/2025-11-20-auth-feature-review.md

Review tasks:
✅ Security audit (authentication, token handling)
✅ Performance analysis (database queries, API response times)
✅ Code quality (style, patterns, complexity)
✅ Test coverage validation
✅ Documentation completeness
```

**Handoff benefits**:

- Reviewer has implementation context without reading entire conversation
- Key architectural decisions documented
- Known constraints and requirements listed
- Specific review focus areas highlighted

---

## Pattern 4: Multi-Week Project with Daily Handoffs

**Scenario**: Long-running feature development with daily phase boundaries

**Week 1 - Day 1: Setup**

```
Completed:
✅ Project structure
✅ Configuration
✅ Initial tests passing

/handoff "implement core business logic layer"
→ Creates: 2025-11-20-core-logic-implementation.md
```

**Week 1 - Day 2: Core Logic**

```
Reference: @.opencode/memory/handoffs/2025-11-20-core-logic-implementation.md

Completed:
✅ Business logic implementation
✅ Unit tests
✅ Edge case handling

/handoff "implement API layer using core logic"
→ Creates: 2025-11-21-api-layer-implementation.md
```

**Week 1 - Day 3: API Layer**

```
Reference: @.opencode/memory/handoffs/2025-11-21-api-layer-implementation.md

Completed:
✅ REST endpoints
✅ Request validation
✅ Response formatting

/handoff "implement client-facing UI and integration tests"
→ Creates: 2025-11-22-ui-integration.md
```

**Week 1 - Day 4: UI & Integration**

```
Reference: @.opencode/memory/handoffs/2025-11-22-ui-integration.md

Completed:
✅ User interface
✅ Integration tests
✅ End-to-end workflows

/handoff "perform final review and prepare for production"
→ Creates: 2025-11-23-production-readiness.md
```

**Pattern Benefits**:

- Each day has explicit phase boundary
- Context remains focused and clean
- Easy to parallelize work (team members on different phases)
- Clear progress tracking across days

---

## Implementation Checklist

When using `/handoff` command:

- ✅ Work phase is distinctly complete
- ✅ Clear next phase instructions prepared
- ✅ Key decisions documented
- ✅ Relevant files identified
- ✅ Constraints and requirements listed
- ✅ Trigger: `/handoff "your next phase instructions"`
- ✅ New thread: Reference the generated handoff bundle
- ✅ Continue work with clean context

---

## Handoff Bundle Structure

Every `/handoff` command creates a structured bundle:

```markdown
# Handoff: {Phase Name}

**Date**: YYYY-MM-DD
**From Phase**: Research
**To Phase**: Planning
**Recommended Agent**: @plan

## Summary

{2-4 paragraphs of work completed}

## Key Decisions Made

{List of architectural/design decisions}

## Constraints & Requirements

{Known constraints and requirements}

## Relevant Files

{Files that next phase needs}

## Next Phase Instructions

{Explicit, actionable next steps}
```

---

## Quick Reference: When to Use `/handoff`

| Trigger                    | Action                         |
| -------------------------- | ------------------------------ |
| Completing distinct phase  | `/handoff "next phase goals"`  |
| Handing to different agent | `/handoff "your instructions"` |
| Need portable context      | `/handoff "context bundle"`    |
| Clean slate required       | `/handoff "no history"`        |

---

## Files & Documentation

- `.opencode/command/handoff.md` - Full command documentation
- `.opencode/agent/build.md` - Phase transitions guidance
- `.opencode/agent/rush.md` - Phase transitions guidance
- `.opencode/AGENTS.md` - Global phase transition rules
- `.opencode/memory/handoffs/` - Generated handoff bundles

---

**Status**: Ready for production use. Use `/handoff` command for intentional phase transitions.

_Handoff Workflow Examples - Manual Phase Transitions_
