[P3] Refactor: Decompose LeadAgent monolith (110KB) into focused modules

[frankbria]

Problem

lead_agent.py at 110KB is a monolith that violates Single Responsibility Principle. It handles orchestration, discovery, planning, and conversation management all in one file.

Current State

• File: codeframe/agents/lead_agent.py (~110KB, ~3000+ lines)
• Combines: Agent orchestration, Discovery workflow, Planning pipeline, Conversation/chat, PRD generation

Impact

• Hard to maintain and debug
• Changes to discovery can break planning
• Testing is complex due to tight coupling
• New developers struggle to understand flow

Required Decomposition

New Module Structure

codeframe/agents/
├── lead_agent.py              # Thin orchestrator (reduced to ~500 lines)
├── coordinators/
│   ├── __init__.py
│   ├── discovery_coordinator.py    # Socratic Q&A workflow
│   ├── planning_coordinator.py     # Issue/task generation
│   └── agent_coordinator.py        # Worker agent management
└── managers/
    ├── __init__.py
    └── conversation_manager.py     # Chat persistence

Responsibility Split

Module	Responsibility
LeadAgent	High-level orchestration, state transitions
DiscoveryCoordinator	Socratic questions, answer processing
PlanningCoordinator	PRD → Issues → Tasks pipeline
AgentCoordinator	Worker spawning, task assignment
ConversationManager	Chat history, context persistence

Acceptance Criteria

• LeadAgent reduced to <500 lines
• Each coordinator is independently testable
• No change to external API/behavior
• All existing tests pass
• Coverage maintained at >85%

Migration Strategy

1. Extract DiscoveryCoordinator first (highest complexity)
2. Extract PlanningCoordinator
3. Extract AgentCoordinator
4. Extract ConversationManager
5. Thin LeadAgent to orchestrator only

Committee Report Reference

System Architect and Python Expert both flagged LeadAgent as "architectural smell". Quote: "Doing too much - orchestration, discovery, planning, conversation."

[traycerai]

Plan

Observations

The file:codeframe/agents/lead_agent.py file (~110KB, 2600+ lines) is a monolithic class handling multiple distinct responsibilities: Socratic discovery workflow, PRD generation, issue/task planning, multi-agent coordination, conversation management, and session lifecycle. The codebase already follows clear patterns with focused manager classes (file:codeframe/agents/agent_pool_manager.py, file:codeframe/core/phase_manager.py, file:codeframe/core/session_manager.py). External consumers (file:codeframe/ui/routers/discovery.py, file:codeframe/ui/services/agent_service.py) interact with LeadAgent through well-defined methods. The test suite (file:tests/agents/test_lead_agent_socratic_discovery.py) demonstrates comprehensive coverage with clear unit and integration test patterns.

Approach

The refactoring will follow a phased extraction strategy, creating focused coordinator and manager modules while maintaining the LeadAgent as a thin orchestrator. Each extraction phase will preserve the external API, ensuring zero breaking changes. The approach prioritizes extracting the most complex responsibility first (Discovery) to validate the pattern, then systematically extracts Planning, Agent Coordination, and Conversation Management. The final LeadAgent will delegate to coordinators while maintaining backward compatibility. This aligns with existing codebase patterns where managers handle specific domains (AgentPoolManager for agents, PhaseManager for phases, SessionManager for sessions).

Implementation Steps

Phase 1: Create Module Structure

Create the new directory structure and base files:

1.1 Create Coordinators Directory

• Create file:codeframe/agents/coordinators/ directory
• Create file:codeframe/agents/coordinators/__init__.py with exports for all coordinator classes
• Create file:codeframe/agents/managers/ directory
• Create file:codeframe/agents/managers/__init__.py with exports for manager classes

Phase 2: Extract DiscoveryCoordinator (Highest Complexity)

2.1 Create DiscoveryCoordinator Class

