Metadata-Version: 2.4
Name: maestro
Version: 3.0.2
Summary: Maestro — Fleet Command System: AI-powered multi-agent Claude Code orchestration framework
License: Proprietary
Project-URL: Homepage, https://github.com/tavisbasing/Admiralty
Project-URL: Repository, https://github.com/tavisbasing/Admiralty
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.0
Requires-Dist: jsonschema>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14; extra == "dev"
Provides-Extra: azure-secrets
Requires-Dist: azure-keyvault-secrets>=4.7; extra == "azure-secrets"
Requires-Dist: azure-identity>=1.15; extra == "azure-secrets"
Provides-Extra: azure-anchor
Requires-Dist: azure-storage-blob>=12.19; extra == "azure-anchor"
Requires-Dist: azure-identity>=1.15; extra == "azure-anchor"
Provides-Extra: aws-secrets
Requires-Dist: boto3>=1.34; extra == "aws-secrets"
Provides-Extra: aws-anchor
Requires-Dist: boto3>=1.34; extra == "aws-anchor"
Dynamic: license-file

# Maestro — Multi-Agent Orchestration for Claude Code

[![CI](https://github.com/tavisbasing/Maestro/actions/workflows/ci.yml/badge.svg)](https://github.com/tavisbasing/Maestro/actions/workflows/ci.yml)

> 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:** [maestroai.com](https://maestroai.com) · **Docs:** [docs.maestroai.com](https://docs.maestroai.com) · **Install:** `pip install maestro --extra-index-url https://maestrodevs.github.io/simple/`

> **Formerly Admiralty.** Maestro is the v3.0.0 rebrand of the Admiralty Fleet Command System. The `adm` CLI alias and `ADMIRALTY_*` environment variables are retained for backwards compatibility. All existing workspaces continue to work without changes.

---

## 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](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

```bash
# 1. Install — no GitHub credentials needed; ships from a public wheel index
pip install maestro --extra-index-url https://maestrodevs.github.io/simple/

# 2. Activate your licence (issued via Polar; see https://maestroai.com/pricing)
mso licence activate <YOUR-KEY>

# 3. Verify
mso version
mso licence status
```

Legacy CLI alias: `adm` continues to work as a synonym for `mso`.

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

Then scaffold a workspace:

```bash
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:

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

---

## Quickstart

```bash
pip install maestro --extra-index-url https://maestrodevs.github.io/simple/
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](docs/QUICKSTART.md).

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

---

## Persona Quickstart

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

```bash
# 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 `.adm/config/workspace.json`:

```json
{
  "persona": "corporate"
}
```

Full persona reference: [docs/PERSONAS.md](docs/PERSONAS.md).

---

## CLI Reference

```
mso dispatch      [--max-crews N] [--cleanup] [--stagger-delay S] [--timeout M] [--persona NAME]
mso cleanup
mso status        [--once] [--compact]
mso usage         [--voyage VOY-ID | --order ORDER-ID | --report [--output PATH]]
mso estimate      [--voyage VOY-ID | --order ORDER-ID | --all] [--queue QUEUE-NAME]
mso approve       (--voyage VOY-ID | --plan FILE | --requirement FILE) [--note TEXT]
mso reject        (--voyage VOY-ID | --plan FILE | --requirement FILE) [--reason TEXT]
mso pause         [--crew N | --all]
mso resume        [--crew N | --all]
mso crew          --crew {1-5} [--status | --watch | --cleanup]
mso verify        [--voyage VOY-ID] [--skip-tests]
mso backup        [--project ACRONYM] [--output PATH] [--list]
mso restore       BACKUP_FILE [--project ACRONYM] [--force] [--merge] [--dry-run]
mso init          --project ACRONYM [--directory PATH] [--force]
mso update        [--dry-run] [--force] [--directory PATH]
mso setup         [--check]
mso create-order  [--interactive | --template NAME] [--project ACRONYM] [--title TEXT] ...
mso create-voyage [--interactive] [--project ACRONYM] [--title TEXT] ...
mso diagnose
mso requirement   <create|list|show|edit|plan|status> [flags]
mso licence       <activate|status|deactivate> [KEY]
mso mcp           <list|add|remove|validate|show> [flags]
mso security      scan [--order|--voyage|--since|--json|--severity-threshold]
mso docs          [TOPIC]
mso version
```

All `mso` commands also accept the legacy `adm` prefix (e.g. `adm dispatch`).

See [docs/CLI-REFERENCE.md](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](https://github.com/tavisbasing/Maestro/pull/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](docs/ENTERPRISE-SECURITY.md) — operator + buyer guide
- [docs/COMPLIANCE-MAPPING.md](docs/COMPLIANCE-MAPPING.md) — SOC2 + ISO27001 control mapping
- [docs/TRUST.md](docs/TRUST.md) — public-facing trust posture + open findings + SLAs

## What's New in v3.0.0

**v3.0.0 — Maestro rebrand + persona system**

- **Rebranded from Admiralty to Maestro.** CLI entry point: `mso` (legacy: `adm`). Package: `maestro` (legacy: `admiralty`). Environment variables: `MAESTRO_*` (legacy: `ADMIRALTY_*` fallback). Existing workspaces continue to work without any changes.
- **Persona system.** Four built-in personas: nautical (default, the original Admiralty character), corporate, startup, default (minimal). Switch with `--persona` flag, `MAESTRO_PERSONA` env var, or `workspace.json`. Custom personas supported via YAML. See [docs/PERSONAS.md](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.** `.maestro/` 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**

- **`adm 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`](https://github.com/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:** [maestroai.com](https://maestroai.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 `.adm/` workspace without overwriting user data

## What's New in v2.0.0

**v2.0.0 — Architecture separation + `adm` CLI**
- **`adm` command** — CLI renamed from `admiralty` to `adm` for brevity (now further aliased as `mso` in v3.0.0)
- **`.adm/` folder** — project artefacts live in `.adm/` (or `.maestro/` in v3.0.0+) in user projects
- **CLAUDE.md layering** — three-layer context system: project CLAUDE.md → `.adm/claude.md` → pip docs
- **`mso init`** scaffolds `.adm/` with pre-filled CLAUDE.md layers from templates

See [maestro/docs/VERSIONING.md](maestro/docs/VERSIONING.md) for full version history and scheme.

---

## Repo Structure

| Repository | Visibility | Purpose |
|---|---|---|
| [`tavisbasing/Maestro`](https://github.com/tavisbasing/Maestro) | private | Source — framework code + MSO project state. Single `main` branch; sprint / bug branches PR back to it. |
| [`maestrodevs/maestrodevs.github.io`](https://github.com/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](docs/LICENCE.md)).

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

```
my-project/
├── .adm/             # Maestro artefacts (or .maestro/ — both work)
│   ├── 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](docs/QUICKSTART.md) | New users — 5-minute guide to first dispatch |
| [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) | New users — full installation and setup walkthrough |
| [docs/PERSONAS.md](docs/PERSONAS.md) | All users — persona system reference |
| [docs/CHAIN-OF-COMMAND.md](docs/CHAIN-OF-COMMAND.md) | Technical — 3-layer chain spec with persona-aware sub-sections |
| [docs/LICENCE.md](docs/LICENCE.md) | All users — `mso licence` activate / status / deactivate / revalidate |
| [docs/AIR-GAPPED.md](docs/AIR-GAPPED.md) | Restricted-egress / offline operators |
| [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md) | All users — complete command reference |
| [docs/OPERATOR-GUIDE.md](docs/OPERATOR-GUIDE.md) | All users — daily operations, scaling, cost management |
| [docs/ROLES-GUIDE.md](docs/ROLES-GUIDE.md) | All users — understanding squad roles |
| [docs/ORDERS-AND-VOYAGES.md](docs/ORDERS-AND-VOYAGES.md) | All users — creating and managing work |
| [docs/BRANCH-DISCIPLINE.md](docs/BRANCH-DISCIPLINE.md) | Operators — voyageBranch enforcement |
| [docs/TRUST.md](docs/TRUST.md) | Security buyers — trust posture, threat model, open findings, SLAs |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Security / infra — diagram, data flow, egress inventory |
| [docs/OWNER-GUIDE.md](docs/OWNER-GUIDE.md) | Framework owners — development and releases |

---

## Requirements

- Python 3.9+
- [Claude Code](https://claude.ai/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](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 [maestroai.com/pricing](https://maestroai.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](https://github.com/maestrodevs/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: [maestro@tech127.com](mailto:maestro@tech127.com)
- Website: [maestroai.com](https://maestroai.com)
- Docs: [docs.maestroai.com](https://docs.maestroai.com)
