maestro-fleet 4.5.0

Maestro — Fleet Command System: AI-powered multi-agent Claude Code orchestration framework

Maestro — Multi-Agent Orchestration for Claude Code

AI-powered multi-agent orchestration for Claude Code. Coordinate up to 5 parallel AI squads across complex software projects — with role-based specialisation, dependency ordering, token tracking, backup/restore, and full audit trails.

Site: maestrodevs.com · Docs: docs.maestrodevs.com · Install: pip install maestro-fleet

Formerly Admiralty. Maestro was rebranded from the Admiralty Fleet Command System. In v4.0, the adm/admiralty CLI aliases and ADMIRALTY_* environment variables were permanently removed. Use mso and MAESTRO_* exclusively. The workspace directory is now .mso/ (auto-migrated from .adm/ on first mso dispatch). See docs/MIGRATION-v4.md for the upgrade guide.

---

What It Does

Maestro turns Claude Code into a coordinated team. You define work as Orders (discrete tasks), group them into Sprints (voyages), and the Dispatcher launches up to 5 specialised Squads in parallel — each running as an independent Claude Code session in its own role.

Human (You)  →  LEAD (Claude, interactive)  →  Dispatcher (mso dispatch)  →  5 Squads

In the built-in nautical persona (the default), this reads:

Captain (You)  →  Quartermaster (Claude)  →  Fleet Admiral (mso dispatch)  →  5 Crews

The nautical persona is purely stylistic — same mechanics, different vocabulary. See docs/PERSONAS.md for persona reference and switching instructions.

Roles:

Code	Name	Nautical alias	Focus	Model
PLN	Planner	Navigator (NAV)	Planning & architecture	Sonnet 4.6
BLD	Builder	Shipwright (SHP)	Development & implementation	Sonnet 4.6
TST	Tester	Bosun (BOS)	QA & testing	Sonnet 4.6
DOC	Docs writer	Scribe (SCR)	Documentation	Sonnet 4.6
SEC	Security reviewer	Lookout (LKT)	Security & investigation	Haiku 4.5
REL	Releaser	Coxswain (COX)	Integration & deployment	Opus 4.7

---

Installation

1. Install Maestro from public PyPI:

   pip install maestro-fleet
   

   To pin a specific version, append e.g. ==4.5.0. The Python import name is maestro regardless (so from maestro import … keeps working). Airgapped / restricted-egress operators: see docs/AIR-GAPPED.md for the private-index install pattern.

