Handoff Coordinator

Manages clean transitions between agents and sessions with state serialization and context bridging.

Quick Start

Prepare Handoff

from scripts.handoff_coordinator import HandoffCoordinator

coordinator = HandoffCoordinator(project_dir)
package = await coordinator.prepare_handoff(
    source_agent="coding-agent",
    summary="Completed auth-001, starting auth-002"
)

Execute Handoff

await coordinator.execute_handoff(
    package=package,
    target_agent="coding-agent"
)

Handoff Process

┌─────────────────────────────────────────────────────────────┐
│                    HANDOFF WORKFLOW                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  SOURCE AGENT                                                │
│  ├─ Complete current work                                   │
│  ├─ Save state to files                                    │
│  ├─ Create handoff package                                  │
│  └─ Signal ready for handoff                               │
│                                                              │
│  COORDINATOR                                                 │
│  ├─ Validate state consistency                             │
│  ├─ Serialize handoff package                              │
│  ├─ Store in handoff file                                  │
│  └─ Trigger target agent                                   │
│                                                              │
│  TARGET AGENT                                                │
│  ├─ Load handoff package                                   │
│  ├─ Restore context                                        │
│  ├─ Verify state                                           │
│  └─ Continue work                                          │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Handoff Package

{
  "id": "handoff-20250115-103000",
  "source_agent": "coding-agent",
  "target_agent": "coding-agent",
  "timestamp": "2025-01-15T10:30:00",
  "state": {
    "current_feature": "auth-002",
    "completed_features": ["auth-001"],
    "blockers": [],
    "next_steps": ["Implement logout endpoint"]
  },
  "context": {
    "recent_files": ["src/auth/login.ts"],
    "git_hash": "abc1234",
    "session_number": 5
  },
  "summary": "Completed auth-001, starting auth-002"
}

Handoff Types

Integration Points

• autonomous-session-manager: Triggers session handoffs
• context-compactor: Compacts before handoff
• memory-manager: Stores handoff summaries

References

• references/HANDOFF-PROTOCOL.md - Protocol details
• references/AGENT-TRANSITIONS.md - Transition patterns

Scripts

• scripts/handoff_coordinator.py - Core coordinator
• scripts/state_serializer.py - State serialization
• scripts/context_bridge.py - Context bridging
• scripts/handoff_protocol.py - Protocol implementation