Chapter 25: Sub-Agents and Claude Code Integration

Chapter Status: ✅ 100% Working (20/20 examples)

Last updated: 2025-09-23 PMAT version: pmat 1.0.0

The Problem

Modern AI-assisted development requires sophisticated agent orchestration beyond simple tool calls. PMAT’s sub-agents feature, integrated with Claude Code’s /agents command, enables powerful distributed intelligence for code analysis, refactoring, and quality enforcement. This chapter explores how to build, deploy, and orchestrate specialized agents that work together seamlessly.

Core Concepts

Agent System Architecture

PMAT implements a distributed agent system following actor model principles:

1. Agent Classes: Specialized agents for different tasks

   • Analyzer: Code analysis and metrics extraction
   • Transformer: Code refactoring and modification
   • Validator: Quality gates and threshold enforcement
   • Orchestrator: Workflow coordination and routing

2. Communication Protocol: Message-based interaction

   • JSON message format with headers and payloads
   • Priority-based message routing
   • Request/response and publish/subscribe patterns

3. State Management: Hybrid event sourcing

   • Event logs for audit trails
   • Snapshots for fast recovery
   • CRDT-based eventual consistency for non-critical state

Practical Examples

Example 1: Defining Agents with AGENTS.md

Create an AGENTS.md file in your project root to define your agent system:

# Agent System Definition

## System Agents

### Quality Gate Agent
- **Type**: Validator
- **Priority**: Critical
- **Tools**:
  - `pmat_analyze_complexity`
  - `pmat_detect_satd`
  - `pmat_security_scan`

### Refactoring Agent
- **Type**: Transformer
- **Priority**: High
- **Tools**:
  - `pmat_refactor_code`
  - `pmat_apply_patterns`

### Analysis Agent
- **Type**: Analyzer
- **Priority**: Normal
- **Tools**:
  - `pmat_analyze_code`
  - `pmat_generate_metrics`

## Communication Protocol

- **Message Format**: JSON
- **Transport**: MCP
- **Discovery**: Auto

## Quality Requirements

- **Complexity Limit**: 10
- **Coverage Minimum**: 95%
- **SATD Tolerance**: 0

Example 2: Agent Specification YAML

Define individual agents with detailed specifications:

apiVersion: pmat.io/v1
kind: Agent
metadata:
  name: pmat-quality-gate
  class: Validator
spec:
  description: |
    Enforces quality standards with zero-tolerance for technical debt.
  capabilities:
    - complexity_analysis
    - satd_detection
    - security_scanning
  tools:
    - pmat_analyze_complexity
    - pmat_detect_satd
    - pmat_security_scan
  config:
    thresholds:
      max_complexity: 10
      max_satd_count: 0
      min_coverage: 0.95
    resource_limits:
      max_memory_mb: 512
      max_cpu_percent: 25

Example 3: Agent Communication Messages

Agents communicate using structured JSON messages:

{
  "header": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from": "analyzer-agent",
    "to": "quality-gate-agent",
    "timestamp": 1234567890,
    "priority": "high",
    "correlation_id": "request-123"
  },
  "payload": {
    "type": "analysis_complete",
    "data": {
      "file": "main.rs",
      "complexity": 8,
      "coverage": 0.96,
      "satd_count": 0
    }
  }
}

Example 4: Workflow Orchestration

Define complex workflows that coordinate multiple agents:

name: quality_check_workflow
version: 1.0.0
error_strategy: fail_fast
timeout: 5m

steps:
  - id: analyze
    name: Analyze Code
    agent: analyzer
    operation: analyze_code
    params:
      language: rust
      metrics: [complexity, coverage, satd]

  - id: validate
    name: Quality Gate Check
    agent: quality_gate
    operation: validate_metrics
    depends_on: [analyze]
    retry:
      max_attempts: 3
      backoff:
        type: exponential

  - id: refactor
    name: Apply Refactoring
    agent: transformer
    operation: apply_refactoring
    depends_on: [validate]
    condition: "steps.validate.output.needs_refactoring == true"

Example 5: Claude Code Integration

Create .claude/agents/ directory with agent definitions for Claude Code:

# .claude/agents/pmat-analyzer.md

## Description
Analyzes code quality using PMAT metrics and enforces Toyota Way standards.

