supervisor.md

Supervisor Agent

Overview

The Supervisor Agent is the master orchestrator of ISC-CodeConnect's multi-agent system. It serves as the entry point for complex queries, analyzing them for decomposition requirements and managing multi-stage execution workflows. When a query requires multiple sequential operations, the Supervisor Agent breaks it down into executable stages and coordinates their execution across specialized agents.

Core Responsibilities

1. Query Decomposition Analysis

• Complex Query Assessment: Determines if queries require multi-stage processing
• Stage Definition: Breaks complex requests into sequential, executable stages
• Dependency Management: Identifies stage dependencies and execution order
• Flow Validation: Ensures each stage maps to available agent flows

2. Multi-Stage Orchestration

• Stage Execution Management: Coordinates sequential stage processing
• Progress Tracking: Monitors and reports stage completion status
• State Management: Maintains execution context across stages
• Error Recovery: Handles stage failures and provides graceful fallbacks

3. Frontend Communication

• Real-time Updates: Provides live progress updates during execution
• Task Tracking: Generates unique task IDs for frontend correlation
• Stage Notifications: Sends detailed stage start/completion events
• Error Reporting: Communicates errors with user-friendly messages

Architecture

Function Exports

__all__ = ["send_stage_progress_update", "decompose_query", "process_stage_completion"]

Core Data Models

ExecutionStage

class ExecutionStage(BaseModel):
    stage_id: int = Field(description="Unique identifier for this execution stage")
    stage_query: str = Field(description="The specific query to execute at this stage")
    stage_description: str = Field(description="A short description of what this stage accomplishes")
    requires_previous_stage_output: bool = Field(description="Whether this stage depends on the output of a previous stage")

QueryDecomposition

class QueryDecomposition(BaseModel):
    decomposition_required: bool = Field(description="Whether the query needs to be broken down into multiple stages")
    stages: List[ExecutionStage] = Field(default=[], description="List of execution stages if decomposition is required")

Main Functions

1. decompose_query(state: AgentState, config=RunnableConfig) -> Dict

Purpose: Analyzes queries and determines if they require multi-stage decomposition.

Process Flow:

1. Query Analysis: Uses structured LLM output to analyze query complexity
2. Decomposition Decision: Applies sophisticated rules to determine if breakdown is needed
3. Stage Creation: If decomposition required, creates detailed execution stages
4. State Initialization: Sets up supervisor state for multi-stage execution
5. Frontend Notification: Sends planning progress and stage structure to frontend

Key Decision Logic:

• 13 Available Flows: Maps queries to one of 13 specialized agent flows
• Explicit Request Rule: Only decomposes when users explicitly request multiple deliverables
• Anti-Pattern Protection: Prevents over-decomposition of informational queries
• Best Practice Filtering: Avoids adding implicit stages based on development best practices

Return Scenarios:

• Multi-stage Required: Returns router targeting with first stage query
• Single Stage: Returns router targeting for direct processing
• Error Handling: Returns error state with fallback to router

2. process_stage_completion(state: AgentState, config=RunnableConfig) -> Dict

Purpose: Processes stage completions and manages multi-stage workflow progression.

Process Flow:

1. Stage Result Storage: Captures and stores completed stage output
2. Progress Calculation: Updates completion percentages and metrics
3. Next Stage Preparation: Sets up subsequent stage execution if needed
4. Final Assembly: Combines all stage results when workflow completes
5. Frontend Updates: Sends completion events and progress notifications

State Transitions:

• Continue: Routes to next stage via router agent
• Complete: Finalizes workflow and assembles final response
• Error: Provides graceful error handling with partial results

3. send_stage_progress_update(state: AgentState, progress_message: str, config=RunnableConfig)

Purpose: Allows any agent to send progress updates during stage execution.

Usage: Called by specialized agents to provide real-time progress feedback:

await send_stage_progress_update(state, "Analyzing code patterns...", config)

Decomposition Decision Framework

Query Type Analysis

✅ Decomposition Required

Query: "Create an Apex class for account management and write tests for it"
Stages:
1. Apex Creation → "Create an Apex class for account management"
2. Apex Test Generation → "Write test class for the account management Apex class"