• Create file:codeframe/agents/coordinators/discovery_coordinator.py
• Extract discovery-related methods from LeadAgent (lines 283-995):
  • start_discovery() - Initialize Socratic Q&A session
  • process_discovery_answer() - Process user answers and generate next questions
  • get_discovery_status() - Return current discovery state
  • reset_discovery() - Clear discovery state
  • _generate_next_discovery_question() - AI-powered question generation
  • _build_discovery_question_prompt() - Prompt engineering for Socratic questions
  • _get_category_coverage() - Track coverage of required categories
  • _load_discovery_state() - Load state from database
  • _save_discovery_state() - Persist state to database
  • _discovery_conversation_history - Conversation tracking
  • _discovery_answers - Answer storage
  • _discovery_state - State machine (idle/discovering/completed)

2.2 DiscoveryCoordinator Dependencies

• Accept project_id, db, anthropic_provider in constructor
• Use composition: inject AnthropicProvider instance for AI calls
• Maintain internal state: _conversation_history, _answers, _state
• Expose public methods matching LeadAgent's discovery API

2.3 Update LeadAgent to Delegate Discovery

• In file:codeframe/agents/lead_agent.py __init__(), instantiate DiscoveryCoordinator
• Replace discovery method implementations with delegation:

  def start_discovery(self, initial_context=None):
      return self.discovery_coordinator.start_discovery(initial_context)

• Remove extracted private methods and state variables
• Keep public API signatures identical for backward compatibility

2.4 Update Discovery Tests

• Modify file:tests/agents/test_lead_agent_socratic_discovery.py to test DiscoveryCoordinator directly
• Add integration tests that verify LeadAgent delegation works correctly
• Ensure all existing tests pass without modification to test assertions

Phase 3: Extract PlanningCoordinator

3.1 Create PlanningCoordinator Class

• Create file:codeframe/agents/coordinators/planning_coordinator.py
• Extract planning-related methods from LeadAgent (lines 996-1730):
  • generate_prd() - Generate PRD from discovery data
  • generate_issues(sprint_number) - Create issues from PRD
  • decompose_prd() - Decompose PRD into tasks
  • _save_prd_to_file() - Persist PRD document
  • _index_codebase() - Index project structure
  • _query_codebase() - Query indexed codebase

3.2 PlanningCoordinator Dependencies

• Accept project_id, db, anthropic_provider, workspace_path in constructor
• Depend on DiscoveryCoordinator to access structured discovery data
• Use DependencyResolver for task dependency analysis
• Expose methods: generate_prd(), generate_issues(), decompose_prd()

3.3 Update LeadAgent to Delegate Planning

• Instantiate PlanningCoordinator in __init__()
• Delegate planning methods to coordinator
• Maintain backward-compatible API

3.4 Update Planning Tests

• Create file:tests/agents/coordinators/test_planning_coordinator.py
• Move relevant tests from file:tests/agents/test_lead_agent.py
• Add integration tests for LeadAgent → PlanningCoordinator delegation

Phase 4: Extract AgentCoordinator

4.1 Create AgentCoordinator Class

• Create file:codeframe/agents/coordinators/agent_coordinator.py
• Extract agent management methods from LeadAgent (lines 1937-2279):
  • execute_tasks_parallel() - Main coordination loop
  • assign_task_to_agent() - Task assignment with validation
  • _handle_task_execution() - Execute single task with retry logic
  • _handle_blocker() - SYNC/ASYNC blocker handling
  • _resolve_dependencies() - Dependency resolution
  • _broadcast_task_events() - WebSocket notifications

4.2 AgentCoordinator Dependencies

• Accept project_id, db, agent_pool_manager, dependency_resolver, ws_manager in constructor
• Leverage existing AgentPoolManager for worker lifecycle
• Use DependencyResolver for task ordering
• Expose: execute_tasks_parallel(), assign_task_to_agent()

4.3 Update LeadAgent to Delegate Agent Coordination

• Instantiate AgentCoordinator in __init__()
• Delegate multi-agent execution to coordinator
• Keep orchestration logic in LeadAgent (when to start execution)

4.4 Update Agent Coordination Tests

• Create file:tests/agents/coordinators/test_agent_coordinator.py
• Move tests from file:tests/agents/test_lead_agent.py related to task execution
• Test blocker handling, dependency resolution, parallel execution

Phase 5: Extract ConversationManager

5.1 Create ConversationManager Class

• Create file:codeframe/agents/managers/conversation_manager.py
• Extract conversation methods from LeadAgent (lines 168-282):
  • chat() - Natural language conversation with Claude
  • _load_conversation_history() - Load chat history from database
  • _save_conversation_turn() - Persist conversation turn
  • _conversation_history - Chat message storage