## Available Tools
- pmat_analyze_complexity
- pmat_detect_satd
- pmat_calculate_metrics
- pmat_quality_gate

## Instructions
When asked to analyze code:
1. Run complexity analysis with cyclomatic and cognitive metrics
2. Detect all forms of technical debt (TODO, FIXME, HACK, XXX)
3. Calculate comprehensive quality metrics
4. Apply quality gates with zero-tolerance for SATD
5. Return structured report with actionable recommendations

## Quality Gates
- Max Cyclomatic Complexity: 10
- Max Cognitive Complexity: 7
- SATD Count: 0 (zero tolerance)
- Min Coverage: 95%
- Max Duplication: 2%

## Response Format
```json
{
  "status": "pass|fail",
  "metrics": {
    "complexity": {...},
    "coverage": {...},
    "satd": {...}
  },
  "violations": [...],
  "recommendations": [...]
}

### Example 6: Using Agents with Claude Code

Once configured, use agents via the `/agents` command in Claude Code:

```bash
# List available agents
/agents

# Use a specific agent for analysis
/agents pmat-analyzer analyze src/main.rs

# Orchestrate multiple agents
/agents workflow quality_check_workflow --file src/lib.rs

# Get agent status
/agents status pmat-quality-gate

Example 7: MCP-AGENTS.md Bridge

The bridge enables seamless integration between AGENTS.md and MCP protocols:

#![allow(unused)]
fn main() {
// Bridge configuration in your PMAT setup
use pmat::agents_md::{McpAgentsMdBridge, BridgeConfig, QualityLevel};

let bridge = McpAgentsMdBridge::new(BridgeConfig {
    bidirectional: true,
    auto_discover: true,
    quality_level: QualityLevel::Extreme,
});

// Register tools from AGENTS.md
bridge.discover_and_register().await?;

// Handle requests
let response = bridge.handle_request(request).await?;
}

Example 8: Agent State Management

Agents maintain state using event sourcing with snapshots:

#![allow(unused)]
fn main() {
// Agent state example
pub struct QualityGateState {
    metrics_history: Vec<QualityMetrics>,
    violations: HashMap<FileId, Vec<Violation>>,
    last_snapshot: SystemTime,
}

impl AgentState for QualityGateState {
    fn apply_event(&mut self, event: StateEvent) {
        match event {
            StateEvent::MetricsRecorded { file_id, metrics } => {
                self.metrics_history.push(metrics);
            }
            StateEvent::ViolationDetected { file_id, violation } => {
                self.violations.entry(file_id).or_default().push(violation);
            }
        }
    }

    fn snapshot(&self) -> Snapshot {
        Snapshot {
            state: self.clone(),
            timestamp: SystemTime::now(),
        }
    }
}
}

Example 9: Resource Control

Agents operate within defined resource limits:

resource_limits:
  cpu:
    max_percent: 25        # 25% of one core
    scheduling_priority: low
  memory:
    max_bytes: 536870912   # 512MB
    swap_limit: 0          # No swap
  network:
    ingress_bytes_per_sec: 10485760  # 10MB/s
    egress_bytes_per_sec: 10485760   # 10MB/s
  disk_io:
    read_bytes_per_sec: 52428800     # 50MB/s
    write_bytes_per_sec: 52428800    # 50MB/s

Example 10: Quality Enforcement

Agents enforce strict quality standards:

#![allow(unused)]
fn main() {
// Quality gate enforcement
pub struct QualityGateAgent {
    thresholds: QualityThresholds,
}

impl QualityGateAgent {
    pub async fn validate(&self, metrics: QualityMetrics) -> ValidationResult {
        let mut violations = Vec::new();

        // Zero tolerance for SATD
        if metrics.satd_count > 0 {
            violations.push(Violation::SATD {
                count: metrics.satd_count,
                locations: metrics.satd_locations,
            });
        }

        // Complexity checks
        if metrics.complexity > self.thresholds.max_complexity {
            violations.push(Violation::ExcessiveComplexity {
                found: metrics.complexity,
                max: self.thresholds.max_complexity,
            });
        }

        if violations.is_empty() {
            ValidationResult::Pass
        } else {
            ValidationResult::Fail(violations)
        }
    }
}
}

Common Patterns