❌ No Decomposition - Informational Queries

Query: "How can I create feature switch?"
Reason: Informational query asking for guidance - use General Query Processing flow

❌ No Decomposition - Single Component

Query: "Create an Apex class for account management"
Reason: User only requested one component - don't add test generation implicitly

Flow Mapping System

The Supervisor Agent maps queries to exactly one of 13 available flows:

Apex Flows (6)

1. Apex Code Creation - New classes/triggers
2. Apex Code Modification - Existing code updates
3. Apex Code Explanation - Code analysis
4. Apex Test Generation - Test class creation
5. Apex Test Modification - Test updates
6. Apex Test Explanation - Test analysis

LWC Flows (6)

7. LWC Creation - New components
8. LWC Modification - Component updates
9. LWC Explanation - Component analysis
10. LWC Test Generation - Jest tests
11. LWC Test Modification - Test updates
12. LWC Test Explanation - Test analysis

General Flow (1)

13. General Query Processing - Informational queries, best practices, patterns

Critical Decision Rules

Absolutely Forbidden Stages

• ❌ Validation stages (built into all flows)
• ❌ Integration testing stages (automatic)
• ❌ Verification stages (included automatically)
• ❌ Quality assurance stages (built-in)
• ❌ Best practice stages user didn't request

Only Decompose When

1. User explicitly requests multiple different flow types
2. Query requires genuinely different technologies (Apex + LWC)
3. Sequential dependency exists between different flow types
4. Cannot be satisfied by any single flow

State Management

Supervisor State Variables

{
    "supervisor_active": bool,           # Whether supervisor is managing execution
    "supervisor_task_id": str,           # Unique task identifier
    "supervisor_stages": List[Dict],     # List of execution stages
    "current_stage_index": int,          # Currently executing stage
    "total_stages": int,                 # Total number of stages
    "stage_results": List[Dict],         # Results from completed stages
    "original_query": str,               # User's original query
    "stage_query": str                   # Current stage query
}

Stage Result Format

{
    "stage_id": int,                     # Stage identifier
    "stage_query": str,                  # Query for this stage
    "stage_response": List[Any]          # Agent response(s)
}

Frontend Communication Protocol

Event Types

1. Planning Phase

{
  "chunk": "Analyzing query complexity...",
  "details": {
    "description": "Breaking down complex query into executable stages",
    "response": "Planning execution strategy...",
    "taskId": "task_12345",
    "taskType": "planning",
    "taskStatus": "in_progress"
  }
}

2. Decomposition Complete

{
    "chunk": "Breaking down your request into 2 steps",
    "details": {
        "description": "Task decomposition complete",
        "response": "Here's my execution plan:\n\n**Step 1**: Generate Apex class\n**Step 2**: Generate test class",
        "taskId": "task_12345",
        "taskType": "decomposition",
        "taskStatus": "complete",
        "stages": [...]
    }
}

3. Stage Progress

{
  "chunk": "✅ Completed step 1/2",
  "details": {
    "description": "Stage 1 of 2 completed successfully",
    "response": "✅ **Step 1 Complete**: Generate Apex class\n\n[Generated code here]",
    "taskId": "task_12345",
    "stageId": 1,
    "taskType": "stage_execution",
    "stageStatus": "complete",
    "progressInfo": {
      "completedStages": 1,
      "totalStages": 2,
      "percentComplete": 50
    }
  }
}

4. Final Completion

{
  "chunk": "All 2 steps completed. Final response ready.",
  "details": {
    "description": "Multi-stage task execution complete.",
    "response": "[Combined results from all stages]",
    "taskId": "task_12345",
    "taskType": "final_result",
    "taskStatus": "complete",
    "totalStages": 2
  }
}

Sophisticated Decision Logic

The SUPERVISOR_PROMPT

The Supervisor Agent uses a comprehensive 500+ line prompt that includes:

1. 13 Available Flows Documentation: Complete descriptions of each flow's capabilities
2. Decomposition Rules: Detailed rules for when to decompose vs. single-flow processing
3. Anti-Pattern Examples: Extensive examples of incorrect decomposition patterns
4. Decision Flowchart: Step-by-step decision process
5. Response Examples: Correct and incorrect decomposition examples

