matrix-pattern/docs/schema.md

Matrix Pattern System MCP Server - Advanced pattern management and synchronization

# Matrix Pattern Horizontal Configuration Schema v2.0.0

## Overview

This document describes the Matrix Pattern horizontal configuration schema version 2.0.0, which introduces comprehensive agent specification support. This allows users to configure which agents handle each horizontal, along with their capabilities and specific settings.

## Schema Structure

### Core Configuration Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | ✅ | Unique identifier for the horizontal |
| `description` | string | ✅ | Human-readable description of the horizontal's purpose |
| `sync_strategy` | enum | ✅ | How content is synchronized (`merge`, `replace`, `append`) |
| `priority` | number | ✅ | Execution priority (0 = highest) |
| `required` | boolean | ✅ | Whether this horizontal must have content |
| `validation` | object | ✅ | Content validation rules |
| `metadata` | object | ✅ | Additional metadata about the horizontal |

### Agent Specification Fields (New in v2.0.0)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agentType` | string | ⚠️ | The primary agent type responsible for this horizontal |
| `agentCapabilities` | string[] | ⚠️ | Array of required agent capabilities |
| `agentConfig` | object | ⚠️ | Agent-specific configuration settings |

⚠️ = Optional but recommended for automated agent selection

## Agent Types

The following agent types are supported:

### Core Development Agents
- `coder` - General purpose code generation and implementation
- `backend-dev` - Backend services and server-side development
- `reviewer` - Code review and quality assurance
- `tester` - Test design and quality assurance
- `researcher` - Requirements analysis and research

### Specialized Development Agents
- `api-docs` - API documentation and endpoint specification
- `code-analyzer` - Code analysis and architecture review
- `system-architect` - System architecture and design
- `mobile-dev` - Mobile application development
- `ml-developer` - Machine learning and data science
- `cicd-engineer` - CI/CD and deployment automation

### UI/UX Agents
- `smart-agent` - UI design and user experience
- `planner` - Project planning and coordination

### Coordination Agents
- `hierarchical-coordinator` - Hierarchical task coordination
- `mesh-coordinator` - Mesh network coordination
- `adaptive-coordinator` - Adaptive coordination patterns
- `collective-intelligence-coordinator` - Collective intelligence systems
- `swarm-memory-manager` - Memory management across swarms

### Distributed Systems Agents
- `byzantine-coordinator` - Byzantine fault tolerance
- `raft-manager` - Raft consensus management
- `gossip-coordinator` - Gossip protocol coordination
- `consensus-builder` - Consensus building algorithms
- `crdt-synchronizer` - CRDT synchronization
- `quorum-manager` - Quorum-based decision making
- `security-manager` - Security and authentication

### Performance & Monitoring Agents
- `perf-analyzer` - Performance analysis
- `performance-benchmarker` - Performance benchmarking
- `task-orchestrator` - Task orchestration
- `memory-coordinator` - Memory coordination

### GitHub Integration Agents
- `github-modes` - GitHub integration modes
- `pr-manager` - Pull request management
- `code-review-swarm` - Automated code review
- `issue-tracker` - Issue tracking and management
- `release-manager` - Release management
- `workflow-automation` - Workflow automation
- `project-board-sync` - Project board synchronization
- `repo-architect` - Repository architecture
- `multi-repo-swarm` - Multi-repository coordination

### SPARC Methodology Agents
- `sparc-coord` - SPARC coordination
- `sparc-coder` - SPARC-based coding
- `specification` - Specification writing
- `pseudocode` - Pseudocode generation
- `architecture` - Architecture design
- `refinement` - Code refinement

### Testing & Validation Agents
- `tdd-london-swarm` - TDD London school methodology
- `production-validator` - Production validation

### Migration & Templates
- `migration-planner` - Migration planning
- `swarm-init` - Swarm initialization
- `base-template-generator` - Template generation

## Agent Capabilities

Agent capabilities define what an agent can do. Common capabilities include:

### Development Capabilities
- `code-generation` - Generate code in various languages
- `documentation-generation` - Generate documentation
- `test-design` - Design and create tests
- `debugging` - Debug and troubleshoot issues
- `refactoring` - Refactor and optimize code

### Architecture Capabilities
- `system-design` - Design system architecture
- `database-design` - Design database schemas
- `api-design` - Design APIs and interfaces
- `microservices-architecture` - Design microservices
- `scalability-design` - Design for scalability

### DevOps Capabilities
- `deployment` - Deploy applications
- `containerization` - Containerize applications
- `ci-cd` - Continuous integration/deployment
- `monitoring` - Monitor systems and applications
- `security-implementation` - Implement security measures

### Data & Analytics Capabilities
- `data-modeling` - Model data structures
- `data-preprocessing` - Preprocess data
- `feature-engineering` - Engineer features for ML
- `model-training` - Train machine learning models
- `analytics` - Perform data analytics

### UI/UX Capabilities
- `ui-design` - Design user interfaces
- `ux-research` - Conduct user experience research
- `prototyping` - Create prototypes
- `responsive-design` - Design responsive layouts
- `accessibility` - Implement accessibility features

## Agent Configuration

The `agentConfig` object contains agent-specific settings that customize the agent's behavior. Common configuration patterns:

### Framework Settings
```json
{
  "framework": "react",
  "stateManagement": "redux",
  "styling": "styled-components"
}
```

### Database Settings
```json
{
  "database": {
    "primary": "postgresql",
    "cache": "redis",
    "search": "elasticsearch"
  }
}
```

