[Phase 4] Agent handoff protocols

[frankbria]

Summary

Define protocols for agents to hand off work to other specialized agents.

Problem

Complex features require multiple agent types: implement → test → review. Currently no mechanism for coordinated handoffs.

Proposed Solution

Handoff Types

• Sequential: Implementation → Test → Review pipeline
• Parallel: Multiple agents on independent subtasks
• Escalation: Agent creates blocker, different agent resolves

Context Passing

• Structured handoff messages
• File change summaries
• Relevant context extraction
• Blocker/question forwarding

Handoff Protocol

1. Completing agent summarizes work done
2. Context packaged for next agent
3. Next agent loaded with relevant context
4. Execution continues with role-appropriate focus

Acceptance Criteria

• Sequential handoff: implement → test pipeline works
• Context preserved across handoffs
• Handoff audit trail
• CLI visibility: cf work status shows handoff chain

Related

• Part of Phase 4 multi-agent work
• [Future] Implement Procedural Memory for Agent Learning #73: Procedural memory for learning

[traycerai]

Plan

Observations

The codebase has a mature multi-agent system with specialized agents (lead, backend, frontend, test, review) and robust state management via SQLite. The file:codeframe/core/agent.py handles single-task execution, file:codeframe/core/conductor.py manages batch orchestration, and file:codeframe/agents/lead_agent.py coordinates multi-agent workflows. However, there's no formal handoff protocol—agents currently work independently without structured context passing or handoff tracking. The existing event system (file:codeframe/core/events.py), blocker mechanism (file:codeframe/core/blockers.py), and run tracking (file:codeframe/core/runtime.py) provide solid foundations for building handoff capabilities.

Approach

The implementation will extend the existing architecture by introducing a handoff protocol layer that sits between task execution and agent coordination. This approach leverages the current event system for audit trails, extends the database schema to track handoff chains, and creates a new HandoffCoordinator module to manage context passing between agents. The design prioritizes minimal disruption to existing workflows while enabling sequential (implement→test→review), parallel (independent subtasks), and escalation (blocker resolution) handoff patterns. CLI visibility will be added through extensions to existing status commands.

Implementation Plan

1. Database Schema Extensions

File: file:codeframe/core/workspace.py

Add new table in _init_database() function after the existing runs table:

CREATE TABLE IF NOT EXISTS handoffs (
    id TEXT PRIMARY KEY,
    workspace_id TEXT NOT NULL,
    from_agent_type TEXT NOT NULL,
    to_agent_type TEXT NOT NULL,
    task_id TEXT NOT NULL,
    handoff_type TEXT NOT NULL,
    context_summary TEXT NOT NULL,
    file_changes TEXT,
    metadata TEXT,
    status TEXT NOT NULL DEFAULT 'PENDING',
    created_at TEXT NOT NULL,
    completed_at TEXT,
    parent_handoff_id TEXT,
    FOREIGN KEY (workspace_id) REFERENCES workspace(id),
    FOREIGN KEY (task_id) REFERENCES tasks(id),
    FOREIGN KEY (parent_handoff_id) REFERENCES handoffs(id),
    CHECK (handoff_type IN ('SEQUENTIAL', 'PARALLEL', 'ESCALATION')),
    CHECK (status IN ('PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED'))
)

Add index for handoff chain queries:

CREATE INDEX IF NOT EXISTS idx_handoffs_task ON handoffs(task_id)
CREATE INDEX IF NOT EXISTS idx_handoffs_parent ON handoffs(parent_handoff_id)
CREATE INDEX IF NOT EXISTS idx_handoffs_status ON handoffs(status)

Update _ensure_schema_upgrades() to add this table for existing workspaces.

2. Handoff Data Models

New File: file:codeframe/core/handoffs.py

Create core handoff management module with:

• HandoffType enum: SEQUENTIAL, PARALLEL, ESCALATION
• HandoffStatus enum: PENDING, IN_PROGRESS, COMPLETED, FAILED
• AgentType enum: LEAD, BACKEND, FRONTEND, TEST, REVIEW
• Handoff dataclass with fields: id, workspace_id, from_agent_type, to_agent_type, task_id, handoff_type, context_summary, file_changes, metadata, status, created_at, completed_at, parent_handoff_id
• HandoffContext dataclass for structured context passing: work_summary, file_changes (list of modified files with diffs), blockers_encountered, test_results, review_findings, next_steps

