Metadata-Version: 2.4
Name: maestro-fleet
Version: 5.12.2
Summary: Maestro — Fleet Command System: AI-powered multi-agent Claude Code orchestration framework
License: Proprietary
Project-URL: Homepage, https://www.maestrodevs.com
Project-URL: Documentation, https://docs.maestrodevs.com
Project-URL: Support, https://www.maestrodevs.com/contact/
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.1.6
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: rich>=15.0.0
Provides-Extra: dev
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
Requires-Dist: httpx>=0.28.1; extra == "dev"
Requires-Dist: fastapi>=0.141.1; extra == "dev"
Requires-Dist: uvicorn[standard]>=0.52.4; extra == "dev"
Requires-Dist: build>=1.6.0; extra == "dev"
Requires-Dist: setuptools>=84.0.0; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Provides-Extra: hub
Requires-Dist: fastapi>=0.141.1; extra == "hub"
Requires-Dist: uvicorn[standard]>=0.52.4; extra == "hub"
Provides-Extra: azure-secrets
Requires-Dist: azure-keyvault-secrets>=4.11.2; extra == "azure-secrets"
Requires-Dist: azure-identity>=1.25.3; extra == "azure-secrets"
Provides-Extra: azure-anchor
Requires-Dist: azure-storage-blob>=12.30.1; extra == "azure-anchor"
Requires-Dist: azure-identity>=1.25.3; extra == "azure-anchor"
Provides-Extra: aws-secrets
Requires-Dist: boto3>=1.43.83; extra == "aws-secrets"
Provides-Extra: aws-anchor
Requires-Dist: boto3>=1.43.83; extra == "aws-anchor"
Dynamic: license-file

# 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.

**Website:** [maestrodevs.com](https://www.maestrodevs.com) ·
**Documentation:** [docs.maestrodevs.com](https://docs.maestrodevs.com) ·
**Install:** `pip install maestro-fleet`

---

## What It Does

Maestro turns Claude Code into a coordinated team. You define work as **Orders** (discrete tasks),
group them into **Sprints**, 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. Run
`mso docs personas` after installing for the persona reference and switching instructions.

### Roles

| Code | Name | Nautical alias | Focus | Model |
|------|------|---------------|-------|-------|
| PLN | Planner | Navigator (NAV) | Planning & architecture | Opus 4.8 |
| 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.8 |

---

## Installation

1. Install Maestro from PyPI:

   ```bash
   pip install maestro-fleet
   ```

   To pin a specific version, append e.g. `==5.12.1`. The Python import name is `maestro`
   regardless (so `from maestro import ...` keeps working).

2. Activate your licence:

   ```bash
   mso licence activate <YOUR-KEY>
   ```

   Keys are issued with your subscription. For licensing enquiries, contact
   [maestrodevs.com/contact](https://www.maestrodevs.com/contact/).

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

   ```bash
   mso version
   mso licence status
   ```

The wheel itself is openly distributed; the runtime licence check is the gate.

**Upgrading, uninstalling, or seeing a stale/inconsistent version?** Run
`mso docs install-upgrade-uninstall` — it covers the `maestro` to `maestro-fleet` package rename
(the old package must be *removed*, not upgraded), user-vs-system scope shadowing, `PATH` and
Scripts issues, and the full uninstall procedure.

**Restricted-egress or offline operators:** run `mso docs air-gapped` 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-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: `mso docs quickstart`.

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

---

## Personas

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

```bash
# Corporate persona (professional, no nautical metaphors)
mso dispatch --persona corporate

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

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

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

Full persona reference: `mso docs personas`.

---

## 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 doctor        [--json] [--all-projects] [--explain]                    # read-only fleet self-check
mso hub           start [--port N] [--open] | stop | status                # multi-workspace dashboard (Team/Enterprise)
mso cleanup
mso squad         --crew {1-5} [--status | --watch | --cleanup]            # alias: crew
mso verify        [--voyage VOY-ID] [--skip-tests]

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

# Roles
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
```

Run `mso <command> --help` for the full flag set per command, or `mso docs cli-reference` for the
complete reference.

---

## Documentation

**Every documentation page ships inside the wheel itself.** After installing, run `mso docs` to
list them all, or `mso docs <topic>` to read one offline — no need to be online.

| Topic | Audience |
|-------|----------|
| `mso docs start-here` | New users — where to begin |
| `mso docs quickstart` | New users — 5-minute guide to first dispatch |
| `mso docs getting-started` | New users — full installation and setup walkthrough |
| `mso docs install-upgrade-uninstall` | All users — install, upgrade, and uninstall procedures |
| `mso docs personas` | All users — persona system reference |
| `mso docs chain-of-command` | Technical — the 3-layer chain spec |
| `mso docs licence` | All users — `mso licence` activate / status / deactivate / revalidate |
| `mso docs air-gapped` | Restricted-egress / offline operators |
| `mso docs cli-reference` | All users — complete command reference |
| `mso docs operator-guide` | All users — daily operations, scaling, cost management |
| `mso docs roles-guide` | All users — understanding squad roles |
| `mso docs orders-and-voyages` | All users — creating and managing work |
| `mso docs troubleshooting` | All users — common failures and fixes |
| `mso docs support` | All users — how to get help |
| `mso docs hub` | Team / Enterprise — the multi-workspace dashboard |

The hosted documentation site is at [docs.maestrodevs.com](https://docs.maestrodevs.com).

---

## Enterprise Security

Maestro ships an enterprise control set: identity + capability ACL, a hash-chained audit trail
with external anchoring, a secrets-provider abstraction (Azure Key Vault / AWS Secrets Manager /
HashiCorp Vault / 1Password / OS keyring / env), a data-residency egress filter (permissive /
restrictive / air-gapped / proxied), GDPR-aligned Article 15/17/18 rights tooling, and operator
role separation.

Maestro runs entirely on your own infrastructure — no Maestro-operated servers, no telemetry,
bring-your-own AI key. Security posture is reviewed on a rolling basis, and open findings are
published transparently rather than hidden.

Trust posture, threat model, and compliance mapping:
[maestrodevs.com/trust](https://www.maestrodevs.com/trust/).

**Report vulnerabilities confidentially** via the contact form at
[maestrodevs.com/contact](https://www.maestrodevs.com/contact/) — please do not report security
issues on any public tracker.

---

## Workspace Layout

In your 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 config
│   ├── 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 |

---

## Requirements

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

---

## Licence

Proprietary — All Rights Reserved.

Maestro is commercial software. Use is governed by the terms of the `LICENSE` file distributed
with the package. In summary:

- You may use the software for internal business purposes under the terms of a valid licence.
- Redistribution, resale, sublicensing, and reverse engineering are strictly prohibited.
- All intellectual property rights remain with the licensor.

The published wheel 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:
[maestrodevs.com/contact](https://www.maestrodevs.com/contact/).
