---
description: Create handoff bundle for clean phase transitions
agent: build
---

# Handoff Command - Clean Phase Transitions

You are creating a clean context handoff for transitioning to the next work phase.

## Your Task

When the user invokes `/handoff "next phase instructions"`, create a portable handoff bundle that allows clean phase transitions without context bleed.

### Steps to Execute

1. **Analyze Current Context**
   - Review recent conversation history (last 5-10 messages)
   - Identify key accomplishments and decisions
   - Determine which files are most relevant
   - Extract actionable insights

2. **Summarize Current Work** (2-4 paragraphs max)
   - What was the goal of this phase?
   - What was accomplished?
   - What key decisions were made?
   - What remains incomplete (if anything)?

3. **List Relevant Files**
   - Use @-mentions for all files that the next phase needs
   - Prioritize files that were created or significantly modified
   - Include documentation files with key context
   - Group by category if many files (e.g., "Config files:", "Source files:")

4. **Extract Key Decisions**
   - Review .opencode/memory for recent decisions
   - List architectural choices made
   - Note any constraints or requirements discovered
   - Include learnings that should inform next phase

5. **Generate Next Prompt**
   - Use the user's handoff instruction as the base: $ARGUMENTS
   - Add necessary context for the next agent
   - Be specific and actionable
   - Suggest which agent should handle it (@plan, @build, @researcher, etc.)

## Output Format

Create a new file at: `.opencode/memory/handoffs/YYYY-MM-DD-{phase-name}.md`

Use this exact template:

```markdown
# Handoff: {Phase Name}

**Date**: YYYY-MM-DD  
**Time**: HH:MM  
**From Phase**: {current phase - e.g., Research, Planning, Implementation}  
**To Phase**: {next phase}  
**Recommended Agent**: @{agent-name}

---

## Summary

{2-4 paragraph summary of work completed in current phase}

Key accomplishments:

- Accomplishment 1
- Accomplishment 2
- Accomplishment 3

---

## Relevant Files

### Created/Modified Files

- @path/to/file1.ts - Purpose/description
- @path/to/file2.md - Purpose/description

### Reference Files

- @path/to/config.json - Why next phase needs this
- @path/to/docs.md - Context provided

---

## Key Decisions Made

1. **Decision 1**: Rationale
2. **Decision 2**: Rationale
3. **Decision 3**: Rationale

---

## Constraints & Requirements

- Constraint 1 (e.g., "Must maintain backwards compatibility")
- Constraint 2 (e.g., "Performance budget: <100ms response time")
- Requirement 1 (e.g., "Must use existing auth system")

---

## Next Phase Instructions

$ARGUMENTS

**Suggested approach:**

1. Step 1
2. Step 2
3. Step 3

---

## Notes for Next Agent

{Any additional context, gotchas, or tips that would help the next phase}

---

_Handoff bundle created by /handoff command - OpenCodeKit_
```

## Important Guidelines

- **Data Minimization**: Only include essential context, not entire conversation history
- **Clean Slate**: The handoff should allow the next phase to start fresh without context pollution
- **Actionable**: Next phase instructions must be specific and immediately actionable
- **Self-Contained**: The handoff file should standalone - next agent shouldn't need to read prior threads
- **Security**: Don't include API keys, passwords, or sensitive data in handoff files

## After Creating Handoff

Tell the user:

```
✅ Handoff bundle created: .opencode/memory/handoffs/YYYY-MM-DD-{phase-name}.md

To continue in next phase:
1. Open a new thread with recommended agent: @{agent-name}
2. Reference the handoff: @.opencode/memory/handoffs/YYYY-MM-DD-{phase-name}.md
3. Or copy-paste the "Next Phase Instructions" section

The handoff bundle is portable - you can share it across workspaces or with teammates.

Alternatively, use opencode-sessions plugin:
- Use `session` tool with mode: "new" to create fresh session
- Or mode: "message" for turn-based collaboration
- Or mode: "compact" to compress context before handoff
```

## Examples

### Example 1: Research → Planning Handoff

User types: `/handoff "design the rate limiting system based on research"`

You create: `.opencode/memory/handoffs/2025-11-17-rate-limiting-design.md`

### Example 2: Planning → Implementation Handoff

User types: `/handoff "implement the authentication flow per the plan"`

You create: `.opencode/memory/handoffs/2025-11-17-auth-implementation.md`

### Example 3: Implementation → Review Handoff

User types: `/handoff "review the completed feature for security and performance"`

You create: `.opencode/memory/handoffs/2025-11-17-feature-review.md`

---

**Remember**: The goal is clean phase transitions with minimal context bleed - only essential knowledge flows forward.
