MAESTRO-SSOT Architecture

Overview

MAESTRO-SSOT is a multi-agent software engineering framework where specialized LLM agents collaborate around a shared structured state (Single Source of Truth) instead of passing messages. Execution is guarded by a restrictive harness, and an autonomous control loop orchestrates planning, assignment, execution, validation, and commit.

System Layers

┌─────────────────────────────────────────────┐
│  CLI + TUI (Typer + Rich + prompt_toolkit)  │
├─────────────────────────────────────────────┤
│  Auto-Loop Controller (deterministic FSM)   │
├─────────────────────────────────────────────┤
│  Role Agents (Planning / Backend / Frontend │
│  / Test / Review / Contract Validator)      │
├─────────────────────────────────────────────┤
│  Agent Harness (ACL + Budget + Validator +  │
│  Sandbox + Rollback)                        │
├─────────────────────────────────────────────┤
│  SSOT Hub (Requirements + Contracts + Logs  │
│  + Memory + Versioning + Access Control)    │
└─────────────────────────────────────────────┘

Layer Details

1. SSOT Hub (maestro-ssot)

SQLite-backed shared state with four domains:

Domain	Model	Purpose
Requirements Tree	RequirementNode	Hierarchical task decomposition with dependency tracking
Contract Registry	Contract	Explicit API contracts between modules with versioning
Execution Log	ExecutionLogEntry	Append-only audit trail of all agent actions
Agent Memory	AgentMemoryEntry	Short-term working memory per agent

Access Control: LockManager provides TTL-based per-resource locks. ConflictDetector prevents write conflicts between agents.

Versioning: VersionManager creates atomic snapshots of the entire SSOT state.

2. Agent Harness (maestro-harness)

Policy-aware action interceptor:

• ACL (acl.py): Glob-based file access rules and command prefix filtering
• Budget (budget.py): Token, step, and wall-clock time limits per agent
• Validator (validator.py): Pre-execution dangerous pattern detection (eval(), os.system, large deletions)
• Sandbox (sandbox.py): SandboxProvider protocol with LocalSandbox implementation (subprocess-based)
• Rollback (rollback.py): Git-based snapshot and reset for epoch-level recovery

3. Agents (maestro-agents)

Built on PydanticAI with SSOT tool injection:

Agent	Role	SSOT Write Access
PlanningAgent	Decompose requirements	Requirements Tree
BackendAgent	Implement server-side logic	Codebase (src/api/), Contracts
FrontendAgent	Implement UI components	Codebase (src/ui/), Contracts
TestAgent	Write and run tests	Codebase (tests/), Execution Log
ReviewAgent	Quality and security review	Execution Log (annotations)
ContractValidator	Rule-based contract consistency	Contract Registry (status)

Tools (tools.py): All agents share a set of PydanticAI function tools for reading/writing requirements, contracts, memory, and logs.

4. Auto-Loop (maestro-loop)

Deterministic state machine orchestrating the execution cycle:

PLAN → ASSIGN → EXEC → VALID → COMMIT → CHECK
  ↑                              ↓
  └──────────────────────────────┘ (retry on failure)

• PLAN: Invoke PlanningAgent to decompose requirements
• ASSIGN: Scheduler matches pending tasks to agents by keyword/role
• EXEC: Run each claimed agent through the Harness
• VALID: ContractValidator + ReviewAgent + test runner
• COMMIT: SSOT snapshot + Git tag on success
• CHECK: Verify all requirements DONE; loop or exit

Retry Budget: RetryBudget allows N full-cycle retries before escalating to human.

5. CLI (maestro root package)

Command	Purpose
maestro	Launch interactive REPL
maestro init [path]	Initialize .maestro/ project directory
maestro run <task>	Non-interactive execution (AutoLoop or sequential fallback)
maestro run --demo <task>	Deterministic demo mode (no LLM required)
maestro status	Rich TUI view of requirements, contracts, and logs
maestro config [key] [value]	Layered configuration management
maestro demo	Phase 1 deterministic demonstration

Configuration Layers:

1. ~/.maestro/config.yaml (global defaults)
2. ./.maestro/config.yaml (project overrides)
3. CLI flags (runtime overrides)

Data Flow

1. Human submits requirement via maestro run "..."
2. AutoLoop initializes SSOT with root requirement
3. PlanningAgent decomposes into sub-requirements (via SSOT tools)
4. Scheduler assigns pending tasks to role agents
5. Each execution agent reads contracts, writes code via Harness, updates status
6. ReviewAgent and ContractValidator validate the epoch
7. On success: COMMIT creates SSOT snapshot and Git tag
8. On failure: ROLLBACK resets code and replans

Key Design Decisions

1. Shared state over messages: Agents read/write a structured SSOT, not chat logs
2. Guarded execution: Every action passes through ACL → validator → budget → sandbox
3. Observable by default: All mutations are logged; snapshots enable rollback
4. Testable without LLMs: PydanticAI TestModel + demo mode enable deterministic CI testing