Handoff

Overview

The Handoff Agent implements structured inter-agent communication inspired by OpenAI's Agents SDK handoff pattern. It ensures that when control passes between agents:

• Context is Preserved: All relevant state transfers with the handoff
• Expectations are Clear: Receiving agent knows exactly what's expected
• Rollback is Possible: Failed handoffs can return to sender
• Audit Trail Exists: Complete history of all handoffs for debugging

Handoff Message Structure

{
  "handoff_id": "ho_abc123",
  "source": {
    "agent": "architect",
    "phase": "design_complete"
  },
  "target": {
    "agent": "auto-code",
    "reason": "Implementation of auth module"
  },
  "context": {
    "artifacts": ["/TODO/auth-module.md"],
    "decisions": ["Use JWT", "bcrypt for passwords"],
    "relevant_memories": ["User prefers explicit error handling"]
  },
  "expectations": {
    "deliverables": ["Auth implementation with tests"],
    "constraints": ["No breaking API changes"],
    "acceptance_criteria": ["Tests passing", "Type check clean"]
  },
  "rollback": {
    "on_failure": "architect",
    "checkpoint_id": "chk_def456"
  }
}

Handoff Flow

1. Initiation

Source agent creates handoff message with full context and expectations.

2. Validation

System verifies target agent can handle the request type.

3. Transfer

Context, artifacts, and memories are loaded into target agent.

4. Execution

Target agent works toward deliverables.

5. Completion

Target reports success with deliverables, or failure with rollback request.

Commands

/handoff show

/handoff show ho_abc123

Handoff ho_abc123
From: architect → To: auto-code
Status: Completed ✓
Duration: 28 minutes

Context Transferred:
- Specification: /TODO/auth-module.md
- Decisions: 3 (JWT, refresh tokens, bcrypt)

Deliverables:
- Created: 4 files (/src/auth/*.ts)
- Tests: All passing

/handoff history

/handoff history

Handoff Chain: TaskManager Implementation

architect ──► auto-code ──► qa-guy ──► ciso
  ho_001       ho_002       ho_003     ho_004
  ✓ 15m        ✓ 28m        ✓ 12m      🔄 In Progress

Agent Capabilities

Agent	Accepts	Produces
architect	design_request, review	specification, decision
auto-code	specification, bug_report	code, tests
qa-guy	code, test_request	test_results, bug_report
ciso	code, security_review	security_report, fixes

Integration Points

System	Integration
Conductor	Orchestrates handoffs between workflow phases
Checkpoint	Saves state before handoffs for rollback
Tracing	Records all handoff events
Memory	Stores handoff history