5.2 ConversationManager Dependencies

• Accept project_id, db, anthropic_provider in constructor
• Manage conversation state independently
• Expose: chat(message), get_history(), clear_history()

5.3 Update LeadAgent to Delegate Conversation

• Instantiate ConversationManager in __init__()
• Delegate chat methods to manager
• Maintain backward-compatible API

5.4 Update Conversation Tests

• Create file:tests/agents/managers/test_conversation_manager.py
• Move conversation tests from file:tests/agents/test_lead_agent.py
• Test history persistence, message formatting

Phase 6: Thin LeadAgent to Orchestrator

6.1 Refactor LeadAgent Core

• Reduce file:codeframe/agents/lead_agent.py to ~500 lines
• Keep only:
  • __init__() - Initialize all coordinators/managers
  • High-level orchestration methods (when to trigger discovery → planning → execution)
  • State transition logic (discovery complete → start planning)
  • Public API delegation methods
  • Session lifecycle methods (lines 2280-2676)

6.2 LeadAgent Responsibilities

• Coordinate workflow phases: discovery → planning → execution → review
• Manage project-level state transitions
• Delegate domain-specific work to coordinators
• Maintain backward compatibility with existing API

6.3 Update LeadAgent Imports

• Import coordinators: from codeframe.agents.coordinators import DiscoveryCoordinator, PlanningCoordinator, AgentCoordinator
• Import managers: from codeframe.agents.managers import ConversationManager
• Update file:codeframe/agents/__init__.py to export coordinators/managers if needed

Phase 7: Update External Consumers

7.1 Verify Router Compatibility

• Review file:codeframe/ui/routers/discovery.py - should work unchanged (delegates to LeadAgent)
• Review file:codeframe/ui/routers/agents.py - verify agent lifecycle methods still work
• Review file:codeframe/ui/services/agent_service.py - ensure LeadAgent API unchanged

7.2 Update Documentation

• Update file:AGENTS.md with new architecture diagram
• Document coordinator responsibilities and APIs
• Add migration guide for developers extending LeadAgent

Phase 8: Test Suite Validation

8.1 Run Full Test Suite

• Execute all tests in file:tests/agents/ directory
• Verify file:tests/agents/test_lead_agent.py passes (integration tests)
• Verify file:tests/agents/test_lead_agent_socratic_discovery.py passes
• Verify file:tests/agents/test_lead_agent_blocker_handling.py passes
• Verify file:tests/agents/test_lead_agent_git_integration.py passes
• Verify file:tests/agents/test_lead_agent_session.py passes

8.2 Coverage Validation

• Run coverage report: pytest --cov=codeframe/agents --cov-report=term-missing
• Ensure coverage remains >85% as per acceptance criteria
• Add tests for any uncovered coordinator methods

8.3 Integration Testing

• Test full workflow: discovery → PRD → issues → tasks → execution
• Verify WebSocket broadcasts still work
• Test error handling and fallback mechanisms

Phase 9: Bottleneck Detection Refactoring

9.1 Extract Bottleneck Detection

• Create file:codeframe/agents/coordinators/bottleneck_detector.py
• Extract bottleneck detection methods (lines 1145-1505):
  • detect_workflow_bottlenecks() - Main detection logic
  • _detect_dependency_waits() - Identify blocked tasks
  • _detect_agent_overload() - Find overloaded agents
  • _detect_idle_agents() - Find underutilized agents
  • _detect_critical_path_blockers() - Critical path analysis

9.2 Integrate with AgentCoordinator

• AgentCoordinator uses BottleneckDetector for monitoring
• Expose bottleneck detection through LeadAgent API
• Maintain existing bottleneck detection behavior

Phase 10: Final Cleanup and Optimization

10.1 Remove Dead Code

• Remove any unused imports from LeadAgent
• Clean up commented-out code
• Verify no duplicate logic between coordinators

10.2 Performance Validation

• Benchmark discovery workflow performance (should be unchanged)
• Benchmark planning workflow performance
• Verify no performance regression from delegation overhead

10.3 Code Review Checklist