Example Decision Process

Query: "Write test class for AccountService"

Decision Process:
1. Query Type Check: Technical query (not informational) ✓
2. Explicit Request Check: Single request (test class only) ✓
3. Flow Type Count: 1 flow (Apex Test Generation) ✓
4. Result: decomposition_required = false

Reasoning: Apex Test Generation flow can reference AccountService
without requiring the class to be created first.

Error Handling

Error Recovery Strategies

1. Decomposition Errors: Fall back to normal router processing
2. Stage Completion Errors: Provide partial results with graceful termination
3. State Corruption: Return error state with diagnostic information
4. Frontend Communication: Send error events with user-friendly messages

Error Response Format

{
    "current_agent": "end",
    "error_state": {
        "message": "Error description",
        "location": "function_name"
    },
    "partial_results": [...],  # Any completed stages
    "supervisor_active": False
}

Performance Characteristics

Metrics Tracked

• Decomposition Analysis Time: Query analysis duration
• Stage Execution Time: Individual stage processing time
• Total Workflow Time: End-to-end multi-stage completion
• Success Rate: Successful decomposition and completion rate
• Error Recovery Rate: Successful error handling percentage

Optimization Features

• Structured Output: Uses LLM structured output for reliable parsing
• State Caching: Maintains execution state across stages
• Progress Streaming: Real-time frontend updates
• Error Boundaries: Isolated error handling per stage

Integration Points

Upstream Dependencies

• Router Agent: Receives control from router for complex queries
• LLM Provider: Uses structured output for decomposition analysis

Downstream Dependencies

• Router Agent: Routes stages back to router for processing
• Specialized Agents: Coordinates execution across all agent types
• Frontend: Streams progress and completion events

Cross-Agent Communication

# Other agents can send progress updates
from src.agents.supervisor_agent import send_stage_progress_update

await send_stage_progress_update(
    state,
    "Analyzing retrieved code patterns...",
    config
)

Usage Examples

Multi-Technology Request

# Input Query
"Create an Apex REST API for account management and build an LWC component to consume it"

# Decomposition Result
{
    "decomposition_required": true,
    "stages": [
        {
            "stage_id": 1,
            "stage_query": "Create an Apex REST API service for account management with CRUD operations",
            "stage_description": "Generate Apex REST service",
            "requires_previous_stage_output": false
        },
        {
            "stage_id": 2,
            "stage_query": "Create an LWC component that consumes the account management REST API",
            "stage_description": "Generate LWC for API consumption",
            "requires_previous_stage_output": true
        }
    ]
}

Informational Query (No Decomposition)

# Input Query
"How can I create feature switch?"

# Decomposition Result
{
    "decomposition_required": false,
    "stages": []
}
# Routes to General Query Processing flow for comprehensive guidance

Best Practices

For Agent Developers

1. Use Progress Updates: Call send_stage_progress_update() for long operations
2. Handle Context: Access previous stage results via state["stage_results"]
3. Error Reporting: Provide detailed error information for debugging
4. State Validation: Check supervisor_active before supervisor operations

For Query Design

1. Be Explicit: Only request what you actually need
2. Avoid Assumptions: Don't assume additional components are needed
3. Sequential Thinking: Structure multi-step requests logically
4. Clear Dependencies: Make stage dependencies obvious

Future Enhancements

Planned Features

• Dynamic Stage Modification: Ability to add/remove stages mid-execution
• Parallel Stage Execution: Support for independent parallel stages
• Stage Checkpointing: Resume capability for interrupted workflows
• Advanced Analytics: Detailed performance and success metrics

Integration Opportunities

• CI/CD Integration: Multi-stage deployments with ISC-CodeConnect
• Code Review Workflows: Automated review and improvement stages
• Testing Pipelines: Comprehensive test generation and execution stages

---

The Supervisor Agent represents the sophisticated orchestration capabilities that make ISC-CodeConnect's multi-agent system both powerful and user-friendly, ensuring complex requests are handled intelligently while maintaining simplicity for straightforward queries.