Skip to content

Custom Domains

Jump to bottom
Mo Abualruz edited this page Dec 6, 2025 · 1 revision

Custom Domains Guide

Status: ✅ Complete

Phase: Phase 3

Last Updated: December 6, 2025

Overview

The Domain-Specific Agents system supports adding new domain agents through configuration alone, without modifying code. This guide explains how to create custom domains for your specific development needs.

Key Features

  • Configuration-Driven: Define new domains in YAML/JSON files
  • Auto-Discovery: New domains are automatically discovered and registered
  • Hot-Reload: Configuration changes take effect without restart
  • No Code Changes: Add domains without touching the codebase
  • Full Parity: Custom domains work identically to built-in domains

Quick Start

1. Create a Domain Configuration File

Create a new file in config/domains/{domain-name}.yaml:

cp config/domains/template.yaml config/domains/mobile.yaml

2. Edit the Configuration

Update the file with your domain information:

domain: mobile
name: "Mobile Development Agent"
description: "Specialized agent for mobile development"

capabilities:
  - name: "Framework Selection"
    description: "Recommend mobile frameworks"
    technologies: ["React Native", "Flutter", "Swift", "Kotlin"]

best_practices:
  - title: "Cross-Platform Development"
    description: "Share code between iOS and Android"
    technologies: ["React Native", "Flutter"]
    implementation: "Use cross-platform frameworks to maximize code reuse"

technology_recommendations:
  - technology: "React Native"
    use_cases: ["Cross-platform mobile apps", "Rapid development"]
    pros: ["Code sharing", "Large community", "JavaScript ecosystem"]
    cons: ["Performance limitations", "Native module complexity"]
    alternatives: ["Flutter", "Xamarin"]

3. Validate Your Configuration

The system automatically validates your configuration when it loads:

  • All required fields must be present
  • Technology lists must be non-empty
  • Field types must match the schema
  • No duplicate entries allowed

If validation fails, you'll see a clear error message indicating what needs to be fixed.

4. Use Your Domain

Once created and validated, your domain is immediately available:

Request assistance for mobile development
→ System routes to mobile domain agent
→ Agent provides recommendations based on your configuration

Configuration Structure

Required Fields

Every domain configuration must include:

  1. domain (string)

    • Unique identifier for your domain
    • Lowercase, alphanumeric, hyphens allowed
    • Examples: mobile, data-science, embedded-systems

  2. name (string)

    • Human-readable domain name
    • Displayed in UI and documentation
    • Example: "Mobile Development Agent"

  3. description (string)

    • Explains what this domain covers
    • Helps users understand the domain's purpose
    • Example: "Specialized agent for mobile development"

  4. capabilities (array)

    • Major areas of expertise for this domain
    • At least 1 capability required
    • Each capability must have at least 1 technology

  5. best_practices (array)

    • Recommended approaches and patterns
    • At least 1 best practice required
    • Should be actionable and specific

  6. technology_recommendations (array)

    • Detailed guidance on specific tools/frameworks
    • At least 1 recommendation required
    • Include pros, cons, and alternatives

Capabilities

Capabilities define what your domain agent can help with:

capabilities:
  - name: "Capability Name"
    description: "What this capability covers"
    technologies:
      - "Technology A"
      - "Technology B"
      - "Technology C"

Requirements:

  • At least 1 capability per domain
  • Each capability must have at least 1 technology
  • Technology names should be specific (e.g., "React" not "Frontend")

Best Practices

Best practices are recommended approaches for your domain:

best_practices:
  - title: "Best Practice Name"
    description: "Why this is a best practice"
    technologies:
      - "Technology A"
      - "Technology B"
    implementation: "Specific steps to follow"

Requirements:

  • At least 1 best practice per domain
  • Implementation should be specific and actionable
  • Technologies should match those in capabilities

Technology Recommendations

Technology recommendations provide detailed guidance on specific tools:

technology_recommendations:
  - technology: "Technology Name"
    use_cases:
      - "Use case 1"
      - "Use case 2"
    pros:
      - "Advantage 1"
      - "Advantage 2"
    cons:
      - "Limitation 1"
      - "Limitation 2"
    alternatives:
      - "Alternative 1"
      - "Alternative 2"

Requirements:

  • At least 1 technology recommendation per domain
  • Each technology must have at least 1 use case
  • Each technology must have at least 1 pro and 1 con
  • Alternatives should be realistic options

Examples

Example 1: Mobile Development Domain

Create config/domains/mobile.yaml:

domain: mobile
name: "Mobile Development Agent"
description: "Specialized agent for mobile development"

capabilities:
  - name: "Framework Selection"
    description: "Recommend mobile frameworks"
    technologies: ["React Native", "Flutter", "Swift", "Kotlin"]
  
  - name: "Platform-Specific Guidance"
    description: "iOS and Android specific recommendations"
    technologies: ["iOS", "Android"]

best_practices:
  - title: "Cross-Platform Development"
    description: "Share code between iOS and Android"
    technologies: ["React Native", "Flutter"]
    implementation: "Use cross-platform frameworks to maximize code reuse"
  
  - title: "Performance Optimization"
    description: "Optimize mobile app performance"
    technologies: ["React Native", "Flutter", "Swift", "Kotlin"]
    implementation: "Profile app performance, optimize rendering, minimize memory usage"

technology_recommendations:
  - technology: "React Native"
    use_cases: ["Cross-platform mobile apps", "Rapid development", "Code sharing"]
    pros: ["Code sharing", "Large community", "JavaScript ecosystem"]
    cons: ["Performance limitations", "Native module complexity"]
    alternatives: ["Flutter", "Xamarin"]
  
  - technology: "Flutter"
    use_cases: ["Cross-platform mobile apps", "Beautiful UIs", "High performance"]
    pros: ["Fast development", "Beautiful widgets", "Excellent performance"]
    cons: ["Smaller ecosystem", "Dart language"]
    alternatives: ["React Native", "Xamarin"]

Example 2: Data Science Domain

Create config/domains/data-science.yaml:

domain: data-science
name: "Data Science Agent"
description: "Specialized agent for data science and machine learning"

capabilities:
  - name: "Framework Selection"
    description: "Recommend ML frameworks and libraries"
    technologies: ["TensorFlow", "PyTorch", "Scikit-learn", "XGBoost"]
  
  - name: "Data Processing"
    description: "Data cleaning, transformation, and analysis"
    technologies: ["Pandas", "NumPy", "Polars", "Dask"]
  
  - name: "Visualization"
    description: "Data visualization and exploration"
    technologies: ["Matplotlib", "Seaborn", "Plotly", "Altair"]

best_practices:
  - title: "Data Pipeline Design"
    description: "Design reproducible data pipelines"
    technologies: ["Pandas", "Dask", "Apache Spark"]
    implementation: "Use version control for data, document transformations, test data quality"
  
  - title: "Model Validation"
    description: "Properly validate machine learning models"
    technologies: ["Scikit-learn", "TensorFlow", "PyTorch"]
    implementation: "Use cross-validation, test on holdout set, monitor for data drift"

technology_recommendations:
  - technology: "TensorFlow"
    use_cases: ["Deep learning", "Production ML systems", "Large-scale training"]
    pros: ["Production-ready", "Excellent documentation", "Wide adoption"]
    cons: ["Steep learning curve", "Verbose API"]
    alternatives: ["PyTorch", "JAX"]
  
  - technology: "Pandas"
    use_cases: ["Data manipulation", "Data analysis", "Data cleaning"]
    pros: ["Easy to use", "Powerful", "Large community"]
    cons: ["Memory limitations", "Performance on large datasets"]
    alternatives: ["Polars", "Dask"]

Example 3: Embedded Systems Domain