• Each coordinator is <500 lines
• Each coordinator has single responsibility
• All coordinators are independently testable
• No circular dependencies between coordinators
• LeadAgent is <500 lines (orchestrator only)
• All external APIs unchanged
• All tests pass
• Coverage >85%

Architecture Diagram

sequenceDiagram
    participant UI as UI Router
    participant LA as LeadAgent<br/>(Orchestrator)
    participant DC as DiscoveryCoordinator
    participant PC as PlanningCoordinator
    participant AC as AgentCoordinator
    participant CM as ConversationManager
    participant DB as Database

    UI->>LA: start_discovery()
    LA->>DC: start_discovery()
    DC->>DB: load_discovery_state()
    DC->>DC: generate_first_question()
    DC-->>LA: first_question
    LA-->>UI: first_question

    UI->>LA: process_discovery_answer()
    LA->>DC: process_discovery_answer()
    DC->>DB: save_answer()
    DC->>DC: check_completion()
    DC-->>LA: next_question / completed
    LA-->>UI: response

    UI->>LA: generate_prd()
    LA->>PC: generate_prd()
    PC->>DC: get_structured_data()
    PC->>PC: build_prd_from_discovery()
    PC->>DB: save_prd()
    PC-->>LA: prd_content
    LA-->>UI: prd_content

    UI->>LA: generate_issues()
    LA->>PC: generate_issues()
    PC->>DB: get_prd()
    PC->>PC: decompose_into_issues()
    PC->>DB: save_issues()
    PC-->>LA: issues
    LA-->>UI: issues

    UI->>LA: execute_tasks_parallel()
    LA->>AC: execute_tasks_parallel()
    AC->>AC: resolve_dependencies()
    AC->>AC: assign_tasks_to_agents()
    AC->>DB: update_task_status()
    AC-->>LA: execution_result
    LA-->>UI: execution_result

Loading

Module Responsibility Matrix

Module	Lines	Responsibilities	Key Methods
LeadAgent	~500	High-level orchestration, state transitions, workflow coordination	__init__(), workflow phase transitions, session lifecycle
DiscoveryCoordinator	~400	Socratic Q&A workflow, question generation, category coverage tracking	start_discovery(), process_discovery_answer(), get_discovery_status(), reset_discovery()
PlanningCoordinator	~350	PRD generation, issue creation, task decomposition, codebase indexing	generate_prd(), generate_issues(), decompose_prd()
AgentCoordinator	~400	Worker agent management, task assignment, parallel execution, blocker handling	execute_tasks_parallel(), assign_task_to_agent(), _handle_blocker()
ConversationManager	~150	Chat history persistence, natural language conversation	chat(), get_history(), clear_history()
BottleneckDetector	~300	Workflow bottleneck detection, critical path analysis	detect_workflow_bottlenecks(), _detect_dependency_waits()

Dependency Flow

graph TD
    LA[LeadAgent<br/>Orchestrator]
    DC[DiscoveryCoordinator]
    PC[PlanningCoordinator]
    AC[AgentCoordinator]
    CM[ConversationManager]
    BD[BottleneckDetector]
    
    LA --> DC
    LA --> PC
    LA --> AC
    LA --> CM
    
    PC -.depends on.-> DC
    AC --> BD
    
    DC --> DB[(Database)]
    PC --> DB
    AC --> DB
    CM --> DB
    
    DC --> AP[AnthropicProvider]
    PC --> AP
    CM --> AP
    
    AC --> APM[AgentPoolManager]
    AC --> DR[DependencyResolver]

Loading

Testing Strategy

Test File	Focus	Coverage Target
test_discovery_coordinator.py	Discovery workflow, Socratic Q&A, category coverage	>90%
test_planning_coordinator.py	PRD generation, issue/task creation	>85%
test_agent_coordinator.py	Task execution, blocker handling, parallel coordination	>85%
test_conversation_manager.py	Chat history, conversation persistence	>90%
test_bottleneck_detector.py	Bottleneck detection, critical path analysis	>85%
test_lead_agent.py (updated)	Integration tests, workflow orchestration, backward compatibility	>85%

Migration Validation Checklist