CRUD functions:

• create_handoff(): Create new handoff record
• get_handoff(): Retrieve handoff by ID
• list_handoffs_for_task(): Get all handoffs for a task
• get_handoff_chain(): Retrieve full handoff chain for a task
• update_handoff_status(): Transition handoff status
• complete_handoff(): Mark handoff as completed with results

3. Handoff Coordinator

New File: file:codeframe/core/handoff_coordinator.py

Central orchestration for handoff workflows:

Class: HandoffCoordinator

Methods:

• __init__(workspace, llm_provider): Initialize with workspace and LLM for context extraction
• initiate_sequential_handoff(task_id, from_agent, to_agent, context): Start sequential pipeline (e.g., implement→test)
• initiate_parallel_handoff(task_id, subtasks, agent_assignments): Distribute subtasks to multiple agents
• initiate_escalation_handoff(task_id, blocker_id, from_agent, to_agent): Hand off blocker resolution
• extract_handoff_context(task_id, run_id): Use LLM to summarize work done, extract file changes, identify key context
• package_context_for_agent(handoff_id, target_agent_type): Prepare context tailored to receiving agent's role
• execute_handoff(handoff_id): Execute the handoff by loading context into next agent's run
• get_handoff_status(task_id): Get current handoff state for a task

Context Extraction Logic:

• Query file:codeframe/core/runtime.py run logs for the task
• Parse file changes from agent's step results
• Extract blocker information from file:codeframe/core/blockers.py
• Use LLM to generate concise summary (max 500 tokens) of work completed
• Structure as HandoffContext object

4. Agent Integration

File: file:codeframe/core/agent.py

Extend Agent class to support handoffs:

• Add handoff_context: Optional[HandoffContext] parameter to __init__()
• In run() method, check for incoming handoff context before loading task context
• If handoff context exists, prepend it to the agent's context with clear markers
• After successful completion, check if task requires handoff to next agent
• Call HandoffCoordinator.initiate_sequential_handoff() if configured

Add new method:

• _check_handoff_requirements(task_id): Determine if task needs handoff based on task metadata or agent type

File: file:codeframe/core/runtime.py

Extend execute_agent() function:

• Before creating Agent, check for pending handoffs via HandoffCoordinator.get_handoff_status()
• If handoff exists, load context via HandoffCoordinator.package_context_for_agent()
• Pass handoff context to Agent constructor
• After agent completion, update handoff status to COMPLETED

5. Lead Agent Coordination

File: file:codeframe/agents/lead_agent.py

Extend multi-agent execution methods:

In start_multi_agent_execution():

• After task assignment, create handoff records for sequential pipelines
• For tasks requiring implement→test→review, create handoff chain
• Track handoff IDs in task metadata

Add new method:

• _configure_task_handoffs(task_id, task_type): Determine handoff chain based on task type
  • Backend tasks: backend_worker → test_worker → review_worker
  • Frontend tasks: frontend_worker → test_worker → review_worker
  • Test tasks: test_worker → review_worker
  • Review tasks: review_worker → lead (for approval)

In complete_issue():

• Check if all handoffs in chain are completed before marking issue done
• Aggregate handoff results for final summary

6. Event System Extensions

File: file:codeframe/core/events.py

Add new event types to EventType class:

HANDOFF_INITIATED = "HANDOFF_INITIATED"
HANDOFF_CONTEXT_PACKAGED = "HANDOFF_CONTEXT_PACKAGED"
HANDOFF_AGENT_STARTED = "HANDOFF_AGENT_STARTED"
HANDOFF_COMPLETED = "HANDOFF_COMPLETED"
HANDOFF_FAILED = "HANDOFF_FAILED"
HANDOFF_CHAIN_COMPLETED = "HANDOFF_CHAIN_COMPLETED"

