Initial public release: Multi-Agent MCP Delegation Server

A Model Context Protocol (MCP) server that enables intelligent task
delegation across multiple AI coding agents (Claude, Gemini, Aider).

Features:
- Capability-based routing with automatic fallback
- 10+ specialized task types (security, refactoring, code review, etc.)
- Flexible configuration via YAML and Python install.py wizard
- Hugging Face Space demo with interactive query tester
- Comprehensive test suite and example workflows
- Docker support for easy deployment

Token efficiency: <1% context overhead (1,739 tokens)

License: MIT

.dockerignore

@@ -0,0 +1,65 @@
+# Git and version control
+.git
+.gitignore
+.gitattributes
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv
+venv/
+env/
+ENV/
+.pytest_cache
+*.egg-info
+dist/
+build/
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+logs/
+
+# Data and cache
+data/
+*.db
+*.sqlite
+
+# Agent-specific
+.gemini
+.claude
+.aider*
+
+# Lock files (we'll use requirements.txt in container)
+uv.lock
+poetry.lock
+Pipfile.lock
+
+# Documentation
+*.md
+!README.md
+
+# Test files
+tests/
+.coverage
+htmlcov/
+.tox/
+
+# OS
+Thumbs.db
+.DS_Store

.env.example

@@ -0,0 +1,22 @@
+# Delegation MCP Environment Variables
+
+# API Keys (if using cloud-hosted CLIs)
+# ANTHROPIC_API_KEY=your_key_here
+# GOOGLE_API_KEY=your_key_here
+# OPENAI_API_KEY=your_key_here
+
+# MCP Server Configuration
+MCP_SERVER_PORT=3000
+MCP_SERVER_HOST=localhost
+
+# Gradio UI Configuration
+GRADIO_SERVER_PORT=7860
+GRADIO_SERVER_NAME=0.0.0.0
+
+# Logging
+LOG_LEVEL=INFO
+LOG_FILE=delegation_mcp.log
+
+# Delegation Settings
+AUTO_APPROVE=false
+LOG_DELEGATIONS=true

.github/workflows/python-app.yml

@@ -0,0 +1,39 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python application
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8 pytest
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest

.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment
+.env
+.env.local
+*.log
+
+# MCP
+mcp_data/
+*.db
+*.sqlite
+*.backup
+
+# Gradio
+gradio_cached_examples/
+flagged/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.aider*
+.gemini_security/
+bandit_report.json

Dockerfile