• LeadAgent reduced to <500 lines
• DiscoveryCoordinator independently testable
• PlanningCoordinator independently testable
• AgentCoordinator independently testable
• ConversationManager independently testable
• No changes to external API (routers, services work unchanged)
• All existing tests pass without modification
• Coverage maintained at >85%
• No performance regression
• Documentation updated

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `file:codeframe/agents/lead_agent.py` file (~110KB, 2600+ lines) is a monolithic class handling multiple distinct responsibilities: Socratic discovery workflow, PRD generation, issue/task planning, multi-agent coordination, conversation management, and session lifecycle. The codebase already follows clear patterns with focused manager classes (`file:codeframe/agents/agent_pool_manager.py`, `file:codeframe/core/phase_manager.py`, `file:codeframe/core/session_manager.py`). External consumers (`file:codeframe/ui/routers/discovery.py`, `file:codeframe/ui/services/agent_service.py`) interact with LeadAgent through well-defined methods. The test suite (`file:tests/agents/test_lead_agent_socratic_discovery.py`) demonstrates comprehensive coverage with clear unit and integration test patterns.

## Approach

The refactoring will follow a phased extraction strategy, creating focused coordinator and manager modules while maintaining the LeadAgent as a thin orchestrator. Each extraction phase will preserve the external API, ensuring zero breaking changes. The approach prioritizes extracting the most complex responsibility first (Discovery) to validate the pattern, then systematically extracts Planning, Agent Coordination, and Conversation Management. The final LeadAgent will delegate to coordinators while maintaining backward compatibility. This aligns with existing codebase patterns where managers handle specific domains (AgentPoolManager for agents, PhaseManager for phases, SessionManager for sessions).

## Implementation Steps

### Phase 1: Create Module Structure

Create the new directory structure and base files:

**1.1 Create Coordinators Directory**
- Create `file:codeframe/agents/coordinators/` directory
- Create `file:codeframe/agents/coordinators/__init__.py` with exports for all coordinator classes
- Create `file:codeframe/agents/managers/` directory  
- Create `file:codeframe/agents/managers/__init__.py` with exports for manager classes

### Phase 2: Extract DiscoveryCoordinator (Highest Complexity)

**2.1 Create DiscoveryCoordinator Class**
- Create `file:codeframe/agents/coordinators/discovery_coordinator.py`
- Extract discovery-related methods from LeadAgent (lines 283-995):
  - `start_discovery()` - Initialize Socratic Q&A session
  - `process_discovery_answer()` - Process user answers and generate next questions
  - `get_discovery_status()` - Return current discovery state
  - `reset_discovery()` - Clear discovery state
  - `_generate_next_discovery_question()` - AI-powered question generation
  - `_build_discovery_question_prompt()` - Prompt engineering for Socratic questions
  - `_get_category_coverage()` - Track coverage of required categories
  - `_load_discovery_state()` - Load state from database
  - `_save_discovery_state()` - Persist state to database
  - `_discovery_conversation_history` - Conversation tracking
  - `_discovery_answers` - Answer storage
  - `_discovery_state` - State machine (idle/discovering/completed)

**2.2 DiscoveryCoordinator Dependencies**
- Accept `project_id`, `db`, `anthropic_provider` in constructor
- Use composition: inject AnthropicProvider instance for AI calls
- Maintain internal state: `_conversation_history`, `_answers`, `_state`
- Expose public methods matching LeadAgent's discovery API

**2.3 Update LeadAgent to Delegate Discovery**
- In `file:codeframe/agents/lead_agent.py` `__init__()`, instantiate DiscoveryCoordinator
- Replace discovery method implementations with delegation:
  ```python
  def start_discovery(self, initial_context=None):
      return self.discovery_coordinator.start_discovery(initial_context)
  ```
- Remove extracted private methods and state variables
- Keep public API signatures identical for backward compatibility

**2.4 Update Discovery Tests**
- Modify `file:tests/agents/test_lead_agent_socratic_discovery.py` to test DiscoveryCoordinator directly
- Add integration tests that verify LeadAgent delegation works correctly
- Ensure all existing tests pass without modification to test assertions

### Phase 3: Extract PlanningCoordinator

