# Agent Handoff Workflow

**Purpose:** Create comprehensive handoff memory for the next agent and save it to Serena.

## Overview

The `handoff` workflow enables seamless context preservation between AI agent sessions by creating structured handoff memories. It reads the current workflow status, validates required fields, generates a comprehensive handoff document, and saves it to Serena with collision-proof timestamped naming.

## Features

- **Automatic workflow status reading** - Extracts project state and next agent info
- **Field validation** - Ensures all required fields are present before proceeding
- **Comprehensive context capture** - Includes work completed, files to review, success criteria
- **Timestamped naming** - Prevents collisions with format: `[agent]-handoff-YYYY-MM-DD-HHmmss`
- **Serena integration** - Persistent storage across sessions
- **BMAD integration** - Complements `/workflow-status` command
- **Error recovery** - Graceful handling of missing files or fields

## How to Invoke

From any BMAD-enabled session:

```
workflow handoff
```

Or if using the compiled command:

```
/handoff
```

## Requirements

### Dependencies:

- **Serena MCP** - Must be installed and configured
  - `mcp__serena__activate_project`
  - `mcp__serena__write_memory`
- **Workflow status file** - `docs/bmm-workflow-status.md` must exist

### Required Workflow Status Fields:

- `PROJECT_NAME` (required)
- `CURRENT_PHASE` (required)
- `NEXT_AGENT` (required)
- `NEXT_COMMAND` (optional - defaults to "Begin next phase")

## Workflow Steps

1. **Validate workflow status file** - Ensures file exists and has required fields
2. **Read workflow status** - Extract project metadata and next agent info
3. **Extract completed work** - From status file or infer from context
4. **Activate Serena project** - Prepare for memory storage
5. **Validate required fields** - Confirm all critical data is present
6. **Generate handoff memory** - Create structured handoff document
7. **Save to Serena** - Store with timestamped collision-proof name
8. **Output next agent prompt** - Ready-to-use prompt for next session

## Expected Inputs

- **Workflow status file:** `{output_folder}/bmm-workflow-status.md`
- **Current conversation context:** Used to infer completed work

## Generated Outputs

### Serena Memory:

- **Name pattern:** `[next-agent]-handoff-YYYY-MM-DD-HHmmss`
- **Example:** `dev-handoff-2025-10-20-143530`

### Handoff Memory Contains:

- Header metadata (date, from, to, command)
- Work just completed summary
- Current project state
- Task for next agent
- Key context (3-5 critical items)
- Files to review (categorized)
- Success criteria (measurable)
- Next steps
- Important reminders

### Terminal Output:

- Confirmation message with memory name
- Ready-to-use prompt for next session
- Quick version command suggestion

## Integration with BMAD

This workflow complements the BMAD `/workflow-status` command:

- **`/workflow-status`** - Check current state and next recommended action
- **`/handoff`** - Save detailed context for next agent (this workflow)
- **`/handoff-receive`** - Load handoff and display actionable summary

Together they enable seamless agent-to-agent context preservation throughout the BMAD workflow lifecycle.

## Example Usage

### Step 1: Current agent completes their work

```
User: /handoff
```

### Step 2: Workflow executes automatically

- Reads workflow status
- Validates fields
- Generates comprehensive handoff
- Saves to Serena

### Step 3: Agent outputs prompt

```
✅ Handoff memory saved to Serena: dev-handoff-2025-10-20-143530

📋 Copy/paste this prompt for the next session:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Read Serena memory: dev-handoff-2025-10-20-143530

Then execute the handoff.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Quick version: /handoff-receive
```

### Step 4: Next agent receives the handoff

In a new session:

```
User: /handoff-receive
```

## Error Handling

### Missing workflow status file:

```
⚠️ Workflow status file not found or invalid.
Suggestion: Run workflow initialization command or create the file manually
```

### Missing required fields:

```
⚠️ Missing required field: PROJECT_NAME
Continue with placeholder value or cancel? (continue/cancel)
```

### Serena MCP unavailable:

```
⚠️ Failed to activate Serena project.
Troubleshooting: Check Serena MCP server status and configuration
```

## Version Information

- **Version:** 1.0.0
- **BMAD Version:** 6.0.0-alpha.0
- **Author:** BMad Core
- **Requires:** Serena MCP
- **Type:** Action workflow (no document generation)

## Files in This Workflow

```
bmad/core/workflows/handoff/
├── workflow.yaml       # Workflow configuration
├── instructions.md     # Step-by-step execution guide
└── README.md          # This file
```

## Related Workflows

- **`handoff-receive`** - Companion workflow for loading handoffs
- **`workflow-status`** - Check current BMAD workflow state

## Troubleshooting

### Handoff not saving:

1. Verify Serena MCP is installed and running
2. Check project activation status
3. Ensure write permissions to memory store

### Fields not found:

1. Verify workflow status file format
2. Check field names match exactly
3. Update workflow status file with required fields

### Naming collisions:

- Impossible with timestamped format (HHmmss precision)
- If using legacy format, upgrade to timestamped version

## Next Steps After Creating Workflow

1. **Test the workflow** - Run in a real session
2. **Verify Serena integration** - Confirm memories are saved
3. **Test with handoff-receive** - Ensure full round-trip works
4. **Update documentation** - Add project-specific context if needed

---

**Ready to preserve context and enable seamless agent handoffs!** 🚀