BMAD-METHOD/docs/how-it-works/orchestrator-mechanics.md

Orchestrator Mechanics: The Brain of BMAD

The Orchestrator is the central intelligence system that coordinates all BMAD personas and tasks. Understanding how it works is crucial for maximizing the effectiveness of the BMAD Method.

Orchestrator Architecture

```mermaid title="Orchestrator System Architecture" type="diagram" graph TB subgraph "User Interface Layer" A["User Input"] B["Command Parser"] C["Response Formatter"] end

subgraph "Orchestrator Core"
    D["Request Analyzer"]
    E["Context Manager"]
    F["Persona Selector"]
    G["Task Coordinator"]
    H["Quality Controller"]
end

subgraph "Persona Layer"
    I["PM Persona"]
    J["Architect Persona"]
    K["UX/UI Persona"]
    L["Developer Persona"]
    M["Analyst Persona"]
end

subgraph "Knowledge Base"
    N["Project Context"]
    O["Templates"]
    P["Checklists"]
    Q["Best Practices"]
end

A --> B
B --> D
D --> E
E --> F
F --> G
G --> I
G --> J
G --> K
G --> L
G --> M

I --> H
J --> H
K --> H
L --> H
M --> H

H --> C

E <--> N
G <--> O
H <--> P
F <--> Q

```

Core Components

1. Request Analyzer

The Request Analyzer is the first component that processes user input:

Functions:

• Intent Recognition: Determines what the user wants to accomplish
• Context Extraction: Identifies relevant project context and constraints
• Complexity Assessment: Evaluates the scope and difficulty of the request
• Priority Classification: Determines urgency and importance levels

Decision Matrix:

Input Type	Analysis Focus	Output
Feature Request	Business value, technical complexity	PM + Architect personas
Bug Report	Impact assessment, root cause analysis	Developer + Analyst personas
Design Change	User impact, implementation effort	UX/UI + Developer personas
Architecture Question	System implications, scalability	Architect + Developer personas

2. Context Manager

Maintains and provides access to all project information:

Responsibilities:

• State Tracking: Current project status and progress
• History Management: Complete record of all decisions and changes
• Dependency Mapping: Relationships between components and features
• Knowledge Synthesis: Combining information from multiple sources

Context Structure:

```mermaid title="Context Information Flow" type="diagram" graph LR A["User Interactions"] --> B["Context Manager"] C["Persona Outputs"] --> B D["Task Results"] --> B E["External Data"] --> B

B --> F["Current State"]
B --> G["Historical Record"]
B --> H["Dependency Graph"]
B --> I["Knowledge Base"]

F --> J["Active Personas"]
G --> J
H --> J
I --> J

```

3. Persona Selector

Intelligently chooses the right persona(s) for each task:

Selection Criteria:

• Domain Expertise: Match task requirements to persona specialization
• Current Context: Consider what information is already available
• Workflow Stage: Align with current project phase
• Resource Availability: Optimize for efficiency and parallel execution

Selection Algorithm:

```mermaid title="Persona Selection Logic" type="diagram" graph TD A["Analyze Request"] --> B{["Primary Domain?"]}

B -->|Planning| C["PM Persona"]
B -->|Technical| D["Architect Persona"]
B -->|Design| E["UX/UI Persona"]
B -->|Implementation| F["Developer Persona"]
B -->|Analysis| G["Analyst Persona"]

C --> H{["Need Support?"]}
D --> H
E --> H
F --> H
G --> H

H -->|Yes| I["Select Secondary Personas"]
H -->|No| J["Execute with Primary"]

I --> K["Coordinate Multi-Persona Task"]
J --> L["Execute Single-Persona Task"]

K --> M["Synthesize Results"]
L --> M

```

4. Task Coordinator

Manages the execution of tasks across personas:

Coordination Functions:

• Task Decomposition: Breaking complex requests into manageable tasks
• Dependency Resolution: Ensuring tasks execute in the correct order
• Parallel Execution: Running independent tasks simultaneously
• Progress Monitoring: Tracking completion status and quality metrics

Task Execution Flow:

```mermaid title="Task Coordination Process" type="diagram" graph TD A["Receive Task Request"] --> B["Decompose into Subtasks"] B --> C["Identify Dependencies"] C --> D["Create Execution Plan"] D --> E["Assign to Personas"]

E --> F{["Parallel Execution?"]}
F -->|Yes| G["Execute Simultaneously"]
F -->|No| H["Execute Sequentially"]

G --> I["Monitor Progress"]
H --> I

I --> J{["All Complete?"]}
J -->|No| K["Continue Execution"]
J -->|Yes| L["Synthesize Results"]

K --> I
L --> M["Quality Check"]
M --> N["Deliver Results"]

```

5. Quality Controller

Ensures all outputs meet BMAD standards:

Quality Assurance Process:

• Template Compliance: Verify outputs follow required formats
• Completeness Check: Ensure all required sections are present
• Consistency Validation: Check alignment with project context
• Best Practice Review: Validate against established standards

Command Processing

Web Environment Commands

Command	Function	Example
/persona [name]	Activate specific persona	/persona pm
/task [name]	Execute specific task	/task create-prd
/context	Show current project context	/context
/help	Display available options	/help

IDE Environment Commands

Command	Function	Example
*persona [name]	Activate specific persona	*persona architect
*task [name]	Execute specific task	*task create-architecture
*context	Show current project context	*context
*help	Display available options	*help

Advanced Orchestration Features

1. Adaptive Learning

The Orchestrator learns from each interaction:

• Pattern Recognition: Identifies common request types and optimal responses
• Performance Optimization: Improves task execution based on historical data
• Context Refinement: Enhances context management through usage patterns
• Quality Improvement: Adjusts quality standards based on feedback

2. Multi-Modal Integration

Supports various input and output formats:

Input Modes:

• Text commands and descriptions
• File uploads and attachments
• Screenshots and images
• Voice commands (in supported environments)

Output Modes:

• Structured documents (Markdown, PDF)
• Code files and implementations
• Diagrams and visualizations
• Interactive prototypes

3. Environment Adaptation

Automatically adapts to different environments:

Web Environment Features:

• File attachment processing
• Rich text formatting
• Interactive elements
• Collaborative features

IDE Environment Features:

• File system integration
• Code completion and suggestions
• Terminal command execution
• Version control integration

Troubleshooting Common Issues

Issue: Persona Not Responding Correctly

Diagnosis Steps:

1. Check command syntax (/persona vs *persona)
2. Verify persona name spelling
3. Confirm current context is appropriate
4. Review recent interaction history

Solutions:

• Reset context with /context reset
• Explicitly specify requirements
• Use /help to see available options
• Try alternative persona for the task

Issue: Task Execution Incomplete

Diagnosis Steps:

1. Review task requirements and scope
2. Check for missing dependencies
3. Verify persona has necessary context
4. Examine quality control feedback

Solutions:

• Break complex tasks into smaller parts
• Provide additional context or requirements
• Use /task status to check progress
• Manually trigger quality review

Issue: Context Loss or Confusion

Diagnosis Steps:

1. Review recent context changes
2. Check for conflicting information
3. Verify persona state consistency
4. Examine interaction history

Solutions:

• Use /context refresh to rebuild state
• Explicitly restate current objectives
• Clear conflicting information
• Start fresh with /context reset

Performance Optimization

Best Practices for Orchestrator Efficiency

1. Clear Communication: Provide specific, detailed requests
2. Context Management: Keep project context current and relevant
3. Task Sizing: Break large requests into manageable tasks
4. Persona Selection: Choose the most appropriate persona for each task
5. Quality Focus: Review outputs and provide feedback for improvement

Monitoring and Metrics

Track these key performance indicators:

• Response Time: How quickly the orchestrator processes requests
• Task Completion Rate: Percentage of tasks completed successfully
• Quality Score: Average quality rating of deliverables
• Context Accuracy: How well the orchestrator maintains project state
• User Satisfaction: Feedback on orchestrator performance

Next Steps

• See It In Action: Workflow Examples
• Understand the Team: Persona System
• Try It Yourself: Getting Started Guide

---

The Orchestrator is the heart of the BMAD Method. Master its mechanics, and you'll unlock unprecedented development efficiency and quality.