Emit these events from HandoffCoordinator at appropriate lifecycle points for audit trail.

7. CLI Status Command

File: file:codeframe/cli/tasks_commands.py

Add new command:

@tasks_app.command("handoffs")
def show_handoffs(
    task_id: str,
    format: str = typer.Option("table", "--format", "-f")
)

Display handoff chain for a task:

• Query handoffs table for task
• Build tree structure showing handoff sequence
• Show: agent transitions, status, timestamps, context summaries
• Use Rich library for formatted table output

File: file:codeframe/cli/app.py (or equivalent work commands file)

Extend cf work status command:

• Add handoff chain section showing current handoff state
• Display: current agent, next agent in chain, pending handoffs
• Show context summary for active handoff

8. Batch Execution Integration

File: file:codeframe/core/conductor.py

Extend batch execution to support handoff-aware scheduling:

In _execute_parallel():

• Check for handoff dependencies between tasks
• Ensure tasks with sequential handoffs execute in order
• Allow parallel execution of independent handoff chains

Add new function:

• _build_handoff_dependency_graph(task_ids): Analyze handoff chains to build execution order
• Merge with existing dependency graph from file:codeframe/core/dependency_graph.py

9. Configuration and Metadata

File: file:codeframe/core/tasks.py

Extend task metadata to include handoff configuration:

• Add handoff_chain field (JSON array of agent types)
• Add requires_handoff boolean flag
• Add handoff_strategy field (sequential/parallel/escalation)

Update task creation in PRD generation to infer handoff requirements based on task type.

10. Testing Strategy

Create comprehensive test coverage:

New File: file:tests/core/test_handoffs.py

• Test handoff CRUD operations
• Test handoff chain retrieval
• Test status transitions

New File: file:tests/core/test_handoff_coordinator.py

• Test sequential handoff flow
• Test parallel handoff distribution
• Test escalation handoff
• Test context extraction and packaging
• Mock LLM calls for context summarization

New File: file:tests/integration/test_handoff_pipeline.py

• End-to-end test: implement → test → review pipeline
• Verify context preservation across handoffs
• Verify event emission
• Verify CLI visibility

Extend: file:tests/cli/test_tasks_commands.py

• Test cf tasks handoffs command output
• Test handoff chain display in status

11. Documentation

New File: file:docs/HANDOFF_PROTOCOL.md

Document:

• Handoff types and when to use each
• Context structure and what gets passed
• How to configure handoff chains for tasks
• CLI commands for monitoring handoffs
• Event types emitted during handoffs
• Troubleshooting handoff failures

Update: file:docs/CLI_WIREFRAME.md

• Add cf tasks handoffs <task-id> command
• Add cf work status handoff section
• Document handoff-related flags

Update: file:README.md

• Add handoff protocol to Key Features section
• Add example workflow showing handoff chain

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant LeadAgent
    participant HandoffCoordinator
    participant BackendAgent
    participant TestAgent
    participant ReviewAgent
    participant Database

    User->>CLI: cf work start task-123 --execute
    CLI->>LeadAgent: assign_task(task-123)
    LeadAgent->>HandoffCoordinator: configure_task_handoffs(task-123, "backend")
    HandoffCoordinator->>Database: create_handoff(backend→test)
    HandoffCoordinator->>Database: create_handoff(test→review)
    
    LeadAgent->>BackendAgent: execute_task(task-123)
    BackendAgent->>BackendAgent: implement feature
    BackendAgent->>HandoffCoordinator: extract_handoff_context(task-123)
    HandoffCoordinator->>Database: save context summary
    HandoffCoordinator->>Database: update_handoff_status(COMPLETED)
    HandoffCoordinator-->>Database: emit HANDOFF_COMPLETED event
    
    HandoffCoordinator->>TestAgent: initiate_sequential_handoff()
    HandoffCoordinator->>TestAgent: package_context_for_agent(test)
    TestAgent->>TestAgent: load handoff context
    TestAgent->>TestAgent: write tests based on context
    TestAgent->>HandoffCoordinator: extract_handoff_context(task-123)
    HandoffCoordinator->>Database: update_handoff_status(COMPLETED)
    
    HandoffCoordinator->>ReviewAgent: initiate_sequential_handoff()
    HandoffCoordinator->>ReviewAgent: package_context_for_agent(review)
    ReviewAgent->>ReviewAgent: load handoff context
    ReviewAgent->>ReviewAgent: review code + tests
    ReviewAgent->>HandoffCoordinator: complete_handoff()
    HandoffCoordinator->>Database: update_handoff_status(COMPLETED)
    HandoffCoordinator-->>Database: emit HANDOFF_CHAIN_COMPLETED event
    
    User->>CLI: cf tasks handoffs task-123
    CLI->>Database: get_handoff_chain(task-123)
    Database-->>CLI: handoff chain data
    CLI-->>User: Display handoff chain table

