MLRSA - Multi-Layer Recursive Specification Architecture

A professional specification-driven development framework that enables autonomous software orchestration using Claude AI agents. Now with ATLAS integration for persistent agent memory and continuous learning.

🚀 Overview

MLRSA transforms complex software development into a systematic, specification-driven process with AI agents that learn and improve over time through persistent memory.

✨ Key Features

• 🎯 Specification-Driven Development - Define projects through structured specifications with automatic translation to executable agent tasks
• 🤖 Multi-Agent Orchestration - 8 specialized agent roles working in concert with shared knowledge
• 🧠 Persistent Memory (ATLAS) - Agents remember past experiences and continuously improve
• 🔗 Claude MCP Integration - Native integration with Claude MCP server for autonomous orchestration
• 🛡️ AI Code Management - Hallucination detection, constraint enforcement, compilation recovery
• 📈 Iterative Improvement - Each run gets better as agents accumulate experience

📚 Documentation

• 🚀 Quick Start Guide - Get started in 5 minutes
• 📖 Complete Documentation - Full documentation index
• 🧠 ATLAS Integration - Persistent memory system
• 🔧 API Reference - Complete API documentation
• 💡 Examples - Sample projects and use cases

🚦 Quick Start

Prerequisites

• Python 3.11+
• Docker Desktop (for ATLAS memory)
• Node.js 18+ (optional, for MCP)

Installation

# 1. Clone MLRSA
git clone https://github.com/jthom233/mlrsa.git
cd mlrsa

# 2. Install dependencies
pip install -r requirements.txt

# 3. (Optional) Install ATLAS Bridge for persistent memory
pip install qdrant-client
git clone https://github.com/jthom233/mlrsa-atlas-bridge.git
cd mlrsa-atlas-bridge && docker-compose up -d

Windows Users: See Windows Installation Guide

Troubleshooting Installation

If you encounter compilation errors on Windows, use pre-compiled packages:

# Install latest compatible versions (recommended for Windows)
pip install numpy pandas scipy matplotlib scikit-learn psutil pydantic mypy pytest-cov

# Then install remaining pinned dependencies
pip install pyyaml==6.0.1 requests==2.31.0 networkx==3.2.1 aiofiles==24.1.0 httpx==0.27.0 python-dotenv==1.0.1 websockets==12.0 pytest==7.4.4 pytest-asyncio==0.21.1 black==23.12.1 flake8==7.0.0 colorama==0.4.6 tqdm==4.66.1 tabulate==0.9.0 click==8.1.7 rich==13.7.0 sphinx==7.2.6 sphinx-rtd-theme==2.0.0

Create Your First Project

Option 1: Interactive Generator (Recommended)

python quick_project_generator.py
# Follow the prompts to configure your project

Option 2: CLI

python claude_cli.py init my_app \
  -r "Build a task management system with React and Node.js" \
  -t web_application \
  -s 1000

Option 3: Tell Claude

Read the specifications in ~/Projects/my_app/specifications/
and begin autonomous multi-agent orchestration.

🏗️ Architecture

System Overview

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│    MLRSA    │────▶│ ATLAS Bridge │────▶│    ATLAS    │
│(Orchestration)     │   (Integration)     │   (Memory)   │
└─────────────┘     └──────────────┘     └─────────────┘
       │                                         │
       ▼                                         ▼
┌──────────────────────────┐          ┌──────────────────┐
│   AI Agent Orchestra     │◀─────────│  Persistent      │
│ • Meta-Architect         │          │  Memory Layers   │
│ • Creative Director      │          │ • Hot (Redis)    │
│ • Code Generator         │          │ • Warm (Redis)   │
│ • Tester                 │          │ • Cold (Postgres)│
│ • Optimizer              │          │ • Vector (Qdrant)│
└──────────────────────────┘          └──────────────────┘

Execution Phases

1. Initialize - Set up project with constraints
2. Architecture - Design system with memory guidance
3. Implementation - Build with learned patterns
4. Testing - Validate using past bug knowledge
5. Optimization - Improve based on experience
6. Knowledge Sharing - Agents share learnings