**3.1 Create PlanningCoordinator Class**
- Create `file:codeframe/agents/coordinators/planning_coordinator.py`
- Extract planning-related methods from LeadAgent (lines 996-1730):
  - `generate_prd()` - Generate PRD from discovery data
  - `generate_issues(sprint_number)` - Create issues from PRD
  - `decompose_prd()` - Decompose PRD into tasks
  - `_save_prd_to_file()` - Persist PRD document
  - `_index_codebase()` - Index project structure
  - `_query_codebase()` - Query indexed codebase

**3.2 PlanningCoordinator Dependencies**
- Accept `project_id`, `db`, `anthropic_provider`, `workspace_path` in constructor
- Depend on DiscoveryCoordinator to access structured discovery data
- Use DependencyResolver for task dependency analysis
- Expose methods: `generate_prd()`, `generate_issues()`, `decompose_prd()`

**3.3 Update LeadAgent to Delegate Planning**
- Instantiate PlanningCoordinator in `__init__()`
- Delegate planning methods to coordinator
- Maintain backward-compatible API

**3.4 Update Planning Tests**
- Create `file:tests/agents/coordinators/test_planning_coordinator.py`
- Move relevant tests from `file:tests/agents/test_lead_agent.py`
- Add integration tests for LeadAgent → PlanningCoordinator delegation

### Phase 4: Extract AgentCoordinator

**4.1 Create AgentCoordinator Class**
- Create `file:codeframe/agents/coordinators/agent_coordinator.py`
- Extract agent management methods from LeadAgent (lines 1937-2279):
  - `execute_tasks_parallel()` - Main coordination loop
  - `assign_task_to_agent()` - Task assignment with validation
  - `_handle_task_execution()` - Execute single task with retry logic
  - `_handle_blocker()` - SYNC/ASYNC blocker handling
  - `_resolve_dependencies()` - Dependency resolution
  - `_broadcast_task_events()` - WebSocket notifications

**4.2 AgentCoordinator Dependencies**
- Accept `project_id`, `db`, `agent_pool_manager`, `dependency_resolver`, `ws_manager` in constructor
- Leverage existing AgentPoolManager for worker lifecycle
- Use DependencyResolver for task ordering
- Expose: `execute_tasks_parallel()`, `assign_task_to_agent()`

**4.3 Update LeadAgent to Delegate Agent Coordination**
- Instantiate AgentCoordinator in `__init__()`
- Delegate multi-agent execution to coordinator
- Keep orchestration logic in LeadAgent (when to start execution)

**4.4 Update Agent Coordination Tests**
- Create `file:tests/agents/coordinators/test_agent_coordinator.py`
- Move tests from `file:tests/agents/test_lead_agent.py` related to task execution
- Test blocker handling, dependency resolution, parallel execution

### Phase 5: Extract ConversationManager

**5.1 Create ConversationManager Class**
- Create `file:codeframe/agents/managers/conversation_manager.py`
- Extract conversation methods from LeadAgent (lines 168-282):
  - `chat()` - Natural language conversation with Claude
  - `_load_conversation_history()` - Load chat history from database
  - `_save_conversation_turn()` - Persist conversation turn
  - `_conversation_history` - Chat message storage

**5.2 ConversationManager Dependencies**
- Accept `project_id`, `db`, `anthropic_provider` in constructor
- Manage conversation state independently
- Expose: `chat(message)`, `get_history()`, `clear_history()`

**5.3 Update LeadAgent to Delegate Conversation**
- Instantiate ConversationManager in `__init__()`
- Delegate chat methods to manager
- Maintain backward-compatible API

**5.4 Update Conversation Tests**
- Create `file:tests/agents/managers/test_conversation_manager.py`
- Move conversation tests from `file:tests/agents/test_lead_agent.py`
- Test history persistence, message formatting

### Phase 6: Thin LeadAgent to Orchestrator

**6.1 Refactor LeadAgent Core**
- Reduce `file:codeframe/agents/lead_agent.py` to ~500 lines
- Keep only:
  - `__init__()` - Initialize all coordinators/managers
  - High-level orchestration methods (when to trigger discovery → planning → execution)
  - State transition logic (discovery complete → start planning)
  - Public API delegation methods
  - Session lifecycle methods (lines 2280-2676)