Loading

Implementation Order

1. Phase 1 - Foundation (Days 1-2)

   • Database schema extensions in file:codeframe/core/workspace.py
   • Core data models in file:codeframe/core/handoffs.py
   • Basic CRUD operations and tests

2. Phase 2 - Coordination (Days 3-4)

   • HandoffCoordinator class in file:codeframe/core/handoff_coordinator.py
   • Context extraction logic with LLM integration
   • Event system extensions in file:codeframe/core/events.py

3. Phase 3 - Agent Integration (Days 5-6)

   • Extend file:codeframe/core/agent.py for handoff context
   • Update file:codeframe/core/runtime.py execute_agent()
   • Modify file:codeframe/agents/lead_agent.py coordination logic

4. Phase 4 - CLI & Visibility (Day 7)

   • Add handoff commands to file:codeframe/cli/tasks_commands.py
   • Extend status display in work commands
   • Integration with batch execution in file:codeframe/core/conductor.py

5. Phase 5 - Testing & Documentation (Days 8-9)

   • Comprehensive unit and integration tests
   • End-to-end handoff pipeline tests
   • Documentation in file:docs/HANDOFF_PROTOCOL.md

6. Phase 6 - Validation (Day 10)

   • Manual testing of all three handoff types
   • Performance testing with multiple concurrent handoffs
   • CLI usability validation

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a mature multi-agent system with specialized agents (lead, backend, frontend, test, review) and robust state management via SQLite. The `file:codeframe/core/agent.py` handles single-task execution, `file:codeframe/core/conductor.py` manages batch orchestration, and `file:codeframe/agents/lead_agent.py` coordinates multi-agent workflows. However, there's no formal handoff protocol—agents currently work independently without structured context passing or handoff tracking. The existing event system (`file:codeframe/core/events.py`), blocker mechanism (`file:codeframe/core/blockers.py`), and run tracking (`file:codeframe/core/runtime.py`) provide solid foundations for building handoff capabilities.

## Approach

The implementation will extend the existing architecture by introducing a handoff protocol layer that sits between task execution and agent coordination. This approach leverages the current event system for audit trails, extends the database schema to track handoff chains, and creates a new `HandoffCoordinator` module to manage context passing between agents. The design prioritizes minimal disruption to existing workflows while enabling sequential (implement→test→review), parallel (independent subtasks), and escalation (blocker resolution) handoff patterns. CLI visibility will be added through extensions to existing status commands.

## Implementation Plan

### 1. Database Schema Extensions

**File: `file:codeframe/core/workspace.py`**

Add new table in `_init_database()` function after the existing `runs` table:

```sql
CREATE TABLE IF NOT EXISTS handoffs (
    id TEXT PRIMARY KEY,
    workspace_id TEXT NOT NULL,
    from_agent_type TEXT NOT NULL,
    to_agent_type TEXT NOT NULL,
    task_id TEXT NOT NULL,
    handoff_type TEXT NOT NULL,
    context_summary TEXT NOT NULL,
    file_changes TEXT,
    metadata TEXT,
    status TEXT NOT NULL DEFAULT 'PENDING',
    created_at TEXT NOT NULL,
    completed_at TEXT,
    parent_handoff_id TEXT,
    FOREIGN KEY (workspace_id) REFERENCES workspace(id),
    FOREIGN KEY (task_id) REFERENCES tasks(id),
    FOREIGN KEY (parent_handoff_id) REFERENCES handoffs(id),
    CHECK (handoff_type IN ('SEQUENTIAL', 'PARALLEL', 'ESCALATION')),
    CHECK (status IN ('PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED'))
)
```