🤖 Agent Roles

Agent	Responsibility	Capabilities
Meta Architect	System design	Architecture patterns, tech stack selection, scalability planning
Spec Writer	Technical specifications	API definitions, data models, business logic
Code Generator	Implementation	Multi-language code generation, test creation
Tester	Quality assurance	Unit/integration/performance testing
Validator	Formal verification	Security validation, compliance checking
Optimizer	Performance tuning	Algorithm optimization, resource reduction
Creative Director	UX/Content	User experience, creative features
Polish Director	Refinement	Post-deployment improvements, A/B testing

🛠️ CLI Commands

Core Commands

Command	Description	Example
init	Initialize new project	python claude_cli.py init my_app -r "requirements" -t api -s 10000
status	Check project status	python claude_cli.py status -p my_app
validate	Validate specifications	python claude_cli.py validate my_app
agent	Manage agents	python claude_cli.py agent --list

AI Code Management

Command	Description	Example
ai-validate	Validate AI code	python claude_cli.py ai-validate ./src --fix
compile	Compile with recovery	python claude_cli.py compile my_app -l python
debug	Debug code issues	python claude_cli.py debug src/main.py
monitor	Monitor runtime	python claude_cli.py monitor --pid 12345

Polish & Optimization

Command	Description	Example
polish	Run polish mode	python claude_cli.py polish -m autonomous -p my_app
generate	Generate prompts	`python claude_cli.py generate code_generator '{"module": "auth"}'

🎯 Common Use Cases

Web Application

python claude_cli.py init social_network \
  -r "Social media platform with posts, comments, likes, and real-time chat" \
  -t web_application \
  -s 100000

REST API

python claude_cli.py init payment_api \
  -r "Payment processing API with Stripe integration and fraud detection" \
  -t api \
  -s 50000

Mobile App

python claude_cli.py init fitness_app \
  -r "Cross-platform fitness tracker with workout plans" \
  -t mobile \
  -s 25000

🌟 Advanced Features

AI Code Validation

• Hallucination Detection - Identifies non-existent packages/methods
• Security Scanning - Finds SQL injection, hardcoded passwords
• Performance Analysis - Detects inefficient algorithms
• Auto-Fixing - Automatically corrects common issues

Polish System Modes

• Interactive - Manual review and approval
• Autonomous - Automatic optimization cycles
• Vibe Adjust - Atmosphere tuning (professional/playful/minimal)

Compilation Recovery

• Multi-language support (Python, JS, TS, Rust, C++)
• Automatic error fixing (up to 3 attempts)
• Pattern-based error resolution

📁 Project Structure

mlrsa/
├── Core System
│   ├── claude_orchestrator.py      # Main orchestration engine
│   ├── claude_cli.py               # CLI interface
│   ├── polish_orchestrator.py      # Polish system
│   └── agent_prompts.py            # Agent templates
│
├── AI Code Management (src/orchestrators/)
│   ├── ai_code_validator.py        # Validation & fixing
│   ├── compilation_manager.py      # Compilation recovery
│   ├── debug_orchestrator.py       # Auto-debugging
│   ├── runtime_monitor.py          # Live monitoring
│   ├── version_manager.py          # Dependency resolution
│   └── integration_manager.py      # Module contracts
│
├── Configuration
│   ├── specifications/              # Project specs
│   ├── templates/                   # Project templates
│   ├── examples/                    # Example configs
│   └── mcp_config.json             # MCP settings
│
└── Generated Projects (workspace/)
    └── {project_name}/
        ├── src/                     # Source code
        ├── tests/                   # Test suites
        ├── docs/                    # Documentation
        └── deployment/              # Deploy configs

🧪 Testing

Run the comprehensive test suite:

# Quick validation test
python quick_test.py

# Full test suite
python test_mlrsa.py

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📝 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Full Docs

🎉 Acknowledgments

Built with Claude AI and the power of specification-driven development.

---

Ready to revolutionize how you build software? Start with MLRSA today! 🚀