**6.2 LeadAgent Responsibilities**
- Coordinate workflow phases: discovery → planning → execution → review
- Manage project-level state transitions
- Delegate domain-specific work to coordinators
- Maintain backward compatibility with existing API

**6.3 Update LeadAgent Imports**
- Import coordinators: `from codeframe.agents.coordinators import DiscoveryCoordinator, PlanningCoordinator, AgentCoordinator`
- Import managers: `from codeframe.agents.managers import ConversationManager`
- Update `file:codeframe/agents/__init__.py` to export coordinators/managers if needed

### Phase 7: Update External Consumers

**7.1 Verify Router Compatibility**
- Review `file:codeframe/ui/routers/discovery.py` - should work unchanged (delegates to LeadAgent)
- Review `file:codeframe/ui/routers/agents.py` - verify agent lifecycle methods still work
- Review `file:codeframe/ui/services/agent_service.py` - ensure LeadAgent API unchanged

**7.2 Update Documentation**
- Update `file:AGENTS.md` with new architecture diagram
- Document coordinator responsibilities and APIs
- Add migration guide for developers extending LeadAgent

### Phase 8: Test Suite Validation

**8.1 Run Full Test Suite**
- Execute all tests in `file:tests/agents/` directory
- Verify `file:tests/agents/test_lead_agent.py` passes (integration tests)
- Verify `file:tests/agents/test_lead_agent_socratic_discovery.py` passes
- Verify `file:tests/agents/test_lead_agent_blocker_handling.py` passes
- Verify `file:tests/agents/test_lead_agent_git_integration.py` passes
- Verify `file:tests/agents/test_lead_agent_session.py` passes

**8.2 Coverage Validation**
- Run coverage report: `pytest --cov=codeframe/agents --cov-report=term-missing`
- Ensure coverage remains >85% as per acceptance criteria
- Add tests for any uncovered coordinator methods

**8.3 Integration Testing**
- Test full workflow: discovery → PRD → issues → tasks → execution
- Verify WebSocket broadcasts still work
- Test error handling and fallback mechanisms

### Phase 9: Bottleneck Detection Refactoring

**9.1 Extract Bottleneck Detection**
- Create `file:codeframe/agents/coordinators/bottleneck_detector.py`
- Extract bottleneck detection methods (lines 1145-1505):
  - `detect_workflow_bottlenecks()` - Main detection logic
  - `_detect_dependency_waits()` - Identify blocked tasks
  - `_detect_agent_overload()` - Find overloaded agents
  - `_detect_idle_agents()` - Find underutilized agents
  - `_detect_critical_path_blockers()` - Critical path analysis

**9.2 Integrate with AgentCoordinator**
- AgentCoordinator uses BottleneckDetector for monitoring
- Expose bottleneck detection through LeadAgent API
- Maintain existing bottleneck detection behavior

### Phase 10: Final Cleanup and Optimization

**10.1 Remove Dead Code**
- Remove any unused imports from LeadAgent
- Clean up commented-out code
- Verify no duplicate logic between coordinators

**10.2 Performance Validation**
- Benchmark discovery workflow performance (should be unchanged)
- Benchmark planning workflow performance
- Verify no performance regression from delegation overhead

**10.3 Code Review Checklist**
- Each coordinator is <500 lines
- Each coordinator has single responsibility
- All coordinators are independently testable
- No circular dependencies between coordinators
- LeadAgent is <500 lines (orchestrator only)
- All external APIs unchanged
- All tests pass
- Coverage >85%

## Architecture Diagram