Add index for handoff chain queries:
```sql
CREATE INDEX IF NOT EXISTS idx_handoffs_task ON handoffs(task_id)
CREATE INDEX IF NOT EXISTS idx_handoffs_parent ON handoffs(parent_handoff_id)
CREATE INDEX IF NOT EXISTS idx_handoffs_status ON handoffs(status)
```

Update `_ensure_schema_upgrades()` to add this table for existing workspaces.

### 2. Handoff Data Models

**New File: `file:codeframe/core/handoffs.py`**

Create core handoff management module with:

- `HandoffType` enum: SEQUENTIAL, PARALLEL, ESCALATION
- `HandoffStatus` enum: PENDING, IN_PROGRESS, COMPLETED, FAILED
- `AgentType` enum: LEAD, BACKEND, FRONTEND, TEST, REVIEW
- `Handoff` dataclass with fields: id, workspace_id, from_agent_type, to_agent_type, task_id, handoff_type, context_summary, file_changes, metadata, status, created_at, completed_at, parent_handoff_id
- `HandoffContext` dataclass for structured context passing: work_summary, file_changes (list of modified files with diffs), blockers_encountered, test_results, review_findings, next_steps

CRUD functions:
- `create_handoff()`: Create new handoff record
- `get_handoff()`: Retrieve handoff by ID
- `list_handoffs_for_task()`: Get all handoffs for a task
- `get_handoff_chain()`: Retrieve full handoff chain for a task
- `update_handoff_status()`: Transition handoff status
- `complete_handoff()`: Mark handoff as completed with results

### 3. Handoff Coordinator

**New File: `file:codeframe/core/handoff_coordinator.py`**

Central orchestration for handoff workflows:

**Class: `HandoffCoordinator`**

Methods:
- `__init__(workspace, llm_provider)`: Initialize with workspace and LLM for context extraction
- `initiate_sequential_handoff(task_id, from_agent, to_agent, context)`: Start sequential pipeline (e.g., implement→test)
- `initiate_parallel_handoff(task_id, subtasks, agent_assignments)`: Distribute subtasks to multiple agents
- `initiate_escalation_handoff(task_id, blocker_id, from_agent, to_agent)`: Hand off blocker resolution
- `extract_handoff_context(task_id, run_id)`: Use LLM to summarize work done, extract file changes, identify key context
- `package_context_for_agent(handoff_id, target_agent_type)`: Prepare context tailored to receiving agent's role
- `execute_handoff(handoff_id)`: Execute the handoff by loading context into next agent's run
- `get_handoff_status(task_id)`: Get current handoff state for a task

**Context Extraction Logic:**
- Query `file:codeframe/core/runtime.py` run logs for the task
- Parse file changes from agent's step results
- Extract blocker information from `file:codeframe/core/blockers.py`
- Use LLM to generate concise summary (max 500 tokens) of work completed
- Structure as `HandoffContext` object

### 4. Agent Integration

**File: `file:codeframe/core/agent.py`**

Extend `Agent` class to support handoffs:

- Add `handoff_context: Optional[HandoffContext]` parameter to `__init__()`
- In `run()` method, check for incoming handoff context before loading task context
- If handoff context exists, prepend it to the agent's context with clear markers
- After successful completion, check if task requires handoff to next agent
- Call `HandoffCoordinator.initiate_sequential_handoff()` if configured

Add new method:
- `_check_handoff_requirements(task_id)`: Determine if task needs handoff based on task metadata or agent type

**File: `file:codeframe/core/runtime.py`**

Extend `execute_agent()` function:
- Before creating `Agent`, check for pending handoffs via `HandoffCoordinator.get_handoff_status()`
- If handoff exists, load context via `HandoffCoordinator.package_context_for_agent()`
- Pass handoff context to `Agent` constructor
- After agent completion, update handoff status to COMPLETED

### 5. Lead Agent Coordination

