Maia documentation

Architecture documents describe target contracts, not implemented behavior. Current source status lives in the repository README, the roadmap and maia help --json.

Start here

• Repository README: what Maia is, status and quick start
• Development: setup, parallel worktrees, local gates and CI
• Benchmarks and codebase metrics: the metric catalog, snapshots, base-against-head comparison and the regression policy
• Release, update and compatibility: channels, installer and updates
• Source organization: folder and module rules
• Effect boundaries: the Effect lint rules, boundary adapters and their baseline
• Testing policy: real boundaries over mocks, time, coverage and the test-quality rules
• Decision log: why each architectural choice was made

Swarm coordination

• Swarm coordination: primitives and Skills

• Skills: standard operating procedures: writing, pinning, keeping current, delivering and tracing Skills

• External brain and vendor executors (v1)

• Codex and Claude Code usability audit

• Maia Swarm architecture

• S47 OpenShell containment: the planned containment design.

• Multi-server execution: placement, enrollment and the full Desktop.

• Completed swarm slices: completion notes moved out of the roadmap

• Maia extensions: third-party and Maia verified extensions, authoring, the reviewed directory and the GitHub extension.

• Maia builds Maia: self-hosting SH0–SH3, the autonomous development loop and the rules for parallel agents.

• A managed version is planned; it is tracked outside this repository (D-205).

• Agent operations acceptance: acceptance for S53–S73

• Coordinator

Components

• Maia Node, harness configuration and local telemetry
• Zero-impact updates (the recovery contract) and its spikes
• Maia Agent, coordinator learning, the Pi harness migration and its port record
• Providers and login
• Desktop and mobile clients, the UI specification, the presentation runtime, the portfolio voice contract and the mobile connection proposal
• Portfolio and Workspace acceptance: portfolio user stories, portfolio dogfood suites, Workspace hierarchy delivery and Workspace and Project stories

Reference and operations

• Normative contracts
• Event core: envelope, journal, cursors, federation
• CLI reference
• SDK reference
• Operations and recovery
• Enterprise readiness plan: standards, gaps and certification order

Direction: an organization's agent hub

• Team Workspaces and Control Nodes
• Feature coverage map: requested features mapped to Maia slices, or marked open or not planned
• Identity, authentication and tenancy

Repository rules and the component map are in AGENTS.md.