```mermaid
sequenceDiagram
    participant UI as UI Router
    participant LA as LeadAgent<br/>(Orchestrator)
    participant DC as DiscoveryCoordinator
    participant PC as PlanningCoordinator
    participant AC as AgentCoordinator
    participant CM as ConversationManager
    participant DB as Database

    UI->>LA: start_discovery()
    LA->>DC: start_discovery()
    DC->>DB: load_discovery_state()
    DC->>DC: generate_first_question()
    DC-->>LA: first_question
    LA-->>UI: first_question

    UI->>LA: process_discovery_answer()
    LA->>DC: process_discovery_answer()
    DC->>DB: save_answer()
    DC->>DC: check_completion()
    DC-->>LA: next_question / completed
    LA-->>UI: response

    UI->>LA: generate_prd()
    LA->>PC: generate_prd()
    PC->>DC: get_structured_data()
    PC->>PC: build_prd_from_discovery()
    PC->>DB: save_prd()
    PC-->>LA: prd_content
    LA-->>UI: prd_content

    UI->>LA: generate_issues()
    LA->>PC: generate_issues()
    PC->>DB: get_prd()
    PC->>PC: decompose_into_issues()
    PC->>DB: save_issues()
    PC-->>LA: issues
    LA-->>UI: issues

    UI->>LA: execute_tasks_parallel()
    LA->>AC: execute_tasks_parallel()
    AC->>AC: resolve_dependencies()
    AC->>AC: assign_tasks_to_agents()
    AC->>DB: update_task_status()
    AC-->>LA: execution_result
    LA-->>UI: execution_result
```

## Module Responsibility Matrix

| Module | Lines | Responsibilities | Key Methods |
|--------|-------|------------------|-------------|
| **LeadAgent** | ~500 | High-level orchestration, state transitions, workflow coordination | `__init__()`, workflow phase transitions, session lifecycle |
| **DiscoveryCoordinator** | ~400 | Socratic Q&A workflow, question generation, category coverage tracking | `start_discovery()`, `process_discovery_answer()`, `get_discovery_status()`, `reset_discovery()` |
| **PlanningCoordinator** | ~350 | PRD generation, issue creation, task decomposition, codebase indexing | `generate_prd()`, `generate_issues()`, `decompose_prd()` |
| **AgentCoordinator** | ~400 | Worker agent management, task assignment, parallel execution, blocker handling | `execute_tasks_parallel()`, `assign_task_to_agent()`, `_handle_blocker()` |
| **ConversationManager** | ~150 | Chat history persistence, natural language conversation | `chat()`, `get_history()`, `clear_history()` |
| **BottleneckDetector** | ~300 | Workflow bottleneck detection, critical path analysis | `detect_workflow_bottlenecks()`, `_detect_dependency_waits()` |

## Dependency Flow

```mermaid
graph TD
    LA[LeadAgent<br/>Orchestrator]
    DC[DiscoveryCoordinator]
    PC[PlanningCoordinator]
    AC[AgentCoordinator]
    CM[ConversationManager]
    BD[BottleneckDetector]
    
    LA --> DC
    LA --> PC
    LA --> AC
    LA --> CM
    
    PC -.depends on.-> DC
    AC --> BD
    
    DC --> DB[(Database)]
    PC --> DB
    AC --> DB
    CM --> DB
    
    DC --> AP[AnthropicProvider]
    PC --> AP
    CM --> AP
    
    AC --> APM[AgentPoolManager]
    AC --> DR[DependencyResolver]
```

## Testing Strategy

| Test File | Focus | Coverage Target |
|-----------|-------|-----------------|
| `test_discovery_coordinator.py` | Discovery workflow, Socratic Q&A, category coverage | >90% |
| `test_planning_coordinator.py` | PRD generation, issue/task creation | >85% |
| `test_agent_coordinator.py` | Task execution, blocker handling, parallel coordination | >85% |
| `test_conversation_manager.py` | Chat history, conversation persistence | >90% |
| `test_bottleneck_detector.py` | Bottleneck detection, critical path analysis | >85% |
| `test_lead_agent.py` (updated) | Integration tests, workflow orchestration, backward compatibility | >85% |

## Migration Validation Checklist

- [ ] LeadAgent reduced to <500 lines
- [ ] DiscoveryCoordinator independently testable
- [ ] PlanningCoordinator independently testable
- [ ] AgentCoordinator independently testable
- [ ] ConversationManager independently testable
- [ ] No changes to external API (routers, services work unchanged)
- [ ] All existing tests pass without modification
- [ ] Coverage maintained at >85%
- [ ] No performance regression
- [ ] Documentation updated

---

Execution Information

Branch: main
Commit: a107395

---

💡 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.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#37 - feat: Multi-agent per project architecture (Phases 1-5) [merged]
#82 - Review FastAPI server file refactoring strategy [merged]
#128 - Implement bottleneck detection for workflow monitoring [merged]
#129 - Implement Project.start() with LeadAgent integration [merged]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!