**File: `file:codeframe/agents/lead_agent.py`**

Extend multi-agent execution methods:

In `start_multi_agent_execution()`:
- After task assignment, create handoff records for sequential pipelines
- For tasks requiring implement→test→review, create handoff chain
- Track handoff IDs in task metadata

Add new method:
- `_configure_task_handoffs(task_id, task_type)`: Determine handoff chain based on task type
  - Backend tasks: backend_worker → test_worker → review_worker
  - Frontend tasks: frontend_worker → test_worker → review_worker
  - Test tasks: test_worker → review_worker
  - Review tasks: review_worker → lead (for approval)

In `complete_issue()`:
- Check if all handoffs in chain are completed before marking issue done
- Aggregate handoff results for final summary

### 6. Event System Extensions

**File: `file:codeframe/core/events.py`**

Add new event types to `EventType` class:
```python
HANDOFF_INITIATED = "HANDOFF_INITIATED"
HANDOFF_CONTEXT_PACKAGED = "HANDOFF_CONTEXT_PACKAGED"
HANDOFF_AGENT_STARTED = "HANDOFF_AGENT_STARTED"
HANDOFF_COMPLETED = "HANDOFF_COMPLETED"
HANDOFF_FAILED = "HANDOFF_FAILED"
HANDOFF_CHAIN_COMPLETED = "HANDOFF_CHAIN_COMPLETED"
```

Emit these events from `HandoffCoordinator` at appropriate lifecycle points for audit trail.

### 7. CLI Status Command

**File: `file:codeframe/cli/tasks_commands.py`**

Add new command:
```python
@tasks_app.command("handoffs")
def show_handoffs(
    task_id: str,
    format: str = typer.Option("table", "--format", "-f")
)
```

Display handoff chain for a task:
- Query `handoffs` table for task
- Build tree structure showing handoff sequence
- Show: agent transitions, status, timestamps, context summaries
- Use Rich library for formatted table output

**File: `file:codeframe/cli/app.py`** (or equivalent work commands file)

Extend `cf work status` command:
- Add handoff chain section showing current handoff state
- Display: current agent, next agent in chain, pending handoffs
- Show context summary for active handoff

### 8. Batch Execution Integration

**File: `file:codeframe/core/conductor.py`**

Extend batch execution to support handoff-aware scheduling:

In `_execute_parallel()`:
- Check for handoff dependencies between tasks
- Ensure tasks with sequential handoffs execute in order
- Allow parallel execution of independent handoff chains

Add new function:
- `_build_handoff_dependency_graph(task_ids)`: Analyze handoff chains to build execution order
- Merge with existing dependency graph from `file:codeframe/core/dependency_graph.py`

### 9. Configuration and Metadata

**File: `file:codeframe/core/tasks.py`**

Extend task metadata to include handoff configuration:
- Add `handoff_chain` field (JSON array of agent types)
- Add `requires_handoff` boolean flag
- Add `handoff_strategy` field (sequential/parallel/escalation)

Update task creation in PRD generation to infer handoff requirements based on task type.

### 10. Testing Strategy

Create comprehensive test coverage:

**New File: `file:tests/core/test_handoffs.py`**
- Test handoff CRUD operations
- Test handoff chain retrieval
- Test status transitions

**New File: `file:tests/core/test_handoff_coordinator.py`**
- Test sequential handoff flow
- Test parallel handoff distribution
- Test escalation handoff
- Test context extraction and packaging
- Mock LLM calls for context summarization

**New File: `file:tests/integration/test_handoff_pipeline.py`**
- End-to-end test: implement → test → review pipeline
- Verify context preservation across handoffs
- Verify event emission
- Verify CLI visibility

**Extend: `file:tests/cli/test_tasks_commands.py`**
- Test `cf tasks handoffs` command output
- Test handoff chain display in status

### 11. Documentation

**New File: `file:docs/HANDOFF_PROTOCOL.md`**

Document:
- Handoff types and when to use each
- Context structure and what gets passed
- How to configure handoff chains for tasks
- CLI commands for monitoring handoffs
- Event types emitted during handoffs
- Troubleshooting handoff failures