Create config/domains/embedded-systems.yaml:

domain: embedded-systems
name: "Embedded Systems Agent"
description: "Specialized agent for embedded systems development"

capabilities:
  - name: "Microcontroller Selection"
    description: "Recommend microcontrollers and development boards"
    technologies: ["Arduino", "STM32", "ESP32", "Raspberry Pi"]
  
  - name: "Real-Time Systems"
    description: "Real-time operating systems and scheduling"
    technologies: ["FreeRTOS", "RTOS", "Bare Metal"]
  
  - name: "Hardware Integration"
    description: "Sensor and actuator integration"
    technologies: ["I2C", "SPI", "UART", "GPIO"]

best_practices:
  - title: "Power Management"
    description: "Optimize power consumption"
    technologies: ["Arduino", "STM32", "ESP32"]
    implementation: "Use sleep modes, optimize clock speeds, minimize peripheral usage"
  
  - title: "Memory Optimization"
    description: "Manage limited memory resources"
    technologies: ["Arduino", "STM32"]
    implementation: "Use PROGMEM for constants, minimize stack usage, profile memory"

technology_recommendations:
  - technology: "Arduino"
    use_cases: ["Prototyping", "Hobbyist projects", "Educational use"]
    pros: ["Easy to use", "Large community", "Extensive libraries"]
    cons: ["Limited performance", "Limited memory"]
    alternatives: ["STM32", "ESP32"]
  
  - technology: "ESP32"
    use_cases: ["IoT applications", "WiFi/Bluetooth projects", "Web connectivity"]
    pros: ["WiFi/Bluetooth built-in", "Powerful processor", "Good documentation"]
    cons: ["More complex than Arduino", "Power consumption"]
    alternatives: ["Arduino with WiFi shield", "Raspberry Pi"]

Configuration Schema

Your configuration is validated against config/schemas/domain.schema.json. The schema ensures:

  • ✓ All required fields are present
  • ✓ Field types are correct (strings, arrays, etc.)
  • ✓ Technology lists are non-empty
  • ✓ No duplicate entries
  • ✓ Required fields in nested objects are present

Schema Validation Rules

Field Type Required Min Max Pattern
domain string yes 1 50 ^[a-z][a-z0-9-]*$
name string yes 1 100 -
description string yes 1 500 -
capabilities array yes 1 - -
best_practices array yes 1 - -
technology_recommendations array yes 1 - -

Nested Field Validation

Capability fields:

  • name (string, 1-100 chars, required)
  • description (string, 1-500 chars, required)
  • technologies (array of strings, min 1 item, required)

Best Practice fields:

  • title (string, 1-100 chars, required)
  • description (string, 1-500 chars, required)
  • technologies (array of strings, min 1 item, required)
  • implementation (string, 1-1000 chars, required)

Technology Recommendation fields:

  • technology (string, 1-100 chars, required)
  • use_cases (array of strings, min 1 item, required)
  • pros (array of strings, min 1 item, required)
  • cons (array of strings, min 1 item, required)
  • alternatives (array of strings, min 1 item, required)

Hot-Reload Support

The system automatically detects configuration changes and reloads agents without restart:

  1. Save your changes to the YAML file
  2. System detects the change (within 5 seconds)
  3. Configuration is validated against schema
  4. Agent is recreated with new configuration
  5. New requests use updated configuration
  6. Existing requests continue with old configuration until completion

Example: Updating a Domain

  1. Edit config/domains/mobile.yaml
  2. Add a new capability or technology recommendation
  3. Save the file
  4. System automatically detects and reloads
  5. New requests immediately use the updated configuration

Troubleshooting

Domain Not Discovered

Problem: Your domain configuration is not being discovered

Solutions:

  • Check that file is in config/domains/ directory
  • Verify file has .yaml extension
  • Ensure YAML syntax is valid (use a YAML validator)
  • Check that domain field is present and non-empty
  • Verify domain identifier matches pattern: ^[a-z][a-z0-9-]*$