2. Activate your licence (issued via Polar; see https://maestrodevs.com/pricing):

   mso licence activate <YOUR-KEY>
   

3. Verify the CLI is installed and the licence is active:

   mso version
   mso licence status
   

v4.0: Legacy CLI aliases have been removed. Use mso exclusively.

The wheel itself is openly distributed; the runtime licence check is the gate. Source remains private under proprietary licence; see LICENSE for the full terms. Air-gapped / restricted-egress environments: see docs/AIR-GAPPED.md for the staging-machine activation pattern and the egress allowlist.

Then scaffold a workspace:

mso init --project MYPROJECT --directory my-workspace
cd my-workspace
mso dispatch --max-crews 3

To enable the Slack bridge for mobile control, run the setup wizard before starting the bridge:

mso bridge setup    # interactive configuration wizard (first-time setup)
mso bridge start    # start after setup is complete

---

Quickstart

pip install maestro-fleet
mso quickstart

mso quickstart verifies your environment, scaffolds a demo workspace, dispatches a three-order demo sprint, and prints a summary — all in one command. Full guide: docs/QUICKSTART.md.

For deeper configuration, prerequisite validation, project analysis, and CI-friendly --check mode: mso setup — see docs/SETUP.md.

---

Persona Quickstart

Maestro ships with four built-in personas. Switch with:

# Use corporate persona (professional, no nautical metaphors)
mso dispatch --persona corporate

# Use startup persona (casual, fast-moving)
mso dispatch --persona startup

# Use default (minimal, no character)
mso dispatch --persona default

# The nautical persona is active by default
mso dispatch  # same as --persona nautical

Or set it permanently in .mso/config/workspace.json:

{
  "persona": "corporate"
}

Full persona reference: docs/PERSONAS.md.

---

CLI Reference

# Dispatch & monitoring
mso dispatch      [--max-crews N] [--cleanup] [--stagger-delay S] [--timeout M] [--max-turns N] [--persona NAME]
mso status        [--once] [--compact]
mso cleanup
mso squad         --crew {1-5} [--status | --watch | --cleanup]          # alias: crew
mso verify        [--voyage VOY-ID] [--skip-tests]

# Sprints (voyages), orders & review
mso sprint        create "Title" | list | status VOY-ID | reconcile [--dry-run]   # alias: voyage
mso bug           "description" [!high]
mso review        queue | show | approve | revise --notes T | reject --notes T   <ORDER-ID>

# Roles (per-role overlays — FTR-0186)
mso roles         list | show CODE [--core|--overlay-only|--json] | validate | diff CODE | migrate-paths

# Workspace lifecycle
mso init          --project ACRONYM [--directory PATH]
mso quickstart
mso setup         [--check]
mso update        [--dry-run] [--force] [--directory PATH]
mso config        models
mso projects      list | remove

# Usage / security / identity / audit (enterprise tiers)
mso usage         [--summary | --voyage VOY-ID | --order ID | --report]
mso security      scan [--json --severity-threshold HIGH] | review [--against REF --staged]
mso identity      init | add-user | add-group | user|group|acl <add|remove|list> | show
mso audit         anchor [--auto]
mso secrets       doctor | rotate --key KEY | scrub | list
mso data-flow

# Licence / MCP / bridge / hooks / backup
mso licence       activate <KEY> | status | deactivate | revalidate     # alias: license
mso mcp           list | add | remove | validate | show
mso bridge        setup | start | stop | restart | status | test
mso hooks         install | uninstall
mso backup        [--project ACRONYM] [--list]
mso restore       BACKUP_FILE [--force] [--dry-run]
mso version

All commands use the mso prefix exclusively (the adm alias was removed in v4.0). Run mso <command> --help for the full flag set per command.

See docs/CLI-REFERENCE.md for full documentation.

---

V6 Enterprise Hardening — foundation merged (v3.0.0 release-gated)

A sprint targeting v3.0.0 has shipped its foundation: identity + ACL, immutable audit trail with external anchoring, secrets-provider abstraction (Azure Key Vault / AWS Secrets Manager / HashiCorp Vault / 1Password / OS keyring / env), data-residency egress filter (permissive / restrictive / air-gapped / proxied), GDPR-aligned identity privacy + Article 15/17/18 rights tooling, and operator role separation (Human / Fleet Operator / Contributor / Auditor). Foundation merged in PR #24.

The post-implementation pen-test found 2 CRITICAL + 2 HIGH open findings (audit-log truncation, print/subprocess secrets exfil, raw-socket egress bypass). The REL release gate BLOCKS v3.0.0 until those are resolved in a v3.0.x patch sprint.

See:

• docs/ENTERPRISE-SECURITY.md — operator + buyer guide
• docs/COMPLIANCE-MAPPING.md — SOC2 + ISO27001 control mapping
• docs/TRUST.md — public-facing trust posture + open findings + SLAs

What's New

For the full per-release history (including the latest release) see CHANGELOG.md. Highlights since v4.0:

• v4.3.x — dispatcher reliability: per-crew worktree isolation (parallel squads), crash-safe finalization + watchdog, convergence gating (no silent archive on a failed merge), per-tick heartbeat, and a process-tree kill for hung crews.
• v4.2.0 — security posture hardening + mso usage --voyage fixes.
• v4.1.0 — v4 clean-break (legacy admiralty/adm purge completed).

v4.0.0 — Hard-cutover rebrand

• All legacy aliases removed. Legacy CLI entry points are gone. Use mso only. MAESTRO_* env vars exclusively. See docs/MIGRATION-v4.md.
• Workspace directory: .adm/ auto-migrates to .mso/ on first mso dispatch. Use mso migrate-workspace --resolve for split-brain situations.
• mso migrate-workspace command added for manual migration and split-brain resolution.
• Default GitHub org configurable via workspace.json defaultGitHubOrg field.

What's New in v3.0.0

v3.0.0 — Admiralty → Maestro rebrand + persona system

• Rebrand to Maestro. CLI entry point: mso (legacy adm retained through v3.x). Package: maestro (legacy admiralty retained through v3.x). Environment variables: MAESTRO_* (legacy ADMIRALTY_* dual-read through v3.x). All shims removed in v4.0.
• Persona system. Four built-in personas: nautical (default, the heritage theme), corporate, startup, default (minimal). Switch with --persona flag, MAESTRO_PERSONA env var, or workspace.json. Custom personas supported via YAML. See docs/PERSONAS.md.
• Role renames. Canonical codes: PLN/BLD/TST/DOC/SEC/REL/LEAD. Legacy codes NAV/SHP/BOS/SCR/LKT/COX/QM remain as aliases and continue to work in all order JSON, role-paths config, and CLI flags.
• Dual-read workspace. .mso/ preferred, .adm/ fallback. Both are equivalent; existing .adm/ workspaces work without migration.
• CLAUDE.md persona injection. The Quartermaster (nautical) / LEAD (default) framing in CLAUDE.md is now persona-driven via templates.

What's New in v2.5.0

v2.5.0 — Licence backend (Polar.sh) + public wheel distribution + branch discipline

• mso licence CLI — activate <KEY> / status / deactivate / revalidate. Replaces the GitHub-collaborator auth gate. HMAC-signed local store at ~/.maestro/licence.json (mode 0600); per-customer signing secret in OS keychain. 14-day offline grace from each successful online validation.
• Polar.sh as the single licence integration. Selected over Lemon Squeezy / Paddle / Keygen-self-host on take rate, OSS alignment, and AU-tax MoR coverage.
• Public wheel distribution at maestrodevs/maestrodevs.github.io. The source repo stays private; the dist repo ships built wheels via a GitHub Pages PEP 503 simple/ index.
• Branch discipline enforcement (BUG-0004). voyageBranch is now load-bearing across three layers — dispatcher's _verify_dispatcher_branch, pretool branch_guard.py, and a "Branch discipline (mandatory)" section in every role prompt template.
• Domain: maestrodevs.com (live).

What's New in v2.2.0

v2.2.0 — Releaser role expansion

• REL (Coxswain) is the terminal role for every sprint — opens the PR, monitors gh pr checks --watch, fetches Copilot review comments, applies/regresses/declines each, resolves review threads via GraphQL, writes the REL-to-LEAD.md handoff, and notifies the Human via the bridge
• Default REL model bumped to Opus 4.7 (claude-opus-4-7)
• One sprint = one branch = one PR — bundling forbidden by the branching policy

What's New in v2.1.0

v2.1.0 — Quality gates + workspace updates

• Quality gates — structured acceptanceCriteria in orders; TST validates, REL enforces. Three validation types: manual, command, file-exists. Two severity levels: blocking and advisory
• mso update — new command to propagate schema and template changes from the installed pip package into an existing .mso/ workspace without overwriting user data

What's New in v2.0.0

v2.0.0 — Architecture separation + adm CLI

• adm command — CLI renamed from the v1.x binary to adm for brevity (now mso in v3.0.0+)
• .mso/ folder — project artefacts live in .mso/ (or .maestro/ in v3.0.0+) in user projects
• CLAUDE.md layering — three-layer context system: project CLAUDE.md → .mso/claude.md → pip docs
• mso init scaffolds .mso/ with pre-filled CLAUDE.md layers from templates

See maestro/docs/VERSIONING.md for full version history and scheme.

---

Repo Structure

Repository	Visibility	Purpose
tavisbasing/Maestro	private	Source — framework code + MSO project state. Single main branch; sprint / bug branches PR back to it.
maestrodevs/maestrodevs.github.io	public	Distribution — built wheels + PEP 503 simple/ index served via GitHub Pages. Auto-populated by the publish workflow on every v*.*.* tag-push.

The wheel is openly downloadable; runtime use requires a valid licence key (see docs/LICENCE.md).

In user projects, Maestro artefacts live under .mso/ (scaffolded by mso init):

my-project/
├── .mso/             # Maestro artefacts
│   ├── claude.md     # Layer 2: Maestro orchestration context
│   ├── config/       # workspace.json, role-paths.json
│   ├── orders/       # active/, complete/, failed/
│   ├── voyages/      # active/, complete/
│   └── queues/       # orders/, bugs/, security/, ...
└── CLAUDE.md         # Layer 1: project architecture, stack, conventions

---

Glossary

Maestro uses role-neutral terminology by default. The built-in nautical persona adds a layer of seafaring vocabulary. Here is the full mapping:

Canonical term	Nautical persona	Plain description
Human	Captain	The person directing the squads
LEAD	Quartermaster	Your AI partner in the main session — plans, delegates, advises
Dispatcher	Fleet Admiral	The automation layer that launches and manages squads
Squad	Crew	An independent Claude Code session executing a single order
PLN	Navigator (NAV)	Plans, writes architecture notes, breaks requirements into orders
BLD	Shipwright (SHP)	Implements features and fixes bugs
TST	Bosun (BOS)	Tests, reviews, and validates work
DOC	Scribe (SCR)	Creates and updates documentation
SEC	Lookout (LKT)	Audits code for vulnerabilities and risks
REL	Coxswain (COX)	Handles deployment, CI/CD, and release
Order	Order	A single unit of work assigned to one squad
Sprint	Voyage	A group of related orders, tracked together
Requirement	Requirement	High-level description of what needs to happen
Dispatch	Dispatch	Starting the fleet to process queued orders

---

Documentation

Document	Audience
docs/QUICKSTART.md	New users — 5-minute guide to first dispatch
docs/GETTING-STARTED.md	New users — full installation and setup walkthrough
docs/PERSONAS.md	All users — persona system reference
docs/CHAIN-OF-COMMAND.md	Technical — 3-layer chain spec with persona-aware sub-sections
docs/LICENCE.md	All users — mso licence activate / status / deactivate / revalidate
docs/AIR-GAPPED.md	Restricted-egress / offline operators
docs/CLI-REFERENCE.md	All users — complete command reference
docs/OPERATOR-GUIDE.md	All users — daily operations, scaling, cost management
docs/ROLES-GUIDE.md	All users — understanding squad roles
docs/ORDERS-AND-VOYAGES.md	All users — creating and managing work
docs/BRANCH-DISCIPLINE.md	Operators — voyageBranch enforcement
docs/TRUST.md	Security buyers — trust posture, threat model, open findings, SLAs
docs/ARCHITECTURE.md	Security / infra — diagram, data flow, egress inventory
docs/OWNER-GUIDE.md	Framework owners — development and releases

---

Security

For security questions, vulnerability reporting, and compliance documentation:

• SECURITY.md — vulnerability reporting policy + links to all security docs
• docs/PUBLIC-SECURITY-OVERVIEW.md — 1-page CISO-facing summary with data-flow diagram
• docs/ENTERPRISE-SECURITY.md — operator technical detail (ACL, audit, secrets, egress)
• docs/COMPLIANCE-MAPPING.md — SOC2 + ISO27001 control mapping

Report vulnerabilities to [e-mail] — do not open public GitHub issues.

---

Requirements

• Python 3.9+
• Claude Code CLI installed and authenticated
• Anthropic API key with access to Sonnet 4.6, Haiku 4.5, and Opus 4.7

---

License

Proprietary — All Rights Reserved.

The Maestro framework is commercial software, owned and operated by Tech 127 Pty Ltd (Australia). Use is governed by the terms of the LICENSE file included in this repository. In summary:

• You may use the software for internal business purposes under the terms of a valid licence (issued at activation via Polar — see maestrodevs.com/pricing).
• Redistribution, resale, sublicensing, and reverse engineering are strictly prohibited.
• All intellectual property rights remain with Tech 127 Pty Ltd.

The wheel published at maestrodevs.github.io is openly downloadable; the runtime licence check is the gate. Runtime use without a valid key is unauthorised and a breach of the licence.

For licensing enquiries, billing, or sales:

• Email: [e-mail]
• Website: maestrodevs.com
• Docs: docs.maestrodevs.com