**Update: `file:docs/CLI_WIREFRAME.md`**
- Add `cf tasks handoffs <task-id>` command
- Add `cf work status` handoff section
- Document handoff-related flags

**Update: `file:README.md`**
- Add handoff protocol to Key Features section
- Add example workflow showing handoff chain

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant LeadAgent
    participant HandoffCoordinator
    participant BackendAgent
    participant TestAgent
    participant ReviewAgent
    participant Database

    User->>CLI: cf work start task-123 --execute
    CLI->>LeadAgent: assign_task(task-123)
    LeadAgent->>HandoffCoordinator: configure_task_handoffs(task-123, "backend")
    HandoffCoordinator->>Database: create_handoff(backend→test)
    HandoffCoordinator->>Database: create_handoff(test→review)
    
    LeadAgent->>BackendAgent: execute_task(task-123)
    BackendAgent->>BackendAgent: implement feature
    BackendAgent->>HandoffCoordinator: extract_handoff_context(task-123)
    HandoffCoordinator->>Database: save context summary
    HandoffCoordinator->>Database: update_handoff_status(COMPLETED)
    HandoffCoordinator-->>Database: emit HANDOFF_COMPLETED event
    
    HandoffCoordinator->>TestAgent: initiate_sequential_handoff()
    HandoffCoordinator->>TestAgent: package_context_for_agent(test)
    TestAgent->>TestAgent: load handoff context
    TestAgent->>TestAgent: write tests based on context
    TestAgent->>HandoffCoordinator: extract_handoff_context(task-123)
    HandoffCoordinator->>Database: update_handoff_status(COMPLETED)
    
    HandoffCoordinator->>ReviewAgent: initiate_sequential_handoff()
    HandoffCoordinator->>ReviewAgent: package_context_for_agent(review)
    ReviewAgent->>ReviewAgent: load handoff context
    ReviewAgent->>ReviewAgent: review code + tests
    ReviewAgent->>HandoffCoordinator: complete_handoff()
    HandoffCoordinator->>Database: update_handoff_status(COMPLETED)
    HandoffCoordinator-->>Database: emit HANDOFF_CHAIN_COMPLETED event
    
    User->>CLI: cf tasks handoffs task-123
    CLI->>Database: get_handoff_chain(task-123)
    Database-->>CLI: handoff chain data
    CLI-->>User: Display handoff chain table
```

## Implementation Order

1. **Phase 1 - Foundation** (Days 1-2)
   - Database schema extensions in `file:codeframe/core/workspace.py`
   - Core data models in `file:codeframe/core/handoffs.py`
   - Basic CRUD operations and tests

2. **Phase 2 - Coordination** (Days 3-4)
   - `HandoffCoordinator` class in `file:codeframe/core/handoff_coordinator.py`
   - Context extraction logic with LLM integration
   - Event system extensions in `file:codeframe/core/events.py`

3. **Phase 3 - Agent Integration** (Days 5-6)
   - Extend `file:codeframe/core/agent.py` for handoff context
   - Update `file:codeframe/core/runtime.py` execute_agent()
   - Modify `file:codeframe/agents/lead_agent.py` coordination logic

4. **Phase 4 - CLI & Visibility** (Day 7)
   - Add handoff commands to `file:codeframe/cli/tasks_commands.py`
   - Extend status display in work commands
   - Integration with batch execution in `file:codeframe/core/conductor.py`

5. **Phase 5 - Testing & Documentation** (Days 8-9)
   - Comprehensive unit and integration tests
   - End-to-end handoff pipeline tests
   - Documentation in `file:docs/HANDOFF_PROTOCOL.md`

6. **Phase 6 - Validation** (Day 10)
   - Manual testing of all three handoff types
   - Performance testing with multiple concurrent handoffs
   - CLI usability validation

---

Execution Information

Branch: main
Commit: e768c1d

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[frankbria]

Closing: Superseded by #408 (Agent Adapter Architecture). External agents don't hand off to each other within CodeFrame. CodeFrame orchestrates the pipeline (Think → Build → Prove → Ship), not inter-agent communication.