Pattern 1: Agent Discovery

Agents automatically discover each other:

#![allow(unused)]
fn main() {
// Auto-discovery using mDNS
let discovery = AgentDiscovery::new();
let agents = discovery.discover().await?;

for agent in agents {
    println!("Found agent: {} at {}", agent.name, agent.endpoint);
    registry.register(agent).await?;
}
}

Pattern 2: Workflow DAG Execution

Execute complex workflows as directed acyclic graphs:

#![allow(unused)]
fn main() {
let dag = WorkflowDAG::from_yaml("workflow.yaml")?;
let executor = WorkflowExecutor::new(dag);

// Execute with progress tracking
let result = executor
    .with_progress(|stage, progress| {
        println!("Stage {}: {}%", stage, progress * 100.0);
    })
    .execute()
    .await?;
}

Pattern 3: Circuit Breaker for Resilience

Protect against cascading failures:

#![allow(unused)]
fn main() {
let breaker = CircuitBreaker::new(CircuitBreakerConfig {
    failure_threshold: 5,
    success_threshold: 2,
    timeout: Duration::from_secs(30),
});

let result = breaker.call(
    async { agent.process(request).await },
    || Response::default(),  // Fallback
).await?;
}

Troubleshooting

Issue: Agent Communication Timeout

Problem: Agents fail to communicate within expected timeframes.

Solution:

1. Check network connectivity between agents
2. Verify message queue isn’t full (default: 1024 messages)
3. Increase timeout in workflow configuration
4. Check agent resource limits aren’t too restrictive

Issue: State Consistency Errors

Problem: Agents report different states for the same data.

Solution:

1. Verify Raft consensus is working (for critical state)
2. Check event log for missing events
3. Force snapshot and recovery:

   pmat agent snapshot --agent quality-gate
   pmat agent recover --agent quality-gate --from-snapshot
   

Issue: Quality Gate Too Strict

Problem: All code fails quality gates.

Solution:

1. Start with lower thresholds and gradually increase
2. Use phased enforcement:

   quality_levels:
     phase1:
       max_complexity: 20
       min_coverage: 0.70
     phase2:
       max_complexity: 15
       min_coverage: 0.85
     phase3:
       max_complexity: 10
       min_coverage: 0.95
   

Integration with CI/CD

GitHub Actions Integration

name: PMAT Agent Quality Check
on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup PMAT
        run: |
          cargo install pmat
          pmat agent start --config .pmat/agents.yaml

      - name: Run Agent Workflow
        run: |
          pmat workflow execute quality_check_workflow.yaml \
            --timeout 300 \
            --fail-on-violation

      - name: Upload Agent Reports
        uses: actions/upload-artifact@v3
        with:
          name: agent-reports
          path: .pmat/reports/

Docker Deployment

FROM rust:1.80 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y ca-certificates
COPY --from=builder /app/target/release/pmat-agent /usr/local/bin/
COPY agents.yaml /etc/pmat/
EXPOSE 3000
CMD ["pmat-agent", "serve", "--config", "/etc/pmat/agents.yaml"]

Performance Benchmarks

Best Practices

1. Start with Modular Monolith: Begin with in-process agents before distributing
2. Use Raft for Critical State: Ensure consistency for quality-critical data
3. Implement Circuit Breakers: Protect against cascade failures
4. Set Resource Limits: Prevent resource exhaustion
5. Monitor Agent Health: Track metrics and set up alerts
6. Version Your Workflows: Use semantic versioning for workflow definitions
7. Test Agent Interactions: Include integration tests for agent communication
8. Document Agent Contracts: Clearly define inputs/outputs for each agent

Summary

PMAT’s sub-agents feature provides a powerful framework for building distributed intelligence systems that enforce extreme quality standards. By integrating with Claude Code’s /agents command, developers can orchestrate sophisticated analysis and refactoring workflows while maintaining zero-tolerance for technical debt.

Key takeaways:

• Agents are specialized, independent units with specific responsibilities
• AGENTS.md provides a human-readable definition format
• MCP-AGENTS.md bridge enables seamless protocol translation
• Event sourcing with snapshots ensures fast recovery
• Resource control prevents system overload
• Quality gates enforce Toyota Way standards
• Claude Code integration enables natural language orchestration