### Testing Settings
```json
{
  "testing": {
    "unit": "jest",
    "integration": "testcontainers",
    "e2e": "playwright"
  }
}
```

### Deployment Settings
```json
{
  "deployment": {
    "strategy": "blue-green",
    "containerization": "docker",
    "orchestration": "kubernetes"
  }
}
```

## Validation Rules

The schema includes comprehensive validation for agent configurations:

### Agent Type Validation
- Must be one of the supported agent types
- Case-sensitive matching
- Provides suggestions for invalid types

### Agent Capabilities Validation
- Must be an array of non-empty strings
- Validates capability alignment with agent type
- Suggests relevant capabilities for specific agent types

### Agent Config Validation
- Supports string, number, boolean, and string array values
- Validates nested object structures
- Provides suggestions for empty configurations

## Examples

### Basic Configuration
```json
{
  "name": "api",
  "description": "API layer patterns and endpoint documentation",
  "sync_strategy": "merge",
  "priority": 1,
  "required": false,
  "validation": {
    "allow_empty": true,
    "min_content_length": 0,
    "max_content_length": 50000
  },
  "metadata": {
    "category": "technical",
    "audience": ["developers", "api-consumers"],
    "format": "markdown",
    "schema_version": "2.0.0"
  },
  "agentType": "api-docs",
  "agentCapabilities": [
    "documentation-generation",
    "api-design",
    "endpoint-specification"
  ],
  "agentConfig": {
    "documentationStyle": "openapi",
    "includeExamples": true,
    "generateTests": true
  }
}
```

### Advanced Configuration
```json
{
  "name": "backend",
  "description": "Backend services and server-side logic",
  "sync_strategy": "merge",
  "priority": 5,
  "required": false,
  "validation": {
    "allow_empty": true,
    "min_content_length": 0,
    "max_content_length": 50000
  },
  "metadata": {
    "category": "implementation",
    "audience": ["backend-developers", "devops"],
    "format": "markdown",
    "schema_version": "2.0.0"
  },
  "agentType": "backend-dev",
  "agentCapabilities": [
    "server-architecture",
    "database-design",
    "api-implementation",
    "authentication",
    "caching",
    "performance-optimization",
    "microservices",
    "deployment"
  ],
  "agentConfig": {
    "framework": "express",
    "database": "postgresql",
    "authentication": "jwt",
    "caching": "redis",
    "containerization": "docker",
    "testingFramework": "jest",
    "loggingLevel": "info",
    "healthChecks": true
  }
}
```

## Migration from v1.0.0

To migrate from schema version 1.0.0 to 2.0.0:

1. **Update schema version**: Change `metadata.schema_version` to `"2.0.0"`

2. **Add agent specification** (optional but recommended):
   - Add `agentType` field with appropriate agent type
   - Add `agentCapabilities` array with relevant capabilities
   - Add `agentConfig` object with agent-specific settings

3. **Validate configuration**: Use the updated validator to ensure compatibility

### Migration Example

**Before (v1.0.0):**
```json
{
  "name": "api",
  "description": "API layer patterns",
  "metadata": {
    "schema_version": "1.0.0"
  }
}
```

**After (v2.0.0):**
```json
{
  "name": "api",
  "description": "API layer patterns",
  "metadata": {
    "schema_version": "2.0.0"
  },
  "agentType": "api-docs",
  "agentCapabilities": ["documentation-generation", "api-design"],
  "agentConfig": {
    "documentationStyle": "openapi",
    "includeExamples": true
  }
}
```

## Best Practices

### Agent Selection
1. **Choose specific agents**: Use the most specific agent type for your use case
2. **Align capabilities**: Ensure agent capabilities match the horizontal's requirements
3. **Configure appropriately**: Provide relevant configuration for the selected agent

### Capability Definition
1. **Be specific**: Use precise capability names rather than generic terms
2. **Consider dependencies**: Include capabilities that depend on each other
3. **Validate alignment**: Ensure capabilities align with the chosen agent type

### Configuration Management
1. **Environment-specific configs**: Consider different configurations for different environments
2. **Version control**: Track configuration changes in version control
3. **Documentation**: Document custom configuration options

### Validation
1. **Use strict validation**: Enable strict mode for production configurations
2. **Regular validation**: Validate configurations regularly as part of CI/CD
3. **Monitor quality scores**: Track configuration quality scores over time

## Troubleshooting

### Common Issues

**Invalid Agent Type**
```
Error: Invalid agent type: 'invalid-agent'
Solution: Use one of the supported agent types listed in this documentation
```

**Empty Capabilities**
```
Warning: Agent capabilities array is empty
Solution: Add relevant capabilities for your agent type
```

**Capability Misalignment**
```
Suggestion: Agent type 'api-docs' typically requires capabilities like: documentation-generation, api-design
Solution: Add suggested capabilities or choose a different agent type
```

**Invalid Configuration**
```
Error: Agent configuration must be an object with string, number, boolean, or string array values
Solution: Ensure all configuration values are of supported types
```

## Schema Validation

The validator provides comprehensive feedback:

- **Errors**: Critical issues that prevent configuration usage
- **Warnings**: Issues that should be addressed but don't block usage
- **Suggestions**: Recommendations for improvement
- **Quality Score**: Numerical score (0-100) indicating configuration quality

## Support

For additional support or to report issues with the schema:

1. Check the example configurations in `/examples/`
2. Validate your configuration using the built-in validator
3. Refer to the agent capability alignment suggestions
4. Review the troubleshooting section above

---

*Schema version 2.0.0 - Supporting automated agent selection and configuration*