Documentation

• Introduction
  • Shared State over Messages
  • Guarded Execution
  • Autonomous Orchestration
  • When to Use MAESTRO
• Installation
  • One-Line Install
  • Requirements
  • Verify Installation
  • Uninstall
  • Manual Install (from source)
• Quick Start
• Configuration
• Architecture
• SSOT Hub
• Agent Harness
• Auto-Loop
• Agents
• Contract-Bench
• SWE-bench
• API Reference
  • SSOTHub
  • Harness
  • AutoLoop
  • MaestroAgent

---

Introduction

MAESTRO-SSOT is a multi-agent software engineering framework where specialized LLM agents collaborate around a shared structured state instead of passing messages — coordinated by an autonomous control loop and guarded by a restrictive execution harness.

Shared State over Messages

Traditional multi-agent systems (AutoGen, ChatDev) treat collaboration as message passing: agents chat in a group, then try to reconcile their individual work. This causes:

• Integration failures: Agent A assumes Agent B implemented X, but B never did
• Redundant communication: N agents require O(N²) message pairs
• Opaque execution: No audit trail of who changed what and when

MAESTRO replaces chat with a Single Source of Truth (SSOT) — a SQLite-backed structured store for:

Domain	Purpose
Requirements Tree	Hierarchical tasks with dependencies and status
Contract Registry	API schema agreements between agents
Execution Log	Immutable audit trail of every action
Agent Memory	Per-agent key-value working memory

Guarded Execution

Every agent action passes through a Harness pipeline:

Agent Tool Call
      │
      ▼
┌─────────────┐
│   ACL Check │  ← File path allow/deny lists
│   (fnmatch) │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Validator  │  ← Dangerous pattern detection
│  (regex)    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Budget    │  ← Token/step/time limits
│   Tracker   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Sandbox   │  ← Subprocess execution
│   (Local)   │
└─────────────┘

Autonomous Orchestration

The Auto-Loop is an LLM-driven controller that observes the full SSOT state and decides the next action dynamically:

• DECOMPOSE: Break requirements into sub-tasks
• ASSIGN: Match tasks to the best agent
• EXECUTE: Run agents on their assigned tasks
• VERIFY: Validate contracts, run tests, review code
• COMMIT: Snapshot the successful state
• DONE: Terminate when all work is complete

When to Use MAESTRO

MAESTRO is designed for cross-module software engineering tasks that require multiple specialized agents:

• Backend API + Frontend UI coordination
• Database schema + Migration + Test generation
• Multi-service microservices with contract validation
• Bug fixes that span multiple files

For simple single-file tasks, a single-agent approach may be more efficient.

---

Installation

One-Line Install

curl -sSL https://raw.githubusercontent.com/HYPERVAPOR/maestro-ssot/main/scripts/install.sh | bash

The installer will:

1. Check for uv, pipx, or pip and use the best available method
2. Install the maestro CLI tool
3. Create a global config at ~/.maestro/config.toml

Requirements

• Python 3.12+
• macOS, Linux, or WSL

Verify Installation

maestro --version

Uninstall

curl -sSL https://raw.githubusercontent.com/HYPERVAPOR/maestro-ssot/main/scripts/install.sh | MAESTRO_UNINSTALL=1 bash

Manual Install (from source)

git clone https://github.com/HYPERVAPOR/maestro-ssot.git
cd maestro-ssot
uv sync
uv run maestro --version

---

Quick Start

Coming soon...

---

Configuration

Coming soon...

---

Architecture

Coming soon...

---

SSOT Hub

Coming soon...

---

Agent Harness

Coming soon...

---

Auto-Loop

Coming soon...

---

Agents

Coming soon...

---

Contract-Bench

Coming soon...

---

SWE-bench

Coming soon...

---

API Reference

SSOTHub

Coming soon...

Harness

Coming soon...

AutoLoop

Coming soon...

MaestroAgent

Coming soon...