@@ -0,0 +1,35 @@
+FROM python:3.10
+
+# Install Node.js and npm (for Claude/Gemini CLIs)
+RUN apt-get update && apt-get install -y \
+    nodejs \
+    npm \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy project files
+COPY . .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir .
+
+# Install Agent CLIs
+# Aider is installed via pip (already in requirements or setup.py, but ensuring here)
+RUN pip install --no-cache-dir aider-chat
+
+# Gemini and Claude CLIs via npm
+RUN npm install -g @google/gemini-cli @anthropic-ai/claude-code
+
+# Create data directory for persistence
+RUN mkdir -p data
+RUN chmod 777 data
+
+# Expose port 7860 for Hugging Face Spaces
+EXPOSE 7860
+
+# Run the application
+CMD ["python", "app.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Delegation MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,335 @@
+---
+title: Delegation MCP
+emoji: 🚀
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+short_description: Intelligent Multi-Agent Routing & Guidance
+tags:
+  - mcp-server
+  - building-mcp-track-enterprise
+  - multi-agent
+  - agent-orchestration
+---
+
+# 🚀 Delegation MCP Server
+
+**Intelligent Multi-Agent Routing & Guidance**
+
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)]() [![License](https://img.shields.io/badge/license-MIT-blue)]() [![MCP](https://img.shields.io/badge/MCP-1.0-purple)]() [![Version](https://img.shields.io/badge/version-0.4.0-orange)]() [![Anthropic](https://img.shields.io/badge/Anthropic-Compliant-green)]()
+
+> *Built for the MCP 1st Birthday Hackathon - Winter 2025*
+
+## ⚡ Quick Start
+
+```bash
+# One command to install and configure everything
+python install.py
+```
+
+**That's it!** Restart Claude Code and start delegating:
+
+```
+"scan this codebase for security vulnerabilities"
+→ MCP suggests: "Delegate to Gemini"
+→ Claude executes: gemini scan .
+
+"design an authentication architecture"
+→ MCP suggests: "Handle directly (Claude is best)"
+→ Claude executes: (Internal reasoning)
+
+"refactor the delegation engine"
+→ MCP suggests: "Delegate to Aider"
+→ Claude executes: aider --message "refactor delegation engine"
+```
+
+**Features**:
+- ✅ **One-command installation** - 30 seconds to full setup
+- ✅ **Intelligent Routing** - Rules + Capabilities analysis
+- ✅ **Privacy-First** - Your code never passes through this server
+- ✅ **Lightweight** - Minimal footprint, no heavy databases
+- ✅ **Cross-platform** - Windows, Mac, Linux
+
+---
+
+## 🎮 Try the Interactive Demo
+
+**[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Cduplar/multi-agent-mcp)**
+
+Experience the routing intelligence in action! Our HF Space demo lets you:
+
+### Interactive Features:
+- 🧪 **Test Any Query** - See routing decisions in real-time
+- 📊 **Routing Transparency** - View the complete decision-making process:
+  - Task classification (security, architecture, refactoring, etc.)
+  - Complexity assessment (simple/medium/complex)
+  - Detected keywords and routing reasoning
+  - CLI command that would be executed
+- ⚙️ **Live Configuration** - Toggle agents and routing strategies to see how settings affect decisions
+- 💡 **Example Queries** - Simple and complex multi-step scenarios
+
+### Try This:
+1. Visit the [HF Space](https://huggingface.co/spaces/Cduplar/multi-agent-mcp)
+2. Enter: *"Audit the authentication system for SQL injection, XSS, and CSRF vulnerabilities"*
+3. Watch it route to Gemini with full reasoning
+4. Disable Gemini in settings → See it route to Claude instead!
+
+**Want to test with real agents?** Duplicate the Space and add your API keys!
+
+---
+
+## 🌟 What Is This?
+
+A **lightweight MCP server** that acts as a routing intelligence layer for AI coding agents. Instead of executing tasks itself (which creates a bottleneck and security risk), it analyzes your request and **guides** your main agent (like Claude Code) on which tool to use.
+
+**Key Insight**: This follows the **Routing Guidance** pattern:
+1. **Analyze**: The server analyzes the prompt (e.g., "audit security").
+2. **Route**: It determines the best agent based on your **presets** and **rules**.
+3. **Guide**: It returns the *exact command* to run.
+4. **Execute**: The client (Claude) executes the command directly.
+
+This ensures **zero lock-in**, **maximum privacy**, and **native performance**.
+
+---
+
+## 🎯 The Core Value Proposition
+
+### Problem
+Developers manually switch between AI agents, losing context and productivity:
+- Claude for architecture
+- Gemini for security analysis
+- Aider for git operations
+- Copilot for GitHub integration
+
+### Solution
+**One MCP server that tells your agent who to call:**
+
+```
+You → Claude Code → Delegation MCP → "Use Gemini for this" → Claude calls Gemini
+```
+
+**You work with ONE agent, but get the power of ALL agents.**
+
+---
+
+## 📦 Installation
+
+### Prerequisites
+- Python 3.10+
+- At least one AI agent CLI installed:
+  - [Gemini CLI](https://github.com/google/generative-ai-cli): `npm install -g @google/gemini-cli`
+  - [Aider](https://aider.chat): `pip install aider-chat`
+  - [Claude Code](https://claude.ai/download): `npm install -g @anthropic-ai/claude-code`
+  - [GitHub Copilot](https://github.com/features/copilot): `npm install -g github/copilot`
+
+### Automated Installation (Recommended)
+
+```bash
+# Clone repository
+git clone https://github.com/carlosduplar/multi-agent-mcp.git
+cd multi-agent-mcp
+
+# One-command install
+python install.py
+
+# Or on Unix/Mac
+bash install.sh
+```
+
+The installer will:
+1. Check system requirements
+2. Discover installed agents
+3. Configure Claude Code automatically
+4. Verify everything works
+
+**Restart Claude Code and you're ready!**
+
+---
+
+## 🎯 How It Works
+
+### Intelligent Routing Guidance
+
+We use a hybrid approach to determine the best agent for the job:
+
+1. **Rule-Based Presets**: Your configured rules take priority (e.g., "Always use Gemini for security").
+2. **Capability Analysis**: If no rule matches, we analyze agent capabilities to find the best fit.
+
+**Query**: "scan for vulnerabilities"
+
+1. **Check Rules**: Matches `security_audit` preset? -> **Gemini**
+2. **Guide**: Return guidance to use Gemini
+
+### Example Interaction
+
+**User**: "Audit my authentication code for SQL injection"
+
+**Claude Code** calls `get_routing_guidance`:
+```json
+{
+  "query": "Audit auth.py for SQL injection"
+}
+```
+
+**MCP Server** responds:
+```json
+{
+  "decision": "DELEGATE_TO: gemini",
+  "agent": "gemini",
+  "task_type": "security_audit",
+  "cli_command": "gemini \"Audit auth.py for SQL injection\""
+}
+```
+
+**Claude Code** then executes:
+```bash
+gemini "Audit auth.py for SQL injection"
+```
+
+---
+
+## 🔧 MCP Tools
+
+### `get_routing_guidance`
+Get routing guidance for a task. Returns which agent should handle it and the exact CLI command to run.
+
+```python
+{
+  "query": "Audit auth.py for SQL injection"
+}
+```
+
+### `discover_agents`
+Automatically discover available CLI agents on the system and register them.
+
+```python
+{
+  "force_refresh": false  # Optional: force re-discovery
+}
+```
+
+### `list_agents`
+List all registered agents and their availability status.
+
+### ⚡ Token Overhead
+
+One of the key advantages of this MCP server is its **minimal context footprint**. Here's the actual token usage:
+
+```
+MCP Tools:
+├─ get_routing_guidance: 601 tokens
+├─ discover_agents:      584 tokens
+└─ list_agents:          554 tokens
+                         ─────────
+Total MCP overhead:      1,739 tokens (0.9% of 200k context)
+```
+
+**What this means**:
+- ✅ Less than 1% of your context budget
+- ✅ Leaves 99%+ for actual code and conversation
+- ✅ No heavy prompts or bloated instructions
+- ✅ Intelligent routing without sacrificing context
+
+Compare this to running multiple agent instances or complex orchestration frameworks that can consume 10-20% of your context just for coordination overhead.
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  Claude Code (or other MCP client)      │
+│  - User chats here                      │
+│  - Calls get_routing_guidance           │
+│  - EXECUTES the returned command        │
+└──────────────┬──────────────────────────┘
+               │ MCP Protocol (stdio)
+               ▼
+┌──────────────────────────────────────────┐
+│  Delegation MCP Server                   │
+│  - Analyzes task complexity & type       │
+│  - Checks rules & capabilities           │
+│  - Returns guidance (NO EXECUTION)       │
+└──────────────────────────────────────────┘
+```
+
+### v0.4.0 - Lightweight Architecture
+
+**Privacy & Security**:
+- **No Code Execution**: The server never executes code or commands. It only suggests them.
+- **No Data Persistence**: No databases or logs of your code are kept by the server.
+- **Direct Connection**: Your agent talks directly to the delegated tool (e.g., Claude -> Gemini).
+
+**Agent Auto-Discovery**:
+- Automatically detects installed CLI agents (Claude, Gemini, Aider, etc.)
+- Verifies agent availability
+- Graceful error handling
+
+---
+
+## 🗂️ Project Structure
+
+```
+multi-agent-mcp/
+├── src/delegation_mcp/
+│   ├── server.py              # MCP server (Routing Guidance) ⭐
+│   ├── delegation.py          # Routing logic & scoring
+│   ├── orchestrator.py        # Agent registry
+│   ├── agent_discovery.py     # System scanner for agents
+│   ├── tool_discovery.py      # Tool definitions
+│   ├── config.py              # Configuration handling
+│   ├── cli.py                 # CLI tools
+│   └── adapters/              # Agent definitions
+│       ├── claude.py
+│       ├── gemini.py
+│       ├── copilot.py
+│       └── aider.py
+├── tools/                     # Tool definitions (JSON)
+├── tests/                     # Comprehensive tests
+└── config/                    # Default delegation rules
+```
+
+---
+
+## 🚀 Roadmap
+
+### ✅ Phase 1: Foundation (COMPLETE)
+- MCP server with routing guidance
+- Capability-based routing
+- Agent auto-discovery
+- Production-grade architecture
+
+### 🔜 Phase 2: Intelligence (Q1 2026)
+- ML-powered routing
+- Learning from user feedback
+- Custom agent definitions
+
+### 🔮 Phase 3: Collaboration (Q2 2026)
+- Complex multi-step workflows
+- Parallel agent execution guidance
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Add new agent adapters, improve routing logic, or enhance documentation.
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE)
+
+---
+
+## 🎯 The Vision
+
+> **"You work with ONE agent, but get the power of ALL agents."**
+
+Today's AI landscape has amazing specialists, but they work in silos. **Delegation MCP changes that.** It's the intelligence layer that lets agents collaborate, creating something greater than the sum of its parts.
+
+---
+
+**Built with ❤️ for the MCP ecosystem**

app.py

@@ -0,0 +1,94 @@
+import asyncio
+import logging
+import os
+from contextlib import asynccontextmanager
+
+import uvicorn
+from fastapi import FastAPI, Request
+from sse_starlette.sse import EventSourceResponse
+from mcp.server.sse import SseServerTransport
+
+import gradio as gr
+from delegation_mcp.server import DelegationMCPServer
+from delegation_mcp.gradio_monitor import create_monitor_ui
+from mcp.server.models import InitializationOptions
+
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Global server instance
+mcp_server = None
+transport = None
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Manage server lifecycle."""
+    global mcp_server
+
+    # Initialize MCP server
+    logger.info("Initializing Delegation MCP Server...")
+    mcp_server = DelegationMCPServer(enable_auto_discovery=True)
+
+    # Initialize agent discovery
+    if mcp_server.enable_auto_discovery:
+        await mcp_server._discover_and_register_agents()
+
+    logger.info("MCP Server ready!")
+
+    yield
+
+    # Cleanup
+    logger.info("Shutting down Delegation MCP Server...")
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/sse")
+async def handle_sse(request: Request):
+    """Handle SSE connections for MCP."""
+    global mcp_server, transport
+    
+    transport = SseServerTransport("/messages")
+    
+    async def event_generator():
+        async with mcp_server.server.run(
+            transport.read_stream, 
+            transport.write_stream, 
+            InitializationOptions(
+                server_name="delegation-mcp",
+                server_version="0.3.0",
+                capabilities=mcp_server.server.get_capabilities(
+                    notification_options=None,
+                    experimental_capabilities={
+                        "tool_discovery": {},
+                        "on_demand_loading": {},
+                        "agent_discovery": {},
+                    },
+                ),
+            )
+        ) as stream:
+            async for message in stream:
+                yield message
+                
+    return EventSourceResponse(event_generator())
+
+@app.post("/messages")
+async def handle_messages(request: Request):
+    """Handle incoming messages for MCP."""
+    global transport
+    if transport:
+        return await transport.handle_post_message(request)
+    return {"error": "No active transport"}
+
+# Initialize a temporary server for the Gradio UI demo
+# This is separate from the MCP server instance above
+temp_server_for_ui = DelegationMCPServer(enable_auto_discovery=False)
+
+# Mount Gradio app
+logger.info("Mounting Gradio monitor...")
+monitor_app = create_monitor_ui(demo_server=temp_server_for_ui)
+app = gr.mount_gradio_app(app, monitor_app, path="/")
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860)

config/delegation_rules.yaml

@@ -0,0 +1,141 @@
+# Delegation MCP Configuration
+# Auto-generated based on user selections
+
+orchestrator: claude
+routing_strategy: hybrid
+orchestrators:
+  claude:
+    name: claude
+    command: claude
+    args: ["-p"]
+    enabled: true
+    env: {}
+    timeout: 300
+    max_retries: 3
+    cost_per_1k_tokens: 0.001
+    capabilities:
+      security_audit: 0.8
+      vulnerability_scan: 0.75
+      code_review: 0.9
+      architecture: 0.95
+      refactoring: 0.75
+      quick_fix: 0.7
+      documentation: 0.9
+      testing: 0.8
+      performance: 0.75
+      browser_interaction: 0.6
+      git_operations: 0.65
+      shell_tasks: 0.65
+      general: 0.85
+  gemini:
+    name: gemini
+    command: gemini
+    args: []
+    enabled: true
+    env: {}
+    timeout: 300
+    max_retries: 3
+    cost_per_1k_tokens: 0.001
+    capabilities:
+      security_audit: 0.85
+      vulnerability_scan: 0.8
+      code_review: 0.85
+      architecture: 0.8
+      refactoring: 0.75
+      quick_fix: 0.75
+      documentation: 0.8
+      testing: 0.8
+      performance: 0.85
+      browser_interaction: 0.7
+      git_operations: 0.7
+      shell_tasks: 0.7
+      general: 0.85
+  aider:
+    name: aider
+    command: aider
+    args: ["--yes", "--no-auto-commits"]
+    enabled: true
+    env: {}
+    timeout: 300
+    max_retries: 3
+    cost_per_1k_tokens: 0.001
+    capabilities:
+      security_audit: 0.6
+      vulnerability_scan: 0.6
+      code_review: 0.75
+      architecture: 0.65
+      refactoring: 0.95
+      quick_fix: 0.9
+      documentation: 0.7
+      testing: 0.75
+      performance: 0.7
+      browser_interaction: 0.4
+      git_operations: 0.95
+      shell_tasks: 0.8
+      general: 0.7
+rules:
+- delegate_to: gemini
+  description: Security audits, vulnerability scans, safety checks
+  pattern: security|vulnerability|audit|CVE
+  priority: 10
+  requires_approval: false
+- delegate_to: gemini
+  description: Code quality review, best practices analysis
+  pattern: review|code quality|best practices
+  priority: 9
+  requires_approval: false
+- delegate_to: claude
+  description: System design, architecture planning, complex reasoning
+  pattern: architecture|design|system design
+  priority: 8
+  requires_approval: false
+- delegate_to: aider
+  description: Code refactoring, cleanup, optimization
+  pattern: refactor|cleanup|optimize code
+  priority: 7
+  requires_approval: false
+- delegate_to: aider
+  description: Rapid bug fixes, small code changes
+  pattern: fix|bug|quick change
+  priority: 6
+  requires_approval: false
+- delegate_to: claude
+  description: README files, API docs, code comments
+  pattern: documentation|docs|README|comments
+  priority: 5
+  requires_approval: false
+- delegate_to: gemini
+  description: Unit tests, integration tests, test coverage
+  pattern: test|testing|coverage
+  priority: 4
+  requires_approval: false
+- delegate_to: gemini
+  description: Performance analysis and optimization
+  pattern: performance|optimize|speed
+  priority: 3
+  requires_approval: false
+- delegate_to: gemini
+  description: Browser automation, web scraping, UI testing
+  pattern: browser|selenium|playwright|chrome
+  priority: 2
+  requires_approval: false
+- delegate_to: aider
+  description: Git workflows, repository management
+  pattern: git|commit|merge|branch
+  priority: 1
+  requires_approval: false
+- delegate_to: aider
+  description: Shell scripting, terminal commands
+  pattern: shell|terminal|bash|script
+  priority: 1
+  requires_approval: false
+- delegate_to: claude
+  description: Default for tasks that don't fit specific categories
+  pattern: general|misc|other
+  priority: 1
+  requires_approval: false
+- delegate_to: claude
+  description: General queries and fallback
+  pattern: .*
+  priority: 1
+  requires_approval: false

config/orchestrators.yaml

@@ -0,0 +1,25 @@
+orchestrators:
+  claude:
+    name: claude
+    command: claude
+    args: []
+    enabled: true
+    env: {}
+    timeout: 300
+    max_retries: 3
+  gemini:
+    name: gemini
+    command: gemini
+    args: []
+    enabled: true
+    env: {}
+    timeout: 300
+    max_retries: 3
+  aider:
+    name: aider
+    command: aider
+    args: []
+    enabled: true
+    env: {}
+    timeout: 300
+    max_retries: 3

examples/claude_code_usage.py

@@ -0,0 +1,180 @@
+"""
+Example: How Claude Code should use the Delegation MCP Server
+
+This demonstrates the CORRECT MCP code execution pattern:
+✅ Claude Code writes code that imports and uses the MCP server
+❌ NOT a chat UI that directly calls MCP tools
+
+When you ask Claude Code to delegate a task, it should write code similar to this.
+"""
+
+import asyncio
+from pathlib import Path
+from delegation_mcp.server import DelegationMCPServer
+from delegation_mcp.config import DelegationConfig
+
+
+async def example_delegation():
+    """Example: Claude Code delegating a security audit to Gemini."""
+
+    print("🚀 Initializing Delegation MCP Server...")
+
+    # Initialize the server (Claude Code does this)
+    server = DelegationMCPServer(
+        config_path=Path("config/delegation_rules.yaml"),
+        enable_security=True,
+        enable_persistence=True,
+    )
+
+    print("✅ Server initialized\n")
+
+    # Example 1: Delegate security audit to Gemini
+    print("📝 Example 1: Security Audit")
+    print("Query: 'Audit auth.py for SQL injection vulnerabilities'")
+    print("Expected: Routes to Gemini (best for security analysis)\n")
+
+    # This is what Claude Code would do when you ask it to delegate:
+    result = await server.engine.process(
+        "Audit the authentication code for SQL injection vulnerabilities"
+    )
+
+    print(f"Orchestrator: {result.orchestrator}")
+    print(f"Delegated to: {result.delegated_to}")
+    print(f"Success: {result.success}")
+    print(f"Duration: {result.duration:.2f}s")
+    print(f"Output preview: {result.output[:200]}...\n")
+
+    print("-" * 60 + "\n")
+
+    # Example 2: Delegate refactoring to Claude
+    print("📝 Example 2: Code Refactoring")
+    print("Query: 'Refactor database connection to use connection pooling'")
+    print("Expected: Routes to Claude (best for architecture)\n")
+
+    result = await server.engine.process(
+        "Refactor the database connection code to use connection pooling"
+    )
+
+    print(f"Orchestrator: {result.orchestrator}")
+    print(f"Delegated to: {result.delegated_to}")
+    print(f"Success: {result.success}")
+    print(f"Duration: {result.duration:.2f}s")
+    print(f"Output preview: {result.output[:200]}...\n")
+
+    print("-" * 60 + "\n")
+
+    # Example 3: Check agent statistics
+    print("📊 Example 3: Get Delegation Statistics")
+
+    if server.persistence:
+        stats = server.persistence.get_statistics()
+        print(f"Total tasks: {stats.get('total_tasks', 0)}")
+        print(f"Success rate: {stats.get('success_rate', 0):.1%}")
+        print(f"Average duration: {stats.get('avg_duration', 0):.2f}s")
+        print(f"Agent usage: {stats.get('agent_usage', {})}\n")
+
+    print("✅ Examples complete!")
+    print("\n" + "=" * 60)
+    print("💡 Key Insight:")
+    print("=" * 60)
+    print("""
+This is the CORRECT MCP pattern:
+- Claude Code writes and runs this Python code
+- The code imports and uses the delegation MCP server
+- Tasks are routed to specialized agents automatically
+- Results come back through the code
+
+This is WRONG:
+- A Gradio chat UI that directly calls MCP tools
+- That violates the code execution pattern
+- The UI should only monitor activity, not execute it
+""")
+
+
+async def example_mcp_protocol_usage():
+    """
+    Example: How an MCP client (like Claude Code) uses the server via MCP protocol.
+
+    Note: This is pseudocode showing what happens under the hood when Claude Code
+    uses the MCP server through the stdio protocol.
+    """
+    print("\n" + "=" * 60)
+    print("📡 MCP Protocol Usage (Pseudocode)")
+    print("=" * 60 + "\n")
+
+    print("""
+When Claude Code is configured to use this MCP server:
+
+1. Configuration (~/.config/claude/mcp.json):
+   {
+     "mcpServers": {
+       "delegation": {
+         "command": "delegation-mcp"
+       }
+     }
+   }
+
+2. User asks Claude Code: "Audit my code for security issues"
+
+3. Claude Code recognizes it should use the delegation server
+
+4. Claude Code calls the MCP tool via stdio:
+   {
+     "jsonrpc": "2.0",
+     "method": "tools/call",
+     "params": {
+       "name": "delegate_task",
+       "arguments": {
+         "query": "Audit auth.py for SQL injection",
+         "orchestrator": "claude"
+       }
+     }
+   }
+
+5. Delegation MCP server receives the call, routes to Gemini
+
+6. Response comes back:
+   {
+     "orchestrator": "claude",
+     "delegated_to": "gemini",
+     "success": true,
+     "output": "Found 3 SQL injection vulnerabilities...",
+     "duration": 2.5
+   }
+
+7. Claude Code presents the result to the user
+
+✅ User works with Claude Code, but gets Gemini's security expertise!
+""")
+
+
+if __name__ == "__main__":
+    print("""
+╔═══════════════════════════════════════════════════════════════╗
+║  Delegation MCP Server - Correct Usage Pattern Examples      ║
+║                                                               ║
+║  This demonstrates how Claude Code (or other MCP clients)    ║
+║  should use the delegation server following Anthropic's      ║
+║  code execution pattern.                                      ║
+╚═══════════════════════════════════════════════════════════════╝
+""")
+
+    # Run async examples
+    asyncio.run(example_delegation())
+
+    # Show MCP protocol usage
+    asyncio.run(example_mcp_protocol_usage())
+
+    print("\n" + "=" * 60)
+    print("🎯 Ready for Production!")
+    print("=" * 60)
+    print("""
+To use in production:
+
+1. Install: pip install -e .
+2. Configure Claude Code to use delegation-mcp
+3. Chat with Claude Code naturally
+4. Watch tasks get routed to the best agent!
+
+Optional: Run `delegation-monitor` to visualize activity for demos.
+""")

examples/example_workflow.py

@@ -0,0 +1,72 @@
+"""Example workflow using delegation MCP."""
+
+import asyncio
+from pathlib import Path
+
+from delegation_mcp import DelegationConfig, OrchestratorRegistry, DelegationEngine
+
+
+async def main():
+    """Run example delegation workflow."""
+
+    # Load configuration
+    config_path = Path("config/delegation_rules.yaml")
+    config = DelegationConfig.from_yaml(config_path)
+
+    # Setup registry and engine
+    registry = OrchestratorRegistry()
+    engine = DelegationEngine(config, registry)
+
+    # Register orchestrators
+    for name, orch_config in config.orchestrators.items():
+        registry.register(orch_config)
+
+    print("=== Delegation MCP Example Workflow ===\n")
+
+    # Example 1: Security audit (should delegate to Gemini)
+    print("Example 1: Security Audit")
+    result1 = await engine.process("Run a security audit on authentication module")
+    print(f"  Primary: {result1.orchestrator}")
+    print(f"  Delegated to: {result1.delegated_to}")
+    print(f"  Rule matched: {result1.rule.pattern if result1.rule else 'None'}")
+    print(f"  Success: {result1.success}\n")
+
+    # Example 2: Refactoring (should delegate to Aider)
+    print("Example 2: Refactoring")
+    result2 = await engine.process("Refactor the database connection code")
+    print(f"  Primary: {result2.orchestrator}")
+    print(f"  Delegated to: {result2.delegated_to}")
+    print(f"  Rule matched: {result2.rule.pattern if result2.rule else 'None'}")
+    print(f"  Success: {result2.success}\n")
+
+    # Example 3: Pull request (should delegate to Copilot if enabled)
+    print("Example 3: Pull Request")
+    result3 = await engine.process("Create a pull request for the new feature")
+    print(f"  Primary: {result3.orchestrator}")
+    print(f"  Delegated to: {result3.delegated_to}")
+    print(f"  Rule matched: {result3.rule.pattern if result3.rule else 'None'}")
+    print(f"  Success: {result3.success}\n")
+
+    # Example 4: No rule match (uses primary orchestrator)
+    print("Example 4: No Rule Match")
+    result4 = await engine.process("Explain how async/await works in Python")
+    print(f"  Primary: {result4.orchestrator}")
+    print(f"  Delegated to: {result4.delegated_to}")
+    print(f"  Rule matched: {result4.rule.pattern if result4.rule else 'None'}")
+    print(f"  Success: {result4.success}\n")
+
+    # Show statistics
+    print("=== Statistics ===")
+    stats = engine.get_statistics()
+    print(f"Total queries: {stats['total']}")
+    print(f"Delegations: {stats['delegations']}")
+    print(f"Delegation rate: {stats['delegation_rate']:.1f}%")
+    print(f"Success rate: {stats['success_rate']:.1f}%")
+    print(f"Avg duration: {stats['avg_duration']:.2f}s")
+    print(f"\nBy orchestrator:")
+    for orch, count in stats['by_orchestrator'].items():
+        print(f"  {orch}: {count}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

install.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""Delegation MCP Installer - One-command setup."""
+
+if __name__ == "__main__":
+    from src.delegation_mcp.installer import DelegationInstaller
+    import sys
+
+    installer = DelegationInstaller()
+    success = installer.install()
+    sys.exit(0 if success else 1)

install.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Delegation MCP Installer - One-line installation script
+# Usage: curl -fsSL https://raw.githubusercontent.com/USER/REPO/main/install.sh | bash
+
+set -e
+
+echo "=========================================="
+echo "Delegation MCP Installer"
+echo "=========================================="
+
+# Check Python version
+if ! command -v python3 &> /dev/null; then
+    echo "Error: Python 3 not found. Please install Python 3.10+"
+    exit 1
+fi
+
+PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+echo "Found Python $PYTHON_VERSION"
+
+# Check minimum version
+if ! python3 -c 'import sys; exit(0 if sys.version_info >= (3, 10) else 1)'; then
+    echo "Error: Python 3.10+ required (found $PYTHON_VERSION)"
+    exit 1
+fi
+
+# Clone or update repository
+if [ -d "multi-agent-mcp" ]; then
+    echo "Updating existing installation..."
+    cd multi-agent-mcp
+    git pull
+else
+    echo "Cloning repository..."
+    git clone https://github.com/carlosduplar/multi-agent-mcp.git
+    cd multi-agent-mcp
+fi
+
+# Install dependencies
+echo "Installing dependencies..."
+if command -v uv &> /dev/null; then
+    echo "Using uv (fast!)..."
+    uv sync
+else
+    echo "Using pip..."
+    pip install -e .
+fi
+
+# Run installer
+echo ""
+echo "Running automated setup..."
+python3 install.py
+
+echo ""
+echo "=========================================="
+echo "Installation script complete!"
+echo "=========================================="
+echo ""
+echo "Next: Restart Claude Code and try:"
+echo "  'scan for security vulnerabilities'"
+echo ""

pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "delegation-mcp"
+version = "0.4.0"
+description = "Multi-orchestrator delegation MCP server for AI coding agents with production-grade architecture"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Your Name", email = "your.email@example.com"}
+]
+keywords = ["mcp", "ai", "agents", "delegation", "orchestration"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0",
+    "click>=8.0.0",
+    "rich>=13.0.0",
+    "asyncio-mqtt>=0.16.0",
+    "python-dotenv>=1.0.0",
+    "psutil>=5.9.0",  # For resource monitoring (CPU, memory limits)
+]
+
+[project.optional-dependencies]
+ui = [
+    "gradio>=5.0.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.scripts]
+delegation-mcp = "delegation_mcp.server:main"
+delegation-ui = "delegation_mcp.ui.app:main"
+delegation-workflow = "delegation_mcp.cli:main"
+delegation-install = "delegation_mcp.installer:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "I", "N", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

requirements.txt

@@ -0,0 +1,12 @@
+mcp>=1.0.0
+gradio>=5.0.0
+pydantic>=2.0.0
+pyyaml>=6.0
+click>=8.0.0
+rich>=13.0.0
+asyncio-mqtt>=0.16.0
+python-dotenv>=1.0.0
+psutil>=5.9.0
+sse-starlette>=1.8.0
+uvicorn>=0.20.0
+fastapi>=0.100.0

src/delegation_mcp/__init__.py

@@ -0,0 +1,15 @@
+"""Delegation MCP Server - Multi-orchestrator delegation for AI coding agents."""
+
+__version__ = "0.4.0"
+
+from .config import DelegationConfig, OrchestratorConfig, DelegationRule
+from .orchestrator import OrchestratorRegistry
+from .delegation import DelegationEngine
+
+__all__ = [
+    "DelegationConfig",
+    "OrchestratorConfig",
+    "DelegationRule",
+    "OrchestratorRegistry",
+    "DelegationEngine",
+]

src/delegation_mcp/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""CLI adapters for different orchestrators."""
+
+from .base import CLIAdapter
+from .claude import ClaudeAdapter
+from .gemini import GeminiAdapter
+from .copilot import CopilotAdapter
+from .aider import AiderAdapter
+
+__all__ = [
+    "CLIAdapter",
+    "ClaudeAdapter",
+    "GeminiAdapter",
+    "CopilotAdapter",
+    "AiderAdapter",
+]

src/delegation_mcp/adapters/aider.py

@@ -0,0 +1,102 @@
+"""Aider CLI adapter."""
+
+import asyncio
+import subprocess
+from typing import Any
+
+from .base import CLIAdapter
+
+
+class AiderAdapter(CLIAdapter):
+    """Adapter for Aider CLI."""
+
+    async def execute(self, task: str, progress_callback: Any = None, timeout: int | None = None, **kwargs: Any) -> tuple[str, str, int]:
+        """Execute task using Aider CLI with optional streaming."""
+        if progress_callback:
+            return await self.execute_streaming(task, progress_callback, timeout, **kwargs)
+        
+        cmd = self.format_task(task, **kwargs)
+        resolved_cmd = self.resolve_command(cmd)
+
+        # Sanitize environment for Windows/prompt_toolkit compatibility
+        env = {**subprocess.os.environ, **self.get_env()}
+        env["TERM"] = "dumb"  # Prevent prompt_toolkit from seeing xterm-256color on Windows
+        env["PYTHONIOENCODING"] = "utf-8"
+
+        process = await asyncio.create_subprocess_exec(
+            *resolved_cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+        )
+
+        try:
+            effective_timeout = timeout or self.get_timeout()
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(), timeout=effective_timeout
+            )
+            return (
+                stdout.decode("utf-8", errors="replace"),
+                stderr.decode("utf-8", errors="replace"),
+                process.returncode or 0,
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            raise TimeoutError(f"Aider CLI timed out after {effective_timeout}s")
+
+    def get_env(self) -> dict[str, str]:
+        """Get environment variables for Aider."""
+        env = super().get_env().copy()
+        env["TERM"] = "dumb"  # Prevent prompt_toolkit from seeing xterm-256color on Windows
+        env["PYTHONIOENCODING"] = "utf-8"
+        return env
+
+    def validate(self) -> bool:
+        """Validate Aider is available."""
+        try:
+            subprocess.run(
+                ["which", "aider"] if subprocess.os.name != "nt" else ["where", "aider"],
+                capture_output=True,
+                check=True,
+            )
+            return True
+        except subprocess.CalledProcessError:
+            return False
+
+    def format_task(self, task: str, **kwargs: Any) -> list[str]:
+        """Format task for Aider CLI."""
+        cmd = ["aider"]
+
+        # Add message flag for non-interactive mode
+        cmd.append("--message")
+        cmd.append(task)
+
+        # Add model if specified
+        if model := kwargs.get("model"):
+            cmd.extend(["--model", model])
+
+        # Add mode flags
+        if kwargs.get("architect_mode"):
+            cmd.append("--architect")
+        elif kwargs.get("ask_mode"):
+            cmd.append("--ask")
+
+        # Auto-commit changes
+        if kwargs.get("auto_commit", True):
+            cmd.append("--auto-commits")
+
+        # Add optimization flags
+        cmd.extend([
+            "--no-pretty",
+            "--stream",
+            "--no-check-update",
+            "--no-show-release-notes",
+            "--verbose",
+            "--yes-always",
+        ])
+
+        # Add any custom args from config
+        cmd.extend(self.get_args())
+
+        return cmd

src/delegation_mcp/adapters/base.py

@@ -0,0 +1,179 @@
+"""Base adapter interface for CLI orchestrators."""
+
+import os
+import shutil
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class CLIAdapter(ABC):
+    """Base adapter for CLI orchestrators."""
+
+    def __init__(self, name: str, config: dict[str, Any]):
+        self.name = name
+        self.config = config
+
+    @abstractmethod
+    async def execute(self, task: str, **kwargs: Any) -> tuple[str, str, int]:
+        """
+        Execute a task using the CLI.
+
+        Args:
+            task: Task description/query
+            **kwargs: Additional CLI-specific arguments
+
+        Returns:
+            tuple: (stdout, stderr, return_code)
+        """
+        pass
+
+    @abstractmethod
+    def validate(self) -> bool:
+        """Validate the CLI is installed and accessible."""
+        pass
+
+    @abstractmethod
+    def format_task(self, task: str, **kwargs: Any) -> list[str]:
+        """
+        Format task into CLI command arguments.
+
+        Args:
+            task: Task description
+            **kwargs: Additional formatting options
+
+        Returns:
+            list: Command arguments
+        """
+        pass
+
+    def get_command(self) -> str | list[str]:
+        """Get base command for this adapter."""
+        return self.config.get("command", self.name)
+
+    def get_args(self) -> list[str]:
+        """Get default arguments for this adapter."""
+        return self.config.get("args", [])
+
+    def get_env(self) -> dict[str, str]:
+        """Get environment variables for this adapter."""
+        return self.config.get("env", {})
+
+    def get_timeout(self) -> int:
+        """Get timeout in seconds."""
+        return self.config.get("timeout", 300)
+
+    async def execute_streaming(
+        self, 
+        task: str,
+        progress_callback: Any = None,
+        timeout: int | None = None,
+        **kwargs: Any
+    ) -> tuple[str, str, int]:
+        """
+        Execute task with real-time output streaming.
+        
+        Args:
+            task: Task description/query
+            progress_callback: Optional async callback for progress updates
+            timeout: Override timeout in seconds
+            **kwargs: Additional CLI-specific arguments
+        
+        Returns:
+            tuple: (stdout, stderr, return_code)
+        """
+        import asyncio
+        
+        # Get command and args
+        cmd_args = self.format_task(task, **kwargs)
+        resolved_cmd = self.resolve_command(cmd_args[0])
+        
+        if isinstance(resolved_cmd, str):
+            full_cmd = [resolved_cmd] + cmd_args[1:]
+        else:
+            full_cmd = resolved_cmd + cmd_args[1:]
+        
+        # Merge environment
+        env = os.environ.copy()
+        env.update(self.get_env())
+        
+        # Start process with pipes for streaming
+        process = await asyncio.create_subprocess_exec(
+            *full_cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env
+        )
+        
+        stdout_lines = []
+        stderr_lines = []
+        
+        async def read_stream(stream, line_buffer, prefix=""):
+            """Read stream line-by-line and call progress callback."""
+            while True:
+                line = await stream.readline()
+                if not line:
+                    break
+                decoded = line.decode().strip()
+                if decoded:
+                    line_buffer.append(decoded)
+                    if progress_callback:
+                        try:
+                            await progress_callback(f"{prefix}{decoded}")
+                        except Exception:
+                            pass  # Don't fail on callback errors
+        
+        try:
+            # Read both streams concurrently with timeout
+            effective_timeout = timeout or self.get_timeout()
+            await asyncio.wait_for(
+                asyncio.gather(
+                    read_stream(process.stdout, stdout_lines),
+                    read_stream(process.stderr, stderr_lines, "[stderr] "),
+                ),
+                timeout=effective_timeout
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            raise TimeoutError(f"{self.name} timed out after {effective_timeout}s")
+        
+        # Wait for process to complete
+        await process.wait()
+        
+        return (
+            "\n".join(stdout_lines),
+            "\n".join(stderr_lines),
+            process.returncode
+        )
+
+    @staticmethod
+    def resolve_command(cmd: str | list[str]) -> str | list[str]:
+        """
+        Resolve command to full path on Windows.
+
+        On Windows, asyncio.create_subprocess_exec() doesn't reliably search PATH,
+        so we need to resolve commands to their full paths using shutil.which().
+
+        Args:
+            cmd: Command string or list of command parts
+
+        Returns:
+            Resolved command (full path on Windows, original on Unix)
+        """
+        if os.name != "nt":
+            # On Unix systems, PATH search works fine
+            return cmd
+
+        # On Windows, resolve the executable path
+        if isinstance(cmd, list):
+            if not cmd:
+                return cmd
+            # Resolve first element (the executable)
+            resolved = shutil.which(cmd[0])
+            if resolved:
+                return [resolved] + cmd[1:]
+            return cmd
+        else:
+            # Single string command
+            resolved = shutil.which(cmd)
+            return resolved if resolved else cmd

src/delegation_mcp/adapters/claude.py

@@ -0,0 +1,69 @@
+"""Claude Code CLI adapter."""
+
+import asyncio
+import subprocess
+from typing import Any
+
+from .base import CLIAdapter
+
+
+class ClaudeAdapter(CLIAdapter):
+    """Adapter for Claude Code CLI."""
+
+    async def execute(self, task: str, progress_callback: Any = None, timeout: int | None = None, **kwargs: Any) -> tuple[str, str, int]:
+        """Execute task using Claude Code with optional streaming."""
+        if progress_callback:
+            return await self.execute_streaming(task, progress_callback, timeout, **kwargs)
+        
+        cmd = self.format_task(task, **kwargs)
+        resolved_cmd = self.resolve_command(cmd)
+
+        process = await asyncio.create_subprocess_exec(
+            *resolved_cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env={**subprocess.os.environ, **self.get_env()},
+        )
+
+        try:
+            effective_timeout = timeout or self.get_timeout()
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(), timeout=effective_timeout
+            )
+            return (
+                stdout.decode("utf-8", errors="replace"),
+                stderr.decode("utf-8", errors="replace"),
+                process.returncode or 0,
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            raise TimeoutError(f"Claude CLI timed out after {effective_timeout}s")
+
+    def validate(self) -> bool:
+        """Validate Claude CLI is available."""
+        try:
+            subprocess.run(
+                ["which", "claude"] if subprocess.os.name != "nt" else ["where", "claude"],
+                capture_output=True,
+                check=True,
+            )
+            return True
+        except subprocess.CalledProcessError:
+            return False
+
+    def format_task(self, task: str, **kwargs: Any) -> list[str]:
+        """Format task for Claude CLI."""
+        cmd = ["claude"]
+
+        # Add any custom args from config
+        cmd.extend(self.get_args())
+
+        # Add mode if specified
+        if mode := kwargs.get("mode"):
+            cmd.extend(["--mode", mode])
+
+        # Add task as final argument
+        cmd.append(task)
+
+        return cmd

src/delegation_mcp/adapters/copilot.py

@@ -0,0 +1,70 @@
+"""GitHub Copilot CLI adapter."""
+
+import asyncio
+import subprocess
+from typing import Any
+
+from .base import CLIAdapter
+
+
+class CopilotAdapter(CLIAdapter):
+    """Adapter for GitHub Copilot CLI."""
+
+    async def execute(self, task: str, progress_callback: Any = None, timeout: int | None = None, **kwargs: Any) -> tuple[str, str, int]:
+        """Execute task using Copilot CLI with optional streaming."""
+        if progress_callback:
+            return await self.execute_streaming(task, progress_callback, timeout, **kwargs)
+        
+        cmd = self.format_task(task, **kwargs)
+        resolved_cmd = self.resolve_command(cmd)
+
+        process = await asyncio.create_subprocess_exec(
+            *resolved_cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env={**subprocess.os.environ, **self.get_env()},
+        )
+
+        try:
+            effective_timeout = timeout or self.get_timeout()
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(), timeout=effective_timeout
+            )
+            return (
+                stdout.decode("utf-8", errors="replace"),
+                stderr.decode("utf-8", errors="replace"),
+                process.returncode or 0,
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            raise TimeoutError(f"Copilot CLI timed out after {effective_timeout}s")
+
+    def validate(self) -> bool:
+        """Validate Copilot CLI is available."""
+        try:
+            # Check for copilot CLI
+            subprocess.run(
+                ["which", "copilot"] if subprocess.os.name != "nt" else ["where", "copilot"],
+                capture_output=True,
+                check=True,
+            )
+            return True
+        except subprocess.CalledProcessError:
+            return False
+
+    def format_task(self, task: str, **kwargs: Any) -> list[str]:
+        """Format task for Copilot CLI."""
+        cmd = ["copilot"]
+
+        # Add subcommand (suggest, explain, etc.)
+        subcommand = kwargs.get("subcommand", "suggest")
+        cmd.append(subcommand)
+
+        # Add any custom args from config
+        cmd.extend(self.get_args())
+
+        # Add task
+        cmd.append(task)
+
+        return cmd

src/delegation_mcp/adapters/gemini.py

@@ -0,0 +1,79 @@
+"""Gemini CLI adapter."""
+
+import asyncio
+import subprocess
+from typing import Any
+
+from .base import CLIAdapter
+
+
+class GeminiAdapter(CLIAdapter):
+    """Adapter for Gemini CLI."""
+
+    async def execute(self, task: str, progress_callback: Any = None, timeout: int | None = None, **kwargs: Any) -> tuple[str, str, int]:
+        """Execute task using Gemini CLI with optional streaming."""
+        # Use streaming method from base class if progress_callback provided
+        if progress_callback:
+            return await self.execute_streaming(task, progress_callback, timeout, **kwargs)
+        
+        # Otherwise use buffered execution (legacy)
+        cmd = self.format_task(task, **kwargs)
+       
+        resolved_cmd = self.resolve_command(cmd)
+
+        process = await asyncio.create_subprocess_exec(
+            *resolved_cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env={**subprocess.os.environ,  **self.get_env()},
+        )
+
+        try:
+            effective_timeout = timeout or self.get_timeout()
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(), timeout=effective_timeout
+            )
+            return (
+                stdout.decode("utf-8", errors="replace"),
+                stderr.decode("utf-8", errors="replace"),
+                process.returncode or 0,
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await process.wait()
+            raise TimeoutError(f"Gemini CLI timed out after {effective_timeout}s")
+
+    def validate(self) -> bool:
+        """Validate Gemini CLI is available."""
+        try:
+            subprocess.run(
+                ["which", "gemini"] if subprocess.os.name != "nt" else ["where", "gemini"],
+                capture_output=True,
+                check=True,
+            )
+            return True
+        except subprocess.CalledProcessError:
+            return False
+
+    def format_task(self, task: str, **kwargs: Any) -> list[str]:
+        """Format task for Gemini CLI."""
+        cmd = ["gemini"]
+
+        # Add model if specified in kwargs or config
+        if model := kwargs.get("model") or self.config.get("model"):
+            cmd.extend(["-m", model])
+
+        # Add allowed tools if specified
+        if tools := kwargs.get("allowed_tools"):
+            tool_list = tools if isinstance(tools, str) else ",".join(tools)
+            cmd.extend(["--allowed-tools", tool_list])
+
+        # Add any custom args from config
+        for arg in self.get_args():
+            if arg not in cmd:  # Avoid duplicates
+                cmd.append(arg)
+
+        # Add task as final argument (quoted)
+        cmd.append(task)
+
+        return cmd

src/delegation_mcp/agent_discovery.py

@@ -0,0 +1,518 @@
+"""Agent auto-discovery system for detecting installed CLI agents.
+
+Automatically discovers which agents (Claude Code, Gemini CLI, Aider, Copilot, etc.)
+are installed and available on the user's system.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import platform
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentMetadata:
+    """Metadata for a discovered agent."""
+
+    name: str
+    command: str | list[str]
+    version: str | None = None
+    available: bool = False
+    path: str | None = None
+    error_message: str | None = None
+    capabilities: list[str] | None = None
+    verified_at: str | None = None
+
+
+class AgentDiscovery:
+    """Automatic discovery system for CLI agents."""
+
+    # Known agent patterns to scan for
+    # Note: On Windows, gemini must be checked first due to subprocess interaction issues
+    VERIFICATION_TIMEOUT = 30.0
+
+    KNOWN_AGENTS = {
+        "gemini": {
+            "command": "gemini",
+            "version_flag": "--version",
+            "capabilities": ["security", "vision", "fast_iteration"],
+        },
+        "claude": {
+            "command": "claude",
+            "version_flag": "--version",
+            "capabilities": ["reasoning", "architecture", "code_generation"],
+        },
+        "aider": {
+            "command": "aider",
+            "version_flag": "--version",
+            "capabilities": ["git_operations", "code_editing", "refactoring"],
+        },
+        "copilot": {
+            "command": "copilot",
+            "version_flag": "--version",
+            "capabilities": ["github_integration", "suggestions"],
+        },
+        "qwen": {
+            "command": "qwen-code",
+            "version_flag": "--version",
+            "capabilities": ["code_generation", "multilingual"],
+        },
+    }
+
+    def __init__(self, cache_file: Path | None = None):
+        """Initialize agent discovery system.
+
+        Args:
+            cache_file: Path to cache file for discovered agents
+        """
+        # Set up safe cache directory
+        cache_dir = Path.home() / ".cache" / "delegation-mcp"
+
+        if cache_file:
+            # Validate user-provided cache file path to prevent traversal
+            cache_file = Path(cache_file)
+
+            # Ensure it's just a filename, not a path
+            if len(cache_file.parts) > 1:
+                logger.warning(f"Cache file path contains directories, using only filename: {cache_file.name}")
+                cache_file = cache_dir / cache_file.name
+            else:
+                cache_file = cache_dir / cache_file
+
+            # Resolve to absolute path and check it's within cache_dir
+            try:
+                cache_file = cache_file.resolve()
+                if not str(cache_file).startswith(str(cache_dir.resolve())):
+                    raise ValueError(f"Cache file path outside allowed directory: {cache_file}")
+            except (OSError, ValueError) as e:
+                logger.error(f"Invalid cache file path: {e}")
+                cache_file = cache_dir / "discovered_agents.json"
+        else:
+            cache_file = cache_dir / "discovered_agents.json"
+
+        self.cache_file = cache_file
+        self._discovered_agents: dict[str, AgentMetadata] = {}
+        self._load_cache()
+
+    def _load_cache(self) -> None:
+        """Load cached discovery results with validation."""
+        if self.cache_file.exists():
+            try:
+                with open(self.cache_file) as f:
+                    data = json.load(f)
+
+                    # Validate data structure
+                    if not isinstance(data, dict):
+                        logger.warning("Invalid cache format: expected dictionary")
+                        return
+
+                    # Validate each entry
+                    required_fields = {'name', 'command', 'available'}
+                    for name, metadata in data.items():
+                        # Validate name is safe
+                        if not isinstance(name, str) or not re.match(r'^[a-zA-Z0-9_\-]+$', name):
+                            logger.warning(f"Skipping invalid agent name in cache: {name}")
+                            continue
+
+                        # Validate metadata structure
+                        if not isinstance(metadata, dict):
+                            logger.warning(f"Skipping invalid metadata for {name}")
+                            continue
+
+                        if not required_fields.issubset(metadata.keys()):
+                            logger.warning(f"Skipping incomplete cache entry: {name}")
+                            continue
+
+                        try:
+                            self._discovered_agents[name] = AgentMetadata(**metadata)
+                        except Exception as e:
+                            logger.warning(f"Failed to load agent {name} from cache: {e}")
+                            continue
+
+                logger.info(f"Loaded {len(self._discovered_agents)} agents from cache")
+            except Exception as e:
+                logger.warning(f"Failed to load agent cache: {e}")
+
+    def _save_cache(self) -> None:
+        """Save discovery results to cache."""
+        try:
+            self.cache_file.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.cache_file, "w") as f:
+                data = {name: asdict(agent) for name, agent in self._discovered_agents.items()}
+                json.dump(data, f, indent=2)
+            logger.info(f"Saved {len(self._discovered_agents)} agents to cache")
+        except Exception as e:
+            logger.error(f"Failed to save agent cache: {e}")
+
+    def _resolve_command_path(self, command: str | list[str]) -> str | None:
+        """Resolve command to full path if available.
+
+        Args:
+            command: Command string or list
+
+        Returns:
+            Full path to executable or None if not found
+        """
+        cmd = command[0] if isinstance(command, list) else command
+
+        # Use shutil.which for cross-platform command resolution
+        path = shutil.which(cmd)
+        if path:
+            logger.debug(f"Found {cmd} at {path}")
+            return path
+
+        logger.debug(f"Command {cmd} not found in PATH")
+        return None
+
+    def _get_node_script_path(self, cmd_path: str) -> tuple[str, list[str]] | None:
+        """For npm .cmd files on Windows, extract the underlying Node.js script.
+
+        Args:
+            cmd_path: Path to .cmd file
+
+        Returns:
+            Tuple of (node_executable, [script_path]) or None
+        """
+        if not cmd_path.lower().endswith('.cmd'):
+            return None
+
+        try:
+            # Read the .cmd file to find the node script
+            with open(cmd_path, 'r') as f:
+                content = f.read()
+
+            # Look for pattern like: "%_prog%" "%dp0%\node_modules\...\index.js"
+            import re
+            match = re.search(r'"%dp0%\\node_modules\\([^"]+)"', content)
+            if match:
+                script_rel_path = match.group(1)
+                npm_dir = Path(cmd_path).parent
+                script_path = npm_dir / "node_modules" / script_rel_path
+
+                if script_path.exists():
+                    node_exe = shutil.which("node")
+                    if node_exe:
+                        logger.debug(f"Found node script: {script_path}")
+                        return node_exe, [str(script_path)]
+        except Exception as e:
+            logger.debug(f"Could not extract node script from {cmd_path}: {e}")
+
+        return None
+
+    async def _verify_agent(
+        self,
+        name: str,
+        command: str | list[str],
+        version_flag: str = "--version",
+    ) -> tuple[bool, str | None, str | None]:
+        """Verify agent is working by running version command.
+
+        Args:
+            name: Agent name
+            command: Command to execute
+            version_flag: Flag to get version (--version or --help)
+
+        Returns:
+            tuple: (is_available, version_string, error_message)
+        """
+        # Build command
+        if isinstance(command, list):
+            cmd = command + [version_flag]
+        else:
+            cmd = [command, version_flag]
+
+        logger.debug(f"Verifying {name} with command: {cmd}, is_list: {isinstance(command, list)}")
+
+        try:
+            # Try --version first
+            # On Windows with string commands (not node direct calls), use cmd /c
+            if platform.system() == "Windows" and isinstance(command, str):
+                # Use cmd /c with proper quoting for Windows CMD/BAT files
+                cmd_str = " ".join(cmd)
+                process = await asyncio.create_subprocess_exec(
+                    "cmd",
+                    "/c",
+                    cmd_str,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    stdin=asyncio.subprocess.PIPE,
+                )
+            else:
+                # Direct execution (Unix or Windows with node direct call)
+                process = await asyncio.create_subprocess_exec(
+                    *cmd,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    stdin=asyncio.subprocess.PIPE,
+                )
+
+            # Close stdin to prevent processes from hanging while waiting for input
+            if process.stdin:
+                process.stdin.close()
+
+            stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=self.VERIFICATION_TIMEOUT)
+
+            if process.returncode == 0:
+                version = stdout.decode("utf-8", errors="replace").strip()
+                if not version:
+                    version = stderr.decode("utf-8", errors="replace").strip()
+                
+                # Take only the first line to avoid multi-line version outputs
+                version = version.split('\n')[0].strip() if version else ""
+                
+                logger.info(f"Agent {name} verified: {version[:100]}")
+                return True, version[:200], None
+            else:
+                # Try --help as fallback
+                if version_flag == "--version":
+                    return await self._verify_agent(name, command, "--help")
+
+                error = stderr.decode("utf-8", errors="replace").strip()
+                logger.warning(f"Agent {name} verification failed: {error}")
+                return False, None, error[:200]
+
+        except asyncio.TimeoutError:
+            error = f"Agent {name} timed out during verification"
+            logger.warning(error)
+            return False, None, error
+        except FileNotFoundError:
+            error = f"Command not found: {cmd[0]}"
+            logger.debug(error)
+            return False, None, error
+        except Exception as e:
+            error = f"Failed to verify {name}: {str(e)}"
+            logger.warning(error)
+            return False, None, error
+
+    async def discover_agents(
+        self,
+        force_refresh: bool = False,
+        agents_to_check: list[str] | None = None,
+    ) -> dict[str, AgentMetadata]:
+        """Discover available agents on the system.
+
+        Args:
+            force_refresh: Force re-discovery even if cache exists
+            agents_to_check: Specific agents to check (default: all known agents)
+
+        Returns:
+            Dictionary of agent name to metadata
+        """
+        if not force_refresh and self._discovered_agents:
+            logger.info("Using cached agent discovery results")
+            return self._discovered_agents
+
+        logger.info("Starting agent discovery...")
+
+        # Determine which agents to check
+        agents = agents_to_check or list(self.KNOWN_AGENTS.keys())
+
+        # Use a semaphore to limit concurrency on all platforms to avoid resource spikes
+        # On Windows this is critical, on others it's just good practice
+        concurrency_limit = 5 if platform.system() == "Windows" else 10
+        semaphore = asyncio.Semaphore(concurrency_limit)
+
+        async def _bounded_discover(name: str, config: dict[str, Any]) -> AgentMetadata | Exception:
+            async with semaphore:
+                try:
+                    return await self._discover_single_agent(name, config)
+                except Exception as e:
+                    logger.error(f"Discovery task failed for {name}: {e}")
+                    return e
+
+        logger.debug(f"Running agent discovery in parallel (limit={concurrency_limit})")
+        tasks = []
+        for name in agents:
+            if name not in self.KNOWN_AGENTS:
+                logger.warning(f"Unknown agent: {name}")
+                continue
+
+            config = self.KNOWN_AGENTS[name]
+            tasks.append(_bounded_discover(name, config))
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Process results
+        for result in results:
+            if isinstance(result, AgentMetadata):
+                self._discovered_agents[result.name] = result
+            elif isinstance(result, Exception):
+                # Already logged in _bounded_discover
+                pass
+
+        # Save to cache
+        self._save_cache()
+
+        logger.info(
+            f"Discovery complete: {sum(1 for a in self._discovered_agents.values() if a.available)}/{len(self._discovered_agents)} agents available"
+        )
+
+        return self._discovered_agents
+
+    async def _discover_single_agent(
+        self,
+        name: str,
+        config: dict[str, Any],
+    ) -> AgentMetadata:
+        """Discover a single agent.
+
+        Args:
+            name: Agent name
+            config: Agent configuration
+
+        Returns:
+            AgentMetadata for the agent
+        """
+        command = config["command"]
+        version_flag = config.get("version_flag", "--version")
+        capabilities = config.get("capabilities", [])
+
+        # Resolve command path
+        path = self._resolve_command_path(command)
+
+        if not path:
+            return AgentMetadata(
+                name=name,
+                command=command,
+                available=False,
+                error_message=self._get_install_message(name),
+            )
+
+        # On Windows, try to extract node script from .cmd files
+        verify_command = command
+        if platform.system() == "Windows" and isinstance(command, str):
+            node_script = self._get_node_script_path(path)
+            if node_script:
+                node_exe, script_args = node_script
+                verify_command = [node_exe] + script_args
+
+        # Verify agent works
+        available, version, error = await self._verify_agent(name, verify_command, version_flag)
+
+        from datetime import datetime
+
+        return AgentMetadata(
+            name=name,
+            command=command,
+            version=version,
+            available=available,
+            path=path,
+            error_message=error if not available else None,
+            capabilities=capabilities if available else None,
+            verified_at=datetime.utcnow().isoformat() if available else None,
+        )
+
+    def _get_install_message(self, agent_name: str) -> str:
+        """Get installation instructions for an agent.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Installation instructions
+        """
+        install_messages = {
+            "claude": "Claude Code not found. Install with: npm install -g @anthropic/claude-code",
+            "gemini": "Gemini CLI not found. Install with: npm install -g @google/gemini-cli",
+            "aider": "Aider not found. Install with: pip install aider-chat",
+            "copilot": "GitHub Copilot CLI not found. Install with: npm install -g @github/copilot",
+            "qwen": "Qwen Code not found. Install with: npm install -g @qwen-code/qwen-code",
+        }
+
+        return install_messages.get(
+            agent_name,
+            f"{agent_name} not found. Check agent documentation for installation instructions.",
+        )
+
+    def get_available_agents(self) -> list[AgentMetadata]:
+        """Get list of available agents.
+
+        Returns:
+            List of available agent metadata
+        """
+        return [agent for agent in self._discovered_agents.values() if agent.available]
+
+    def get_unavailable_agents(self) -> list[AgentMetadata]:
+        """Get list of unavailable agents.
+
+        Returns:
+            List of unavailable agent metadata
+        """
+        return [agent for agent in self._discovered_agents.values() if not agent.available]
+
+    def is_agent_available(self, name: str) -> bool:
+        """Check if a specific agent is available.
+
+        Args:
+            name: Agent name
+
+        Returns:
+            True if agent is available
+        """
+        agent = self._discovered_agents.get(name)
+        return agent.available if agent else False
+
+    def get_agent_metadata(self, name: str) -> AgentMetadata | None:
+        """Get metadata for a specific agent.
+
+        Args:
+            name: Agent name
+
+        Returns:
+            Agent metadata or None if not found
+        """
+        return self._discovered_agents.get(name)
+
+    def get_discovery_summary(self) -> dict[str, Any]:
+        """Get summary of discovery results.
+
+        Returns:
+            Dictionary with discovery summary
+        """
+        available = self.get_available_agents()
+        unavailable = self.get_unavailable_agents()
+
+        return {
+            "total_agents": len(self._discovered_agents),
+            "available": len(available),
+            "unavailable": len(unavailable),
+            "available_agents": [
+                {"name": a.name, "version": a.version, "path": a.path} for a in available
+            ],
+            "unavailable_agents": [
+                {"name": a.name, "error": a.error_message} for a in unavailable
+            ],
+            "system_info": {
+                "platform": platform.system(),
+                "python_version": platform.python_version(),
+            },
+        }
+
+    def clear_cache(self) -> None:
+        """Clear the discovery cache."""
+        self._discovered_agents.clear()
+        if self.cache_file.exists():
+            self.cache_file.unlink()
+        logger.info("Agent discovery cache cleared")
+
+
+async def discover_agents(force_refresh: bool = False) -> dict[str, AgentMetadata]:
+    """Convenience function to discover agents.
+
+    Args:
+        force_refresh: Force re-discovery even if cache exists
+
+    Returns:
+        Dictionary of agent name to metadata
+    """
+    discovery = AgentDiscovery()
+    return await discovery.discover_agents(force_refresh=force_refresh)

src/delegation_mcp/cli.py

@@ -0,0 +1,358 @@
+"""CLI for executing workflows."""
+
+import asyncio
+import click
+import sys
+from pathlib import Path
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
+from rich.table import Table
+from rich.panel import Panel
+from rich.syntax import Syntax
+
+from .workflow import WorkflowEngine, WorkflowDefinition
+from .orchestrator import OrchestratorRegistry
+from .config import DelegationConfig
+from .logging_config import setup_logging
+from .agent_discovery import AgentDiscovery
+
+
+console = Console()
+
+
+@click.group()
+@click.option('--verbose', '-v', is_flag=True, help='Verbose output')
+@click.option('--config', '-c', type=click.Path(exists=True), help='Config file path')
+@click.pass_context
+def cli(ctx, verbose, config):
+    """Delegation MCP - Multi-Agent Workflow Orchestration."""
+    ctx.ensure_object(dict)
+    ctx.obj['verbose'] = verbose
+    ctx.obj['config_path'] = Path(config) if config else Path("config/delegation_rules.yaml")
+
+    # Setup logging
+    import logging
+    setup_logging(level=logging.DEBUG if verbose else logging.INFO, verbose=verbose)
+
+
+@cli.command('list')
+@click.pass_context
+def list_workflows(ctx):
+    """List all available workflows."""
+    workflows_dir = Path("workflows")
+
+    if not workflows_dir.exists():
+        console.print("[red]❌ Workflows directory not found[/red]")
+        sys.exit(1)
+
+    console.print("\n[bold cyan]📚 Available Workflows[/bold cyan]\n")
+
+    table = Table(show_header=True, header_style="bold magenta")
+    table.add_column("Name", style="cyan", no_wrap=True)
+    table.add_column("Steps", justify="center", style="yellow")
+    table.add_column("Agents", style="green")
+    table.add_column("Category", style="blue")
+    table.add_column("Difficulty", style="magenta")
+    table.add_column("Duration", justify="right", style="yellow")
+
+    for workflow_file in sorted(workflows_dir.glob("*.yaml")):
+        try:
+            workflow = WorkflowDefinition.from_yaml(workflow_file)
+            agents = ", ".join(sorted(set(step.agent for step in workflow.steps)))
+            category = workflow.metadata.get("category", "general")
+            difficulty = workflow.metadata.get("difficulty", "intermediate")
+            duration = workflow.metadata.get("estimated_duration", 0)
+
+            table.add_row(
+                workflow.name,
+                str(len(workflow.steps)),
+                agents,
+                category,
+                difficulty,
+                f"{duration // 60}min"
+            )
+        except Exception as e:
+            console.print(f"[red]⚠️  Failed to load {workflow_file.name}: {e}[/red]")
+
+    console.print(table)
+    console.print()
+
+
+@cli.command()
+@click.argument('workflow_name')
+@click.pass_context
+def show(ctx, workflow_name):
+    """Show workflow details."""
+    workflows_dir = Path("workflows")
+    workflow = _find_workflow(workflow_name, workflows_dir)
+
+    if not workflow:
+        sys.exit(1)
+
+    # Display workflow info
+    console.print()
+    console.print(Panel(
+        f"[bold]{workflow.name}[/bold]\n\n{workflow.description}",
+        title="📋 Workflow Details",
+        border_style="cyan"
+    ))
+
+    # Display steps
+    console.print("\n[bold cyan]🔄 Workflow Steps[/bold cyan]\n")
+
+    for i, step in enumerate(workflow.steps, 1):
+        console.print(f"[bold yellow]Step {i}:[/bold yellow] {step.id}")
+        console.print(f"  [cyan]Agent:[/cyan] {step.agent}")
+        console.print(f"  [green]Task:[/green] {step.task}")
+        if step.output:
+            console.print(f"  [blue]Output:[/blue] {step.output}")
+        if step.condition:
+            console.print(f"  [magenta]Condition:[/magenta] {step.condition}")
+        console.print()
+
+    # Display metadata
+    if workflow.metadata:
+        console.print("[bold cyan]📊 Metadata[/bold cyan]")
+        for key, value in workflow.metadata.items():
+            console.print(f"  [cyan]{key}:[/cyan] {value}")
+
+    console.print()
+
+
+@cli.command()
+@click.argument('workflow_name')
+@click.option('--context', '-c', multiple=True, help='Context variables (key=value)')
+@click.option('--dry-run', is_flag=True, help='Show what would be executed without running')
+@click.pass_context
+def execute(ctx, workflow_name, context, dry_run):
+    """Execute a workflow."""
+    workflows_dir = Path("workflows")
+    workflow = _find_workflow(workflow_name, workflows_dir)
+
+    if not workflow:
+        sys.exit(1)
+
+    # Parse context
+    context_dict = {}
+    for ctx_item in context:
+        if '=' in ctx_item:
+            key, value = ctx_item.split('=', 1)
+            context_dict[key.strip()] = value.strip()
+
+    if dry_run:
+        console.print("\n[bold yellow]🔍 Dry Run Mode[/bold yellow]\n")
+        console.print(f"[cyan]Workflow:[/cyan] {workflow.name}")
+        console.print(f"[cyan]Steps:[/cyan] {len(workflow.steps)}")
+        console.print(f"[cyan]Context:[/cyan] {context_dict}")
+        console.print("\n[bold green]Would execute:[/bold green]\n")
+        for i, step in enumerate(workflow.steps, 1):
+            console.print(f"  {i}. [{step.agent}] {step.task}")
+        console.print()
+        return
+
+    # Execute workflow
+    asyncio.run(_execute_workflow(ctx, workflow, context_dict))
+
+
+async def _execute_workflow(ctx, workflow, context):
+    """Execute workflow with progress display."""
+    # Setup
+    config_path = ctx.obj['config_path']
+    if config_path.exists():
+        config = DelegationConfig.from_yaml(config_path)
+    else:
+        config = DelegationConfig(orchestrator="claude")
+
+    registry = OrchestratorRegistry()
+    for name, orch_config in config.orchestrators.items():
+        registry.register(orch_config)
+
+    engine = WorkflowEngine(registry)
+
+    # Display header
+    console.print()
+    console.print(Panel(
+        f"[bold]{workflow.name}[/bold]\n{workflow.description}",
+        title="🚀 Executing Workflow",
+        border_style="green"
+    ))
+    console.print()
+
+    # Execute with progress
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        console=console,
+    ) as progress:
+
+        task = progress.add_task(
+            f"[cyan]Executing {len(workflow.steps)} steps...",
+            total=len(workflow.steps)
+        )
+
+        # We need to modify the engine to support progress callbacks
+        # For now, just execute
+        result = await engine.execute(workflow, initial_context=context)
+
+        progress.update(task, completed=len(workflow.steps))
+
+    # Display results
+    console.print()
+    if result.success:
+        console.print(Panel(
+            f"[bold green]✅ Workflow Completed Successfully[/bold green]\n\n"
+            f"Steps: {result.steps_completed}/{result.total_steps}\n"
+            f"Duration: {result.duration:.2f}s",
+            border_style="green"
+        ))
+    else:
+        console.print(Panel(
+            f"[bold red]❌ Workflow Failed[/bold red]\n\n"
+            f"Steps: {result.steps_completed}/{result.total_steps}\n"
+            f"Duration: {result.duration:.2f}s",
+            border_style="red"
+        ))
+
+    # Display outputs
+    if result.outputs:
+        console.print("\n[bold cyan]📤 Outputs[/bold cyan]\n")
+        for key, value in result.outputs.items():
+            console.print(f"[bold]{key}:[/bold]")
+            # Truncate long outputs
+            display_value = str(value)
+            if len(display_value) > 1000:
+                display_value = display_value[:1000] + "\n... (truncated)"
+            console.print(Panel(display_value, border_style="blue"))
+
+    # Display errors
+    if result.errors:
+        console.print("\n[bold red]❌ Errors[/bold red]\n")
+        for error in result.errors:
+            console.print(f"  • {error}")
+
+    console.print()
+
+
+@cli.command()
+@click.argument('workflow_file', type=click.Path(exists=True))
+@click.pass_context
+def validate(ctx, workflow_file):
+    """Validate a workflow file."""
+    try:
+        workflow = WorkflowDefinition.from_yaml(Path(workflow_file))
+        console.print(f"[green]✅ Workflow '{workflow.name}' is valid[/green]")
+        console.print(f"   Steps: {len(workflow.steps)}")
+        console.print(f"   Agents: {', '.join(set(step.agent for step in workflow.steps))}")
+    except Exception as e:
+        console.print(f"[red]❌ Invalid workflow: {e}[/red]")
+        sys.exit(1)
+
+
+@cli.command('discover-agents')
+@click.option('--force-refresh', '-f', is_flag=True, help='Force re-discovery even if cache exists')
+@click.option('--json', 'output_json', is_flag=True, help='Output results as JSON')
+@click.pass_context
+def discover_agents_cmd(ctx, force_refresh, output_json):
+    """Discover available CLI agents on the system."""
+    asyncio.run(_discover_agents(force_refresh, output_json))
+
+
+async def _discover_agents(force_refresh, output_json):
+    """Execute agent discovery."""
+    console.print()
+    console.print("[bold cyan]Discovering CLI Agents...[/bold cyan]\n")
+
+    # Create discovery instance and run discovery
+    discovery = AgentDiscovery()
+
+    console.print("[cyan]Scanning system PATH...[/cyan]")
+    discovered = await discovery.discover_agents(force_refresh=force_refresh)
+    console.print()
+
+    summary = discovery.get_discovery_summary()
+
+    if output_json:
+        # Output as JSON
+        import json
+        console.print(json.dumps(summary, indent=2))
+        return
+
+    # Display results in table format
+    console.print()
+    console.print(Panel(
+        f"[bold]Agent Discovery Results[/bold]\n\n"
+        f"Total agents scanned: {summary['total_agents']}\n"
+        f"Available: [green]{summary['available']}[/green]\n"
+        f"Unavailable: [red]{summary['unavailable']}[/red]",
+        title="Summary",
+        border_style="cyan"
+    ))
+    console.print()
+
+    # Display available agents
+    if summary['available_agents']:
+        console.print("[bold green]Available Agents[/bold green]\n")
+        table = Table(show_header=True, header_style="bold magenta")
+        table.add_column("Agent", style="cyan", no_wrap=True)
+        table.add_column("Version", style="yellow")
+        table.add_column("Path", style="green")
+
+        for agent in summary['available_agents']:
+            table.add_row(
+                agent['name'],
+                agent['version'][:50] if agent['version'] else 'Unknown',
+                agent['path']
+            )
+
+        console.print(table)
+        console.print()
+
+    # Display unavailable agents
+    if summary['unavailable_agents']:
+        console.print("[bold red]Unavailable Agents[/bold red]\n")
+        for agent in summary['unavailable_agents']:
+            console.print(f"[red]x[/red] [bold]{agent['name']}[/bold]")
+            console.print(f"  {agent['error']}\n")
+
+    console.print()
+    console.print("[dim]Tip: Use --force-refresh to re-scan, or --json for machine-readable output[/dim]")
+    console.print()
+
+
+def _find_workflow(name, workflows_dir):
+    """Find workflow by name or filename."""
+    if not workflows_dir.exists():
+        console.print("[red]❌ Workflows directory not found[/red]")
+        return None
+
+    # Try exact name match
+    for workflow_file in workflows_dir.glob("*.yaml"):
+        try:
+            workflow = WorkflowDefinition.from_yaml(workflow_file)
+            if workflow.name.lower() == name.lower():
+                return workflow
+        except Exception:
+            continue
+
+    # Try filename match
+    workflow_path = workflows_dir / f"{name}.yaml"
+    if workflow_path.exists():
+        try:
+            return WorkflowDefinition.from_yaml(workflow_path)
+        except Exception as e:
+            console.print(f"[red]❌ Failed to load workflow: {e}[/red]")
+            return None
+
+    console.print(f"[red]❌ Workflow '{name}' not found[/red]")
+    console.print("\nTry: [cyan]delegation-workflow list[/cyan] to see available workflows")
+    return None
+
+
+def main():
+    """Entry point."""
+    cli(obj={})
+
+
+if __name__ == '__main__':
+    main()

src/delegation_mcp/config.py

@@ -0,0 +1,253 @@
+"""Configuration models for delegation MCP server."""
+
+from typing import Any, Literal
+from pathlib import Path
+from pydantic import BaseModel, Field
+import yaml
+import re
+from collections import defaultdict
+
+
+class ConfigValidationError(Exception):
+    """Exception raised when configuration validation fails."""
+
+    def __init__(self, errors: list[str]):
+        self.errors = errors
+        super().__init__(f"Configuration validation failed: {'; '.join(errors)}")
+
+
+class AgentCapabilities(BaseModel):
+    """Capability scores for an agent."""
+
+    security_audit: float = 0.5
+    vulnerability_scan: float = 0.5
+    code_review: float = 0.5
+    architecture: float = 0.5
+    refactoring: float = 0.5
+    quick_fix: float = 0.5
+    documentation: float = 0.5
+    testing: float = 0.5
+    performance: float = 0.5
+    git_workflow: float = 0.5        # Git operations (commit, push, merge, rebase)
+    github_operations: float = 0.5   # GitHub operations (PR, issues, releases)
+    general: float = 0.5              # Fallback capability
+
+
+class OrchestratorConfig(BaseModel):
+    """Configuration for a single orchestrator/CLI."""
+
+    name: str
+    command: str | list[str]
+    args: list[str] = Field(default_factory=list)
+    enabled: bool = True
+    env: dict[str, str] = Field(default_factory=dict)
+    timeout: int = 300  # seconds
+    max_retries: int = 3
+    capabilities: AgentCapabilities = Field(default_factory=AgentCapabilities)
+    cost_per_1k_tokens: float = 0.001  # Cost estimate for routing decisions
+
+
+class DelegationRule(BaseModel):
+    """Rule for delegating tasks to specific orchestrators."""
+
+    pattern: str  # Regex pattern to match
+    delegate_to: str  # Target orchestrator name
+    priority: int = 0  # Higher priority wins
+    requires_approval: bool = False
+    description: str = ""
+
+
+class DelegationConfig(BaseModel):
+    """Main configuration for delegation MCP server."""
+
+    orchestrator: Literal["claude"] = "claude"  # Primary orchestrator
+    orchestrators: dict[str, OrchestratorConfig] = Field(default_factory=dict)
+    rules: list[DelegationRule] = Field(default_factory=list)
+    auto_approve: bool = False
+    log_delegations: bool = True
+    routing_strategy: Literal["capability", "pattern", "hybrid"] = "capability"  # Routing approach
+
+
+
+    def to_yaml(self, path: Path) -> None:
+        """Save configuration to YAML file."""
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(self.model_dump(), f, default_flow_style=False)
+
+    def get_orchestrator(self, name: str) -> OrchestratorConfig | None:
+        """Get orchestrator configuration by name."""
+        return self.orchestrators.get(name)
+
+    def find_delegation_rule(self, query: str) -> DelegationRule | None:
+        """Find matching delegation rule for query."""
+        matching_rules = [
+            rule
+            for rule in self.rules
+            if re.search(rule.pattern, query, re.IGNORECASE)
+        ]
+
+        if not matching_rules:
+            return None
+
+        # Return highest priority rule
+        return max(matching_rules, key=lambda r: r.priority)
+
+    def _validate_minimum_agents(self) -> list[str]:
+        """Validate that at least 2 agents are enabled."""
+        errors = []
+        enabled_count = sum(
+            1 for orch in self.orchestrators.values() if orch.enabled
+        )
+
+        if enabled_count < 2:
+            errors.append(
+                f"At least 2 agents must be enabled, but only {enabled_count} "
+                f"{'is' if enabled_count == 1 else 'are'} enabled. "
+                f"Enable more agents in orchestrators configuration."
+            )
+
+        return errors
+
+    def _validate_regex_patterns(self) -> list[str]:
+        """Validate YAML regex syntax in routing rules."""
+        errors = []
+
+        for i, rule in enumerate(self.rules):
+            try:
+                # Attempt to compile the regex pattern
+                re.compile(rule.pattern)
+            except re.error as e:
+                errors.append(
+                    f"Rule #{i + 1} (delegate_to: {rule.delegate_to}): "
+                    f"Invalid regex pattern '{rule.pattern}': {str(e)}"
+                )
+
+        return errors
+
+    def _validate_agent_references(self) -> list[str]:
+        """Validate that all referenced agents exist."""
+        errors = []
+
+        # Check primary orchestrator exists
+        if self.orchestrator not in self.orchestrators:
+            errors.append(
+                f"Primary orchestrator '{self.orchestrator}' is not defined "
+                f"in orchestrators configuration. Available orchestrators: "
+                f"{', '.join(self.orchestrators.keys())}"
+            )
+
+        # Check all delegation rule targets exist
+        for i, rule in enumerate(self.rules):
+            if rule.delegate_to not in self.orchestrators:
+                errors.append(
+                    f"Rule #{i + 1} (pattern: '{rule.pattern}'): "
+                    f"Target orchestrator '{rule.delegate_to}' is not defined. "
+                    f"Available orchestrators: {', '.join(self.orchestrators.keys())}"
+                )
+
+        return errors
+
+    def _validate_no_circular_delegation(self) -> list[str]:
+        """
+        Validate that there are no obvious circular delegation patterns.
+
+        Note: In the current delegation system, queries are processed once and returned
+        to the user - there is no automatic re-delegation. Therefore, true circular
+        delegation is not possible. This check looks for potential issues like:
+        - Duplicate patterns delegating to different orchestrators (ambiguous routing)
+        - Rules with very similar patterns that might cause confusion
+
+        Since circular delegation is not a real concern in this architecture, this
+        validation performs only basic sanity checks.
+        """
+        errors = []
+
+        if not self.rules:
+            return errors
+
+        # Check for duplicate or highly similar patterns
+        # This could cause ambiguous delegation behavior
+        pattern_targets: dict[str, list[str]] = defaultdict(list)
+
+        for rule in self.rules:
+            # Normalize pattern for comparison (case-insensitive)
+            normalized_pattern = rule.pattern.lower().strip()
+            pattern_targets[normalized_pattern].append(rule.delegate_to)
+
+        # Check for exact duplicate patterns with different targets
+        for pattern, targets in pattern_targets.items():
+            unique_targets = set(targets)
+            if len(unique_targets) > 1:
+                # Same pattern delegates to multiple different orchestrators
+                # This is actually fine - highest priority wins
+                # But if priorities are the same, it could be ambiguous
+
+                # Find rules with this pattern
+                matching_rules = [
+                    r for r in self.rules
+                    if r.pattern.lower().strip() == pattern
+                ]
+
+                # Check if they have the same priority
+                priorities = {r.priority for r in matching_rules}
+                if len(priorities) == 1:
+                    # All have same priority - ambiguous!
+                    targets_str = ", ".join(sorted(unique_targets))
+                    errors.append(
+                        f"Ambiguous delegation: pattern '{pattern}' delegates to "
+                        f"multiple orchestrators ({targets_str}) with the same priority. "
+                        f"This could cause unpredictable behavior. Consider using "
+                        f"different priorities or combining into a single rule."
+                    )
+
+        return errors
+
+    def validate(self) -> None:
+        """
+        Validate the entire configuration.
+
+        Performs the following validations:
+        1. At least 2 agents are enabled
+        2. All regex patterns in routing rules are valid
+        3. All referenced agents exist in orchestrators
+        4. No circular delegation rules exist
+
+        Raises:
+            ConfigValidationError: If any validation fails, with detailed error messages.
+        """
+        all_errors: list[str] = []
+
+        # Run all validation checks
+        all_errors.extend(self._validate_minimum_agents())
+        all_errors.extend(self._validate_regex_patterns())
+        all_errors.extend(self._validate_agent_references())
+        all_errors.extend(self._validate_no_circular_delegation())
+
+        # Raise exception if any errors found
+        if all_errors:
+            raise ConfigValidationError(all_errors)
+
+    @classmethod
+    def from_yaml(cls, path: Path, validate: bool = True) -> "DelegationConfig":
+        """
+        Load configuration from YAML file.
+
+        Args:
+            path: Path to YAML configuration file
+            validate: Whether to validate the configuration after loading (default: True)
+
+        Returns:
+            DelegationConfig instance
+
+        Raises:
+            ConfigValidationError: If validation is enabled and fails
+        """
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        config = cls(**data)
+
+        if validate:
+            config.validate()
+
+        return config

src/delegation_mcp/delegation.py

@@ -0,0 +1,461 @@
+"""Delegation engine for routing tasks to orchestrators."""
+
+import re
+import logging
+from typing import Any
+from datetime import datetime
+
+from .config import DelegationConfig, DelegationRule
+from .orchestrator import OrchestratorRegistry
+from .retry import retry_with_backoff
+from .logging_config import delegation_logger
+
+
+logger = logging.getLogger(__name__)
+
+
+class DelegationResult:
+    """Result of a delegation operation."""
+
+    def __init__(
+        self,
+        query: str,
+        orchestrator: str,
+        delegated_to: str | None,
+        rule: DelegationRule | None,
+        output: str,
+        error: str,
+        success: bool,
+        duration: float,
+    ):
+        self.query = query
+        self.orchestrator = orchestrator
+        self.delegated_to = delegated_to
+        self.rule = rule
+        self.output = output
+        self.error = error
+        self.success = success
+        self.duration = duration
+        self.timestamp = datetime.now()
+
+    def __repr__(self) -> str:
+        delegation = f" -> {self.delegated_to}" if self.delegated_to else ""
+        return f"<DelegationResult {self.orchestrator}{delegation}: {self.success}>"
+
+
+class DelegationEngine:
+    """Engine for delegating tasks based on rules."""
+
+    def __init__(self, config: DelegationConfig, registry: OrchestratorRegistry):
+        self.config = config
+        self.registry = registry
+        self.history: list[DelegationResult] = []
+
+    async def _execute_with_fallback(
+        self,
+        query: str,
+        ranked_agents: list[str],
+        tried_agents: list[str] = None,
+        progress_callback: Any = None,
+        timeout: int | None = None,
+    ) -> tuple[str, str, str, int]:
+        """
+        Execute query with automatic fallback to next best agent on failure.
+
+        Returns:
+            tuple: (target_agent, stdout, stderr, returncode)
+        """
+        if tried_agents is None:
+            tried_agents = []
+
+        for agent in ranked_agents:
+            if agent in tried_agents:
+                continue
+
+            try:
+                logger.info(f"Executing: {agent}")
+                stdout, stderr, returncode = await self.registry.execute(
+                    agent, query, timeout=timeout, progress_callback=progress_callback
+                )
+
+                if returncode == 0:
+                    logger.info(f"Success: {agent} completed task")
+                    return agent, stdout, stderr, returncode
+
+                # Failed but can try fallback
+                logger.warning(f"Fallback: {agent} failed (rc={returncode}) → trying next agent")
+                tried_agents.append(agent)
+
+            except (TimeoutError, RuntimeError, Exception) as e:
+                error_type = type(e).__name__
+                logger.warning(f"Fallback: {agent} error ({error_type}) → trying next agent")
+                tried_agents.append(agent)
+                continue
+
+        # All agents failed
+        raise RuntimeError(f"All agents failed. Tried: {', '.join(tried_agents)}")
+
+    async def process(
+        self,
+        query: str,
+        force_delegate: str | None = None,
+        progress_callback: Any = None,
+        guidance_only: bool = False,
+    ) -> DelegationResult:
+        """
+        Process a query with delegation logic and automatic fallback.
+
+        Args:
+            query: User query/task
+            force_delegate: Force delegation to specific orchestrator
+            progress_callback: Optional async callback for progress reporting
+            guidance_only: If True, return routing guidance without executing
+
+        Returns:
+            DelegationResult
+        """
+        start = datetime.now()
+        orchestrator = "claude"
+
+        # Determine delegation and get ranked agents
+        target, rule = self._determine_delegation(query, force_delegate)
+        
+        # If guidance_only mode, return routing recommendation without executing
+        if guidance_only:
+            if target == orchestrator:
+                return DelegationResult(
+                    query=query,
+                    orchestrator=orchestrator,
+                    delegated_to=None,
+                    rule=rule,
+                    output="HANDLE_DIRECTLY",
+                    error="",
+                    success=True,
+                    duration=0.0,
+                )
+            else:
+                return DelegationResult(
+                    query=query,
+                    orchestrator=orchestrator,
+                    delegated_to=target,
+                    rule=rule,
+                    output=f"DELEGATE_TO: {target}",
+                    error="",
+                    success=True,
+                    duration=0.0,
+                )
+
+        # Get full ranking for fallback
+        if force_delegate:
+            ranked_agents = [force_delegate]
+        else:
+            ranked_agents = self._rank_by_capabilities(query)
+            
+            # Ensure target is executed first
+            if target in ranked_agents:
+                ranked_agents.remove(target)
+            ranked_agents.insert(0, target)
+            
+            if not ranked_agents:
+                ranked_agents = [orchestrator]
+
+        # Get recommended timeout based on task  classification
+        _, recommended_timeout = self._classify_task(query)
+        
+        # Log delegation start
+        delegated_to = target if target != orchestrator else None
+        delegation_logger.delegation_start(orchestrator, query, delegated_to)
+
+        # Execute with fallback
+        try:
+            actual_agent, stdout, stderr, returncode = await self._execute_with_fallback(
+                query, ranked_agents, progress_callback=progress_callback, timeout=recommended_timeout
+            )
+            success = returncode == 0
+
+            # Update delegated_to if we fell back to different agent
+            if actual_agent != target:
+                logger.info(f"Fallback chain: {target} → {actual_agent}")
+                delegated_to = actual_agent if actual_agent != orchestrator else None
+            else:
+                delegated_to = target if target != orchestrator else None
+
+        except Exception as e:
+            # All agents failed
+            stdout = ""
+            stderr = str(e)
+            success = False
+            actual_agent = target
+            logger.error(f"All agents failed: {e}")
+
+        duration = (datetime.now() - start).total_seconds()
+
+        result = DelegationResult(
+            query=query,
+            orchestrator=orchestrator,
+            delegated_to=delegated_to,
+            rule=rule,
+            output=stdout,
+            error=stderr,
+            success=success,
+            duration=duration,
+        )
+
+        # Log result
+        if success:
+            delegation_logger.delegation_success(orchestrator, delegated_to, duration)
+        else:
+            delegation_logger.delegation_failure(orchestrator, delegated_to, stderr, duration)
+
+        if self.config.log_delegations:
+            self.history.append(result)
+
+        return result
+
+    def _estimate_task_complexity(self, query: str) -> str:
+        """
+        Estimate task complexity to determine if delegation overhead is worth it.
+
+        Returns:
+            "simple" | "medium" | "complex"
+
+        Simple tasks: Claude handles directly (delegation overhead > token savings)
+        Medium/Complex tasks: Delegate to specialized agents (token savings > overhead)
+        """
+        query_lower = query.lower()
+
+        # SIMPLE: Read-only operations and single-step deterministic commands
+        # These don't benefit from AI - just execute directly
+        simple_patterns = [
+            r"^git\s+status\s*$",
+            r"^git\s+log",
+            r"^git\s+show",
+            r"^git\s+diff\s+[\w\./\-]+\s*$",  # Single file diff
+            r"^git\s+branch\s*(-a|-r)?\s*$",
+            r"^git\s+remote",
+            r"^git\s+stash\s+(list|show)?\s*$",
+            r"^git\s+checkout\s+[\w\-/]+\s*$",  # Simple branch switch
+            r"^git\s+checkout\s+-b\s+[\w\-/]+\s*$",  # Create branch
+            r"^git\s+add\s+[\w\./\-]+\s*$",  # Add specific files
+            r"^git\s+pull\s*$",  # Simple pull (no conflicts mentioned)
+            r"^gh\s+pr\s+(view|list)",
+            r"^gh\s+issue\s+list",
+            r"^gh\s+repo\s+view",
+        ]
+
+        # COMPLEX: Multi-step workflows, content generation, safety-critical operations
+        # These have high token costs or need AI decision-making
+        complex_indicators = [
+            # Git operations requiring intelligence
+            "commit",  # Needs message generation
+            "create a commit",
+            "commit message",
+            "amend",
+            "rebase",
+            "cherry-pick",
+            "squash",
+            "merge conflict",
+            "resolve conflict",
+            "git history",
+            "clean up",
+            "--force",
+            "force push",
+            "force-with-lease",
+
+            # GitHub operations requiring content generation
+            "create pr",
+            "create pull request",
+            "pr create",
+            "pull request",
+            "create issue",
+            "issue create",
+            "pr review",
+            "review pr",
+            "create release",
+            "release create",
+
+            # Multi-step workflows
+            "create a pr for",
+            "commit and push",
+            "push my changes",
+            "stage and commit",
+        ]
+
+        # MEDIUM: Operations that might need error handling but aren't always complex
+        medium_indicators = [
+            "push -u",
+            "set-upstream",
+            "push origin",
+            "push --tags",
+            "merge",  # Might have conflicts
+            "revert",
+            "tag -a",
+            "checkout -b.*origin",  # Track remote branch
+        ]
+
+        # Check simple patterns first
+        for pattern in simple_patterns:
+            if re.match(pattern, query, re.IGNORECASE):
+                logger.debug(f"Complexity: SIMPLE (pattern match: {pattern})")
+                return "simple"
+
+        # Check complex indicators
+        for indicator in complex_indicators:
+            if indicator in query_lower:
+                logger.debug(f"Complexity: COMPLEX (indicator: {indicator})")
+                return "complex"
+
+        # Check medium indicators
+        for indicator in medium_indicators:
+            if indicator in query_lower:
+                logger.debug(f"Complexity: MEDIUM (indicator: {indicator})")
+                return "medium"
+
+        # Default: if query mentions git/github at all, it's medium
+        # Otherwise let task classification determine routing
+        if "git" in query_lower or "gh " in query_lower:
+            logger.debug("Complexity: MEDIUM (default git/gh command)")
+            return "medium"
+
+        # Not a git/github command - let normal routing decide
+        return "medium"
+
+    def _classify_task(self, query: str) -> tuple[str, int]:
+        """Classify task type and return recommended timeout."""
+        query_lower = query.lower()
+
+        keywords = {
+            "security_audit": ["security", "vulnerability", "audit", "cve", "exploit", "penetration"],
+            "vulnerability_scan": ["scan", "vulnerability", "vuln", "security issue"],
+            "code_review": ["review", "code quality", "best practice", "lint"],
+            "architecture": ["architecture", "design", "system design", "structure"],
+            "refactoring": ["refactor", "restructure", "clean up", "improve code"],
+            "quick_fix": ["fix", "bug", "error", "issue", "broken"],
+            "documentation": ["document", "docs", "readme", "guide", "explain"],
+            "testing": ["test", "unittest", "integration test", "e2e"],
+            "performance": ["performance", "optimize", "speed", "latency", "benchmark"],
+            "git_workflow": ["commit", "push", "rebase", "merge", "cherry-pick", "squash", "git history"],
+            "github_operations": ["pull request", "pr create", "pr review", "issue create", "release"],
+        }
+
+        # Timeout presets based on task complexity
+        TIMEOUT_PRESETS = {
+            "quick_fix": 60,           # 1 min - simple bug fixes
+            "refactoring": 300,        # 5 min - code refactoring
+            "security_audit": 600,     # 10 min - comprehensive security review
+            "code_review": 600,        # 10 min - full code review
+            "performance": 900,        # 15 min - profiling/optimization
+            "testing": 300,            # 5 min - test generation
+            "documentation": 180,      # 3 min - documentation writing
+            "architecture": 300,       # 5 min - design work
+            "vulnerability_scan": 300, # 5 min - automated scanning
+            "git_workflow": 180,       # 3 min - git operations
+            "github_operations": 240,  # 4 min - GitHub API operations
+            "general": 300,            # 5 min - default
+        }
+
+        for task_type, terms in keywords.items():
+            if any(term in query_lower for term in terms):
+                timeout = TIMEOUT_PRESETS.get(task_type, 300)
+                return task_type, timeout
+
+        return "general", 300
+
+    def _rank_by_capabilities(self, query: str) -> list[str]:
+        """Rank agents by capability scores for this query."""
+        task_type, _ = self._classify_task(query)  # Unpack tuple, ignore timeout
+
+        scores = []
+        for name, config in self.config.orchestrators.items():
+            if not config.enabled:
+                continue
+
+            # Get capability score for this task type
+            capability_score = getattr(config.capabilities, task_type, 0.5)
+
+            # Simple scoring: capability is primary factor
+            score = capability_score
+
+            scores.append((name, score))
+
+        # Sort by score descending
+        scores.sort(key=lambda x: x[1], reverse=True)
+
+        # Log ranking for transparency
+        if scores:
+            ranking_str = ", ".join([f"{name} ({score:.2f})" for name, score in scores[:3]])
+            logger.info(f"Task: {task_type} | Ranked: {ranking_str}")
+
+        # Return agent names in ranked order
+        return [name for name, _ in scores]
+
+    def _determine_delegation(
+        self,
+        query: str,
+        force_delegate: str | None,
+    ) -> tuple[str, DelegationRule | None]:
+        """
+        Determine which orchestrator should handle the query using capability-based routing.
+
+        Returns:
+            tuple: (target_orchestrator, matching_rule)
+        """
+        # Force delegation overrides everything
+        if force_delegate:
+            logger.info(f"Routing: FORCED → {force_delegate}")
+            return force_delegate, None
+
+        # Check task complexity first - simple tasks handled directly by Claude
+        complexity = self._estimate_task_complexity(query)
+        if complexity == "simple":
+            logger.info(f"Routing: SIMPLE task → claude (delegation overhead not worth it)")
+            return "claude", None
+
+        # Check explicit delegation rules
+        rule = self.config.find_delegation_rule(query)
+        if rule:
+            logger.info(f"Routing: {rule.pattern} → {rule.delegate_to} (rule-based)")
+            return rule.delegate_to, rule
+
+        # Use capability-based routing for medium/complex tasks
+        if self.config.routing_strategy in ["capability", "hybrid"]:
+            ranked = self._rank_by_capabilities(query)
+            if ranked:
+                task_type, _ = self._classify_task(query)  # Unpack tuple
+                # If top ranked agent is Claude, check if delegation is still worth it
+                if ranked[0] == "claude" and complexity == "medium":
+                    logger.info(f"Routing: {task_type} → claude (best match, medium complexity)")
+                    return "claude", None
+                logger.info(f"Routing: {task_type} [{complexity}] → {ranked[0]} (capability-based)")
+                return ranked[0], None
+
+        # Fallback to primary orchestrator
+        logger.info(f"Routing: DEFAULT → claude")
+        return "claude", None
+
+    def get_statistics(self) -> dict[str, Any]:
+        """Get delegation statistics."""
+        if not self.history:
+            return {"total": 0, "by_orchestrator": {}, "delegations": 0}
+
+        by_orchestrator: dict[str, int] = {}
+        delegations = 0
+
+        for result in self.history:
+            target = result.delegated_to or result.orchestrator
+            by_orchestrator[target] = by_orchestrator.get(target, 0) + 1
+            if result.delegated_to:
+                delegations += 1
+
+        return {
+            "total": len(self.history),
+            "by_orchestrator": by_orchestrator,
+            "delegations": delegations,
+            "delegation_rate": delegations / len(self.history) * 100,
+            "success_rate": sum(r.success for r in self.history) / len(self.history) * 100,
+            "avg_duration": sum(r.duration for r in self.history) / len(self.history),
+        }
+
+    def clear_history(self) -> None:
+        """Clear delegation history."""
+        self.history.clear()

src/delegation_mcp/gradio_monitor.py

@@ -0,0 +1,329 @@
+"""
+Minimal Gradio monitor for demo videos.
+
+This is NOT a chat interface - it's a live activity monitor that shows
+delegation events happening when Claude Code (or other MCP clients) call
+the delegation MCP server.
+
+Purpose: Makes demo videos visually compelling by showing real-time delegation activity.
+"""
+
+try:
+    import gradio as gr
+    GRADIO_AVAILABLE = True
+except ImportError:
+    GRADIO_AVAILABLE = False
+    # Mock gr for type hinting if needed, or just handle availability check
+    gr = None  # type: ignore
+
+from pathlib import Path
+from datetime import datetime
+from collections import deque
+
+# from .persistence import PersistenceManager
+
+
+class DelegationMonitor:
+    """Monitors delegation activity for demo visualization."""
+
+    def __init__(self, db_path: Path = Path("data/delegation.db")):
+        # self.persistence = PersistenceManager(db_path)
+        self.recent_events = deque(maxlen=20)  # Keep last 20 events
+
+    def get_recent_activity(self):
+        """Get recent delegation events for display."""
+        return []
+        # try:
+        #     history = self.persistence.get_task_history(limit=20)
+        #     return [
+        #         [
+        #             entry.timestamp.strftime("%H:%M:%S"),
+        #             entry.orchestrator,
+        #             entry.delegated_to or "N/A",
+        #             "✅" if entry.success else "❌",
+        #             f"{entry.duration:.2f}s"
+        #         ]
+        #         for entry in history
+        #     ]
+        # except Exception:
+        #     return []
+
+    def get_statistics(self):
+        """Get delegation statistics for charts."""
+        return {"total": 0, "success_rate": 0.0, "avg_duration": 0.0, "agent_usage": {}}
+        # try:
+        #     stats = self.persistence.get_statistics()
+        #     return {
+        #         "total": stats.get("total_tasks", 0),
+        #         "success_rate": stats.get("success_rate", 0.0),
+        #         "avg_duration": stats.get("avg_duration", 0.0),
+        #         "agent_usage": stats.get("agent_usage", {}),
+        #     }
+        # except Exception:
+        #     return {"total": 0, "success_rate": 0.0, "avg_duration": 0.0, "agent_usage": {}}
+
+
+def create_monitor_ui(demo_server=None):
+    """Create minimal monitoring UI for demo videos (< 150 lines)."""
+    if not GRADIO_AVAILABLE:
+        print("Error: Gradio is not installed. Please install with `pip install .[ui]`")
+        return None
+
+    monitor = DelegationMonitor()
+
+    with gr.Blocks(title="Delegation MCP Monitor") as app:
+        gr.Markdown("""
+        # 🚀 Delegation MCP - Interactive Demo
+
+        **Test the intelligent routing system!** Enter a query below to see which agent
+        the MCP would route it to. Adjust settings to see how configuration affects routing.
+
+        ---
+        """)
+
+        # Configuration Section
+        with gr.Accordion("⚙️ Task Routing Configuration (Just like install.py!)", open=False):
+            gr.Markdown("### Assign Agents to Task Categories")
+            gr.Markdown("*Configure which agent handles each type of task - same options as install.py*")
+
+            with gr.Row():
+                with gr.Column():
+                    security_agent = gr.Radio(["gemini", "claude", "aider"], value="gemini", label="🔒 Security Audits")
+                    architecture_agent = gr.Radio(["claude", "gemini", "aider"], value="claude", label="🏗️ Architecture Design")
+                    refactoring_agent = gr.Radio(["aider", "claude", "gemini"], value="aider", label="🔧 Refactoring")
+                    quick_fix_agent = gr.Radio(["aider", "claude", "gemini"], value="aider", label="⚡ Quick Fixes")
+
+                with gr.Column():
+                    code_review_agent = gr.Radio(["claude", "gemini", "aider"], value="claude", label="👀 Code Review")
+                    performance_agent = gr.Radio(["gemini", "claude", "aider"], value="gemini", label="🚀 Performance")
+                    testing_agent = gr.Radio(["claude", "gemini", "aider"], value="claude", label="🧪 Testing")
+                    git_agent = gr.Radio(["aider", "claude", "gemini"], value="aider", label="📦 Git Operations")
+
+            gr.Markdown("""
+            **Try it:** Change "Security Audits" from Gemini to Claude, then test a security query!
+            **Note:** These are the "Balanced" preset defaults - experiment with different combinations!
+            """)
+
+        # Interactive Query Tester
+        with gr.Row():
+            with gr.Column():
+                gr.Markdown("### 🧪 Test Routing Intelligence")
+                query_input = gr.Textbox(
+                    label="Enter your query",
+                    placeholder="e.g., 'Scan my code for SQL injection vulnerabilities'",
+                    lines=3
+                )
+
+                submit_btn = gr.Button("🔍 Get Routing Decision", variant="primary", size="lg")
+
+                # Example queries
+                with gr.Accordion("💡 Example Queries", open=True):
+                    gr.Markdown("**Simple Tasks:**")
+                    gr.Examples(
+                        examples=[
+                            ["Scan this codebase for security vulnerabilities"],
+                            ["Fix the bug causing tests to fail"],
+                            ["Create a pull request with my changes"],
+                        ],
+                        inputs=query_input,
+                    )
+
+                    gr.Markdown("**Multi-Agent Workflows:**")
+                    gr.Examples(
+                        examples=[
+                            ["Scan the codebase for frontend optimization improvements. Generate a report and fix the critical issues. Commit, push, deploy to preview, and test improvements with browser automation"],
+                            ["Audit the authentication system for SQL injection and XSS. Create detailed security report with CVE references. Fix all critical vulnerabilities and update tests"],
+                            ["Analyze API performance bottlenecks using profiling. Optimize database queries and add caching. Generate benchmark report comparing before/after metrics"],
+                            ["Review the entire codebase for code quality issues. Refactor problem areas with proper error handling. Update documentation and create comprehensive test suite"],
+                            ["Design microservices architecture for user management. Implement the service with authentication. Set up CI/CD pipeline and deploy to staging with monitoring"],
+                        ],
+                        inputs=query_input,
+                    )
+
+            with gr.Column():
+                gr.Markdown("### 📊 Routing Decision")
+                decision_output = gr.Textbox(
+                    label="Decision",
+                    lines=2,
+                    interactive=False
+                )
+                task_type_output = gr.Textbox(
+                    label="Task Classification",
+                    lines=1,
+                    interactive=False
+                )
+                complexity_output = gr.Textbox(
+                    label="Complexity Assessment",
+                    lines=1,
+                    interactive=False
+                )
+                reasoning_output = gr.Textbox(
+                    label="Routing Reasoning",
+                    lines=4,
+                    interactive=False
+                )
+                cli_command_output = gr.Textbox(
+                    label="CLI Command (if delegated)",
+                    lines=2,
+                    interactive=False
+                )
+
+        async def test_routing(query, sec_agent, arch_agent, refactor_agent, fix_agent,
+                              review_agent, perf_agent, test_agent, git_agent):
+            """Test routing for a query without executing."""
+            if not query.strip():
+                return "Please enter a query", "", "", "", ""
+
+            if not demo_server:
+                return "❌ Server not initialized", "", "", "", ""
+
+            try:
+                # Map task categories to selected agents
+                task_agent_map = {
+                    "security_audit": sec_agent,
+                    "vulnerability_scan": sec_agent,
+                    "architecture": arch_agent,
+                    "refactoring": refactor_agent,
+                    "quick_fix": fix_agent,
+                    "code_review": review_agent,
+                    "performance": perf_agent,
+                    "testing": test_agent,
+                    "git_workflow": git_agent,
+                    "github_operations": git_agent,
+                }
+
+                # Temporarily update routing rules based on user selection
+                from delegation_mcp.config import DelegationRule
+                demo_server.config.rules.clear()
+
+                # Add rules for each task category
+                for task_type, agent in task_agent_map.items():
+                    rule = DelegationRule(
+                        delegate_to=agent,
+                        pattern=task_type,
+                        description=f"User configured: {task_type} → {agent}",
+                        priority=10
+                    )
+                    demo_server.config.rules.append(rule)
+
+                # Get routing guidance
+                result = await demo_server.engine.process(
+                    query,
+                    guidance_only=True
+                )
+
+                # Classify task type and complexity
+                task_type, timeout = demo_server.engine._classify_task(query)
+                complexity = demo_server.engine._estimate_task_complexity(query)
+
+                # Determine delegation and get reasoning
+                target, rule = demo_server.engine._determine_delegation(query, None)
+
+                # Build reasoning explanation
+                reasoning_parts = []
+
+                # Complexity assessment
+                reasoning_parts.append(f"📏 Complexity: {complexity.upper()}")
+
+                # Task type detection
+                query_lower = query.lower()
+                keywords = {
+                    "security_audit": ["security", "vulnerability", "audit", "cve"],
+                    "architecture": ["architecture", "design", "system design"],
+                    "refactoring": ["refactor", "restructure", "clean up"],
+                    "quick_fix": ["fix", "bug", "error"],
+                    "performance": ["performance", "optimize", "speed"],
+                    "code_review": ["review", "code quality", "best practice"],
+                }
+                detected_keywords = []
+                for task, kws in keywords.items():
+                    if task == task_type:
+                        detected_keywords = [kw for kw in kws if kw in query_lower]
+                        break
+
+                if detected_keywords:
+                    reasoning_parts.append(f"🔍 Keywords: {', '.join(detected_keywords[:3])}")
+
+                # Routing strategy
+                if rule:
+                    if "User configured" in rule.description:
+                        reasoning_parts.append(f"⚙️ User Configuration: {task_type} → {result.delegated_to or 'claude'}")
+                    else:
+                        reasoning_parts.append(f"📋 Matched Rule: {rule.pattern}")
+                elif complexity == "simple":
+                    reasoning_parts.append("⚡ Simple task - no delegation overhead needed")
+                else:
+                    reasoning_parts.append(f"🎯 Capability-based routing for {task_type}")
+
+                reasoning = "\n".join(reasoning_parts)
+
+                # Format decision
+                if result.delegated_to:
+                    decision = f"✅ DELEGATE TO: {result.delegated_to.upper()}"
+                    cli_cmd = f'{result.delegated_to} "{query}"'
+                else:
+                    decision = "✅ HANDLE DIRECTLY (Claude)"
+                    cli_cmd = "N/A - Claude handles internally"
+
+                task_info = f"{task_type.replace('_', ' ').title()}"
+                complexity_info = f"{complexity.title()} (timeout: {timeout}s)"
+
+                return decision, task_info, complexity_info, reasoning, cli_cmd
+
+            except Exception as e:
+                return f"❌ Error: {str(e)}", "", "", "", ""
+
+        submit_btn.click(
+            fn=test_routing,
+            inputs=[
+                query_input,
+                security_agent, architecture_agent, refactoring_agent, quick_fix_agent,
+                code_review_agent, performance_agent, testing_agent, git_agent
+            ],
+            outputs=[decision_output, task_type_output, complexity_output, reasoning_output, cli_command_output]
+        )
+
+        gr.Markdown("---")
+
+        gr.Markdown("""
+        ## 🚀 Want to Test the Full System?
+
+        This demo shows the **routing intelligence** only. To see actual task delegation with AI agents:
+
+        ### Option 1: Duplicate This Space
+        1. Click the **⋮** menu (top right) → **Duplicate Space**
+        2. Add your API keys in **Settings → Secrets**:
+           - `ANTHROPIC_API_KEY` - For Claude
+           - `GOOGLE_API_KEY` - For Gemini
+        3. Install agent CLIs in your duplicated Space (optional for full functionality)
+
+        ### Option 2: Install Locally
+        ```bash
+        git clone https://github.com/carlosduplar/multi-agent-mcp.git
+        cd multi-agent-mcp
+        pip install -e .
+        python install.py
+        ```
+
+        Then configure Claude Code to use the MCP server and start delegating tasks!
+
+        ---
+
+        ### 📚 Learn More
+        - **GitHub**: [carlosduplar/multi-agent-mcp](https://github.com/carlosduplar/multi-agent-mcp)
+        - **Documentation**: Full setup guide in README
+        - **MCP Hackathon**: Built for MCP 1st Birthday (Winter 2025)
+        """)
+
+    return app
+
+
+def main():
+    """Launch monitor UI."""
+    app = create_monitor_ui()
+    if app:
+        app.launch(server_name="0.0.0.0", server_port=7860, share=False)
+
+
+if __name__ == "__main__":
+    main()

src/delegation_mcp/installer/__init__.py

@@ -0,0 +1,5 @@
+"""Automated installer for delegation-mcp."""
+
+from .installer import DelegationInstaller, main
+
+__all__ = ["DelegationInstaller", "main"]

src/delegation_mcp/installer/agent_profiles.py

@@ -0,0 +1,312 @@
+"""Agent capability profiles and routing presets.
+
+This module defines factual capability profiles for known agents and
+routing presets for different delegation strategies.
+"""
+
+from typing import TypedDict, Literal, Any
+
+
+class AgentAttributes(TypedDict):
+    """Factual attributes for an agent."""
+    cost_tier: Literal["free", "subscription", "pay-per-token"]
+    deployment: Literal["local", "cloud"]
+    context_window: int  # approximate tokens
+    has_git_integration: bool
+    has_browser_tools: bool
+    response_speed: Literal["fast", "medium", "slow"]
+    primary_strength: str
+    description: str
+    capabilities: dict[str, float]
+
+
+# Default profile for unknown agents
+DEFAULT_ATTRIBUTES: AgentAttributes = {
+    "cost_tier": "pay-per-token",
+    "deployment": "cloud",
+    "context_window": 8192,
+    "has_git_integration": False,
+    "has_browser_tools": False,
+    "response_speed": "medium",
+    "primary_strength": "general",
+    "description": "General purpose agent",
+    "capabilities": {
+        "security_audit": 0.5,
+        "vulnerability_scan": 0.5,
+        "code_review": 0.5,
+        "architecture": 0.5,
+        "refactoring": 0.5,
+        "quick_fix": 0.5,
+        "documentation": 0.5,
+        "testing": 0.5,
+        "performance": 0.5,
+        "git_workflow": 0.5,
+        "github_operations": 0.5,
+        "general": 0.5,
+    },
+}
+
+# Factual profiles for known agents
+AGENT_PROFILES: dict[str, AgentAttributes] = {
+    "claude": {
+        "cost_tier": "pay-per-token",
+        "deployment": "cloud",
+        "context_window": 200000,
+        "has_git_integration": False,
+        "has_browser_tools": False,
+        "response_speed": "medium",
+        "primary_strength": "complex reasoning",
+        "description": "Best for complex reasoning, architecture, and code review",
+        "capabilities": {
+            "security_audit": 0.8,
+            "vulnerability_scan": 0.7,
+            "code_review": 0.9,
+            "architecture": 0.9,
+            "refactoring": 0.8,
+            "quick_fix": 0.7,
+            "documentation": 0.9,
+            "testing": 0.8,
+            "performance": 0.7,
+            "git_workflow": 0.1,
+            "github_operations": 0.1,
+            "general": 0.9,
+        },
+    },
+    "gemini": {
+        "cost_tier": "pay-per-token",
+        "deployment": "cloud",
+        "context_window": 1000000,
+        "has_git_integration": False,
+        "has_browser_tools": True,
+        "response_speed": "medium",
+        "primary_strength": "security & performance",
+        "description": "Strong security analysis, performance optimization, and browser tools",
+        "capabilities": {
+            "security_audit": 0.9,
+            "vulnerability_scan": 0.9,
+            "code_review": 0.8,
+            "architecture": 0.8,
+            "refactoring": 0.7,
+            "quick_fix": 0.7,
+            "documentation": 0.8,
+            "testing": 0.8,
+            "performance": 0.9,
+            "git_workflow": 0.1,
+            "github_operations": 0.1,
+            "general": 0.8,
+        },
+    },
+    "aider": {
+        "cost_tier": "free",  # The tool itself is free, uses BYO keys or local models
+        "deployment": "local",
+        "context_window": 32000, # Depends on model, but tool manages context
+        "has_git_integration": True,
+        "has_browser_tools": False,
+        "response_speed": "fast",
+        "primary_strength": "git & refactoring",
+        "description": "Excellent for rapid code editing, refactoring, and git operations",
+        "capabilities": {
+            "security_audit": 0.4,
+            "vulnerability_scan": 0.4,
+            "code_review": 0.7,
+            "architecture": 0.6,
+            "refactoring": 0.9,
+            "quick_fix": 0.9,
+            "documentation": 0.6,
+            "testing": 0.7,
+            "performance": 0.5,
+            "git_workflow": 0.9,
+            "github_operations": 0.8,
+            "general": 0.7,
+        },
+    },
+    "copilot": {
+        "cost_tier": "subscription",
+        "deployment": "cloud",
+        "context_window": 32000,
+        "has_git_integration": False,
+        "has_browser_tools": False,
+        "response_speed": "fast",
+        "primary_strength": "quick fixes",
+        "description": "Balanced capabilities with strong quick fixes and testing",
+        "capabilities": {
+            "security_audit": 0.5,
+            "vulnerability_scan": 0.5,
+            "code_review": 0.7,
+            "architecture": 0.6,
+            "refactoring": 0.8,
+            "quick_fix": 0.9,
+            "documentation": 0.7,
+            "testing": 0.9,
+            "performance": 0.6,
+            "git_workflow": 0.3,
+            "github_operations": 0.3,
+            "general": 0.7,
+        },
+    },
+    "qwen": {
+        "cost_tier": "free", # Usually run locally
+        "deployment": "local",
+        "context_window": 32000,
+        "has_git_integration": False,
+        "has_browser_tools": False,
+        "response_speed": "medium",
+        "primary_strength": "code review",
+        "description": "Code-focused with strong review and architecture capabilities",
+        "capabilities": {
+            "security_audit": 0.6,
+            "vulnerability_scan": 0.6,
+            "code_review": 0.8,
+            "architecture": 0.7,
+            "refactoring": 0.7,
+            "quick_fix": 0.7,
+            "documentation": 0.6,
+            "testing": 0.7,
+            "performance": 0.6,
+            "git_workflow": 0.2,
+            "github_operations": 0.2,
+            "general": 0.7,
+        },
+    },
+}
+
+
+class RoutingPreset(TypedDict):
+    """Configuration for a routing strategy."""
+    name: str
+    description: str
+    strategy_description: str
+    cost_priority: Literal["low", "medium", "high"]
+    quality_priority: Literal["low", "medium", "high"]
+
+
+ROUTING_PRESETS: dict[str, RoutingPreset] = {
+    "best_in_class": {
+        "name": "Best in Class",
+        "description": "Highest quality, cost is secondary",
+        "strategy_description": "Prefer Claude for architecture/review, Gemini for security, Aider for git",
+        "cost_priority": "low",
+        "quality_priority": "high",
+    },
+    "cost_optimized": {
+        "name": "Cost Optimized",
+        "description": "Minimize API costs, prefer local",
+        "strategy_description": "Prefer local models and Aider, use cloud agents only when necessary",
+        "cost_priority": "high",
+        "quality_priority": "medium",
+    },
+    "token_saver": {
+        "name": "Token Saver",
+        "description": "Minimize token usage",
+        "strategy_description": "Use agents with large context windows, prefer concise responders",
+        "cost_priority": "high",
+        "quality_priority": "medium",
+    },
+    "speed_first": {
+        "name": "Speed First",
+        "description": "Fastest iteration, good for dev",
+        "strategy_description": "Prefer faster models like Aider and quick cloud APIs",
+        "cost_priority": "low",
+        "quality_priority": "medium",
+    },
+    "specialized": {
+        "name": "Specialized Routing",
+        "description": "Match tasks to native capabilities",
+        "strategy_description": "Match tasks to agents with native tool support (e.g. Browser -> Gemini)",
+        "cost_priority": "medium",
+        "quality_priority": "high",
+    },
+    "balanced": {
+        "name": "Balanced (Recommended)",
+        "description": "Good mix of quality, speed, cost",
+        "strategy_description": "Distribute work sensibly across all available agents",
+        "cost_priority": "medium",
+        "quality_priority": "medium",
+    },
+}
+
+
+class RoutingRule(TypedDict):
+    """Rule for routing a specific task category."""
+    preferred: list[str]
+    reason: str
+
+
+# Default routing rules for "Best in Class" / "Balanced" baseline
+# These are modified by the strategy logic in task_mapper.py
+DEFAULT_ROUTING_RULES: dict[str, RoutingRule] = {
+    "architecture": {
+        "preferred": ["claude"],
+        "reason": "Marketed for complex reasoning",
+    },
+    "code_review": {
+        "preferred": ["claude", "qwen"],
+        "reason": "Strong reasoning capabilities",
+    },
+    "security_audit": {
+        "preferred": ["gemini"],
+        "reason": "Strong security analysis capabilities",
+    },
+    "refactoring": {
+        "preferred": ["aider"],
+        "reason": "Optimized for code editing",
+    },
+    "quick_fix": {
+        "preferred": ["aider", "copilot"],
+        "reason": "Optimized for speed and small edits",
+    },
+    "documentation": {
+        "preferred": ["claude"],
+        "reason": "Strong long-form writing capabilities",
+    },
+    "testing": {
+        "preferred": ["copilot", "claude"],
+        "reason": "Balanced testing capabilities",
+    },
+    "performance": {
+        "preferred": ["gemini"],
+        "reason": "Strong analytical capabilities",
+    },
+    "browser_interaction": {
+        "preferred": ["gemini"],
+        "reason": "Has browser automation tools",
+    },
+    "git_operations": {
+        "preferred": ["aider"],
+        "reason": "Native git integration",
+    },
+    "shell_tasks": {
+        "preferred": ["aider"],
+        "reason": "Strong command line capabilities",
+    },
+    "exploration": {
+        "preferred": ["claude"],
+        "reason": "Large context window for codebase understanding",
+    },
+    "debugging": {
+        "preferred": ["claude"],
+        "reason": "Complex reasoning for root cause analysis",
+    },
+    "impact_analysis": {
+        "preferred": ["claude"],
+        "reason": "Complex reasoning for dependency analysis",
+    },
+    "general": {
+        "preferred": ["claude"],
+        "reason": "General purpose reasoning",
+    },
+}
+
+
+def get_agent_profile(agent_name: str) -> AgentAttributes:
+    """
+    Get factual profile for an agent.
+    
+    Args:
+        agent_name: Name of the agent (case-insensitive)
+        
+    Returns:
+        AgentAttributes with factual metadata
+    """
+    agent_key = agent_name.lower().strip()
+    return AGENT_PROFILES.get(agent_key, DEFAULT_ATTRIBUTES)

src/delegation_mcp/installer/agent_selector.py

@@ -0,0 +1,164 @@
+"""Interactive agent selection UI for installation.
+
+This module provides an interactive interface for users to select
+which agents they want to enable for delegation.
+"""
+
+import logging
+from pathlib import Path
+
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+from rich.table import Table
+
+from ..agent_discovery import AgentMetadata
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+class AgentSelector:
+    """Manages interactive agent selection during installation."""
+
+    def __init__(self):
+        """Initialize the agent selector."""
+        self.selected_agents: list[str] = []
+
+    def display_agents(self, discovered_agents: dict[str, AgentMetadata]) -> None:
+        """
+        Display discovered agents in a formatted table.
+        
+        Args:
+            discovered_agents: Dictionary of agent name to metadata
+        """
+        if not discovered_agents:
+            console.print("\n[yellow]No agents discovered.[/yellow]")
+            return
+
+        table = Table(title="Discovered Agents", show_header=True, header_style="bold magenta")
+        table.add_column("Agent", style="cyan", no_wrap=True)
+        table.add_column("Version", style="green")
+        table.add_column("Path", style="blue")
+        table.add_column("Attributes", style="yellow")
+
+        for name, metadata in discovered_agents.items():
+            # Get brief capabilities summary
+            attributes = self._get_attributes_summary(name)
+            version = metadata.version or "unknown"
+            path = str(metadata.path) if metadata.path else "system PATH"
+            
+            table.add_row(name, version, path, attributes)
+
+        console.print("\n")
+        console.print(table)
+        console.print("\n")
+
+    def _get_attributes_summary(self, agent_name: str) -> str:
+        """
+        Get a brief summary of agent attributes.
+        
+        Args:
+            agent_name: Name of the agent
+            
+        Returns:
+            Brief attributes description
+        """
+        from .agent_profiles import get_agent_profile
+
+        profile = get_agent_profile(agent_name)
+        
+        parts = []
+        parts.append(profile["primary_strength"])
+        
+        if profile["has_git_integration"]:
+            parts.append("git")
+        if profile["has_browser_tools"]:
+            parts.append("browser")
+            
+        return ", ".join(parts)
+
+    def prompt_selection(self, discovered_agents: dict[str, AgentMetadata]) -> list[str]:
+        """
+        Interactive prompt for agent selection.
+        
+        Args:
+            discovered_agents: Dictionary of agent name to metadata
+            
+        Returns:
+            List of selected agent names
+        """
+        if not discovered_agents:
+            return []
+
+        self.display_agents(discovered_agents)
+
+        console.print("[bold]Agent Selection[/bold]")
+        console.print("You can enable/disable individual agents or use all discovered agents.\n")
+
+        # Ask if user wants to customize selection
+        use_all = Confirm.ask(
+            "Enable all discovered agents?",
+            default=True
+        )
+
+        if use_all:
+            self.selected_agents = list(discovered_agents.keys())
+            console.print(f"\n[green]✓[/green] Selected all {len(self.selected_agents)} agents\n")
+            return self.selected_agents
+
+        # Custom selection
+        console.print("\nSelect agents to enable (you'll be prompted for each agent):\n")
+        self.selected_agents = []
+
+        for name, metadata in discovered_agents.items():
+            from .agent_profiles import get_agent_profile
+            
+            profile = get_agent_profile(name)
+            description = profile["description"]
+            
+            console.print(f"\n[cyan]{name}[/cyan]: {description}")
+            
+            # Auto-enable Claude
+            if name.lower() == "claude":
+                self.selected_agents.append(name)
+                console.print(f"  [green]✓[/green] Enabled (Required for orchestration)")
+                continue
+
+            enable = Confirm.ask(f"  Enable {name}?", default=True)
+            
+            if enable:
+                self.selected_agents.append(name)
+                console.print(f"  [green]✓[/green] Enabled")
+            else:
+                console.print(f"  [dim]✗[/dim] Disabled")
+
+        console.print(f"\n[green]✓[/green] Selected {len(self.selected_agents)} agents: {', '.join(self.selected_agents)}\n")
+        return self.selected_agents
+
+    def get_selected_agents(self) -> list[str]:
+        """
+        Get the list of selected agents.
+        
+        Returns:
+            List of selected agent names
+        """
+        return self.selected_agents
+
+    def validate_selection(self, selected_agents: list[str]) -> tuple[bool, str]:
+        """
+        Validate that the selection meets requirements.
+        
+        Args:
+            selected_agents: List of selected agent names
+            
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if len(selected_agents) < 2:
+            return False, (
+                f"At least 2 agents are required for delegation, but only "
+                f"{len(selected_agents)} {'is' if len(selected_agents) == 1 else 'are'} selected. "
+                f"Please enable more agents."
+            )
+        
+        return True, ""

src/delegation_mcp/installer/config_generator.py

@@ -0,0 +1,324 @@
+"""Configuration file generator for orchestrators and delegation rules.
+
+This module generates YAML configuration files based on user selections
+during installation.
+"""
+
+import logging
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+from rich.console import Console
+from rich.prompt import Confirm
+
+from ..agent_discovery import AgentMetadata
+from .agent_profiles import get_agent_profile
+from .task_mapper import TASK_CATEGORIES
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+class ConfigGenerator:
+    """Generates configuration files based on user selections."""
+
+    def __init__(self):
+        """Initialize the config generator."""
+        self.orchestrators_config: dict[str, Any] = {}
+        self.delegation_config: dict[str, Any] = {}
+
+    def check_existing_configs(self, project_dir: Path) -> bool:
+        """
+        Check if configuration files already exist.
+        
+        Args:
+            project_dir: Project directory path
+            
+        Returns:
+            True if configs exist, False otherwise
+        """
+        config_dir = project_dir / "config"
+        orchestrators_file = config_dir / "orchestrators.yaml"
+        delegation_file = config_dir / "delegation_rules.yaml"
+
+        return orchestrators_file.exists() or delegation_file.exists()
+
+    def prompt_existing_configs(self, project_dir: Path) -> str:
+        """
+        Prompt user for how to handle existing configs.
+        
+        Args:
+            project_dir: Project directory path
+            
+        Returns:
+            User choice: "overwrite", "backup", or "skip"
+        """
+        console.print("\n[yellow]⚠ Existing configuration detected[/yellow]")
+        console.print("\nConfiguration files already exist in this project.")
+        console.print("You can:")
+        console.print("  [cyan]O[/cyan]verwrite - Replace existing files with new configuration")
+        console.print("  [cyan]B[/cyan]ackup   - Backup existing files and create new ones")
+        console.print("  [cyan]S[/cyan]kip     - Keep existing files unchanged\n")
+
+        choice = ""
+        while choice not in ["o", "b", "s"]:
+            choice = input("Choose an option (O/B/S): ").lower().strip()
+
+        choice_map = {"o": "overwrite", "b": "backup", "s": "skip"}
+        return choice_map[choice]
+
+    def backup_existing_configs(self, project_dir: Path) -> None:
+        """
+        Backup existing configuration files.
+        
+        Args:
+            project_dir: Project directory path
+        """
+        config_dir = project_dir / "config"
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+        files_to_backup = [
+            "orchestrators.yaml",
+            "delegation_rules.yaml",
+        ]
+
+        for filename in files_to_backup:
+            source = config_dir / filename
+            if source.exists():
+                backup_name = f"{source.stem}.backup_{timestamp}{source.suffix}"
+                backup_path = config_dir / backup_name
+                shutil.copy2(source, backup_path)
+                console.print(f"[green]✓[/green] Backed up {filename} to {backup_name}")
+
+    def generate_orchestrators_yaml(
+        self,
+        selected_agents: list[str],
+        agent_metadata: dict[str, AgentMetadata],
+    ) -> dict[str, Any]:
+        """
+        Generate orchestrators.yaml configuration.
+        
+        Args:
+            selected_agents: List of selected agent names
+            agent_metadata: Dictionary of agent name to metadata
+            
+        Returns:
+            Orchestrators configuration dictionary
+        """
+        config: dict[str, Any] = {"orchestrators": {}}
+
+        for agent_name in selected_agents:
+            metadata = agent_metadata.get(agent_name)
+            if not metadata:
+                continue
+
+            # Get command and args from metadata
+            # command can be a string or list[str]
+            if isinstance(metadata.command, list):
+                command = metadata.command[0] if metadata.command else agent_name
+                args = metadata.command[1:] if len(metadata.command) > 1 else []
+            else:
+                command = metadata.command or agent_name
+                args = []
+
+            # Build orchestrator config
+            orch_config: dict[str, Any] = {
+                "name": agent_name,
+                "command": command,
+                "args": args,
+                "enabled": True,
+                "env": {},
+                "timeout": 300,
+                "max_retries": 3,
+            }
+
+            config["orchestrators"][agent_name] = orch_config
+
+        self.orchestrators_config = config
+        return config
+
+    def generate_delegation_rules_yaml(
+        self,
+        selected_agents: list[str],
+        task_mappings: dict[str, str],
+        agent_metadata: dict[str, AgentMetadata],
+        primary_orchestrator: str,
+    ) -> dict[str, Any]:
+        """
+        Generate delegation_rules.yaml configuration.
+        
+        Args:
+            selected_agents: List of selected agent names
+            task_mappings: Dictionary of task_key -> agent_name
+            agent_metadata: Dictionary of agent name to metadata
+            primary_orchestrator: Name of primary orchestrator
+            
+        Returns:
+            Delegation rules configuration dictionary
+        """
+        config: dict[str, Any] = {
+            "orchestrator": primary_orchestrator,
+            "routing_strategy": "hybrid",
+            "orchestrators": {},
+            "rules": [],
+        }
+
+        # Build orchestrators section with capabilities
+        for agent_name in selected_agents:
+            metadata = agent_metadata.get(agent_name)
+            if not metadata:
+                continue
+
+            profile = get_agent_profile(agent_name)
+            capabilities = profile["capabilities"]
+
+            # Get command and args from metadata
+            # command can be a string or list[str]
+            if isinstance(metadata.command, list):
+                command = metadata.command[0] if metadata.command else agent_name
+                args = metadata.command[1:] if len(metadata.command) > 1 else []
+            else:
+                command = metadata.command or agent_name
+                args = []
+
+            orch_config: dict[str, Any] = {
+                "name": agent_name,
+                "command": command,
+                "args": args,
+                "enabled": True,
+                "env": {},
+                "timeout": 300,
+                "max_retries": 3,
+                "cost_per_1k_tokens": 0.001,
+                "capabilities": dict(capabilities),
+            }
+
+            config["orchestrators"][agent_name] = orch_config
+
+        # Build delegation rules from task mappings
+        # Create task key to category mapping
+        category_map = {cat["key"]: cat for cat in TASK_CATEGORIES}
+
+        priority = 10  # Start with high priority
+        for task_key, agent_name in task_mappings.items():
+            category = category_map.get(task_key)
+            if not category:
+                continue
+
+            # Build pattern from examples
+            pattern_parts = category["pattern_examples"]
+            pattern = "|".join(pattern_parts)
+
+            rule: dict[str, Any] = {
+                "delegate_to": agent_name,
+                "description": category["description"],
+                "pattern": pattern,
+                "priority": max(1, priority),
+                "requires_approval": False,
+            }
+
+            config["rules"].append(rule)
+            priority -= 1  # Decrease priority for next rule
+
+        # Add fallback rule (general tasks)
+        if "general" not in task_mappings:
+            # Use primary orchestrator as fallback
+            fallback_agent = primary_orchestrator
+        else:
+            fallback_agent = task_mappings["general"]
+
+        fallback_rule: dict[str, Any] = {
+            "delegate_to": fallback_agent,
+            "description": "General queries and fallback",
+            "pattern": ".*",
+            "priority": 1,
+            "requires_approval": False,
+        }
+        config["rules"].append(fallback_rule)
+
+        self.delegation_config = config
+        return config
+
+    def save_configs(self, project_dir: Path) -> None:
+        """
+        Save configuration files to disk.
+        
+        Args:
+            project_dir: Project directory path
+        """
+        config_dir = project_dir / "config"
+        config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Save orchestrators.yaml
+        orchestrators_file = config_dir / "orchestrators.yaml"
+        with open(orchestrators_file, "w", encoding="utf-8") as f:
+            yaml.dump(
+                self.orchestrators_config,
+                f,
+                default_flow_style=False,
+                sort_keys=False,
+            )
+        console.print(f"[green]✓[/green] Generated {orchestrators_file}")
+
+        # Save delegation_rules.yaml
+        delegation_file = config_dir / "delegation_rules.yaml"
+        with open(delegation_file, "w", encoding="utf-8") as f:
+            # Add header comment
+            f.write("# Delegation MCP Configuration\n")
+            f.write("# Auto-generated based on user selections\n\n")
+            yaml.dump(
+                self.delegation_config,
+                f,
+                default_flow_style=False,
+                sort_keys=False,
+            )
+        console.print(f"[green]✓[/green] Generated {delegation_file}")
+
+    def generate_configs(
+        self,
+        selected_agents: list[str],
+        task_mappings: dict[str, str],
+        agent_metadata: dict[str, AgentMetadata],
+        primary_orchestrator: str,
+        project_dir: Path,
+        scope: str = "local",
+    ) -> None:
+        """
+        Complete configuration generation flow.
+        
+        Args:
+            selected_agents: List of selected agent names
+            task_mappings: Dictionary of task_key -> agent_name
+            agent_metadata: Dictionary of agent name to metadata
+            primary_orchestrator: Name of primary orchestrator
+            project_dir: Project directory path
+            scope: Installation scope - "local" for project-level, "user" for user-level
+        """
+        # Determine config directory based on scope
+        if scope == "user":
+            config_base_dir = Path.home() / ".delegation-mcp"
+        else:
+            config_base_dir = project_dir
+        
+        # Check for existing configs
+        if self.check_existing_configs(config_base_dir):
+            choice = self.prompt_existing_configs(config_base_dir)
+
+            if choice == "skip":
+                console.print("\n[yellow]⚠[/yellow] Keeping existing configuration files\n")
+                return
+            elif choice == "backup":
+                self.backup_existing_configs(config_base_dir)
+
+        # Generate configurations
+        self.generate_orchestrators_yaml(selected_agents, agent_metadata)
+        self.generate_delegation_rules_yaml(
+            selected_agents, task_mappings, agent_metadata, primary_orchestrator
+        )
+
+        # Save to disk
+        self.save_configs(config_base_dir)
+        console.print("\n[green]✓[/green] Configuration files generated successfully\n")

src/delegation_mcp/installer/installer.py

@@ -0,0 +1,268 @@
+"""Main installer logic."""
+
+import asyncio
+import logging
+import platform
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt
+
+from ..agent_discovery import AgentDiscovery, AgentMetadata
+from .agent_selector import AgentSelector
+from .config_generator import ConfigGenerator
+from .mcp_configurator import MCPConfigurator
+from .task_mapper import TASK_CATEGORIES, TaskMapper
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+class DelegationInstaller:
+    """Automated installer for delegation-mcp."""
+
+    def __init__(self):
+        self.project_dir = Path.cwd()
+        self.agent_discovery = AgentDiscovery()
+        self.mcp_configurator = MCPConfigurator()
+        self.agent_selector = AgentSelector()
+        self.task_mapper = TaskMapper()
+        self.config_generator = ConfigGenerator()
+        self.discovered_agents: dict[str, AgentMetadata] = {}
+        self.selected_agents: list[str] = []
+        self.task_mappings: dict[str, str] = {}
+
+    def install(self) -> bool:
+        """Run full installation."""
+        try:
+            self._welcome()
+
+            if not self._check_system():
+                return False
+
+            asyncio.run(self._discover_agents())
+
+            if not self.discovered_agents:
+                self._no_agents_guide()
+                return False
+
+            # Select which agents to enable
+            self.selected_agents = self._select_agents()
+            if len(self.selected_agents) < 2:
+                console.print("[red]Need at least 2 agents for delegation.[/red]")
+                return False
+
+            # Select primary orchestrator
+            self.selected_orchestrator = "claude"
+            # Check if Claude is available
+            if "claude" not in self.discovered_agents:
+                 console.print("[yellow]Claude Code not detected. Please install it first: npm install -g @anthropic/claude-code[/yellow]")
+                 return False
+
+            # Map tasks to agents
+            if len(self.selected_agents) >= 2:
+                self.task_mappings = self._map_tasks()
+
+            # Ask about installation scope
+            install_project_instructions, install_user_instructions, mcp_scope = self._ask_user_level_instructions()
+
+            # Get the actual path to Claude executable
+            orchestrator_path = None
+            if "claude" in self.discovered_agents:
+                orchestrator_path = self.discovered_agents["claude"].path
+
+            if not self._configure_mcp(install_project_instructions, install_user_instructions, orchestrator_path, mcp_scope):
+                return False
+
+            self._print_success()
+            return True
+
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Installation cancelled[/yellow]")
+            return False
+        except Exception as e:
+            console.print(f"\n[red]Installation failed: {e}[/red]")
+            logger.error(f"Installation error: {e}", exc_info=True)
+            return False
+
+    def _welcome(self):
+        """Print welcome message."""
+        console.print(Panel.fit(
+            "[bold blue]Delegation MCP Installer[/bold blue]\n"
+            "Automated multi-agent orchestration setup",
+            border_style="blue"
+        ))
+
+    def _check_system(self) -> bool:
+        """Check system requirements."""
+        console.print("\n[bold]Checking system requirements...[/bold]")
+
+        # Check Python version
+        if sys.version_info < (3, 10):
+            console.print(f"[red]X Python 3.10+ required (found {sys.version_info.major}.{sys.version_info.minor})[/red]")
+            return False
+        console.print(f"[green]OK Python {sys.version_info.major}.{sys.version_info.minor}[/green]")
+
+        # Check OS
+        system = platform.system()
+        console.print(f"[green]OK {system}[/green]")
+
+        return True
+
+    async def _discover_agents(self):
+        """Discover available agents."""
+        console.print("\n[bold]Discovering agents...[/bold]")
+
+        discovered = await self.agent_discovery.discover_agents(force_refresh=True)
+        self.discovered_agents = {k: v for k, v in discovered.items() if v.available}
+
+        if self.discovered_agents:
+            console.print(f"[green]Found {len(self.discovered_agents)} agents:[/green]")
+            for name, meta in self.discovered_agents.items():
+                console.print(f"  [green]OK[/green] {name} ({meta.version})")
+        else:
+            console.print("[yellow]No agents detected[/yellow]")
+
+    def _no_agents_guide(self):
+        """Guide user to install agents."""
+        console.print("\n[bold yellow]No agents detected![/bold yellow]\n")
+        console.print("Install Claude Code:")
+        console.print("  • Claude Code: npm install -g @anthropic/claude-code\n")
+        console.print("Then run: [bold]python install.py[/bold]")
+
+    def _select_agents(self) -> list[str]:
+        """Let user select which agents to enable."""
+        return self.agent_selector.prompt_selection(self.discovered_agents)
+
+
+
+    def _map_tasks(self) -> dict[str, str]:
+        """Interactive task-to-agent mapping."""
+        console.print("\n[bold]Task Assignment Configuration[/bold]")
+        console.print("Configure which agents should handle which types of tasks.\n")
+        return self.task_mapper.map_tasks(self.selected_agents)
+
+    def _ask_user_level_instructions(self) -> tuple[bool, bool, str]:
+        """
+        Ask where to install system instructions and MCP server.
+        
+        Returns:
+            Tuple of (install_project_level, install_user_level, mcp_scope)
+        """
+        console.print("\n[bold]Installation Scope:[/bold]")
+        
+        console.print("  1. Project-level only (.claude/CLAUDE.md + local MCP) - Only for this project")
+        console.print("  2. User-level only (~/.claude/CLAUDE.md + global MCP) - For ALL Claude sessions")
+        console.print("  3. Both project and user level (project instructions + global MCP)")
+        
+        console.print(f"\n[dim]Recommended: Option 1 for project-specific setup, or 2 for global access.[/dim]")
+        
+        choice = Prompt.ask(
+            "Choose installation scope",
+            choices=["1", "2", "3"],
+            default="1"
+        )
+        
+        if choice == "1":
+            return (True, False, "local")  # Project only
+        elif choice == "2":
+            return (False, True, "user")  # User only
+        else:
+            return (True, True, "user")  # Both (use user scope for MCP)
+
+
+    def _configure_mcp(self, install_project_instructions: bool = True, install_user_instructions: bool = False, orchestrator_path: Path = None, scope: str = "local") -> bool:
+        """Configure MCP client for Claude (the only orchestrator)."""
+        console.print(f"\n[bold]Configuring MCP client and delegation rules for Claude...[/bold]")
+
+        # Generate delegation configuration files
+        if self.task_mappings and len(self.selected_agents) >= 2:
+            console.print("\n[cyan]Generating delegation configuration files...[/cyan]")
+            self.config_generator.generate_configs(
+                selected_agents=self.selected_agents,
+                task_mappings=self.task_mappings,
+                agent_metadata=self.discovered_agents,
+                primary_orchestrator="claude",
+                project_dir=self.project_dir,
+                scope=scope,
+            )
+            console.print("[green]✓ Configuration files generated[/green]")
+
+        # Configure MCP server
+        results = self.mcp_configurator.inject_delegation_mcp(
+            self.project_dir, 
+            "claude",  # Claude is the only orchestrator
+            install_project_instructions,
+            install_user_instructions,
+            orchestrator_path,
+            scope,
+            task_mappings=self.task_mappings,
+            selected_agents=self.selected_agents,
+        )
+
+        configured_any = False
+
+        for client, success in results.get("clients", {}).items():
+            if success:
+                console.print(f"[green]OK {client}: delegation-mcp registered[/green]")
+                configured_any = True
+            else:
+                console.print(f"[yellow]! {client} not configured automatically[/yellow]")
+
+        for message in results.get("messages", []):
+            console.print(message)
+
+        manual_steps = results.get("manual_instructions", [])
+        if manual_steps:
+            console.print("\n[bold]Manual setup required:[/bold]")
+            for step in manual_steps:
+                console.print(f"  [cyan]{step}[/cyan]")
+
+        # Claude supports auto-injection, so no manual instructions needed
+        if not configured_any and not results.get("allow_continue", False):
+            console.print("[red]X Failed to configure MCP client automatically.[/red]")
+            return False
+
+        return True
+
+    def _print_success(self):
+        """Print success message."""
+        console.print(f"\n[bold cyan]For Claude:[/bold cyan]")
+        console.print("  1. Restart Claude Desktop app")
+        console.print("  2. Open a chat and try: [cyan]'scan for security vulnerabilities'[/cyan]")
+        
+        console.print("\n[bold]The system will automatically:[/bold]")
+        
+        # Dynamic task routing summary grouped by agent
+        if self.task_mappings:
+            # Create a lookup for task names
+            task_names = {cat["key"]: cat["name"] for cat in TASK_CATEGORIES}
+            
+            # Group tasks by agent
+            agent_tasks = {}
+            for task_key, agent in self.task_mappings.items():
+                task_name = task_names.get(task_key, task_key)
+                if agent not in agent_tasks:
+                    agent_tasks[agent] = []
+                agent_tasks[agent].append(task_name)
+            
+            # Display grouped by agent
+            for agent, tasks in sorted(agent_tasks.items()):
+                tasks_str = ", ".join(tasks)
+                console.print(f"  • Route {tasks_str} to {agent}")
+        
+        console.print("  • Fall back if agent fails")
+
+
+def main():
+    """CLI entry point."""
+    logging.basicConfig(level=logging.INFO)
+    installer = DelegationInstaller()
+    success = installer.install()
+    sys.exit(0 if success else 1)
+
+
+if __name__ == "__main__":
+    main()

src/delegation_mcp/installer/mcp_configurator.py

@@ -0,0 +1,415 @@
+"""MCP client auto-configuration."""
+
+import json
+import logging
+import os
+import platform
+import shutil
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class MCPConfigurator:
+    """Auto-configure MCP clients (Claude Code and Claude Desktop)."""
+
+    def __init__(self, client_type: str = "auto"):
+        """
+        Initialize configurator.
+
+        Args:
+            client_type: "code", "desktop", or "auto" to detect
+        """
+        self.client_type = client_type
+        self.config_path = None
+        if client_type in ("desktop", "auto"):
+            self.desktop_config_path = self._detect_desktop_config_path()
+        else:
+            self.desktop_config_path = None
+
+    def _detect_desktop_config_path(self) -> Path:
+        """Detect Claude Desktop config location (platform-aware)."""
+        system = platform.system()
+
+        if system == "Windows":
+            locations = [
+                Path(os.environ.get("APPDATA", "")) / "Claude" / "claude_desktop_config.json",
+                Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json",
+            ]
+        elif system == "Darwin":  # macOS
+            locations = [
+                Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+            ]
+        else:  # Linux
+            locations = [
+                Path.home() / ".config" / "Claude" / "claude_desktop_config.json",
+            ]
+
+        for loc in locations:
+            if loc.exists():
+                logger.info(f"Found Claude Desktop config: {loc}")
+                return loc
+
+        # Default fallback
+        fallback = locations[0]
+        logger.info(f"Will create new Desktop config: {fallback}")
+        return fallback
+
+    def configure_claude_code(
+        self, 
+        project_dir: Path, 
+        system_instructions: str = None, 
+        install_project_instructions: bool = True,
+        install_user_instructions: bool = False,
+        claude_path: Path = None,
+        scope: str = "local"
+    ) -> tuple[bool, bool]:
+        """
+        Configure MCP for Claude Code using 'claude mcp add' command and inject system instructions.
+        
+        Args:
+            project_dir: Project directory path
+            system_instructions: System instructions text to inject
+            install_project_instructions: If True, install CLAUDE.md at project level
+            install_user_instructions: If True, install CLAUDE.md at user level (~/.claude/)
+            claude_path: Path to claude executable (if None, uses 'claude' from PATH)
+            scope: Configuration scope - "local" (default), "project", or "user"
+        
+        Returns:
+            Tuple of (mcp_configured, instructions_configured)
+        """
+        import subprocess
+
+        mcp_configured = False
+        instructions_configured = False
+
+        # 1. Configure MCP server
+        try:
+            # Determine claude command to use
+            claude_cmd = str(claude_path) if claude_path else "claude"
+            
+            # First, try to remove any existing delegation-mcp server to ensure clean install
+            try:
+                remove_result = subprocess.run(
+                    [claude_cmd, "mcp", "remove", "delegation-mcp"],
+                    cwd=str(project_dir),
+                    capture_output=True,
+                    text=True,
+                    timeout=10
+                )
+                if remove_result.returncode == 0:
+                    logger.info("Removed existing delegation-mcp server before reinstalling")
+            except Exception as e:
+                logger.debug(f"No existing delegation-mcp to remove (or removal failed): {e}")
+            
+            # Use the official claude mcp add command with scope
+            cmd = [
+                claude_cmd,
+                "mcp",
+                "add",
+                "--scope", scope,
+                "delegation-mcp",
+                "delegation-mcp"
+            ]
+
+            result = subprocess.run(
+                cmd,
+                cwd=str(project_dir),
+                capture_output=True,
+                text=True,
+                timeout=30
+            )
+
+            if result.returncode == 0:
+                logger.info(f"Configured delegation-mcp for Claude Code using 'claude mcp add'")
+                
+                # Verify the server was actually added
+                try:
+                    verify_result = subprocess.run(
+                        [claude_cmd, "mcp", "list"],
+                        cwd=str(project_dir),
+                        capture_output=True,
+                        text=True,
+                        timeout=10
+                    )
+                    
+                    if verify_result.returncode == 0 and "delegation-mcp" in verify_result.stdout:
+                        logger.info("Verified delegation-mcp is registered with Claude Code")
+                        mcp_configured = True
+                    else:
+                        logger.warning(f"delegation-mcp not found in 'claude mcp list' output")
+                        mcp_configured = False
+                except Exception as e:
+                    logger.warning(f"Could not verify MCP server registration: {e}")
+                    # Still mark as configured if 'claude mcp add' succeeded
+                    mcp_configured = True
+            else:
+                logger.warning(f"'claude mcp add' failed (exit code {result.returncode}): {result.stderr}")
+
+        except FileNotFoundError:
+            logger.warning(f"Claude executable not found at: {claude_cmd}")
+        except subprocess.TimeoutExpired:
+            logger.error("'claude mcp add' command timed out")
+        except Exception as e:
+            logger.error(f"Failed to configure Claude Code MCP: {e}")
+
+        # 2. Inject system instructions if provided
+        if system_instructions:
+            # Helper function to safely add instructions to a file
+            def add_instructions_to_file(file_path: Path, backup: bool = True):
+                """Add or update delegation instructions using marker tags."""
+                import re
+                
+                try:
+                    # Define markers
+                    BEGIN_MARKER = "<!-- BEGIN DELEGATION-MCP INSTRUCTIONS -->"
+                    END_MARKER = "<!-- END DELEGATION-MCP INSTRUCTIONS -->"
+                    
+                    # Wrap instructions with markers
+                    wrapped_instructions = f"{BEGIN_MARKER}\n{system_instructions}\n{END_MARKER}"
+                    
+                    existing_content = ""
+                    if file_path.exists():
+                        with open(file_path, "r", encoding="utf-8") as f:
+                            existing_content = f.read()
+                        
+                        # Backup existing file
+                        if backup:
+                            backup_path = file_path.with_suffix(".md.backup")
+                            shutil.copy2(file_path, backup_path)
+                            logger.info(f"Backed up existing file to: {backup_path}")
+                    
+                    # Check if markers exist (update case)
+                    marker_pattern = re.compile(
+                        r"<!-- BEGIN DELEGATION-MCP INSTRUCTIONS.*?-->\n.*?\n<!-- END DELEGATION-MCP INSTRUCTIONS -->",
+                        re.DOTALL
+                    )
+                    
+                    if existing_content and marker_pattern.search(existing_content):
+                        # Replace existing wrapped section
+                        new_content = marker_pattern.sub(wrapped_instructions, existing_content)
+                        logger.info(f"Replaced existing delegation instructions in {file_path}")
+                    elif existing_content.strip():
+                        # Prepend wrapped instructions to existing content
+                        new_content = wrapped_instructions + "\n\n" + "="*80 + "\n"
+                        new_content += "# Existing Instructions\n"
+                        new_content += "="*80 + "\n\n"
+                        new_content += existing_content
+                        logger.info(f"Prepended delegation instructions to {file_path}")
+                    else:
+                        # New file, just write wrapped instructions
+                        new_content = wrapped_instructions
+                        logger.info(f"Created new delegation instructions in {file_path}")
+                    
+                    # Create parent directory if needed
+                    file_path.parent.mkdir(parents=True, exist_ok=True)
+                    
+                    # Write the file
+                    with open(file_path, "w", encoding="utf-8") as f:
+                        f.write(new_content)
+                    
+                    return True
+                    
+                except Exception as e:
+                    logger.warning(f"Failed to add instructions to {file_path}: {e}")
+                    return False
+
+            # Project-level CLAUDE.md
+            if install_project_instructions:
+                project_claude_dir = project_dir / ".claude"
+                project_claude_md = project_claude_dir / "CLAUDE.md"
+                if add_instructions_to_file(project_claude_md, backup=True):
+                    instructions_configured = True
+
+            # User-level CLAUDE.md
+            if install_user_instructions:
+                user_claude_dir = Path.home() / ".claude"
+                user_claude_md = user_claude_dir / "CLAUDE.md"
+                if add_instructions_to_file(user_claude_md, backup=True):
+                    instructions_configured = True
+
+        return (mcp_configured, instructions_configured)
+
+    def configure_claude_desktop(self, project_dir: Path) -> bool:
+        """Configure MCP for Claude Desktop using global config."""
+        try:
+            # Backup existing config
+            if self.desktop_config_path.exists():
+                backup_path = self.desktop_config_path.with_suffix(".json.backup")
+                shutil.copy2(self.desktop_config_path, backup_path)
+                logger.info(f"Backed up Desktop config to: {backup_path}")
+
+            # Load existing config
+            if self.desktop_config_path.exists():
+                with open(self.desktop_config_path) as f:
+                    config = json.load(f)
+            else:
+                config = {}
+
+            # Ensure mcpServers exists
+            if "mcpServers" not in config:
+                config["mcpServers"] = {}
+
+            # Add delegation-mcp
+            config["mcpServers"]["delegation-mcp"] = {
+                "command": "uv",
+                "args": [
+                    "--directory",
+                    str(project_dir),
+                    "run",
+                    "delegation-mcp"
+                ]
+            }
+
+            # Save config
+            self.desktop_config_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.desktop_config_path, "w") as f:
+                json.dump(config, f, indent=2)
+
+            self.config_path = self.desktop_config_path
+            logger.info(f"Configured delegation-mcp for Claude Desktop: {self.desktop_config_path}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to configure Claude Desktop: {e}")
+            return False
+
+
+
+    def inject_delegation_mcp(
+        self, 
+        project_dir: Path, 
+        orchestrator: str,
+        install_project_instructions: bool = True,
+        install_user_instructions: bool = False,
+        orchestrator_path: Path = None,
+        scope: str = "local",
+        task_mappings: dict[str, str] | None = None,
+        selected_agents: list[str] | None = None,
+    ) -> dict[str, object]:
+        """
+        Inject delegation-mcp server into config(s).
+        
+        Args:
+            project_dir: Project directory path
+            orchestrator: Name of the orchestrator (claude, gemini, etc.)
+            install_project_instructions: If True, install system instructions at project level
+            install_user_instructions: If True, install system instructions at user level
+            orchestrator_path: Path to orchestrator executable
+            scope: Configuration scope for Claude Code - "local" (default), "project", or "user"
+            task_mappings: Dictionary mapping task categories to agent names
+            selected_agents: List of selected agent names
+        
+        Returns:
+            Dict containing client results, status, and manual instructions
+        """
+        from .system_instructions import get_system_instructions
+
+        orchestrator = (orchestrator or "").lower()
+
+        outcome: dict[str, object] = {
+            "orchestrator": orchestrator,
+            "clients": {},
+            "messages": [],
+            "manual_instructions": [],
+            "system_instructions": get_system_instructions(
+                orchestrator, 
+                task_mappings=task_mappings,
+                selected_agents=selected_agents
+            ),
+            "allow_continue": False,
+        }
+
+        if orchestrator == "claude":
+            system_instructions = str(outcome["system_instructions"])
+            
+            if self.client_type in ("code", "auto"):
+                mcp_configured, instructions_configured = self.configure_claude_code(
+                    project_dir, 
+                    system_instructions,
+                    install_project_instructions,
+                    install_user_instructions,
+                    orchestrator_path,
+                    scope
+                )
+                code_success = mcp_configured or instructions_configured
+                outcome["clients"]["Claude Code"] = code_success
+                
+                if code_success:
+                    # Determine what was actually configured
+                    configured_items = []
+                    if mcp_configured:
+                        configured_items.append("MCP server")
+                    if instructions_configured:
+                        configured_items.append("system instructions")
+                    
+                    outcome["messages"].append(
+                        f"[green]✓ Claude Code: {', '.join(configured_items)} configured![/green]"
+                    )
+                    
+                    if mcp_configured:
+                        outcome["messages"].append(
+                            "[dim]  • MCP server verified with 'claude mcp list'[/dim]"
+                        )
+                    
+                    if install_project_instructions:
+                        outcome["messages"].append(
+                            f"[dim]  • System instructions (project): {project_dir / '.claude' / 'CLAUDE.md'}[/dim]"
+                        )
+                    
+                    if install_user_instructions:
+                        user_claude_md = Path.home() / ".claude" / "CLAUDE.md"
+                        outcome["messages"].append(
+                            f"[dim]  • System instructions (user): {user_claude_md}[/dim]"
+                        )
+                    
+                    # Only show manual instructions if MCP server wasn't configured
+                    if not mcp_configured:
+                        outcome["messages"].append(
+                            "[yellow]! MCP server not added - manual setup required:[/yellow]"
+                        )
+                        outcome["manual_instructions"].append("claude mcp add delegation-mcp delegation-mcp")
+                        outcome["manual_instructions"].append(
+                            "Then verify with: claude mcp list"
+                        )
+                else:
+                    outcome["manual_instructions"].append("claude mcp add delegation-mcp delegation-mcp")
+                    outcome["manual_instructions"].append(
+                        "Add system instructions from delegation_instructions.txt to .claude/CLAUDE.md"
+                    )
+
+            if self.client_type in ("desktop", "auto"):
+                desktop_success = self.configure_claude_desktop(project_dir)
+                outcome["clients"]["Claude Desktop"] = desktop_success
+                if desktop_success and not self.config_path:
+                    self.config_path = self.desktop_config_path
+
+            outcome["allow_continue"] = True
+            return outcome
+
+            outcome["allow_continue"] = True
+            return outcome
+
+        outcome["messages"].append(
+            f"[yellow]! Automatic MCP configuration for '{orchestrator}' is not supported yet.[/yellow]"
+        )
+        outcome["manual_instructions"].append(
+            "Please register the delegation-mcp server manually in your MCP client."
+        )
+        outcome["allow_continue"] = True
+        return outcome
+
+    def verify_config(self) -> bool:
+        """Verify config is valid JSON and has delegation-mcp."""
+        if not self.config_path or not self.config_path.exists():
+            return False
+
+        try:
+            with open(self.config_path) as f:
+                config = json.load(f)
+
+            return "mcpServers" in config and "delegation-mcp" in config["mcpServers"]
+
+        except Exception as e:
+            logger.error(f"Config verification failed: {e}")
+            return False

src/delegation_mcp/installer/system_instructions.py

@@ -0,0 +1,195 @@
+"""System instructions for the orchestrator agent."""
+
+from .task_mapper import TASK_CATEGORIES
+
+
+def get_system_instructions(
+    orchestrator_name: str = "Claude",
+    task_mappings: dict[str, str] | None = None,
+    selected_agents: list[str] | None = None,
+) -> str:
+    """
+    Generate ultra-concise system instructions for orchestrator.
+    
+    Args:
+        orchestrator_name: The name of the orchestrator agent (e.g., "Claude", "Gemini").
+        task_mappings: Dictionary mapping task categories to agent names
+        selected_agents: List of selected agent names
+    
+    Returns:
+        Formatted system instructions string (optimized for minimal tokens).
+    """
+    orchestrator_name = orchestrator_name.capitalize()
+    task_mappings = task_mappings or {}
+    
+    # Build concise routing table
+    routing_rows = []
+    category_map = {cat["key"]: cat for cat in TASK_CATEGORIES}
+    
+    for task_key, agent_name in task_mappings.items():
+        category = category_map.get(task_key)
+        if category and task_key != "general":
+            routing_rows.append(f"- {category['description']} → **{agent_name}**")
+    
+    routing_table = "\n".join(routing_rows) if routing_rows else "No specific mappings configured"
+    
+    instructions = f"""# {orchestrator_name} - Orchestrator
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  STOP - READ BEFORE ANY CODE/FILE/TECHNICAL OPERATION  ⚠️
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Before reading files, editing code, analyzing systems, or ANY technical work:
+
+❓ Did you call `delegate_task(query="...", guidance_only=True)` for this request?
+   □ YES - I called it. Server returned: ________________
+   □ NO - I have NOT called it yet
+
+If you checked NO or left blank: **STOP NOW. Go back. Call the tool.**
+
+If you checked YES: What did the server return?
+   □ "HANDLE_DIRECTLY" → OK to proceed
+   □ "DELEGATE_TO: [agent]" → MUST delegate, do NOT proceed with execution
+
+**VIOLATION CHECK**: If you are reading code/files WITHOUT having called the tool above, you are violating the protocol. STOP IMMEDIATELY.
+
+**MULTI-STEP TASKS**: If request has multiple distinct phases (e.g., "review + fix + commit"), call delegate_task separately for each:
+  1. delegate_task("phase 1") → get results
+  2. delegate_task("phase 2: [specific from results]") → execute  
+  3. delegate_task("phase 3") → finalize
+
+Example: "Review backend, fix issues, commit changes"
+  → Call delegate_task("review backend for scalability") → Gemini analyzes
+  → Call delegate_task("fix critical query issues in api.ts") → Aider implements fixes
+  → Call delegate_task("stage, commit, push with message") → Aider handles git
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Core Function**: Delegate specialized tasks, handle architecture/planning yourself.
+
+## Delegation Protocol
+
+**For ANY code/technical request**:
+1. Call `delegate_task(query=full_user_request, guidance_only=True)` FIRST
+2. Tool returns routing decision: "DELEGATE_TO: agent" or "HANDLE_DIRECTLY"
+3. Follow tool response (do NOT override it)
+
+**Why**: Server has routing logic (keywords + capability scoring). Always consult it.
+
+## Routing Table
+
+{routing_table}
+
+## Tools
+
+- `delegate_task(query, guidance_only?, force_delegate?)` - Get routing guidance or execute delegation
+- `list_orchestrators()` - Show available agents
+- `discover_agents()` - Find new agents
+
+## Rules
+
+1. **ALWAYS call tool first**: `delegate_task(guidance_only=True)` before ANY code work
+2. **Trust server routing**: Uses keyword matching + capability scoring
+3. **Handle directly ONLY if**: Tool explicitly returns "HANDLE_DIRECTLY"
+4. **Never bypass**: Even if task seems "simple" or "quick" - ALWAYS consult tool
+
+**Critical**: If you catch yourself thinking "this is quick, I'll just..." → STOP. Call the tool.
+"""
+    
+    return instructions
+
+
+def _build_routing_table(task_mappings: dict[str, str]) -> list[str]:
+    """Build routing table rows from task mappings."""
+    rows = []
+    category_map = {cat["key"]: cat for cat in TASK_CATEGORIES}
+    
+    for task_key, agent_name in task_mappings.items():
+        category = category_map.get(task_key)
+        if not category or task_key == "general":
+            continue
+        
+        # Format examples for table
+        examples = ", ".join(category["pattern_examples"][:3])  # First 3 examples
+        row = f"| {category['description']} | **{agent_name}** | {examples} |"
+        rows.append(row)
+    
+    return rows
+
+
+def _build_agent_summary(selected_agents: list[str]) -> list[str]:
+    """Build agent capabilities summary.
+    
+    Note: This is intentionally kept simple since actual capabilities
+    are shown in the routing table based on user's task mappings.
+    """
+    if not selected_agents:
+        return []
+    
+    summary = []
+    for agent in selected_agents:
+        summary.append(f"- **{agent}**")
+    
+    return summary
+
+
+def _build_prohibitions(task_mappings: dict[str, str]) -> list[str]:
+    """Build prohibition list dynamically from task mappings.
+    
+    Only prohibit tasks that the user has explicitly mapped to other agents.
+    """
+    if not task_mappings:
+        return []
+    
+    prohibitions = []
+    category_map = {cat["key"]: cat for cat in TASK_CATEGORIES}
+    
+    # Map task types to prohibition descriptions
+    prohibition_templates = {
+        "git_operations": "❌ Execute git commands (git checkout, git pull, git commit, etc.)",
+        "shell_tasks": "❌ Run shell/terminal commands directly",
+        "refactoring": "❌ Perform code refactoring directly",
+        "security_audit": "❌ Conduct security reviews or audits",
+        "testing": "❌ Write or execute tests directly",
+        "performance": "❌ Perform performance analysis or optimization",
+        "browser_interaction": "❌ Execute browser automation tasks",
+        "code_review": "❌ Conduct code reviews",
+        "exploration": "❌ Explore codebase or trace implementations (delegate to save tokens)",
+        "debugging": "❌ Debug issues or investigate errors (delegate to save tokens)",
+        "impact_analysis": "❌ Analyze dependencies or find usages (delegate to save tokens)",
+    }
+    
+    for task_key, agent_name in task_mappings.items():
+        if task_key == "general":
+            continue
+        
+        # Get prohibition template for this task type
+        prohibition = prohibition_templates.get(task_key)
+        if prohibition:
+            prohibitions.append(f"- {prohibition} → **Delegate to {agent_name}**")
+    
+    return prohibitions
+
+
+def _build_routing_examples(task_mappings: dict[str, str]) -> list[str]:
+    """Build routing examples dynamically from actual task mappings."""
+    examples = []
+    category_map = {cat["key"]: cat for cat in TASK_CATEGORIES}
+    
+    # Build examples from actual mappings
+    for task_key, agent_name in task_mappings.items():
+        category = category_map.get(task_key)
+        if not category or task_key == "general":
+            continue
+        
+        # Use first pattern example from the category
+        if category["pattern_examples"]:
+            example_query = category["pattern_examples"][0]
+            examples.append(f'| "{example_query}" | DELEGATE | {agent_name} |')
+    
+    # Add a general handling example
+    examples.append('| "What\'s the best database for this use case?" | HANDLE | (yourself) |')
+    
+    return examples
+
+

src/delegation_mcp/installer/task_mapper.py

@@ -0,0 +1,436 @@
+"""Task-to-agent mapping with intelligent suggestions.
+
+This module provides functionality for mapping task categories to agents
+with intelligent suggestions based on agent capabilities and routing strategies.
+"""
+
+import logging
+from typing import TypedDict
+
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+from rich.table import Table
+
+from .agent_profiles import (
+    get_agent_profile, 
+    ROUTING_PRESETS, 
+    DEFAULT_ROUTING_RULES,
+    RoutingPreset
+)
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+class TaskCategory(TypedDict):
+    """Definition of a task category."""
+    key: str
+    name: str
+    description: str
+    pattern_examples: list[str]
+
+
+# Task categories for delegation
+TASK_CATEGORIES: list[TaskCategory] = [
+    {
+        "key": "security_audit",
+        "name": "Security Audit",
+        "description": "Security audits, vulnerability scans, safety checks",
+        "pattern_examples": [
+            "security", "vulnerability", "audit", "CVE", "harden", "secure", "protect",
+            "lock down", "access control", "permissions", "rules", "firestore rules",
+            "authentication", "authorization", "encrypt", "expose", "leak", "breach",
+            "attack", "threat", "OWASP", "XSS", "injection", "sanitize", "exploit",
+        ],
+    },
+    {
+        "key": "code_review",
+        "name": "Code Review",
+        "description": "Code quality review, best practices analysis",
+        "pattern_examples": [
+            "review", "code quality", "best practices", "lint", "improve", "clean up",
+            "tech debt", "smell", "anti-pattern", "convention", "standards",
+            "maintainability", "readability", "code analysis",
+        ],
+    },
+    {
+        "key": "architecture",
+        "name": "Architecture",
+        "description": "System design, architecture planning, complex reasoning",
+        "pattern_examples": [
+            "architecture", "design", "system design", "structure", "organize", "plan",
+            "approach", "strategy", "pattern", "blueprint", "diagram", "flow", "schema",
+        ],
+    },
+    {
+        "key": "refactoring",
+        "name": "Refactoring",
+        "description": "Code refactoring, cleanup, optimization",
+        "pattern_examples": [
+            "refactor", "cleanup", "optimize code", "rename", "restructure", "reorganize",
+            "simplify", "DRY", "extract", "inline", "consolidate", "modularize",
+        ],
+    },
+    {
+        "key": "quick_fix",
+        "name": "Quick Fixes",
+        "description": "Rapid bug fixes, small code changes",
+        "pattern_examples": [
+            "fix", "bug", "quick change", "error", "crash", "broken", "not working",
+            "issue", "problem", "patch", "hotfix",
+        ],
+    },
+    {
+        "key": "documentation",
+        "name": "Documentation",
+        "description": "README files, API docs, code comments",
+        "pattern_examples": [
+            "documentation", "docs", "README", "comments", "comment", "explain", "describe",
+            "guide", "tutorial", "how-to", "API docs", "docstring", "examples",
+        ],
+    },
+    {
+        "key": "testing",
+        "name": "Testing",
+        "description": "Unit tests, integration tests, test coverage",
+        "pattern_examples": [
+            "test", "testing", "coverage", "unit test", "integration test", "e2e",
+            "spec", "assertion", "mock", "stub", "test case", "test suite",
+        ],
+    },
+    {
+        "key": "performance",
+        "name": "Performance",
+        "description": "Performance analysis and optimization",
+        "pattern_examples": [
+            "performance", "optimize", "speed", "slow", "latency", "throughput",
+            "bottleneck", "profiling", "benchmark", "memory", "CPU", "scalability",
+        ],
+    },
+    {
+        "key": "browser_interaction",
+        "name": "Browser Interaction",
+        "description": "Browser automation, web scraping, UI testing",
+        "pattern_examples": ["browser", "selenium", "playwright", "chrome"],
+    },
+    {
+        "key": "git_operations",
+        "name": "Git Operations",
+        "description": "Git workflows, repository management",
+        "pattern_examples": [
+            "git", "commit", "merge", "branch", "push", "pull", "rebase", "cherry-pick",
+            "stash", "tag", "history", "checkout", "reset", "revert",
+        ],
+    },
+    {
+        "key": "shell_tasks",
+        "name": "Shell/Terminal",
+        "description": "Shell scripting, terminal commands",
+        "pattern_examples": [
+            "shell", "terminal", "bash", "script", "command", "CLI", "automation",
+            "cron", "env", "environment variables", "path", "execute",
+        ],
+    },
+    {
+        "key": "exploration",
+        "name": "Code Exploration",
+        "description": "Code exploration, dependency tracing, implementation analysis",
+        "pattern_examples": ["how does", "trace the flow", "what files implement", "understand the implementation", "map dependencies"],
+    },
+    {
+        "key": "debugging",
+        "name": "Debugging",
+        "description": "Bug investigation, error analysis, root cause identification",
+        "pattern_examples": ["debug", "why is failing", "investigate", "find the cause", "troubleshoot"],
+    },
+    {
+        "key": "impact_analysis",
+        "name": "Impact Analysis",
+        "description": "Dependency analysis, usage finding, breaking change assessment",
+        "pattern_examples": ["what would break", "find all usages", "what depends on", "impact of changing", "all references"],
+    },
+    {
+        "key": "general",
+        "name": "General Tasks",
+        "description": "Default for tasks that don't fit specific categories",
+        "pattern_examples": ["general", "misc", "other"],
+    },
+]
+
+
+class TaskMapper:
+    """Manages task-to-agent mapping during installation."""
+
+    def __init__(self):
+        """Initialize the task mapper."""
+        self.task_mappings: dict[str, str] = {}
+        self.selected_strategy: str = "balanced"
+
+    def select_strategy(self) -> str:
+        """
+        Prompt user to select a routing strategy.
+        
+        Returns:
+            Selected strategy key
+        """
+        console.print("\n[bold]Delegation Strategy[/bold]")
+        console.print("Choose how tasks should be distributed among agents:\n")
+        
+        table = Table(show_header=True, header_style="bold magenta")
+        table.add_column("Option", style="cyan", justify="center")
+        table.add_column("Strategy", style="green")
+        table.add_column("Description", style="white")
+        table.add_column("Priorities", style="yellow")
+        
+        strategies = list(ROUTING_PRESETS.items())
+        
+        for i, (key, preset) in enumerate(strategies, 1):
+            priorities = f"Cost: {preset['cost_priority']}, Quality: {preset['quality_priority']}"
+            table.add_row(str(i), preset["name"], preset["description"], priorities)
+            
+        console.print(table)
+        console.print("\n")
+        
+        choices = [str(i) for i in range(1, len(strategies) + 1)]
+        default_idx = [k for k, _ in strategies].index("balanced") + 1
+        
+        selection = Prompt.ask(
+            "Select strategy",
+            choices=choices,
+            default=str(default_idx)
+        )
+        
+        selected_key = strategies[int(selection) - 1][0]
+        self.selected_strategy = selected_key
+        
+        console.print(f"\n[green]✓[/green] Selected: {ROUTING_PRESETS[selected_key]['name']}\n")
+        return selected_key
+
+    def suggest_mappings(self, agent_names: list[str], strategy_key: str) -> dict[str, tuple[str, str]]:
+        """
+        Generate intelligent mapping suggestions based on strategy and agent capabilities.
+        
+        Args:
+            agent_names: List of available agent names
+            strategy_key: Key of the selected routing strategy
+            
+        Returns:
+            Dictionary of task_key -> (suggested_agent, reasoning)
+        """
+        suggestions: dict[str, tuple[str, str]] = {}
+        preset = ROUTING_PRESETS[strategy_key]
+        
+        # Helper to find best agent from a list of preferred ones
+        def find_best_available(preferred: list[str], fallback_reason: str) -> tuple[str, str]:
+            for agent in preferred:
+                if agent in agent_names:
+                    # Find specific reason from rules if available
+                    return agent, fallback_reason
+            
+            # Fallback logic based on strategy
+            if preset["cost_priority"] == "high":
+                # Prefer free/local agents
+                for agent in agent_names:
+                    profile = get_agent_profile(agent)
+                    if profile["cost_tier"] == "free":
+                        return agent, "Selected for cost efficiency"
+            
+            if preset["quality_priority"] == "high":
+                # Prefer Claude/Gemini
+                for agent in ["claude", "gemini"]:
+                    if agent in agent_names:
+                        return agent, "Selected for high quality"
+                        
+            # Default to first available
+            return agent_names[0], "Best available option"
+
+        for category in TASK_CATEGORIES:
+            task_key = category["key"]
+            
+            # Get default rule
+            rule = DEFAULT_ROUTING_RULES.get(task_key)
+            if not rule:
+                suggestions[task_key] = (agent_names[0], "Default assignment")
+                continue
+                
+            # Apply strategy overrides
+            preferred = rule["preferred"]
+            reason = rule["reason"]
+            
+            if strategy_key == "cost_optimized":
+                # Prioritize free agents
+                free_agents = [a for a in agent_names if get_agent_profile(a)["cost_tier"] == "free"]
+                if free_agents:
+                    preferred = free_agents + preferred
+                    reason = "Cost optimized choice"
+                    
+            elif strategy_key == "speed_first":
+                # Prioritize fast agents
+                fast_agents = [a for a in agent_names if get_agent_profile(a)["response_speed"] == "fast"]
+                if fast_agents:
+                    preferred = fast_agents + preferred
+                    reason = "Optimized for speed"
+            
+            elif strategy_key == "token_saver":
+                # Prioritize large context or concise agents
+                # (Simplified logic: prefer Gemini for context, Aider for conciseness)
+                if task_key in ["architecture", "exploration"]:
+                    preferred = ["gemini"] + preferred
+                    reason = "Large context window"
+                else:
+                    preferred = ["aider"] + preferred
+                    reason = "Concise responses"
+
+            # Find best agent
+            agent, final_reason = find_best_available(preferred, reason)
+            suggestions[task_key] = (agent, final_reason)
+
+        return suggestions
+
+    def display_suggestions(
+        self, 
+        suggestions: dict[str, tuple[str, str]],
+        agent_names: list[str]
+    ) -> None:
+        """
+        Display mapping suggestions in a formatted table.
+        
+        Args:
+            suggestions: Dictionary of task_key -> (agent, reasoning)
+            agent_names: List of available agent names for context
+        """
+        table = Table(
+            title=f"Suggested Mappings ({ROUTING_PRESETS[self.selected_strategy]['name']})",
+            show_header=True,
+            header_style="bold magenta"
+        )
+        table.add_column("Task Category", style="cyan", no_wrap=True)
+        table.add_column("Suggested Agent", style="green")
+        table.add_column("Reasoning", style="yellow")
+
+        # Create task key to category mapping for lookup
+        category_map = {cat["key"]: cat for cat in TASK_CATEGORIES}
+
+        for task_key, (agent, reasoning) in suggestions.items():
+            category = category_map.get(task_key)
+            if category:
+                task_name = category["name"]
+                table.add_row(task_name, agent, reasoning)
+
+        console.print("\n")
+        console.print(table)
+        console.print("\n")
+
+    def prompt_task_assignments(
+        self, 
+        agent_names: list[str],
+        suggestions: dict[str, tuple[str, str]]
+    ) -> dict[str, str]:
+        """
+        Interactive prompt for task-to-agent assignment.
+        
+        Args:
+            agent_names: List of available agent names
+            suggestions: Pre-computed suggestions
+            
+        Returns:
+            Dictionary of task_key -> agent_name
+        """
+        self.display_suggestions(suggestions, agent_names)
+
+        console.print("[bold]Task Assignment Configuration[/bold]")
+        console.print("You can accept all suggestions or customize individual mappings.\n")
+
+        # Ask if user wants to use all suggestions
+        accept_all = Confirm.ask(
+            "Accept all suggested mappings?",
+            default=True
+        )
+
+        if accept_all:
+            self.task_mappings = {
+                task_key: agent 
+                for task_key, (agent, _) in suggestions.items()
+            }
+            console.print("\n[green]✓[/green] Using all suggested mappings\n")
+            return self.task_mappings
+
+        # Custom assignment
+        console.print("\nCustomize task assignments:\n")
+        self.task_mappings = {}
+
+        # Create task key to category mapping
+        category_map = {cat["key"]: cat for cat in TASK_CATEGORIES}
+
+        for task_key, (suggested_agent, reasoning) in suggestions.items():
+            category = category_map.get(task_key)
+            if not category:
+                continue
+
+            task_name = category["name"]
+            description = category["description"]
+
+            console.print(f"\n[cyan]{task_name}[/cyan]: {description}")
+            console.print(f"  Suggested: [green]{suggested_agent}[/green] ({reasoning})")
+
+            # Ask if user wants to change
+            use_suggestion = Confirm.ask(
+                f"  Use {suggested_agent} for {task_name}?",
+                default=True
+            )
+
+            if use_suggestion:
+                self.task_mappings[task_key] = suggested_agent
+                console.print(f"  [green]✓[/green] Assigned to {suggested_agent}")
+            else:
+                # Let user pick an agent
+                console.print(f"  Available agents: {', '.join(agent_names)}")
+                
+                while True:
+                    chosen_agent = Prompt.ask(
+                        f"  Select agent for {task_name}",
+                        choices=agent_names,
+                        default=suggested_agent
+                    )
+                    
+                    if chosen_agent in agent_names:
+                        self.task_mappings[task_key] = chosen_agent
+                        console.print(f"  [green]✓[/green] Assigned to {chosen_agent}")
+                        break
+                    else:
+                        console.print(f"  [red]✗[/red] Invalid agent. Please choose from: {', '.join(agent_names)}")
+
+        console.print(f"\n[green]✓[/green] Task assignment configuration complete\n")
+        return self.task_mappings
+
+    def get_task_mappings(self) -> dict[str, str]:
+        """
+        Get the task-to-agent mappings.
+        
+        Returns:
+            Dictionary of task_key -> agent_name
+        """
+        return self.task_mappings
+
+    def map_tasks(self, agent_names: list[str]) -> dict[str, str]:
+        """
+        Complete task mapping flow with suggestions and user input.
+        
+        Args:
+            agent_names: List of available agent names
+            
+        Returns:
+            Dictionary of task_key -> agent_name
+        """
+        if len(agent_names) < 2:
+            logger.warning("Need at least 2 agents for task mapping")
+            return {}
+
+        # Select strategy
+        strategy_key = self.select_strategy()
+
+        # Generate suggestions based on strategy
+        suggestions = self.suggest_mappings(agent_names, strategy_key)
+
+        # Get user assignments
+        return self.prompt_task_assignments(agent_names, suggestions)

src/delegation_mcp/logging_config.py

@@ -0,0 +1,159 @@
+"""Logging configuration for delegation MCP server."""
+
+import logging
+import sys
+from typing import Any
+from datetime import datetime
+
+
+class StructuredFormatter(logging.Formatter):
+    """Custom formatter for structured logging."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record with structured information."""
+        # Get timestamp
+        timestamp = datetime.fromtimestamp(record.created).isoformat()
+
+        # Build structured log entry
+        parts = [
+            f"[{timestamp}]",
+            f"[{record.levelname}]",
+            f"[{record.name}]",
+        ]
+
+        # Add extra context if available
+        if hasattr(record, "orchestrator"):
+            parts.append(f"[orchestrator={record.orchestrator}]")
+        if hasattr(record, "delegation_to"):
+            parts.append(f"[→{record.delegation_to}]")
+        if hasattr(record, "duration"):
+            parts.append(f"[{record.duration:.2f}s]")
+
+        # Add the message
+        parts.append(record.getMessage())
+
+        # Add exception info if present
+        if record.exc_info:
+            parts.append("\n" + self.formatException(record.exc_info))
+
+        return " ".join(parts)
+
+
+def setup_logging(level: int = logging.INFO, verbose: bool = False) -> None:
+    """
+    Setup logging configuration.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR)
+        verbose: Enable verbose output with structured logging
+    """
+    # Get root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(level)
+
+    # Remove existing handlers
+    root_logger.handlers.clear()
+
+    # Create console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(level)
+
+    # Set formatter
+    if verbose:
+        formatter = StructuredFormatter()
+    else:
+        formatter = logging.Formatter(
+            "%(levelname)s - %(name)s - %(message)s"
+        )
+
+    console_handler.setFormatter(formatter)
+    root_logger.addHandler(console_handler)
+
+    # Set specific log levels for dependencies
+    logging.getLogger("asyncio").setLevel(logging.WARNING)
+    logging.getLogger("urllib3").setLevel(logging.WARNING)
+
+
+class DelegationLogger:
+    """Logger with delegation-specific context."""
+
+    def __init__(self, name: str = "delegation_mcp"):
+        self.logger = logging.getLogger(name)
+
+    def delegation_start(
+        self,
+        orchestrator: str,
+        query: str,
+        delegated_to: str | None = None
+    ) -> None:
+        """Log delegation start."""
+        extra = {"orchestrator": orchestrator}
+        if delegated_to:
+            extra["delegation_to"] = delegated_to
+            msg = f"Delegating query to {delegated_to}"
+        else:
+            msg = f"Processing query with {orchestrator}"
+
+        self.logger.info(msg, extra=extra)
+
+    def delegation_success(
+        self,
+        orchestrator: str,
+        delegated_to: str | None,
+        duration: float,
+    ) -> None:
+        """Log successful delegation."""
+        target = delegated_to or orchestrator
+        extra = {
+            "orchestrator": orchestrator,
+            "duration": duration,
+        }
+        if delegated_to:
+            extra["delegation_to"] = delegated_to
+
+        self.logger.info(f"✓ Delegation completed successfully", extra=extra)
+
+    def delegation_failure(
+        self,
+        orchestrator: str,
+        delegated_to: str | None,
+        error: str,
+        duration: float,
+    ) -> None:
+        """Log failed delegation."""
+        target = delegated_to or orchestrator
+        extra = {
+            "orchestrator": orchestrator,
+            "duration": duration,
+        }
+        if delegated_to:
+            extra["delegation_to"] = delegated_to
+
+        self.logger.error(f"✗ Delegation failed: {error}", extra=extra)
+
+    def retry_attempt(self, attempt: int, max_retries: int, error: str) -> None:
+        """Log retry attempt."""
+        self.logger.warning(
+            f"Retry attempt {attempt}/{max_retries}: {error}"
+        )
+
+    def timeout(self, orchestrator: str, timeout_seconds: float) -> None:
+        """Log timeout."""
+        self.logger.error(
+            f"Timeout after {timeout_seconds}s",
+            extra={"orchestrator": orchestrator}
+        )
+
+    def rule_match(self, pattern: str, delegate_to: str, confidence: int = 100) -> None:
+        """Log rule match."""
+        self.logger.info(
+            f"Rule matched: '{pattern}' → {delegate_to} (confidence: {confidence}%)"
+        )
+
+    def no_rule_match(self, query: str) -> None:
+        """Log when no rule matches."""
+        self.logger.debug(f"No delegation rule matched for query")
+
+
+# Global logger instance
+delegation_logger = DelegationLogger()

src/delegation_mcp/orchestrator.py

@@ -0,0 +1,250 @@
+"""Orchestrator registry and management."""
+
+import asyncio
+import os
+import re
+import shutil
+import subprocess
+from typing import Any
+from pathlib import Path
+
+from .config import OrchestratorConfig
+
+
+class OrchestratorRegistry:
+    """Registry for managing available orchestrators/CLIs."""
+
+    def __init__(self):
+        self.orchestrators: dict[str, OrchestratorConfig] = {}
+        self._active_sessions: dict[str, asyncio.subprocess.Process] = {}
+
+    def register(self, config: OrchestratorConfig) -> None:
+        """Register an orchestrator."""
+        self.orchestrators[config.name] = config
+
+    def unregister(self, name: str) -> None:
+        """Unregister an orchestrator."""
+        self.orchestrators.pop(name, None)
+
+    def get(self, name: str) -> OrchestratorConfig | None:
+        """Get orchestrator configuration."""
+        return self.orchestrators.get(name)
+
+    def list_enabled(self) -> list[str]:
+        """List all enabled orchestrators."""
+        return [name for name, config in self.orchestrators.items() if config.enabled]
+
+    @staticmethod
+    def _resolve_command(cmd: list[str]) -> list[str]:
+        """
+        Resolve command to full path on Windows.
+
+        On Windows, asyncio.create_subprocess_exec() doesn't reliably search PATH,
+        so we need to resolve commands to their full paths using shutil.which().
+
+        Args:
+            cmd: Command list
+
+        Returns:
+            Resolved command (full path on Windows, original on Unix)
+        """
+        if os.name != "nt" or not cmd:
+            # On Unix systems, PATH search works fine
+            return cmd
+
+        # On Windows, resolve the executable path
+        resolved = shutil.which(cmd[0])
+        if resolved:
+            return [resolved] + cmd[1:]
+        return cmd
+
+    async def execute(
+        self,
+        orchestrator_name: str,
+        task: str,
+        timeout: int | None = None,
+        progress_callback: Any = None,
+    ) -> tuple[str, str, int]:
+        """
+        Execute a task using specified orchestrator.
+
+        Args:
+            orchestrator_name: Name of orchestrator to use
+            task: Task description/query
+            timeout: Optional timeout in seconds
+            progress_callback: Optional async callback(line: str) for stdout streaming
+
+        Returns:
+            tuple: (stdout, stderr, return_code)
+        """
+        config = self.get(orchestrator_name)
+        if not config:
+            raise ValueError(f"Orchestrator '{orchestrator_name}' not found")
+
+        if not config.enabled:
+            raise ValueError(f"Orchestrator '{orchestrator_name}' is disabled")
+
+        # Build command
+        if isinstance(config.command, list):
+            cmd = config.command + config.args + [task]
+        else:
+            cmd = [config.command] + config.args + [task]
+
+        # Resolve command path on Windows
+        resolved_cmd = self._resolve_command(cmd)
+
+        # Execute with timeout
+        timeout_seconds = timeout or config.timeout
+        process = None
+
+        # Build safe environment with allowlist approach
+        # Only include essential environment variables
+        allowed_env_vars = [
+            'PATH', 'HOME', 'USER', 'LANG', 'LC_ALL', 'TERM',
+            'PYTHONPATH', 'NODE_PATH', 'OPENROUTER_API_KEY',
+            'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'GOOGLE_API_KEY',
+            'TMPDIR', 'TEMP', 'TMP', 'USERPROFILE', 'SYSTEMROOT',
+        ]
+        safe_env = {}
+        for key in allowed_env_vars:
+            if key in os.environ:
+                safe_env[key] = os.environ[key]
+
+        # Add config-specified env vars with validation
+        for key, value in config.env.items():
+            # Validate env var name (alphanumeric and underscore only)
+            if not re.match(r'^[A-Z_][A-Z0-9_]*$', key):
+                import logging
+                logging.getLogger(__name__).warning(
+                    f"Skipping invalid environment variable name: {key}"
+                )
+                continue
+            safe_env[key] = value
+
+        stdout_chunks = []
+        stderr_chunks = []
+
+        async def _read_stream(stream, is_stderr: bool):
+            while True:
+                line = await stream.readline()
+                if not line:
+                    break
+                text = line.decode("utf-8", errors="replace")
+                if is_stderr:
+                    stderr_chunks.append(text)
+                else:
+                    stdout_chunks.append(text)
+                
+                if on_output:
+                    try:
+                        await on_output(text, is_stderr)
+                    except Exception:
+                        pass  # Ignore callback errors
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *resolved_cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=safe_env,
+            )
+
+            stdout_chunks = []
+            stderr_chunks = []
+
+            async def read_stream(stream, chunks, callback=None):
+                while True:
+                    line = await stream.readline()
+                    if not line:
+                        break
+                    decoded_line = line.decode("utf-8", errors="replace")
+                    chunks.append(decoded_line)
+                    if callback:
+                        try:
+                            if asyncio.iscoroutinefunction(callback):
+                                await callback(decoded_line.strip())
+                            else:
+                                callback(decoded_line.strip())
+                        except Exception:
+                            pass  # Ignore callback errors to prevent crashing execution
+
+            # Create tasks for reading stdout and stderr
+            stdout_task = asyncio.create_task(
+                read_stream(process.stdout, stdout_chunks, progress_callback)
+            )
+            stderr_task = asyncio.create_task(
+                read_stream(process.stderr, stderr_chunks)
+            )
+
+            # Wait for everything to finish or timeout
+            try:
+                # We wait for the process AND the stream readers
+                # This ensures we don't timeout if the process is done but streams are still being read
+                # and conversely, we DO timeout if streams are blocked even if process is done (unlikely but possible)
+                # or if process is hanging.
+                await asyncio.wait_for(
+                    asyncio.gather(process.wait(), stdout_task, stderr_task),
+                    timeout=timeout_seconds
+                )
+            except asyncio.TimeoutError:
+                # Timeout occurred - clean up everything
+                if process:
+                    try:
+                        process.kill()
+                    except ProcessLookupError:
+                        pass
+                
+                # Cancel stream readers
+                stdout_task.cancel()
+                stderr_task.cancel()
+                
+                # Wait for cancellation to complete
+                try:
+                    await asyncio.gather(stdout_task, stderr_task, return_exceptions=True)
+                except Exception:
+                    pass
+
+                raise TimeoutError(
+                    f"Orchestrator '{orchestrator_name}' timed out after {timeout_seconds}s"
+                )
+
+            return (
+                "".join(stdout_chunks),
+                "".join(stderr_chunks),
+                process.returncode or 0,
+            )
+
+        except Exception as e:
+            if process and process.returncode is None:
+                try:
+                    process.kill()
+                    await process.wait()
+                except ProcessLookupError:
+                    pass
+            if isinstance(e, (TimeoutError, RuntimeError)):
+                raise e
+            raise RuntimeError(
+                f"Orchestrator '{orchestrator_name}' failed: {str(e)}"
+            ) from e
+
+    def validate_all(self) -> dict[str, bool]:
+        """
+        Validate all registered orchestrators are available.
+
+        Returns:
+            dict: {orchestrator_name: is_available}
+        """
+        results = {}
+        for name, config in self.orchestrators.items():
+            cmd = config.command if isinstance(config.command, str) else config.command[0]
+            try:
+                subprocess.run(
+                    ["which", cmd] if subprocess.os.name != "nt" else ["where", cmd],
+                    capture_output=True,
+                    check=True,
+                )
+                results[name] = True
+            except subprocess.CalledProcessError:
+                results[name] = False
+
+        return results

src/delegation_mcp/retry.py

@@ -0,0 +1,101 @@
+"""Retry logic with exponential backoff."""
+
+import asyncio
+import logging
+from typing import TypeVar, Callable, Any
+from functools import wraps
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+async def retry_with_backoff(
+    func: Callable[..., Any],
+    *args: Any,
+    max_retries: int = 3,
+    initial_delay: float = 1.0,
+    backoff_factor: float = 2.0,
+    exceptions: tuple = (Exception,),
+    **kwargs: Any,
+) -> Any:
+    """
+    Retry an async function with exponential backoff.
+
+    Args:
+        func: Async function to retry
+        *args: Positional arguments for func
+        max_retries: Maximum number of retry attempts
+        initial_delay: Initial delay in seconds
+        backoff_factor: Multiplier for delay on each retry
+        exceptions: Tuple of exceptions to catch and retry
+        **kwargs: Keyword arguments for func
+
+    Returns:
+        Result of successful function call
+
+    Raises:
+        Last exception if all retries fail
+    """
+    delay = initial_delay
+    last_exception = None
+
+    for attempt in range(max_retries + 1):
+        try:
+            return await func(*args, **kwargs)
+        except exceptions as e:
+            last_exception = e
+
+            if attempt == max_retries:
+                logger.error(
+                    f"Failed after {max_retries} retries: {str(e)}"
+                )
+                raise
+
+            logger.warning(
+                f"Attempt {attempt + 1}/{max_retries + 1} failed: {str(e)}. "
+                f"Retrying in {delay:.1f}s..."
+            )
+
+            await asyncio.sleep(delay)
+            delay *= backoff_factor
+
+    # This should never be reached, but just in case
+    if last_exception:
+        raise last_exception
+
+
+def with_retry(
+    max_retries: int = 3,
+    initial_delay: float = 1.0,
+    backoff_factor: float = 2.0,
+    exceptions: tuple = (Exception,),
+):
+    """
+    Decorator for adding retry logic to async functions.
+
+    Args:
+        max_retries: Maximum number of retry attempts
+        initial_delay: Initial delay in seconds
+        backoff_factor: Multiplier for delay on each retry
+        exceptions: Tuple of exceptions to catch and retry
+
+    Example:
+        @with_retry(max_retries=3, initial_delay=1.0)
+        async def fetch_data():
+            return await api.get('/data')
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            return await retry_with_backoff(
+                func,
+                *args,
+                max_retries=max_retries,
+                initial_delay=initial_delay,
+                backoff_factor=backoff_factor,
+                exceptions=exceptions,
+                **kwargs,
+            )
+        return wrapper
+    return decorator

src/delegation_mcp/server.py

@@ -0,0 +1,367 @@
+"""Main MCP server implementation.
+
+Lightweight discovery-only service that provides:
+- Routing guidance via capability-based task classification
+- On-demand agent discovery and registration
+- Agent availability listing
+"""
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.server.models import InitializationOptions
+from mcp.server.lowlevel import NotificationOptions
+from mcp.types import Tool, TextContent
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any
+from .config import DelegationConfig, OrchestratorConfig
+from .orchestrator import OrchestratorRegistry
+from .delegation import DelegationEngine
+from .agent_discovery import AgentDiscovery
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class DelegationMCPServer:
+    """MCP server for multi-orchestrator delegation."""
+
+    def __init__(
+        self,
+        config_path: Path | None = None,
+        enable_auto_discovery: bool = True,
+    ):
+        """Initialize lightweight MCP server.
+
+        Args:
+            config_path: Path to delegation rules config
+            enable_auto_discovery: Enable automatic agent discovery on startup
+        """
+        self.config_path = config_path or self._resolve_config_path()
+        self.config = self._load_config()
+        self.registry = OrchestratorRegistry()
+        self.engine = DelegationEngine(self.config, self.registry)
+        self.server = Server("delegation-mcp")
+
+        # Agent discovery system for auto-detecting installed agents
+        self.agent_discovery = AgentDiscovery()
+        self.enable_auto_discovery = enable_auto_discovery
+
+        self._setup_handlers()
+        self._register_orchestrators()
+
+    def _resolve_config_path(self) -> Path:
+        """Resolve config path with priority: project → user → defaults.
+        
+        Priority matches CLAUDE.md behavior:
+        1. Project-level config (can override user-level)
+        2. User-level config (fallback for global installs)
+        3. Project path (triggers default config creation)
+        """
+        # Check project-level config first (can override user-level)
+        project_config = Path("config/delegation_rules.yaml")
+        if project_config.exists():
+            return project_config
+        
+        # Fall back to user-level config
+        user_config = Path.home() / ".delegation-mcp" / "config" / "delegation_rules.yaml"
+        if user_config.exists():
+            return user_config
+        
+        # Return project path (will trigger default config creation)
+        return project_config
+
+    def _load_config(self) -> DelegationConfig:
+        """Load configuration from file."""
+        if self.config_path.exists():
+            return DelegationConfig.from_yaml(self.config_path)
+        return self._create_default_config()
+
+    def _create_default_config(self) -> DelegationConfig:
+        """Create default configuration."""
+        return DelegationConfig(
+            orchestrator="claude",
+            orchestrators={
+                "claude": OrchestratorConfig(
+                    name="claude",
+                    command="claude",
+                    args=["-p"],  # Non-interactive mode
+                    enabled=True
+                ),
+                "gemini": OrchestratorConfig(
+                    name="gemini",
+                    command="gemini",
+                    args=[],  # Gemini uses positional args by default
+                    enabled=True,
+                ),
+                "copilot": OrchestratorConfig(
+                    name="copilot", command="copilot", enabled=False
+                ),
+                "aider": OrchestratorConfig(
+                    name="aider",
+                    command="aider",
+                    args=["--yes", "--no-auto-commits"],  # Auto-approve, no commits
+                    enabled=False
+                ),
+            },
+        )
+
+    async def _discover_and_register_agents(self) -> None:
+        """Discover available agents and register them with the registry."""
+        if not self.enable_auto_discovery:
+            logger.info("Agent auto-discovery disabled")
+            return
+
+        logger.info("Starting agent auto-discovery...")
+        discovered = await self.agent_discovery.discover_agents()
+
+        # Register discovered agents that aren't already in config
+        for name, metadata in discovered.items():
+            if metadata.available and name not in self.config.orchestrators:
+                # Create config from discovered metadata
+                agent_config = OrchestratorConfig(
+                    name=name,
+                    command=metadata.command,
+                    enabled=True,
+                    timeout=300,
+                )
+                self.config.orchestrators[name] = agent_config
+                self.registry.register(agent_config)
+                logger.info(f"Auto-registered discovered agent: {name} ({metadata.version})")
+
+        # Report discovery summary
+        summary = self.agent_discovery.get_discovery_summary()
+        logger.info(
+            f"Agent discovery complete: {summary['available']}/{summary['total_agents']} agents available"
+        )
+
+        # Log unavailable agents with install instructions
+        for agent in self.agent_discovery.get_unavailable_agents():
+            logger.info(f"  {agent.name}: {agent.error_message}")
+
+    def _register_orchestrators(self) -> None:
+        """Register all orchestrators from config."""
+        for name, config in self.config.orchestrators.items():
+            self.registry.register(config)
+            logger.info(f"Registered orchestrator: {name} (enabled={config.enabled})")
+
+        # Validate availability
+        availability = self.registry.validate_all()
+        for name, available in availability.items():
+            if not available:
+                logger.warning(f"Orchestrator '{name}' not available in PATH")
+
+    def _setup_handlers(self) -> None:
+        """Setup MCP server handlers with on-demand tool loading."""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """List available lightweight tools for routing guidance and discovery.
+
+            Tools:
+            - get_routing_guidance: Returns which agent should handle a task (no execution)
+            - discover_agents: Discover and register available CLI agents
+            - list_agents: List registered agents and their availability
+            """
+            tools = [
+                Tool(
+                    name="get_routing_guidance",
+                    description="Get routing guidance for a task - returns which agent should handle it and the exact CLI command to run (guidance only, no execution)",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "query": {
+                                "type": "string",
+                                "description": "The task query to get routing guidance for",
+                            },
+                        },
+                        "required": ["query"],
+                    },
+                ),
+                Tool(
+                    name="discover_agents",
+                    description="Discover and register available CLI agents on the system",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "force_refresh": {
+                                "type": "boolean",
+                                "description": "Force re-discovery even if cache exists",
+                                "default": False,
+                            },
+                        },
+                    },
+                ),
+                Tool(
+                    name="list_agents",
+                    description="List all registered agents and their availability status",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {},
+                    },
+                ),
+            ]
+
+            logger.info(f"Listed {len(tools)} lightweight tools")
+            return tools
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: Any) -> list[TextContent]:
+            """Handle lightweight tool calls for routing guidance and discovery."""
+            try:
+                if name == "get_routing_guidance":
+                    # Get routing guidance without executing the task
+                    query = arguments["query"]
+
+                    # Classify the task to determine routing
+                    task_info = self.engine._classify_task(query)
+                    task_type = task_info[0] if isinstance(task_info, tuple) else task_info
+                    timeout = task_info[1] if isinstance(task_info, tuple) and len(task_info) > 1 else 300
+
+                    # Determine which agent should handle it
+                    agent, _ = self.engine._determine_delegation(query, None)
+
+                    if agent:
+                        agent_config = self.registry.get(agent)
+                        # Build the CLI command that should be run
+                        cmd_parts = [agent_config.command] + agent_config.args + [query]
+                        cli_command = " ".join(f'"{part}"' if " " in part else part for part in cmd_parts)
+
+                        response = {
+                            "decision": f"DELEGATE_TO: {agent}",
+                            "agent": agent,
+                            "task_type": task_type,
+                            "timeout": timeout,
+                            "cli_command": cli_command,
+                        }
+                    else:
+                        response = {
+                            "decision": "HANDLE_DIRECTLY",
+                            "task_type": task_type,
+                            "timeout": timeout,
+                        }
+
+                    import json
+                    return [TextContent(type="text", text=json.dumps(response, indent=2))]
+
+                elif name == "discover_agents":
+                    # Discover available agents
+                    force_refresh = arguments.get("force_refresh", False)
+                    discovered = await self.agent_discovery.discover_agents(force_refresh=force_refresh)
+
+                    # Register newly discovered agents
+                    registered_count = 0
+                    for agent_name, metadata in discovered.items():
+                        if metadata.available and agent_name not in self.config.orchestrators:
+                            agent_config = OrchestratorConfig(
+                                name=agent_name,
+                                command=metadata.command,
+                                enabled=True,
+                                timeout=300,
+                            )
+                            self.config.orchestrators[agent_name] = agent_config
+                            self.registry.register(agent_config)
+                            registered_count += 1
+                            logger.info(f"Registered new agent: {agent_name}")
+
+                    # Build response
+                    summary = self.agent_discovery.get_discovery_summary()
+                    text = f"Agent Discovery Results:\n\n"
+                    text += f"Total agents scanned: {summary['total_agents']}\n"
+                    text += f"Available: {summary['available']}\n"
+                    text += f"Unavailable: {summary['unavailable']}\n"
+                    text += f"Newly registered: {registered_count}\n\n"
+
+                    if summary['available_agents']:
+                        text += "Available Agents:\n"
+                        for agent in summary['available_agents']:
+                            text += f"  ✓ {agent['name']}: {agent['version']}\n"
+                            text += f"    Path: {agent['path']}\n"
+
+                    if summary['unavailable_agents']:
+                        text += "\nUnavailable Agents:\n"
+                        for agent in summary['unavailable_agents']:
+                            text += f"  ✗ {agent['name']}\n"
+                            text += f"    {agent['error']}\n"
+
+                    return [TextContent(type="text", text=text)]
+
+                elif name == "list_agents":
+                    # List registered agents and their availability
+                    enabled = self.registry.list_enabled()
+                    all_agents = list(self.registry.orchestrators.keys())
+                    availability = self.registry.validate_all()
+
+                    text = "Registered Agents:\n\n"
+                    for agent_name in all_agents:
+                        config = self.registry.get(agent_name)
+                        status = "✓ Enabled" if agent_name in enabled else "✗ Disabled"
+                        avail = "Available" if availability.get(agent_name) else "Not found in PATH"
+                        text += f"{agent_name}:\n"
+                        text += f"  Status: {status}\n"
+                        text += f"  Availability: {avail}\n"
+                        text += f"  Command: {config.command}\n"
+                        if config.args:
+                            text += f"  Args: {' '.join(config.args)}\n"
+                        text += "\n"
+
+                    return [TextContent(type="text", text=text)]
+
+                else:
+                    logger.error(f"Unknown tool: {name}")
+                    return [TextContent(type="text", text=f"Error: Unknown tool '{name}'")]
+
+            except Exception as e:
+                logger.error(f"Tool call failed: {name} - {e}", exc_info=True)
+                return [TextContent(type="text", text=f"Error: {str(e)}")]
+
+    async def run(self) -> None:
+        """Run the lightweight MCP server."""
+        logger.info("Starting delegation MCP server (lightweight mode)")
+        logger.info("- Mode: Routing guidance only (no execution)")
+        logger.info(f"- Agent auto-discovery: {'ON' if self.enable_auto_discovery else 'OFF'}")
+        logger.info("- Tools: get_routing_guidance, discover_agents, list_agents")
+
+        # Discover and register available agents
+        if self.enable_auto_discovery:
+            await self._discover_and_register_agents()
+
+        try:
+            async with stdio_server() as (read_stream, write_stream):
+                await self.server.run(
+                    read_stream,
+                    write_stream,
+                    InitializationOptions(
+                        server_name="delegation-mcp",
+                        server_version="0.4.0",  # Updated version for lightweight architecture
+                        capabilities=self.server.get_capabilities(
+                            notification_options=NotificationOptions(),
+                            experimental_capabilities={
+                                "agent_discovery": {},
+                                "routing_guidance": {},
+                            },
+                        ),
+                    ),
+                )
+        finally:
+            logger.info("Server stopped")
+
+
+def main():
+    """Main entry point."""
+    import sys
+
+    config_path = Path(sys.argv[1]) if len(sys.argv) > 1 else None
+    server = DelegationMCPServer(config_path)
+
+    try:
+        asyncio.run(server.run())
+    except KeyboardInterrupt:
+        logger.info("Server stopped")
+
+
+if __name__ == "__main__":
+    main()

src/delegation_mcp/tool_discovery.py

@@ -0,0 +1,243 @@
+"""File-based tool discovery system for on-demand loading.
+
+Following Anthropic's MCP architecture recommendations:
+- Organize tools in filesystem hierarchy
+- Load tool definitions on-demand
+- Implement search_tools capability with detail levels
+- Reduce token consumption by 98.7% (150,000 → 2,000 tokens)
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Literal
+from dataclasses import dataclass
+from mcp.types import Tool
+import json
+
+logger = logging.getLogger(__name__)
+
+
+DetailLevel = Literal["minimal", "standard", "full"]
+
+
+@dataclass
+class ToolMetadata:
+    """Lightweight tool metadata for search results."""
+
+    name: str
+    category: str
+    description: str
+    file_path: Path
+
+
+class ToolDiscoverySystem:
+    """File-based tool discovery with on-demand loading."""
+
+    def __init__(self, tools_dir: Path | None = None):
+        """Initialize tool discovery system.
+
+        Args:
+            tools_dir: Directory containing tool definitions (default: ./tools/)
+        """
+        self.tools_dir = tools_dir or Path("tools")
+        self._tool_cache: dict[str, Tool] = {}
+        self._metadata_cache: dict[str, ToolMetadata] = {}
+        self._initialize_metadata()
+
+    def _initialize_metadata(self) -> None:
+        """Initialize lightweight metadata index for all tools."""
+        if not self.tools_dir.exists():
+            logger.warning(f"Tools directory not found: {self.tools_dir}")
+            self._load_default_tools()
+            return
+
+        for tool_file in self.tools_dir.rglob("*.json"):
+            try:
+                with open(tool_file) as f:
+                    data = json.load(f)
+                    metadata = ToolMetadata(
+                        name=data["name"],
+                        category=data.get("category", "general"),
+                        description=data.get("description", ""),
+                        file_path=tool_file,
+                    )
+                    self._metadata_cache[metadata.name] = metadata
+                    logger.debug(f"Indexed tool: {metadata.name}")
+            except Exception as e:
+                logger.error(f"Failed to index tool {tool_file}: {e}")
+
+    def _load_default_tools(self) -> None:
+        """Load default tool metadata when no tools directory exists."""
+        default_tools = [
+            ToolMetadata(
+                name="delegate_task",
+                category="orchestration",
+                description="Delegate a coding task to appropriate AI agent",
+                file_path=Path("tools/orchestration/delegate_task.json"),
+            ),
+            ToolMetadata(
+                name="list_orchestrators",
+                category="orchestration",
+                description="List available orchestrators and their status",
+                file_path=Path("tools/orchestration/list_orchestrators.json"),
+            ),
+            ToolMetadata(
+                name="get_statistics",
+                category="monitoring",
+                description="Get delegation statistics and metrics",
+                file_path=Path("tools/monitoring/get_statistics.json"),
+            ),
+        ]
+        for metadata in default_tools:
+            self._metadata_cache[metadata.name] = metadata
+
+    def search_tools(
+        self,
+        query: str | None = None,
+        category: str | None = None,
+        detail: DetailLevel = "minimal",
+    ) -> list[dict[str, Any]]:
+        """Search tools with configurable detail level.
+
+        Args:
+            query: Search query to match against tool names/descriptions
+            category: Filter by tool category
+            detail: Level of detail to return
+                - minimal: name + category only (lowest token cost)
+                - standard: + description
+                - full: + complete schema (highest token cost)
+
+        Returns:
+            List of tool information at requested detail level
+        """
+        results = []
+
+        for name, metadata in self._metadata_cache.items():
+            # Apply filters
+            if category and metadata.category != category:
+                continue
+            if query and query.lower() not in name.lower() and query.lower() not in metadata.description.lower():
+                continue
+
+            # Build result based on detail level
+            if detail == "minimal":
+                results.append({
+                    "name": name,
+                    "category": metadata.category,
+                })
+            elif detail == "standard":
+                results.append({
+                    "name": name,
+                    "category": metadata.category,
+                    "description": metadata.description,
+                })
+            else:  # full
+                tool = self.load_tool(name)
+                if tool:
+                    results.append({
+                        "name": name,
+                        "category": metadata.category,
+                        "description": tool.description,
+                        "inputSchema": tool.inputSchema,
+                    })
+
+        logger.info(f"Tool search: query={query}, category={category}, detail={detail}, results={len(results)}")
+        return results
+
+    def load_tool(self, name: str) -> Tool | None:
+        """Load complete tool definition on-demand.
+
+        Args:
+            name: Tool name
+
+        Returns:
+            Complete Tool object with schema, or None if not found
+        """
+        # Check cache first
+        if name in self._tool_cache:
+            logger.debug(f"Tool cache hit: {name}")
+            return self._tool_cache[name]
+
+        # Load from file
+        metadata = self._metadata_cache.get(name)
+        if not metadata:
+            logger.warning(f"Tool not found: {name}")
+            return None
+
+        # If file doesn't exist, create tool from metadata (for default tools)
+        if not metadata.file_path.exists():
+            tool = self._create_default_tool(name)
+            if tool:
+                self._tool_cache[name] = tool
+            return tool
+
+        try:
+            with open(metadata.file_path) as f:
+                data = json.load(f)
+                tool = Tool(
+                    name=data["name"],
+                    description=data.get("description", ""),
+                    inputSchema=data.get("inputSchema", {"type": "object", "properties": {}}),
+                )
+                self._tool_cache[name] = tool
+                logger.debug(f"Loaded tool from file: {name}")
+                return tool
+        except Exception as e:
+            logger.error(f"Failed to load tool {name}: {e}")
+            return None
+
+    def _create_default_tool(self, name: str) -> Tool | None:
+        """Create default tool definitions for backward compatibility."""
+        if name == "delegate_task":
+            return Tool(
+                name="delegate_task",
+                description="Route task to specialist agent or confirm orchestrator should handle directly. Always call BEFORE code work to get routing guidance.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Full user request/task to route",
+                        },
+                        "orchestrator": {
+                            "type": "string",
+                            "description": "Override primary orchestrator",
+                        },
+                        "force_delegate": {
+                            "type": "string",
+                            "description": "Force delegation to specific agent",
+                        },
+                        "guidance_only": {
+                            "type": "boolean",
+                            "description": "Return routing guidance without executing (default: false)",
+                            "default": False,
+                        },
+                    },
+                    "required": ["query"],
+                },
+            )
+        elif name == "list_orchestrators":
+            return Tool(
+                name="list_orchestrators",
+                description="List available orchestrators and their status",
+                inputSchema={"type": "object", "properties": {}},
+            )
+        elif name == "get_statistics":
+            return Tool(
+                name="get_statistics",
+                description="Get delegation statistics and metrics",
+                inputSchema={"type": "object", "properties": {}},
+            )
+        return None
+
+    def list_categories(self) -> list[str]:
+        """List all available tool categories."""
+        categories = {metadata.category for metadata in self._metadata_cache.values()}
+        return sorted(categories)
+
+    def get_tool_count(self) -> dict[str, int]:
+        """Get tool count by category."""
+        counts: dict[str, int] = {}
+        for metadata in self._metadata_cache.values():
+            counts[metadata.category] = counts.get(metadata.category, 0) + 1
+        return counts

src/delegation_mcp/ui/__init__.py

@@ -0,0 +1,19 @@
+"""
+Gradio UI for Delegation MCP.
+
+Contains:
+- Monitor tab: Live delegation activity monitoring
+- Configuration tab: Runtime agent and routing rules management
+- Main app: Integrated multi-tab interface
+"""
+
+from .app import create_app, main
+from .config_tab import create_config_tab
+from .config_manager import ConfigurationManager
+
+__all__ = [
+    "create_app",
+    "main",
+    "create_config_tab",
+    "ConfigurationManager",
+]

src/delegation_mcp/ui/app.py

@@ -0,0 +1,216 @@
+"""Main Gradio application with monitoring and configuration tabs."""
+
+try:
+    import gradio as gr
+    GRADIO_AVAILABLE = True
+except ImportError:
+    GRADIO_AVAILABLE = False
+    # Mock gr for type hinting if needed, or just handle availability check
+    gr = None  # type: ignore
+
+from pathlib import Path
+from datetime import datetime
+from collections import deque
+
+# from ..persistence import PersistenceManager
+from .config_tab import create_config_tab
+from .config_manager import ConfigurationManager
+
+
+class DelegationMonitor:
+    """Monitors delegation activity for demo visualization."""
+
+    def __init__(self, db_path: Path = Path("data/delegation.db")):
+        # self.persistence = PersistenceManager(db_path)
+        self.recent_events = deque(maxlen=20)  # Keep last 20 events
+
+    def get_recent_activity(self):
+        """Get recent delegation events for display."""
+        return []
+        # try:
+        #     history = self.persistence.get_task_history(limit=20)
+        #     return [
+        #         [
+        #             entry.timestamp.strftime("%H:%M:%S"),
+        #             entry.orchestrator,
+        #             entry.delegated_to or "N/A",
+        #             "✅" if entry.success else "❌",
+        #             f"{entry.duration:.2f}s"
+        #         ]
+        #         for entry in history
+        #     ]
+        # except Exception:
+        #     return []
+
+    def get_statistics(self):
+        """Get delegation statistics for charts."""
+        return {"total": 0, "success_rate": 0.0, "avg_duration": 0.0, "agent_usage": {}}
+        # try:
+        #     stats = self.persistence.get_statistics()
+        #     return {
+        #         "total": stats.get("total_tasks", 0),
+        #         "success_rate": stats.get("success_rate", 0.0),
+        #         "avg_duration": stats.get("avg_duration", 0.0),
+        #         "agent_usage": stats.get("agent_usage", {}),
+        #     }
+        # except Exception:
+        #     return {"total": 0, "success_rate": 0.0, "avg_duration": 0.0, "agent_usage": {}}
+
+
+def create_app(
+    config_manager: ConfigurationManager | None = None,
+    db_path: Path = Path("data/delegation.db"),
+):
+    """Create main Gradio application with multiple tabs.
+
+    Args:
+        config_manager: Optional ConfigurationManager instance
+        db_path: Path to delegation database for monitoring
+
+    Returns:
+        Gradio Blocks application with Monitor and Configuration tabs
+    """
+    if not GRADIO_AVAILABLE:
+        print("Error: Gradio is not installed. Please install with `pip install .[ui]`")
+        return None
+
+    if config_manager is None:
+        config_manager = ConfigurationManager()
+
+    monitor = DelegationMonitor(db_path)
+
+    # Create the main application with tabs
+    with gr.Blocks(
+        title="Delegation MCP - Monitor & Configuration",
+        theme=gr.themes.Soft(),
+    ) as app:
+        gr.Markdown("""
+        # 🚀 Delegation MCP - Multi-Agent Orchestration
+
+        **Monitor delegation activity and configure agent routing in real-time.**
+
+        This interface provides two main functions:
+        - **Monitor**: View live delegation activity and statistics (for demos and debugging)
+        - **Configuration**: Manage agents and routing rules with immediate effect
+        """)
+
+        with gr.Tabs() as tabs:
+            # Tab 1: Monitor
+            with gr.Tab("📊 Monitor"):
+                gr.Markdown("""
+                # 🔍 Delegation MCP - Live Activity Monitor
+
+                **This monitor shows real-time delegation activity** when Claude Code (or other MCP clients)
+                call the delegation MCP server.
+
+                **How to use:**
+                1. Start the MCP server: `delegation-mcp`
+                2. Configure Claude Code to use it (see README.md)
+                3. Chat with Claude Code and ask it to delegate tasks
+                4. Watch delegations appear here in real-time!
+
+                ---
+                """)
+
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        gr.Markdown("### 📊 Statistics")
+                        total_tasks = gr.Number(label="Total Tasks", value=0, interactive=False)
+                        success_rate = gr.Number(label="Success Rate (%)", value=0, interactive=False)
+                        avg_duration = gr.Number(label="Avg Duration (s)", value=0, interactive=False)
+
+                    with gr.Column(scale=2):
+                        gr.Markdown("### 🤖 Agent Usage")
+                        agent_chart = gr.BarPlot(
+                            x="agent",
+                            y="count",
+                            title="Delegations by Agent",
+                        )
+
+                gr.Markdown("### 📝 Recent Delegations")
+                activity_table = gr.Dataframe(
+                    headers=["Time", "From", "To", "Status", "Duration"],
+                    label="Live Activity",
+                    interactive=False,
+                    wrap=True,
+                )
+
+                refresh_btn = gr.Button("🔄 Refresh", variant="primary")
+
+                def refresh_all():
+                    """Refresh all monitor data."""
+                    # Get statistics
+                    stats = monitor.get_statistics()
+
+                    # Get recent activity
+                    activity = monitor.get_recent_activity()
+
+                    # Format agent usage for chart
+                    agent_data = []
+                    for agent, count in stats["agent_usage"].items():
+                        agent_data.append({"agent": agent, "count": count})
+
+                    return (
+                        stats["total"],
+                        stats["success_rate"] * 100,
+                        stats["avg_duration"],
+                        {"data": agent_data} if agent_data else None,
+                        activity,
+                    )
+
+                # Wire up refresh button
+                refresh_btn.click(
+                    fn=refresh_all,
+                    outputs=[total_tasks, success_rate, avg_duration, agent_chart, activity_table],
+                )
+
+                # Auto-refresh on load
+                app.load(
+                    fn=refresh_all,
+                    outputs=[total_tasks, success_rate, avg_duration, agent_chart, activity_table],
+                )
+
+
+            # Tab 2: Configuration
+            with gr.Tab("⚙️ Configuration"):
+                config_tab = create_config_tab(config_manager)
+
+        gr.Markdown("""
+        ---
+        ### Getting Started
+
+        1. Configure agents in the Configuration tab
+        2. Set up routing rules for automatic task delegation
+        3. Start the MCP server: `delegation-mcp`
+        4. Connect MCP clients (Claude Code, etc.)
+        5. Watch delegations in the Monitor tab
+
+        Changes take effect immediately. See [GitHub](https://github.com/carlosduplar/multi-agent-mcp) for docs.
+        """)
+
+    return app
+
+
+def main(
+    server_name: str = "0.0.0.0",
+    server_port: int = 7860,
+    share: bool = False,
+):
+    """Launch the Gradio application.
+
+    Args:
+        server_name: Server hostname (default: 0.0.0.0 for all interfaces)
+        server_port: Server port (default: 7860)
+        share: Enable Gradio share link (default: False)
+    """
+    app = create_app()
+    if app:
+        app.launch(
+            server_name=server_name,
+            server_port=server_port,
+            share=share,
+        )
+
+
+if __name__ == "__main__":
+    main()

src/delegation_mcp/ui/config_manager.py

@@ -0,0 +1,396 @@
+"""Configuration manager for runtime agent and routing rules management."""
+
+import yaml
+import re
+from pathlib import Path
+from typing import Any
+from dataclasses import dataclass
+
+from ..config import DelegationConfig, OrchestratorConfig, DelegationRule
+from ..orchestrator import OrchestratorRegistry
+
+
+@dataclass
+class AgentStatus:
+    """Agent status information."""
+
+    name: str
+    enabled: bool
+    installed: bool
+    config: OrchestratorConfig | None
+    status_text: str
+    status_icon: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for UI display."""
+        return {
+            "name": self.name,
+            "enabled": self.enabled,
+            "installed": self.installed,
+            "status": self.status_text,
+            "icon": self.status_icon,
+        }
+
+
+class ConfigurationManager:
+    """Manages agent configuration and routing rules."""
+
+    def __init__(
+        self,
+        orchestrators_path: Path = Path("config/orchestrators.yaml"),
+        rules_path: Path = Path("config/delegation_rules.yaml"),
+    ):
+        """Initialize configuration manager.
+
+        Args:
+            orchestrators_path: Path to orchestrators YAML config
+            rules_path: Path to delegation rules YAML config
+        """
+        self.orchestrators_path = orchestrators_path
+        self.rules_path = rules_path
+        self.registry = OrchestratorRegistry()
+
+        # Store default configurations for reset functionality
+        self.default_orchestrators: dict[str, Any] = {}
+        self.default_rules: list[dict[str, Any]] = []
+
+        # Load configurations
+        self.load_configurations()
+
+    def load_configurations(self) -> None:
+        """Load orchestrator and delegation rule configurations."""
+        # Load orchestrators
+        with open(self.orchestrators_path) as f:
+            orch_data = yaml.safe_load(f)
+            self.orchestrators_config = orch_data.get("orchestrators", {})
+
+            # Store defaults
+            if not self.default_orchestrators:
+                self.default_orchestrators = {
+                    k: v.copy() for k, v in self.orchestrators_config.items()
+                }
+
+            # Register orchestrators
+            for name, config in self.orchestrators_config.items():
+                self.registry.register(OrchestratorConfig(**config))
+
+        # Load delegation rules
+        with open(self.rules_path) as f:
+            rules_data = yaml.safe_load(f)
+            self.primary_orchestrator = rules_data.get("orchestrator", "claude")
+            self.rules_list = rules_data.get("rules", [])
+
+            # Store defaults
+            if not self.default_rules:
+                self.default_rules = [r.copy() for r in self.rules_list]
+
+    def get_agent_statuses(self) -> list[AgentStatus]:
+        """Get status information for all agents.
+
+        Returns:
+            List of AgentStatus objects with installation and enablement info
+        """
+        # Validate which agents are installed
+        installed_agents = self.registry.validate_all()
+
+        statuses = []
+        for name, config_dict in self.orchestrators_config.items():
+            config = OrchestratorConfig(**config_dict)
+            is_installed = installed_agents.get(name, False)
+            is_enabled = config.enabled
+
+            # Determine status
+            if is_enabled and is_installed:
+                status_text = "Active"
+                status_icon = "🟢"
+            elif is_enabled and not is_installed:
+                status_text = "Not Installed"
+                status_icon = "⚠️"
+            else:
+                status_text = "Disabled"
+                status_icon = "🔴"
+
+            statuses.append(AgentStatus(
+                name=name,
+                enabled=is_enabled,
+                installed=is_installed,
+                config=config,
+                status_text=status_text,
+                status_icon=status_icon,
+            ))
+
+        return statuses
+
+    def toggle_agent(self, agent_name: str, enabled: bool) -> tuple[bool, str]:
+        """Toggle an agent on or off.
+
+        Args:
+            agent_name: Name of the agent to toggle
+            enabled: True to enable, False to disable
+
+        Returns:
+            tuple: (success, message)
+        """
+        if agent_name not in self.orchestrators_config:
+            return False, f"Agent '{agent_name}' not found"
+
+        # Check if this is the primary orchestrator
+        if not enabled and agent_name == self.primary_orchestrator:
+            return False, f"Cannot disable primary orchestrator '{agent_name}'. Please select a different primary orchestrator first."
+
+        # Check if disabling would break any routing rules
+        if not enabled:
+            broken_rules = [
+                rule for rule in self.rules_list
+                if rule.get("delegate_to") == agent_name
+            ]
+            if broken_rules:
+                rule_descriptions = [r.get("description", r.get("pattern")) for r in broken_rules]
+                return False, f"Cannot disable '{agent_name}'. It is used in {len(broken_rules)} routing rule(s): {', '.join(rule_descriptions[:3])}"
+
+        # Update configuration
+        self.orchestrators_config[agent_name]["enabled"] = enabled
+
+        # Update registry
+        config = OrchestratorConfig(**self.orchestrators_config[agent_name])
+        self.registry.register(config)
+
+        return True, f"Agent '{agent_name}' {'enabled' if enabled else 'disabled'} successfully"
+
+    def set_primary_orchestrator(self, agent_name: str) -> tuple[bool, str]:
+        """Set the primary orchestrator.
+
+        Args:
+            agent_name: Name of the agent to set as primary
+
+        Returns:
+            tuple: (success, message)
+        """
+        if agent_name not in self.orchestrators_config:
+            return False, f"Agent '{agent_name}' not found"
+
+        config = self.orchestrators_config[agent_name]
+
+        # Validate agent is enabled
+        if not config.get("enabled", False):
+            return False, f"Cannot set '{agent_name}' as primary orchestrator because it is disabled. Please enable it first."
+
+        # Validate agent is installed
+        installed = self.registry.validate_all()
+        if not installed.get(agent_name, False):
+            return False, f"Cannot set '{agent_name}' as primary orchestrator because it is not installed."
+
+        self.primary_orchestrator = agent_name
+        return True, f"Primary orchestrator set to '{agent_name}'"
+
+    def validate_routing_rules(self, yaml_text: str) -> tuple[bool, str, list[dict[str, Any]] | None]:
+        """Validate routing rules YAML.
+
+        Args:
+            yaml_text: YAML text to validate
+
+        Returns:
+            tuple: (is_valid, message, parsed_rules)
+        """
+        try:
+            # Parse YAML
+            data = yaml.safe_load(yaml_text)
+
+            if not isinstance(data, list):
+                return False, "Rules must be a list", None
+
+            # Validate each rule
+            for i, rule in enumerate(data):
+                if not isinstance(rule, dict):
+                    return False, f"Rule {i+1} must be a dictionary", None
+
+                # Required fields
+                if "pattern" not in rule:
+                    return False, f"Rule {i+1} missing required field 'pattern'", None
+                if "delegate_to" not in rule:
+                    return False, f"Rule {i+1} missing required field 'delegate_to'", None
+
+                # Validate regex pattern
+                try:
+                    re.compile(rule["pattern"])
+                except re.error as e:
+                    return False, f"Rule {i+1} has invalid regex pattern: {e}", None
+
+                # Validate delegate_to exists
+                delegate_to = rule["delegate_to"]
+                if delegate_to not in self.orchestrators_config:
+                    return False, f"Rule {i+1} delegates to unknown agent '{delegate_to}'", None
+
+                # Validate delegate_to is enabled
+                if not self.orchestrators_config[delegate_to].get("enabled", False):
+                    return False, f"Rule {i+1} delegates to disabled agent '{delegate_to}'", None
+
+                # Validate priority is a number
+                if "priority" in rule and not isinstance(rule["priority"], (int, float)):
+                    return False, f"Rule {i+1} priority must be a number", None
+
+            return True, "✅ Routing rules are valid", data
+
+        except yaml.YAMLError as e:
+            return False, f"YAML parsing error: {e}", None
+        except Exception as e:
+            return False, f"Validation error: {e}", None
+
+    def preview_routing_rules(self, rules: list[dict[str, Any]]) -> str:
+        """Generate a preview of how routing rules will affect delegation.
+
+        Args:
+            rules: List of routing rules
+
+        Returns:
+            Formatted preview text
+        """
+        if not rules:
+            return "No routing rules defined. All tasks will go to the primary orchestrator."
+
+        preview = "## Routing Rules Preview\n\n"
+        preview += f"**Primary Orchestrator:** {self.primary_orchestrator}\n\n"
+
+        # Sort by priority (highest first)
+        sorted_rules = sorted(rules, key=lambda r: r.get("priority", 0), reverse=True)
+
+        preview += "**Rules (by priority):**\n\n"
+        for i, rule in enumerate(sorted_rules, 1):
+            pattern = rule.get("pattern", "")
+            delegate_to = rule.get("delegate_to", "")
+            priority = rule.get("priority", 0)
+            description = rule.get("description", "")
+
+            preview += f"{i}. **Pattern:** `{pattern}`\n"
+            preview += f"   **Delegates to:** {delegate_to}\n"
+            preview += f"   **Priority:** {priority}\n"
+            if description:
+                preview += f"   **Description:** {description}\n"
+            preview += "\n"
+
+        # Add example queries
+        preview += "\n**Example Query Matching:**\n\n"
+        example_queries = [
+            "Fix this security vulnerability",
+            "Refactor the authentication module",
+            "Create a pull request for this feature",
+            "Run the test suite",
+        ]
+
+        for query in example_queries:
+            matched = False
+            for rule in sorted_rules:
+                if re.search(rule["pattern"], query, re.IGNORECASE):
+                    preview += f"- \"{query}\" → **{rule['delegate_to']}** (matches: `{rule['pattern']}`)\n"
+                    matched = True
+                    break
+
+            if not matched:
+                preview += f"- \"{query}\" → **{self.primary_orchestrator}** (no rule match)\n"
+
+        return preview
+
+    def save_configurations(self, rules_yaml: str | None = None) -> tuple[bool, str]:
+        """Save configurations to YAML files.
+
+        Args:
+            rules_yaml: Optional YAML text for routing rules
+
+        Returns:
+            tuple: (success, message)
+        """
+        try:
+            # Save orchestrators
+            with open(self.orchestrators_path, "w") as f:
+                yaml.dump(
+                    {"orchestrators": self.orchestrators_config},
+                    f,
+                    default_flow_style=False,
+                    sort_keys=False,
+                )
+
+            # Save delegation rules
+            rules_data = {
+                "orchestrator": self.primary_orchestrator,
+            }
+
+            if rules_yaml:
+                # Validate and use provided rules
+                is_valid, message, parsed_rules = self.validate_routing_rules(rules_yaml)
+                if not is_valid:
+                    return False, f"Cannot save: {message}"
+                rules_data["rules"] = parsed_rules
+                self.rules_list = parsed_rules or []
+            else:
+                rules_data["rules"] = self.rules_list
+
+            with open(self.rules_path, "w") as f:
+                # Add comment header
+                f.write("# Delegation MCP Configuration\n")
+                f.write("# Configure your primary orchestrator and delegation rules\n")
+                f.write("# Note: Orchestrator definitions are in config/orchestrators.yaml\n\n")
+                yaml.dump(rules_data, f, default_flow_style=False, sort_keys=False)
+
+            return True, "✅ Configuration saved successfully"
+
+        except Exception as e:
+            return False, f"Failed to save configuration: {e}"
+
+    def reset_to_defaults(self) -> tuple[bool, str]:
+        """Reset all configurations to defaults.
+
+        Returns:
+            tuple: (success, message)
+        """
+        try:
+            # Reset orchestrators
+            self.orchestrators_config = {
+                k: v.copy() for k, v in self.default_orchestrators.items()
+            }
+
+            # Reset rules
+            self.rules_list = [r.copy() for r in self.default_rules]
+            self.primary_orchestrator = "claude"
+
+            # Re-register orchestrators
+            for name, config in self.orchestrators_config.items():
+                self.registry.register(OrchestratorConfig(**config))
+
+            # Save defaults
+            success, message = self.save_configurations()
+            if success:
+                return True, "✅ Configuration reset to defaults"
+            return False, f"Failed to save defaults: {message}"
+
+        except Exception as e:
+            return False, f"Failed to reset configuration: {e}"
+
+    def get_rules_yaml(self) -> str:
+        """Get current routing rules as YAML text.
+
+        Returns:
+            YAML text of routing rules
+        """
+        return yaml.dump(self.rules_list, default_flow_style=False, sort_keys=False)
+
+    def get_agent_capabilities(self, agent_name: str) -> dict[str, Any]:
+        """Get agent capabilities from configuration.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Dictionary of agent capabilities
+        """
+        if agent_name not in self.orchestrators_config:
+            return {}
+
+        config = self.orchestrators_config[agent_name]
+
+        return {
+            "command": config.get("command", ""),
+            "args": config.get("args", []),
+            "timeout": config.get("timeout", 300),
+            "max_retries": config.get("max_retries", 3),
+            "enabled": config.get("enabled", False),
+        }

src/delegation_mcp/ui/config_tab.py

@@ -0,0 +1,334 @@
+"""Configuration tab for Gradio UI - manage agents and routing rules."""
+
+try:
+    import gradio as gr
+    GRADIO_AVAILABLE = True
+except ImportError:
+    GRADIO_AVAILABLE = False
+    # Mock gr for type hinting if needed, or just handle availability check
+    gr = None  # type: ignore
+
+from pathlib import Path
+
+from .config_manager import ConfigurationManager, AgentStatus
+
+
+def create_config_tab(config_manager: ConfigurationManager | None = None) -> gr.Blocks | None:
+    """Create configuration tab for runtime agent and routing management.
+
+    Args:
+        config_manager: Optional ConfigurationManager instance (creates new if None)
+
+    Returns:
+        Gradio Blocks interface for configuration
+    """
+    if not GRADIO_AVAILABLE:
+        print("Error: Gradio is not installed. Please install with `pip install .[ui]`")
+        return None
+
+    if config_manager is None:
+        config_manager = ConfigurationManager()
+
+    with gr.Blocks() as config_tab:
+        gr.Markdown("""
+        # ⚙️ Agent Configuration
+
+        Configure which agents are active and how tasks are routed between them.
+        Changes take effect immediately after saving.
+        """)
+
+        # Status message for feedback
+        status_msg = gr.Markdown("", visible=False)
+
+        # Main layout
+        with gr.Row():
+            # Left column: Agent Management
+            with gr.Column(scale=1):
+                gr.Markdown("## 🤖 Available Agents")
+
+                # Primary orchestrator selection
+                agent_statuses = config_manager.get_agent_statuses()
+                agent_names = [status.name for status in agent_statuses if status.installed and status.enabled]
+
+                primary_dropdown = gr.Dropdown(
+                    choices=agent_names,
+                    value=config_manager.primary_orchestrator,
+                    label="Primary Orchestrator",
+                    info="Default agent when no routing rules match",
+                    interactive=True,
+                )
+
+                gr.Markdown("### Agent Status")
+
+                # Create agent toggles and status displays
+                agent_components = {}
+                for status in agent_statuses:
+                    with gr.Row():
+                        with gr.Column(scale=2):
+                            # Agent name and status
+                            gr.Markdown(f"**{status.status_icon} {status.name}**")
+                            gr.Markdown(f"*{status.status_text}*")
+
+                        with gr.Column(scale=1):
+                            # Toggle switch
+                            toggle = gr.Checkbox(
+                                value=status.enabled,
+                                label="Enabled",
+                                interactive=status.installed,  # Only allow toggle if installed
+                                elem_id=f"agent_{status.name}_toggle",
+                            )
+                            agent_components[status.name] = toggle
+
+                        with gr.Column(scale=1):
+                            # Capabilities info button
+                            with gr.Accordion(f"ℹ️", open=False):
+                                caps = config_manager.get_agent_capabilities(status.name)
+                                gr.Markdown(f"""
+                                **Command:** `{caps.get('command', 'N/A')}`
+
+                                **Args:** {' '.join(caps.get('args', []))}
+
+                                **Timeout:** {caps.get('timeout', 300)}s
+
+                                **Max Retries:** {caps.get('max_retries', 3)}
+                                """)
+
+            # Right column: Routing Rules
+            with gr.Column(scale=2):
+                gr.Markdown("## 🔀 Routing Rules")
+
+                # Rules editor
+                rules_yaml = config_manager.get_rules_yaml()
+                rules_editor = gr.TextArea(
+                    value=rules_yaml,
+                    label="Routing Rules (YAML)",
+                    placeholder="Enter routing rules in YAML format...",
+                    lines=15,
+                    max_lines=25,
+                )
+
+                # Validation message
+                validation_msg = gr.Markdown("", visible=False)
+
+                # Buttons row
+                with gr.Row():
+                    validate_btn = gr.Button("✓ Validate Rules", variant="secondary")
+                    preview_btn = gr.Button("👁️ Preview", variant="secondary")
+
+                # Preview panel
+                with gr.Accordion("📋 Routing Preview", open=False) as preview_accordion:
+                    preview_text = gr.Markdown("")
+
+        # Bottom buttons
+        with gr.Row():
+            save_btn = gr.Button("💾 Save Configuration", variant="primary", size="lg")
+            reset_btn = gr.Button("🔄 Reset to Defaults", variant="stop")
+
+        # === Event Handlers ===
+
+        def update_agent_toggle(agent_name: str, enabled: bool):
+            """Handle agent toggle."""
+            success, message = config_manager.toggle_agent(agent_name, enabled)
+
+            if not success:
+                # Revert the toggle
+                return {
+                    status_msg: gr.Markdown(
+                        f"❌ **Error:** {message}",
+                        visible=True
+                    ),
+                    agent_components[agent_name]: gr.Checkbox(value=not enabled),
+                }
+
+            # Update primary dropdown choices if needed
+            agent_statuses = config_manager.get_agent_statuses()
+            active_agents = [s.name for s in agent_statuses if s.installed and s.enabled]
+
+            return {
+                status_msg: gr.Markdown(
+                    f"✅ {message}",
+                    visible=True
+                ),
+                primary_dropdown: gr.Dropdown(choices=active_agents),
+            }
+
+        def set_primary_orchestrator(agent_name: str):
+            """Handle primary orchestrator selection."""
+            success, message = config_manager.set_primary_orchestrator(agent_name)
+
+            if not success:
+                return {
+                    status_msg: gr.Markdown(
+                        f"❌ **Error:** {message}",
+                        visible=True
+                    ),
+                    primary_dropdown: gr.Dropdown(value=config_manager.primary_orchestrator),
+                }
+
+            return status_msg.update(
+                value=f"✅ {message}",
+                visible=True
+            )
+
+        def validate_rules(yaml_text: str):
+            """Validate routing rules."""
+            is_valid, message, _ = config_manager.validate_routing_rules(yaml_text)
+
+            if is_valid:
+                return validation_msg.update(
+                    value=f"✅ {message}",
+                    visible=True
+                )
+            else:
+                return validation_msg.update(
+                    value=f"❌ **Validation Error:** {message}",
+                    visible=True
+                )
+
+        def preview_rules(yaml_text: str):
+            """Generate routing rules preview."""
+            is_valid, message, parsed_rules = config_manager.validate_routing_rules(yaml_text)
+
+            if not is_valid:
+                return {
+                    preview_text: gr.Markdown(f"❌ **Cannot preview:** {message}"),
+                    preview_accordion: gr.Accordion(open=True),
+                }
+
+            preview = config_manager.preview_routing_rules(parsed_rules or [])
+
+            return {
+                preview_text: gr.Markdown(preview),
+                preview_accordion: gr.Accordion(open=True),
+            }
+
+        def save_configuration(yaml_text: str):
+            """Save all configuration changes."""
+            # Validate rules first
+            is_valid, message, _ = config_manager.validate_routing_rules(yaml_text)
+            if not is_valid:
+                return status_msg.update(
+                    value=f"❌ **Cannot save:** {message}",
+                    visible=True
+                )
+
+            # Save configuration
+            success, message = config_manager.save_configurations(rules_yaml=yaml_text)
+
+            if success:
+                return status_msg.update(
+                    value=f"✅ **Configuration saved successfully!** Changes are now active.",
+                    visible=True
+                )
+            else:
+                return status_msg.update(
+                    value=f"❌ **Save failed:** {message}",
+                    visible=True
+                )
+
+        def reset_configuration():
+            """Reset configuration to defaults."""
+            success, message = config_manager.reset_to_defaults()
+
+            if not success:
+                return {
+                    status_msg: gr.Markdown(
+                        f"❌ **Reset failed:** {message}",
+                        visible=True
+                    ),
+                }
+
+            # Reload UI with defaults
+            agent_statuses = config_manager.get_agent_statuses()
+            active_agents = [s.name for s in agent_statuses if s.installed and s.enabled]
+            rules_yaml = config_manager.get_rules_yaml()
+
+            # Build update dictionary
+            updates = {
+                status_msg: gr.Markdown(
+                    f"✅ {message}",
+                    visible=True
+                ),
+                primary_dropdown: gr.Dropdown(
+                    value=config_manager.primary_orchestrator,
+                    choices=active_agents,
+                ),
+                rules_editor: gr.TextArea(value=rules_yaml),
+                validation_msg: gr.Markdown(visible=False),
+                preview_text: gr.Markdown(""),
+            }
+
+            # Update agent toggles
+            for status in agent_statuses:
+                updates[agent_components[status.name]] = gr.Checkbox(value=status.enabled)
+
+            return updates
+
+        # Wire up event handlers
+        primary_dropdown.change(
+            fn=set_primary_orchestrator,
+            inputs=[primary_dropdown],
+            outputs=[status_msg],
+        )
+
+        # Wire up agent toggles
+        for agent_name, toggle in agent_components.items():
+            toggle.change(
+                fn=lambda enabled, name=agent_name: update_agent_toggle(name, enabled),
+                inputs=[toggle],
+                outputs=[status_msg, agent_components[agent_name], primary_dropdown],
+            )
+
+        validate_btn.click(
+            fn=validate_rules,
+            inputs=[rules_editor],
+            outputs=[validation_msg],
+        )
+
+        preview_btn.click(
+            fn=preview_rules,
+            inputs=[rules_editor],
+            outputs=[preview_text, preview_accordion],
+        )
+
+        save_btn.click(
+            fn=save_configuration,
+            inputs=[rules_editor],
+            outputs=[status_msg],
+        )
+
+        # Reset button
+        all_outputs = [
+            status_msg,
+            primary_dropdown,
+            rules_editor,
+            validation_msg,
+            preview_text,
+        ] + list(agent_components.values())
+
+        reset_btn.click(
+            fn=reset_configuration,
+            outputs=all_outputs,
+        )
+
+        # Add helpful tooltips
+        gr.Markdown("""
+        ---
+        ### 💡 Tips
+
+        - **Primary Orchestrator**: Handles all tasks unless a routing rule matches
+        - **Routing Rules**: Use regex patterns to delegate specific tasks to appropriate agents
+        - **Pattern Examples**:
+          - `security|audit|vulnerability` - Security-related tasks
+          - `refactor|redesign` - Code refactoring
+          - `test|pytest|jest` - Testing tasks
+        - **Priority**: Higher priority rules are evaluated first (0-10)
+        - **Agent Status**:
+          - 🟢 Active - Enabled and installed
+          - 🔴 Disabled - Toggled off
+          - ⚠️ Not Installed - Command not found in PATH
+
+        Changes take effect immediately. See [GitHub](https://github.com/carlosduplar/multi-agent-mcp) for docs.
+        """)
+
+    return config_tab

src/delegation_mcp/workflow.py

@@ -0,0 +1,300 @@
+"""Workflow engine for multi-agent collaboration."""
+
+import re
+import logging
+from typing import Any
+from pathlib import Path
+from datetime import datetime
+from pydantic import BaseModel, Field
+import yaml
+
+from .orchestrator import OrchestratorRegistry
+from .logging_config import delegation_logger
+
+
+logger = logging.getLogger(__name__)
+
+
+class WorkflowStep(BaseModel):
+    """A single step in a workflow."""
+
+    id: str
+    agent: str
+    task: str
+    output: str | None = None  # Variable name to store output
+    condition: str | None = None  # Conditional execution
+    description: str = ""
+
+
+class WorkflowDefinition(BaseModel):
+    """Definition of a multi-agent workflow."""
+
+    name: str
+    description: str = ""
+    steps: list[WorkflowStep]
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> "WorkflowDefinition":
+        """Load workflow from YAML file."""
+        with open(path) as f:
+            data = yaml.safe_load(f)
+        return cls(**data)
+
+    def to_yaml(self, path: Path) -> None:
+        """Save workflow to YAML file."""
+        with open(path, "w") as f:
+            yaml.dump(self.model_dump(), f, default_flow_style=False)
+
+
+class WorkflowContext:
+    """Context for workflow execution with variable storage."""
+
+    def __init__(self):
+        self.variables: dict[str, Any] = {}
+        self.history: list[dict[str, Any]] = []
+
+    def set(self, name: str, value: Any) -> None:
+        """Set a variable in context."""
+        self.variables[name] = value
+
+    def get(self, name: str, default: Any = None) -> Any:
+        """Get a variable from context."""
+        return self.variables.get(name, default)
+
+    def interpolate(self, template: str) -> str:
+        """
+        Interpolate variables in template string with safe escaping.
+
+        Supports: {{ variable_name }}
+
+        Note: Values are NOT shell-escaped to allow for flexible use cases.
+        If the interpolated string will be passed to shell commands, the caller
+        must handle escaping appropriately.
+        """
+        def replace_var(match):
+            var_name = match.group(1).strip()
+
+            # Validate variable name (only allow alphanumeric and underscore)
+            if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', var_name):
+                logger.warning(f"Invalid variable name in template: {var_name}")
+                return f"{{{{ {var_name} }}}}"
+
+            value = self.get(var_name)
+            if value is None:
+                return f"{{{{ {var_name} }}}}"
+
+            # Convert to string and sanitize dangerous characters
+            str_value = str(value)
+
+            # Log warning if potentially dangerous characters detected
+            dangerous_chars = [';', '&&', '||', '`', '$', '|', '>', '<', '\n', '\r']
+            if any(char in str_value for char in dangerous_chars):
+                logger.warning(f"Variable '{var_name}' contains potentially dangerous characters: {str_value[:50]}")
+
+            return str_value
+
+        return re.sub(r'\{\{\s*([^}]+)\s*\}\}', replace_var, template)
+
+    def evaluate_condition(self, condition: str) -> bool:
+        """
+        Evaluate a simple condition.
+
+        Supports:
+        - {{ var_name }}: Check if variable exists and is truthy
+        - {{ var_name | length > 0 }}: Check list/string length
+        """
+        if not condition:
+            return True
+
+        # Extract variable name
+        var_match = re.search(r'\{\{\s*([^}|]+)', condition)
+        if not var_match:
+            return True
+
+        var_name = var_match.group(1).strip()
+        value = self.get(var_name)
+
+        # Check for length filter
+        if '| length' in condition:
+            if isinstance(value, (list, str, dict)):
+                length = len(value)
+                # Extract comparison - with null checks to prevent ReDoS
+                if '>' in condition:
+                    match = re.search(r'>\s*(\d+)', condition)
+                    if not match:
+                        logger.warning(f"Invalid condition format: {condition}")
+                        return False
+                    threshold = int(match.group(1))
+                    return length > threshold
+                elif '<' in condition:
+                    match = re.search(r'<\s*(\d+)', condition)
+                    if not match:
+                        logger.warning(f"Invalid condition format: {condition}")
+                        return False
+                    threshold = int(match.group(1))
+                    return length < threshold
+                elif '==' in condition or '=' in condition:
+                    match = re.search(r'==?\s*(\d+)', condition)
+                    if not match:
+                        logger.warning(f"Invalid condition format: {condition}")
+                        return False
+                    threshold = int(match.group(1))
+                    return length == threshold
+            return False
+
+        # Default: check truthiness
+        return bool(value)
+
+    def add_to_history(self, step_id: str, result: dict[str, Any]) -> None:
+        """Add step result to history."""
+        self.history.append({
+            "step_id": step_id,
+            "timestamp": datetime.now().isoformat(),
+            **result
+        })
+
+
+class WorkflowResult(BaseModel):
+    """Result of workflow execution."""
+
+    workflow_name: str
+    success: bool
+    steps_completed: int
+    total_steps: int
+    duration: float
+    outputs: dict[str, Any]
+    errors: list[str] = Field(default_factory=list)
+
+
+class WorkflowEngine:
+    """Engine for executing multi-agent workflows."""
+
+    def __init__(self, registry: OrchestratorRegistry):
+        self.registry = registry
+
+    async def execute(
+        self,
+        workflow: WorkflowDefinition,
+        initial_context: dict[str, Any] | None = None
+    ) -> WorkflowResult:
+        """
+        Execute a workflow.
+
+        Args:
+            workflow: Workflow definition
+            initial_context: Initial variables for context
+
+        Returns:
+            WorkflowResult with execution details
+        """
+        logger.info(f"Starting workflow: {workflow.name}")
+        start = datetime.now()
+
+        # Initialize context
+        context = WorkflowContext()
+        if initial_context:
+            for key, value in initial_context.items():
+                context.set(key, value)
+
+        steps_completed = 0
+        errors = []
+
+        # Execute steps sequentially
+        for step in workflow.steps:
+            logger.info(f"Executing step: {step.id} (agent: {step.agent})")
+
+            # Check condition
+            if step.condition and not context.evaluate_condition(step.condition):
+                logger.info(f"Skipping step {step.id}: condition not met")
+                continue
+
+            # Interpolate task with context variables
+            task = context.interpolate(step.task)
+            logger.debug(f"Task after interpolation: {task}")
+
+            # Execute step
+            try:
+                stdout, stderr, returncode = await self.registry.execute(
+                    step.agent,
+                    task
+                )
+
+                success = returncode == 0
+
+                if success:
+                    steps_completed += 1
+
+                    # Store output in context
+                    if step.output:
+                        # Parse output - for now just store stdout
+                        context.set(step.output, stdout.strip())
+                        logger.info(f"Stored output in variable: {step.output}")
+
+                    # Add to history
+                    context.add_to_history(step.id, {
+                        "agent": step.agent,
+                        "success": True,
+                        "output": stdout,
+                    })
+                else:
+                    error_msg = f"Step {step.id} failed: {stderr}"
+                    logger.error(error_msg)
+                    errors.append(error_msg)
+
+                    context.add_to_history(step.id, {
+                        "agent": step.agent,
+                        "success": False,
+                        "error": stderr,
+                    })
+
+                    # Stop on first error (can be made configurable)
+                    break
+
+            except Exception as e:
+                error_msg = f"Step {step.id} error: {str(e)}"
+                logger.error(error_msg)
+                errors.append(error_msg)
+
+                context.add_to_history(step.id, {
+                    "agent": step.agent,
+                    "success": False,
+                    "error": str(e),
+                })
+
+                # Stop on error
+                break
+
+        duration = (datetime.now() - start).total_seconds()
+
+        result = WorkflowResult(
+            workflow_name=workflow.name,
+            success=steps_completed == len(workflow.steps) and not errors,
+            steps_completed=steps_completed,
+            total_steps=len(workflow.steps),
+            duration=duration,
+            outputs=context.variables,
+            errors=errors,
+        )
+
+        logger.info(
+            f"Workflow {workflow.name} completed: "
+            f"{steps_completed}/{len(workflow.steps)} steps in {duration:.2f}s"
+        )
+
+        return result
+
+    def load_workflow(self, path: Path) -> WorkflowDefinition:
+        """Load workflow from file."""
+        return WorkflowDefinition.from_yaml(path)
+
+    def list_workflows(self, directory: Path) -> list[WorkflowDefinition]:
+        """List all workflows in a directory."""
+        workflows = []
+        for yaml_file in directory.glob("*.yaml"):
+            try:
+                workflow = self.load_workflow(yaml_file)
+                workflows.append(workflow)
+            except Exception as e:
+                logger.warning(f"Failed to load workflow {yaml_file}: {e}")
+        return workflows

tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for delegation MCP server."""

tests/test_agent_discovery.py

@@ -0,0 +1,422 @@
+"""Tests for agent discovery module."""
+
+import asyncio
+import json
+import pytest
+from pathlib import Path
+import tempfile
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from delegation_mcp.agent_discovery import AgentDiscovery, AgentMetadata
+
+
+@pytest.fixture
+def temp_cache_file():
+    """Create a temporary cache file with correct structure."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        home = Path(tmpdir)
+        cache_dir = home / ".cache" / "delegation-mcp"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        cache_file = cache_dir / "test_cache.json"
+        yield cache_file
+
+
+@pytest.fixture
+def discovery(temp_cache_file):
+    """Create an AgentDiscovery instance with temporary cache."""
+    # Patch Path.home() to return the temp directory so validation passes
+    # temp_cache_file is inside temp_home/.cache/delegation-mcp
+    temp_home = temp_cache_file.parent.parent.parent
+    
+    with patch("pathlib.Path.home", return_value=temp_home):
+        # We need to mock the cache_dir construction in __init__ to match
+        with patch("delegation_mcp.agent_discovery.Path.home", return_value=temp_home):
+             return AgentDiscovery(cache_file=temp_cache_file)
+
+
+def test_agent_metadata_creation():
+    """Test creating agent metadata."""
+    metadata = AgentMetadata(
+        name="claude",
+        command="claude",
+        version="1.0.0",
+        available=True,
+        path="/usr/local/bin/claude",
+        capabilities=["reasoning", "code_generation"],
+    )
+
+    assert metadata.name == "claude"
+    assert metadata.command == "claude"
+    assert metadata.version == "1.0.0"
+    assert metadata.available is True
+    assert metadata.path == "/usr/local/bin/claude"
+    assert "reasoning" in metadata.capabilities
+
+
+def test_discovery_initialization(discovery, temp_cache_file):
+    """Test AgentDiscovery initialization."""
+    assert discovery.cache_file == temp_cache_file
+    assert isinstance(discovery._discovered_agents, dict)
+    assert len(AgentDiscovery.KNOWN_AGENTS) > 0
+
+
+def test_cache_save_and_load(discovery, temp_cache_file):
+    """Test saving and loading discovery cache."""
+    # Add some test data
+    discovery._discovered_agents["test_agent"] = AgentMetadata(
+        name="test_agent",
+        command="test",
+        version="1.0.0",
+        available=True,
+        path="/usr/bin/test",
+    )
+
+    # Save cache
+    discovery._save_cache()
+
+    # Verify file exists
+    assert temp_cache_file.exists()
+
+    # Load cache in new instance
+    # We need to patch here too for the new instance
+    temp_home = temp_cache_file.parent.parent.parent
+    with patch("pathlib.Path.home", return_value=temp_home):
+        with patch("delegation_mcp.agent_discovery.Path.home", return_value=temp_home):
+            new_discovery = AgentDiscovery(cache_file=temp_cache_file)
+            assert "test_agent" in new_discovery._discovered_agents
+            assert new_discovery._discovered_agents["test_agent"].name == "test_agent"
+            assert new_discovery._discovered_agents["test_agent"].version == "1.0.0"
+
+
+@pytest.mark.asyncio
+async def test_resolve_command_path(discovery):
+    """Test resolving command paths."""
+    # Mock shutil.which to return a path
+    with patch("shutil.which", return_value="/usr/bin/python3"):
+        path = discovery._resolve_command_path("python3")
+        assert path == "/usr/bin/python3"
+
+    # Test with command not found
+    with patch("shutil.which", return_value=None):
+        path = discovery._resolve_command_path("nonexistent_command")
+        assert path is None
+
+
+@pytest.mark.asyncio
+async def test_verify_agent_success(discovery):
+    """Test successful agent verification."""
+    # Mock subprocess for successful verification
+    mock_process = AsyncMock()
+    mock_process.returncode = 0
+    mock_process.communicate = AsyncMock(
+        return_value=(b"claude version 1.0.0\n", b"")
+    )
+    mock_process.stdin = MagicMock()  # Mock stdin as non-async
+
+    with patch("asyncio.create_subprocess_exec", return_value=mock_process):
+        available, version, error = await discovery._verify_agent(
+            "claude", "claude", "--version"
+        )
+
+        assert available is True
+        assert "1.0.0" in version
+        assert error is None
+
+
+@pytest.mark.asyncio
+async def test_verify_agent_failure(discovery):
+    """Test failed agent verification."""
+    # Mock subprocess for failed verification
+    mock_process = AsyncMock()
+    mock_process.returncode = 1
+    mock_process.communicate = AsyncMock(
+        return_value=(b"", b"command not found\n")
+    )
+    mock_process.stdin = MagicMock()  # Mock stdin as non-async
+
+    with patch("asyncio.create_subprocess_exec", return_value=mock_process):
+        # First call will fail, second with --help should also fail
+        available, version, error = await discovery._verify_agent(
+            "nonexistent", "nonexistent", "--version"
+        )
+
+        # The function retries with --help, so we need to mock that too
+        assert available is False or error is not None
+
+
+@pytest.mark.asyncio
+async def test_verify_agent_timeout(discovery):
+    """Test agent verification timeout."""
+    # Mock subprocess that times out
+    mock_process = AsyncMock()
+    mock_process.communicate = AsyncMock(side_effect=asyncio.TimeoutError())
+    mock_process.stdin = MagicMock()  # Mock stdin as non-async
+
+    with patch("asyncio.create_subprocess_exec", return_value=mock_process):
+        available, version, error = await discovery._verify_agent(
+            "slow_agent", "slow_agent", "--version"
+        )
+
+        assert available is False
+        assert version is None
+        assert "timed out" in error.lower()
+
+
+@pytest.mark.asyncio
+async def test_verify_agent_not_found(discovery):
+    """Test agent verification when command not found."""
+    with patch(
+        "asyncio.create_subprocess_exec",
+        side_effect=FileNotFoundError("Command not found"),
+    ):
+        available, version, error = await discovery._verify_agent(
+            "missing", "missing", "--version"
+        )
+
+        assert available is False
+        assert version is None
+        assert "not found" in error.lower()
+
+
+@pytest.mark.asyncio
+async def test_discover_single_agent(discovery):
+    """Test discovering a single agent."""
+    config = {
+        "command": "python3",
+        "version_flag": "--version",
+        "capabilities": ["scripting", "general"],
+    }
+
+    # Mock shutil.which to return a path
+    with patch("shutil.which", return_value="/usr/bin/python3"):
+        # Mock verify_agent
+        with patch.object(
+            discovery,
+            "_verify_agent",
+            return_value=(True, "Python 3.9.0", None),
+        ):
+            metadata = await discovery._discover_single_agent("python", config)
+
+            assert metadata.name == "python"
+            assert metadata.available is True
+            assert metadata.version == "Python 3.9.0"
+            assert metadata.path == "/usr/bin/python3"
+            assert "scripting" in metadata.capabilities
+
+
+@pytest.mark.asyncio
+async def test_discover_agents_with_cache(discovery, temp_cache_file):
+    """Test agent discovery with caching."""
+    # Add cached data
+    discovery._discovered_agents["cached_agent"] = AgentMetadata(
+        name="cached_agent",
+        command="cached",
+        version="1.0.0",
+        available=True,
+    )
+
+    # First call should use cache
+    result = await discovery.discover_agents(force_refresh=False)
+    assert "cached_agent" in result
+
+    # Force refresh should re-discover
+    with patch.object(discovery, "_discover_single_agent") as mock_discover:
+        mock_discover.return_value = AgentMetadata(
+            name="test",
+            command="test",
+            version="2.0.0",
+            available=True,
+        )
+        result = await discovery.discover_agents(force_refresh=True)
+        # Should have called discover for all known agents
+        assert mock_discover.called
+
+
+@pytest.mark.asyncio
+async def test_discover_agents_parallel(discovery):
+    """Test that agent discovery runs in parallel."""
+    # Mock _discover_single_agent to track calls
+    call_count = 0
+
+    async def mock_discover(name, config):
+        nonlocal call_count
+        call_count += 1
+        await asyncio.sleep(0.01)  # Simulate some work
+        return AgentMetadata(
+            name=name,
+            command=config["command"],
+            available=False,
+            error_message="Not found",
+        )
+
+    with patch.object(discovery, "_discover_single_agent", side_effect=mock_discover):
+        await discovery.discover_agents(force_refresh=True)
+
+        # Should have discovered multiple agents
+        assert call_count == len(AgentDiscovery.KNOWN_AGENTS)
+
+
+def test_get_available_agents(discovery):
+    """Test getting list of available agents."""
+    discovery._discovered_agents = {
+        "agent1": AgentMetadata(name="agent1", command="a1", available=True),
+        "agent2": AgentMetadata(name="agent2", command="a2", available=False),
+        "agent3": AgentMetadata(name="agent3", command="a3", available=True),
+    }
+
+    available = discovery.get_available_agents()
+    assert len(available) == 2
+    assert all(agent.available for agent in available)
+
+
+def test_get_unavailable_agents(discovery):
+    """Test getting list of unavailable agents."""
+    discovery._discovered_agents = {
+        "agent1": AgentMetadata(name="agent1", command="a1", available=True),
+        "agent2": AgentMetadata(name="agent2", command="a2", available=False),
+        "agent3": AgentMetadata(name="agent3", command="a3", available=False),
+    }
+
+    unavailable = discovery.get_unavailable_agents()
+    assert len(unavailable) == 2
+    assert all(not agent.available for agent in unavailable)
+
+
+def test_is_agent_available(discovery):
+    """Test checking if specific agent is available."""
+    discovery._discovered_agents = {
+        "claude": AgentMetadata(name="claude", command="claude", available=True),
+        "gemini": AgentMetadata(name="gemini", command="gemini", available=False),
+    }
+
+    assert discovery.is_agent_available("claude") is True
+    assert discovery.is_agent_available("gemini") is False
+    assert discovery.is_agent_available("nonexistent") is False
+
+
+def test_get_agent_metadata(discovery):
+    """Test getting metadata for specific agent."""
+    metadata = AgentMetadata(
+        name="claude",
+        command="claude",
+        version="1.0.0",
+        available=True,
+    )
+    discovery._discovered_agents["claude"] = metadata
+
+    result = discovery.get_agent_metadata("claude")
+    assert result == metadata
+
+    result = discovery.get_agent_metadata("nonexistent")
+    assert result is None
+
+
+def test_get_discovery_summary(discovery):
+    """Test getting discovery summary."""
+    discovery._discovered_agents = {
+        "agent1": AgentMetadata(
+            name="agent1",
+            command="a1",
+            version="1.0.0",
+            available=True,
+            path="/usr/bin/a1",
+        ),
+        "agent2": AgentMetadata(
+            name="agent2",
+            command="a2",
+            available=False,
+            error_message="Not found",
+        ),
+    }
+
+    summary = discovery.get_discovery_summary()
+
+    assert summary["total_agents"] == 2
+    assert summary["available"] == 1
+    assert summary["unavailable"] == 1
+    assert len(summary["available_agents"]) == 1
+    assert len(summary["unavailable_agents"]) == 1
+    assert summary["available_agents"][0]["name"] == "agent1"
+    assert summary["unavailable_agents"][0]["name"] == "agent2"
+    assert "system_info" in summary
+
+
+def test_clear_cache(discovery, temp_cache_file):
+    """Test clearing the discovery cache."""
+    # Add some data and save
+    discovery._discovered_agents["test"] = AgentMetadata(
+        name="test",
+        command="test",
+        available=True,
+    )
+    discovery._save_cache()
+
+    assert temp_cache_file.exists()
+    assert len(discovery._discovered_agents) > 0
+
+    # Clear cache
+    discovery.clear_cache()
+
+    assert len(discovery._discovered_agents) == 0
+    assert not temp_cache_file.exists()
+
+
+def test_get_install_message(discovery):
+    """Test getting installation instructions."""
+    message = discovery._get_install_message("claude")
+    assert "Claude Code" in message
+    assert "install" in message.lower()
+
+    message = discovery._get_install_message("gemini")
+    assert "Gemini" in message
+    assert "npm install" in message.lower()
+
+    message = discovery._get_install_message("unknown_agent")
+    assert "unknown_agent" in message
+    assert "documentation" in message.lower()
+
+
+@pytest.mark.asyncio
+async def test_discover_agents_convenience_function():
+    """Test the convenience function for discovering agents."""
+    from delegation_mcp.agent_discovery import discover_agents
+
+    with patch("delegation_mcp.agent_discovery.AgentDiscovery") as mock_class:
+        mock_instance = MagicMock()
+        mock_instance.discover_agents = AsyncMock(return_value={})
+        mock_class.return_value = mock_instance
+
+        result = await discover_agents(force_refresh=True)
+
+        mock_instance.discover_agents.assert_called_once_with(force_refresh=True)
+
+
+@pytest.mark.asyncio
+async def test_discover_specific_agents(discovery):
+    """Test discovering only specific agents."""
+    agents_to_check = ["claude", "gemini"]
+
+    with patch.object(discovery, "_discover_single_agent") as mock_discover:
+        mock_discover.return_value = AgentMetadata(
+            name="test",
+            command="test",
+            available=False,
+        )
+
+        await discovery.discover_agents(
+            force_refresh=True,
+            agents_to_check=agents_to_check,
+        )
+
+        # Should only call discover for specified agents
+        assert mock_discover.call_count == len(agents_to_check)
+
+
+def test_known_agents_structure():
+    """Test that KNOWN_AGENTS has expected structure."""
+    for name, config in AgentDiscovery.KNOWN_AGENTS.items():
+        assert "command" in config
+        assert "version_flag" in config
+        assert "capabilities" in config
+        assert isinstance(config["capabilities"], list)
+        assert len(config["capabilities"]) > 0

tests/test_config.py

@@ -0,0 +1,411 @@
+"""Tests for configuration module."""
+
+import pytest
+from pathlib import Path
+import tempfile
+
+from delegation_mcp.config import (
+    DelegationConfig,
+    DelegationRule,
+    OrchestratorConfig,
+    ConfigValidationError,
+)
+
+
+def test_delegation_rule_creation():
+    """Test creating a delegation rule."""
+    rule = DelegationRule(
+        pattern="security|audit",
+        delegate_to="gemini",
+        priority=5,
+        requires_approval=False,
+        description="Security tasks",
+    )
+
+    assert rule.pattern == "security|audit"
+    assert rule.delegate_to == "gemini"
+    assert rule.priority == 5
+
+
+def test_orchestrator_config_creation():
+    """Test creating orchestrator configuration."""
+    config = OrchestratorConfig(
+        name="claude",
+        command="claude",
+        enabled=True,
+    )
+
+    assert config.name == "claude"
+    assert config.command == "claude"
+    assert config.enabled is True
+    assert config.timeout == 300  # default
+
+
+def test_delegation_config_find_rule():
+    """Test finding matching delegation rule."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        rules=[
+            DelegationRule(
+                pattern="security|audit",
+                delegate_to="gemini",
+                priority=5,
+            ),
+            DelegationRule(
+                pattern="refactor",
+                delegate_to="aider",
+                priority=3,
+            ),
+        ],
+    )
+
+    # Should match security rule
+    rule = config.find_delegation_rule("Run a security audit")
+    assert rule is not None
+    assert rule.delegate_to == "gemini"
+
+    # Should match refactor rule
+    rule = config.find_delegation_rule("Refactor the code")
+    assert rule is not None
+    assert rule.delegate_to == "aider"
+
+    # Should not match any rule
+    rule = config.find_delegation_rule("Explain Python")
+    assert rule is None
+
+
+def test_config_save_and_load():
+    """Test saving and loading configuration."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        config_path = Path(tmpdir) / "test_config.yaml"
+
+        # Create and save config
+        config = DelegationConfig(
+            orchestrator="claude",
+            rules=[
+                DelegationRule(
+                    pattern="test",
+                    delegate_to="gemini",
+                    priority=1,
+                ),
+            ],
+        )
+        config.to_yaml(config_path)
+
+        # Load config
+        loaded_config = DelegationConfig.from_yaml(config_path, validate=False)
+
+        assert loaded_config.orchestrator == "claude"
+        assert len(loaded_config.rules) == 1
+        assert loaded_config.rules[0].pattern == "test"
+
+
+# ============================================================================
+# Validation Tests
+# ============================================================================
+
+
+def test_validate_minimum_agents_success():
+    """Test validation passes with 2 or more enabled agents."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=True),
+            "aider": OrchestratorConfig(name="aider", command="aider", enabled=False),
+        },
+        rules=[],
+    )
+
+    # Should not raise exception
+    config.validate()
+
+
+def test_validate_minimum_agents_failure_zero():
+    """Test validation fails with no enabled agents."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=False),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=False),
+        },
+        rules=[],
+    )
+
+    with pytest.raises(ConfigValidationError) as exc_info:
+        config.validate()
+
+    assert "At least 2 agents must be enabled" in str(exc_info.value)
+    assert "only 0 are enabled" in str(exc_info.value)
+
+
+def test_validate_minimum_agents_failure_one():
+    """Test validation fails with only one enabled agent."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=False),
+        },
+        rules=[],
+    )
+
+    with pytest.raises(ConfigValidationError) as exc_info:
+        config.validate()
+
+    assert "At least 2 agents must be enabled" in str(exc_info.value)
+    assert "only 1 is enabled" in str(exc_info.value)
+
+
+def test_validate_regex_patterns_success():
+    """Test validation passes with valid regex patterns."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=True),
+        },
+        rules=[
+            DelegationRule(pattern="security|audit", delegate_to="gemini", priority=5),
+            DelegationRule(pattern="refactor.*code", delegate_to="claude", priority=3),
+            DelegationRule(pattern="^test", delegate_to="gemini", priority=2),
+        ],
+    )
+
+    # Should not raise exception
+    config.validate()
+
+
+def test_validate_regex_patterns_failure():
+    """Test validation fails with invalid regex patterns."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=True),
+        },
+        rules=[
+            DelegationRule(
+                pattern="valid_pattern", delegate_to="gemini", priority=5
+            ),
+            DelegationRule(
+                pattern="[invalid(regex", delegate_to="claude", priority=3
+            ),  # Invalid regex
+            DelegationRule(
+                pattern="(?P<incomplete", delegate_to="gemini", priority=2
+            ),  # Invalid regex
+        ],
+    )
+
+    with pytest.raises(ConfigValidationError) as exc_info:
+        config.validate()
+
+    error_msg = str(exc_info.value)
+    assert "Invalid regex pattern" in error_msg
+    assert "[invalid(regex" in error_msg or "(?P<incomplete" in error_msg
+
+
+def test_validate_agent_references_success():
+    """Test validation passes when all referenced agents exist."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=True),
+            "aider": OrchestratorConfig(name="aider", command="aider", enabled=True),
+        },
+        rules=[
+            DelegationRule(pattern="security", delegate_to="gemini", priority=5),
+            DelegationRule(pattern="refactor", delegate_to="claude", priority=3),
+            DelegationRule(pattern="git", delegate_to="aider", priority=4),
+        ],
+    )
+
+    # Should not raise exception
+    config.validate()
+
+
+
+
+
+def test_validate_agent_references_failure_rule_target():
+    """Test validation fails when rule references non-existent agent."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=True),
+        },
+        rules=[
+            DelegationRule(pattern="security", delegate_to="gemini", priority=5),
+            DelegationRule(
+                pattern="git", delegate_to="nonexistent_agent", priority=3
+            ),  # Invalid reference
+        ],
+    )
+
+    with pytest.raises(ConfigValidationError) as exc_info:
+        config.validate()
+
+    error_msg = str(exc_info.value)
+    assert "Target orchestrator 'nonexistent_agent' is not defined" in error_msg
+    assert "pattern: 'git'" in error_msg
+
+
+def test_validate_no_circular_delegation_success():
+    """Test validation passes with normal delegation rules."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=True),
+            "aider": OrchestratorConfig(name="aider", command="aider", enabled=True),
+        },
+        rules=[
+            DelegationRule(pattern="security", delegate_to="gemini", priority=5),
+            DelegationRule(pattern="refactor", delegate_to="claude", priority=3),
+            DelegationRule(pattern="git", delegate_to="aider", priority=4),
+        ],
+    )
+
+    # Should not raise exception - multiple different patterns to different targets is fine
+    config.validate()
+
+
+def test_validate_no_ambiguous_delegation():
+    """Test validation detects ambiguous delegation patterns."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=True),
+            "aider": OrchestratorConfig(name="aider", command="aider", enabled=True),
+        },
+        rules=[
+            # Same pattern, same priority, different targets - ambiguous!
+            DelegationRule(pattern="security", delegate_to="claude", priority=5),
+            DelegationRule(pattern="security", delegate_to="gemini", priority=5),
+        ],
+    )
+
+    with pytest.raises(ConfigValidationError) as exc_info:
+        config.validate()
+
+    error_msg = str(exc_info.value)
+    assert "ambiguous delegation" in error_msg.lower()
+    assert "security" in error_msg.lower()
+
+
+def test_validate_same_pattern_different_priority_ok():
+    """Test validation allows same pattern with different priorities."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=True),
+            "aider": OrchestratorConfig(name="aider", command="aider", enabled=True),
+        },
+        rules=[
+            # Same pattern but different priorities - OK (higher priority wins)
+            DelegationRule(pattern="security", delegate_to="gemini", priority=5),
+            DelegationRule(pattern="security", delegate_to="claude", priority=3),
+        ],
+    )
+
+    # Should not raise exception - different priorities resolve ambiguity
+    config.validate()
+
+
+def test_validate_multiple_errors():
+    """Test validation reports multiple errors at once."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=False),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=False),
+            # Error 1: less than 2 enabled agents
+        },
+        rules=[
+            DelegationRule(
+                pattern="[invalid(", delegate_to="claude", priority=5
+            ),  # Error 2: invalid regex
+            DelegationRule(
+                pattern="test", delegate_to="missing_agent", priority=3
+            ),  # Error 3: invalid reference
+        ],
+    )
+
+    with pytest.raises(ConfigValidationError) as exc_info:
+        config.validate()
+
+    error_msg = str(exc_info.value)
+    # Should contain multiple errors
+    assert "At least 2 agents must be enabled" in error_msg
+    assert "Invalid regex pattern" in error_msg
+    assert "Target orchestrator 'missing_agent' is not defined" in error_msg
+
+
+def test_from_yaml_with_validation():
+    """Test loading config from YAML with validation enabled."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        config_path = Path(tmpdir) / "test_config.yaml"
+
+        # Create invalid config
+        config = DelegationConfig(
+            orchestrator="claude",
+            orchestrators={
+                "claude": OrchestratorConfig(
+                    name="claude", command="claude", enabled=False
+                ),
+                "gemini": OrchestratorConfig(
+                    name="gemini", command="gemini", enabled=False
+                ),
+            },
+            rules=[],
+        )
+        config.to_yaml(config_path)
+
+        # Try to load with validation - should fail
+        with pytest.raises(ConfigValidationError):
+            DelegationConfig.from_yaml(config_path, validate=True)
+
+        # Load without validation - should succeed
+        loaded = DelegationConfig.from_yaml(config_path, validate=False)
+        assert loaded.orchestrator == "claude"
+
+
+def test_validate_empty_orchestrators():
+    """Test validation fails with no orchestrators defined."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={},  # Empty orchestrators
+        rules=[],
+    )
+
+    with pytest.raises(ConfigValidationError) as exc_info:
+        config.validate()
+
+    error_msg = str(exc_info.value)
+    assert "At least 2 agents must be enabled" in error_msg
+    assert "Primary orchestrator 'claude' is not defined" in error_msg
+
+
+def test_validate_with_three_enabled_agents():
+    """Test validation passes with more than minimum enabled agents."""
+    config = DelegationConfig(
+        orchestrator="claude",
+        orchestrators={
+            "claude": OrchestratorConfig(name="claude", command="claude", enabled=True),
+            "gemini": OrchestratorConfig(name="gemini", command="gemini", enabled=True),
+            "aider": OrchestratorConfig(name="aider", command="aider", enabled=True),
+            "copilot": OrchestratorConfig(
+                name="copilot", command="copilot", enabled=False
+            ),
+        },
+        rules=[
+            DelegationRule(pattern="security", delegate_to="gemini", priority=5),
+        ],
+    )
+
+    # Should not raise exception
+    config.validate()

tests/test_config_ui.py

@@ -0,0 +1,77 @@
+"""Test script for configuration UI - verifies imports and basic functionality."""
+
+import sys
+from pathlib import Path
+
+# Test imports
+try:
+    from src.delegation_mcp.ui import create_app, ConfigurationManager
+    print("✅ Successfully imported create_app and ConfigurationManager")
+except ImportError as e:
+    print(f"❌ Import error: {e}")
+    sys.exit(1)
+
+# Test ConfigurationManager initialization
+try:
+    config_manager = ConfigurationManager()
+    print("✅ ConfigurationManager initialized successfully")
+except Exception as e:
+    print(f"❌ ConfigurationManager initialization failed: {e}")
+    sys.exit(1)
+
+# Test agent status retrieval
+try:
+    statuses = config_manager.get_agent_statuses()
+    print(f"✅ Retrieved {len(statuses)} agent statuses")
+    for status in statuses:
+        print(f"   {status.status_icon} {status.name}: {status.status_text}")
+except Exception as e:
+    print(f"❌ Failed to get agent statuses: {e}")
+    sys.exit(1)
+
+# Test YAML validation
+try:
+    test_yaml = """
+- pattern: test
+  delegate_to: claude
+  priority: 5
+"""
+    is_valid, message, rules = config_manager.validate_routing_rules(test_yaml)
+    if is_valid:
+        print(f"✅ YAML validation works: {message}")
+    else:
+        print(f"⚠️ YAML validation returned: {message}")
+except Exception as e:
+    print(f"❌ YAML validation failed: {e}")
+    sys.exit(1)
+
+# Test preview generation
+try:
+    preview = config_manager.preview_routing_rules(rules if rules else [])
+    print(f"✅ Preview generation works (length: {len(preview)} chars)")
+except Exception as e:
+    print(f"❌ Preview generation failed: {e}")
+    sys.exit(1)
+
+# Test primary orchestrator setting
+try:
+    current_primary = config_manager.primary_orchestrator
+    print(f"✅ Current primary orchestrator: {current_primary}")
+except Exception as e:
+    print(f"❌ Failed to get primary orchestrator: {e}")
+    sys.exit(1)
+
+# Test app creation (don't launch)
+try:
+    app = create_app(config_manager)
+    print("✅ Gradio app created successfully")
+except Exception as e:
+    print(f"❌ App creation failed: {e}")
+    sys.exit(1)
+
+print("\n🎉 All tests passed! The configuration UI is ready to use.")
+print("\nTo launch the UI, run:")
+print("  python -m src.delegation_mcp.ui.app")
+print("or use:")
+print("  from src.delegation_mcp.ui import main")
+print("  main()")