Validation Error

Problem: You get a validation error when loading the domain

Solutions:

  • Check that all required fields are present
  • Verify technology lists are not empty
  • Ensure field types match the schema
  • Check for duplicate technology names
  • Validate YAML syntax

Common errors:

  • Missing domain field → Add domain identifier
  • Empty capabilities array → Add at least 1 capability
  • Missing technologies in capability → Add at least 1 technology
  • Invalid domain name pattern → Use lowercase, alphanumeric, hyphens only

Changes Not Taking Effect

Problem: Configuration changes are not being applied

Solutions:

  • Verify file was saved correctly
  • Check that YAML syntax is valid
  • Wait up to 5 seconds for hot-reload detection
  • Check system logs for validation errors
  • Restart the system if hot-reload doesn't work

Domain Works But Recommendations Are Generic

Problem: Domain is loaded but recommendations are too generic

Solutions:

  • Add more specific technologies to capabilities
  • Provide detailed implementation guidance in best practices
  • Include specific use cases in technology recommendations
  • Add more pros/cons to help users understand trade-offs

Best Practices for Custom Domains

1. Be Specific

Use specific technology names, not generic categories:

# ✓ Good
technologies: ["React", "Vue", "Angular"]

# ✗ Bad
technologies: ["Frontend Frameworks"]

2. Provide Actionable Guidance

Best practices should be specific and actionable:

# ✓ Good
implementation: "Use code splitting with React.lazy(), implement route-based code splitting, monitor bundle size with webpack-bundle-analyzer"

# ✗ Bad
implementation: "Optimize your code"

3. Include Realistic Alternatives

Alternatives should be realistic options developers might consider:

# ✓ Good
alternatives: ["Vue", "Angular", "Svelte"]

# ✗ Bad
alternatives: ["Any other framework"]

4. Balance Pros and Cons

Provide balanced perspectives on technologies:

# ✓ Good
pros: ["Large ecosystem", "Strong community", "Excellent tooling"]
cons: ["Steep learning curve", "JSX syntax", "Frequent updates"]

# ✗ Bad
pros: ["It's the best"]
cons: ["None"]

5. Document Your Domain

Add comments to your configuration explaining your choices:

# Mobile Development Domain
# Covers cross-platform and native mobile development
# Includes React Native, Flutter, Swift, and Kotlin

domain: mobile
name: "Mobile Development Agent"
description: "Specialized agent for mobile development"

Advanced Topics

Extending Built-in Domains

You can extend built-in domains by creating a new domain that references the same technologies:

domain: web-advanced
name: "Advanced Web Development Agent"
description: "Extended web development with advanced patterns"

capabilities:
  # Include all web capabilities plus advanced ones
  - name: "Advanced Performance"
    description: "Advanced performance optimization techniques"
    technologies: ["React", "Vue", "Angular", "Web Workers", "Service Workers"]

Domain Hierarchies

Create domain hierarchies by having domains reference related technologies:

# Parent domain: full-stack
domain: full-stack
name: "Full-Stack Development Agent"
description: "Covers frontend, backend, and infrastructure"

capabilities:
  - name: "Frontend"
    technologies: ["React", "Vue", "Angular"]
  - name: "Backend"
    technologies: ["Node.js", "Python", "Java"]
  - name: "Infrastructure"
    technologies: ["Docker", "Kubernetes", "Terraform"]

Multi-Language Domains

Create domains that support multiple programming languages:

domain: backend-polyglot
name: "Polyglot Backend Development Agent"
description: "Backend development across multiple languages"

capabilities:
  - name: "API Development"
    technologies: ["Node.js", "Python", "Java", "Go", "Rust"]
  - name: "Database Design"
    technologies: ["PostgreSQL", "MongoDB", "Redis", "Elasticsearch"]

See Also

Last updated: December 6, 2025

Clone this wiki locally