Claude Sub-Agent Architecture

CitadelMesh leverages Claude's sub-agent capabilities to create specialized AI personalities that handle specific building automation domains with expert-level knowledge and tool access.

Overview

Claude sub-agents provide the perfect architecture for our autonomous building platform:

• 🎯 Specialized Expertise: Each agent has deep domain knowledge
• 🔒 Tool Isolation: Restricted access to relevant MCP adapters only
• 📦 Context Preservation: Separate context windows prevent cross-contamination
• 🔄 Automatic Delegation: Events automatically route to appropriate specialists

Agent Specializations

🔒 Security Specialist (security-specialist)

Expertise: Threat detection, access control, incident response

Triggers: security.*, access.*, threat.*, incident.*
MCP Tools: SecurityExpert, AccessControl, ThreatIntel
Responsibilities:
  - Monitor security events and anomalies
  - Execute incident response playbooks
  - Manage access control and door systems
  - Coordinate with law enforcement if needed

⚡ Energy Optimizer (energy-optimizer)

Expertise: HVAC optimization, demand response, efficiency analysis

Triggers: energy.*, hvac.*, demand.*, weather.*
MCP Tools: EcoStruxure, HVAC-Control, EnergyAnalytics, Weather
Responsibilities:
  - Optimize energy consumption patterns
  - Participate in utility demand response
  - Maintain occupant comfort within constraints
  - Integrate renewable energy and storage

🏢 Digital Twin Manager (twin-manager)

Expertise: Asset state reconciliation, data synchronization

Triggers: asset.*, telemetry.*, state.*, device.*
MCP Tools: AssetAPI, StateSync, DataValidation, Analytics
Responsibilities:
  - Maintain digital twin state accuracy
  - Synchronize data across building systems
  - Monitor asset health and performance
  - Implement predictive maintenance

🛡️ Policy Enforcer (policy-enforcer)

Expertise: Safety validation, compliance monitoring, risk assessment

Triggers: *.control.*, *.action.*, policy.*, compliance.*
MCP Tools: OPA-Policy, ComplianceCheck, AuditLog
Responsibilities:
  - Validate ALL control actions before execution
  - Enforce zero-trust safety policies
  - Maintain compliance audit trails
  - Emergency override authorization

🎯 Building Coordinator (building-coordinator)

Expertise: Multi-agent orchestration, system-wide optimization

Triggers: Complex multi-system scenarios
MCP Tools: All (read-only for monitoring)
Responsibilities:
  - Coordinate complex multi-agent workflows
  - Resolve conflicts between competing objectives
  - Manage building-wide optimization strategies
  - Serve as incident commander for emergencies

Architecture Integration

Event-Driven Delegation

# CloudEvents automatically route to specialized agents
event_routing = {
    "security.*": "security-specialist",
    "energy.*": "energy-optimizer", 
    "asset.*": "twin-manager",
    "policy.*": "policy-enforcer",
    "coordination.*": "building-coordinator"
}

Safety-First Validation

graph TD
    A[Event Received] --> B[Route to Specialist]
    B --> C[Policy Enforcer Validation]
    C --> D{Policy Check}
    D -->|Allow| E[Execute Action]
    D -->|Deny| F[Block & Audit]
    E --> G[Log Success]
    F --> H[Alert Human Operators]

Tool Access Matrix

Agent	SecurityExpert	EcoStruxure	AssetAPI	OPA-Policy	VS Code Tools
security-specialist	✅	❌	❌	❌	✅
energy-optimizer	❌	✅	❌	❌	✅
twin-manager	❌	❌	✅	❌	✅
policy-enforcer	❌	❌	❌	✅	✅
building-coordinator	👁️	👁️	👁️	👁️	✅

✅ = Full Access, ❌ = No Access, 👁️ = Read-Only

Usage Examples

Automatic Delegation

The system automatically routes events to the appropriate specialist:

# Security event → security-specialist
> "Unauthorized access attempt detected at main entrance"

# Energy event → energy-optimizer  
> "HVAC system consuming 40% above baseline during peak hours"

# Asset event → twin-manager
> "Temperature sensor T-101 reporting inconsistent readings"

# Complex scenario → building-coordinator
> "Implement demand response while maintaining security lockdown"

Explicit Invocation

You can also explicitly request specific specialists:

> "Use the security-specialist to analyze access patterns from last week"
> "Have the energy-optimizer review overnight consumption anomalies"
> "Ask the policy-enforcer to validate this new safety procedure"

Sub-Agent Configuration

Sub-agents are defined in .claude/agents/ as Markdown files with YAML frontmatter:

---
name: security-specialist
description: Expert in building security and threat response. Use PROACTIVELY for security events.
tools: Read, Write, Bash, Grep, Glob, semantic_search, run_in_terminal
model: sonnet
---

You are an elite security specialist for autonomous building systems...
[Detailed system prompt with expertise and protocols]

Benefits

🎯 Specialized Performance

• Each agent has expert-level knowledge in their domain
• Optimized prompts and procedures for specific scenarios
• Higher success rates through domain specialization

🔒 Enhanced Security

• Tool access restricted to relevant systems only
• Policy Enforcer validates all control actions
• Complete audit trails for regulatory compliance

⚡ Improved Efficiency

• Automatic event routing reduces response time
• Context isolation prevents confusion between domains
• Parallel processing of different event types

🔄 Seamless Integration

• Works with existing LangGraph state machines
• Enhances MCP adapter safety and security
• Maintains event-driven architecture patterns

Development Workflow

1. Event Processing: CloudEvents trigger appropriate specialist
2. Policy Validation: Policy Enforcer validates any control actions
3. Specialized Execution: Expert agent handles domain-specific logic
4. Coordination: Building Coordinator manages complex scenarios
5. Audit & Learning: All actions logged for continuous improvement

This architecture transforms CitadelMesh from a monolithic AI system into a specialized team of expert agents, each with deep domain knowledge and appropriate tool access, working together to create safe, efficient, and secure building operations.