Metadata-Version: 2.4
Name: admiralty
Version: 2.5.0
Summary: 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
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

# Admiralty — Fleet Command System

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

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

---

## What It Does

Admiralty turns Claude Code into a coordinated fleet. You define work as **Orders** (discrete tasks), group them into **Voyages** (sprints), and the Fleet Admiral dispatches up to 5 specialised **Crews** in parallel — each running as an independent Claude Code session in its own role.

```
Captain (You)  →  Quartermaster (Claude, interactive)  →  Fleet Admiral (script)  →  5 Crews
```

**Roles:**

| Role | Focus | Model |
|------|-------|-------|
| Navigator (NAV) | Planning & architecture | Sonnet 4.6 |
| Shipwright (SHP) | Development & implementation | Sonnet 4.6 |
| Bosun (BOS) | QA & testing | Sonnet 4.6 |
| Scribe (SCR) | Documentation | Sonnet 4.6 |
| Lookout (LKT) | Security & investigation | Haiku 4.5 |
| Coxswain (COX) | Integration & deployment | Opus 4.7 |

---

## Installation

```bash
# Install from GitHub
pip install git+https://github.com/tavisbasing/Admiralty.git@main

# Verify
adm version
```

> **Note:** The distributed pip package is obfuscated with PyArmor for IP protection. The core engine scripts remain plain Python and are readable by crews at runtime.

Then scaffold a workspace:

```bash
adm init --project MYPROJECT --directory my-workspace
cd my-workspace
adm dispatch --max-crews 3
```

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

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

---

## Quickstart

```bash
pip install git+https://github.com/tavisbasing/Admiralty.git@main
adm quickstart
```

`adm quickstart` verifies your environment, scaffolds a demo workspace, dispatches a three-order demo voyage, and prints a summary — all in one command. Full guide: [docs/QUICKSTART.md](docs/QUICKSTART.md).

---

## CLI Reference

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

See [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md) for full documentation.

---

## V6 Enterprise Hardening (in flight — see [VOY-ADM-2026-0026.md](.adm/reports/voyage/VOY-ADM-2026-0026.md))

A voyage targeting **v3.0.0** is implementing 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 (Captain / Fleet Operator / Contributor / Auditor).

The post-implementation pen-test ([SEC-FTR-ADM-2026-0064.md](.adm/reports/security/SEC-FTR-ADM-2026-0064.md)) found **2 CRITICAL + 2 HIGH** open findings (audit-log truncation, print/subprocess secrets exfil, raw-socket egress bypass). The COX release gate **BLOCKS v3.0.0** until those are resolved in a v3.0.x patch voyage. The foundation work (~14 SHP commits + 14 BOS test files) ships in [PR #24](https://github.com/tavisbasing/Admiralty/pull/24) for review.

See:
- [docs/ENTERPRISE-SECURITY.md](docs/ENTERPRISE-SECURITY.md) — operator + buyer guide
- [docs/COMPLIANCE-MAPPING.md](docs/COMPLIANCE-MAPPING.md) — SOC2 + ISO27001 control mapping

## What's New in v2.3.0

**v2.3.0 — Security tooling + engineering foundations**

Sourced from the comparator-recon voyage against `affaan-m/everything-claude-code` (see [docs/COMPARATOR-everything-claude-code.md](docs/COMPARATOR-everything-claude-code.md)).

- **Secret detection in pretool** — `admiralty/hooks/secret_patterns.py` scans every `Edit`/`Write`/`MultiEdit`/`NotebookEdit` for AWS keys, GitHub PATs, OpenAI / Anthropic / Slack tokens, JWTs, RSA/SSH private keys, and high-entropy strings. Fails closed; per-workspace allowlist at `.adm/config/secret-allowlist.json`.
- **MCP server registry** — canonical `.adm/config/mcp-servers.json` with per-server `risk_level`, `allowed_roles`, and `env_required`. Fleet Admiral refuses to launch crews that request unregistered servers or whose role is denied. New `adm mcp list|add|remove|validate|show` CLI; `adm update` migrates existing `.claude/settings.json mcpServers` entries.
- **OWASP/CWE scanning + COX security gate** — `admiralty/security/owasp_patterns.py` runs in `posttool` for LKT crews, writing `.adm/reports/security/SEC-*.json`. COX merge gate refuses on unresolved HIGH/CRITICAL; MEDIUM requires acknowledged waiver. New `adm security scan` CLI for manual runs. Credential snippet matches are redacted before being written to reports.
- **Unit test suite + GitHub Actions CI** — 55 pytest tests covering `fleet_runner.py`, `crew.py`, `fleet_monitor.py`. CI matrix on Python 3.11 / 3.12 / 3.13 via `pip install -e .[dev]`. 70% coverage gate scaffolded with `continue-on-error: true` until follow-up tests raise actual coverage above the bar.

## What's New in v2.2.0

**v2.2.0 — Coxswain role expansion**
- **COX is the terminal role** for every voyage — opens the PR, monitors `gh pr checks --watch`, fetches Copilot review comments, applies/regresses/declines each, resolves review threads via GraphQL, writes the `COX-to-QM.md` handoff, and notifies the Captain via the bridge
- **Default COX model bumped to Opus 4.7** (`claude-opus-4-7`); Opus 4.6 retained in pricing tables for historical transcripts
- **One voyage = 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; BOS validates, COX enforces. Three validation types: `manual`, `command`, `file-exists`. Two severity levels: `blocking` and `advisory`
- **`adm update`** — new command to propagate schema and template changes from the installed pip package into an existing `.adm/` workspace without overwriting user data. Supports `--dry-run` and `--force`
- **Role prompt upgrades** — BOS and COX role prompts updated to include AC validation and gate logic phases

## What's New in v2.0.0

**v2.0.0 — Architecture separation + `adm` CLI**
- **`adm` command** — CLI renamed from `admiralty` to `adm` for brevity
- **`.adm/` folder** — project artefacts live in `.adm/` (not `.admiralty/`) in user projects
- **CLAUDE.md layering** — three-layer context system: project CLAUDE.md → `.adm/claude.md` → pip docs
- **`adm init`** scaffolds `.adm/` with pre-filled `CLAUDE.md` layers from templates
- **Clean separation** — engine code lives only in pip package; repos contain only project artefacts

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

---

## Repo Structure

```
tavisbasing/Admiralty
├── main              — Clean framework (no project state). pip-installable as `adm`.
└── project/{NAME}    — Project-specific state: orders, voyages, prompts, plans
```

The `main` branch is the installable pip package. `project/` branches layer project state on top. The `.gitignore` on `main` permanently excludes all project state paths.

In user projects, Admiralty artefacts live under `.adm/` (scaffolded by `adm init`):

```
my-project/
├── .adm/             # Fleet Command artefacts
│   ├── claude.md     # Layer 2: Fleet Command integration 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

Admiralty uses nautical terms throughout. Here is a plain-English mapping:

| Nautical term | Plain English | Description |
|---------------|--------------|-------------|
| **Captain** | You | The human directing the fleet |
| **Quartermaster** | Claude (interactive) | Your AI assistant in the main session — plans, delegates, and advises |
| **Fleet Admiral** | Dispatcher script | The automation layer that launches and manages crews |
| **Crew** | AI worker | An independent Claude Code session executing a single order |
| **Navigator (NAV)** | Planner | Writes plans, breaks requirements into voyages and orders |
| **Shipwright (SHP)** | Developer | Implements features and fixes bugs |
| **Bosun (BOS)** | QA engineer | Tests, reviews, and validates work |
| **Scribe (SCR)** | Docs writer | Creates and updates documentation |
| **Lookout (LKT)** | Security reviewer | Audits code for vulnerabilities and risks |
| **Coxswain (COX)** | Integration engineer | Handles deployment, CI/CD, and release |
| **Order** | Task | A single unit of work assigned to one crew |
| **Voyage** | Sprint | A group of related orders, tracked together |
| **Requirement** | PRD / feature request | High-level description of what needs to happen |
| **Dispatch** | Launch | Starting the fleet to process queued orders |
| **Fleet Command** | Orchestration system | The framework itself |

---

## 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/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, notifications, reporting |
| [docs/ROLES-GUIDE.md](docs/ROLES-GUIDE.md) | All users — understanding crew roles |
| [docs/ORDERS-AND-VOYAGES.md](docs/ORDERS-AND-VOYAGES.md) | All users — creating and managing work |
| [docs/OWNER-GUIDE.md](docs/OWNER-GUIDE.md) | Framework owners — development and releases |
| [admiralty/docs/CHAIN-OF-COMMAND.md](admiralty/docs/CHAIN-OF-COMMAND.md) | Technical — full system specification |
| [admiralty/docs/VERSIONING.md](admiralty/docs/VERSIONING.md) | Release notes — version-by-version changelog |
| [docs/COMPARATOR-everything-claude-code.md](docs/COMPARATOR-everything-claude-code.md) | Positioning — Admiralty vs `affaan-m/everything-claude-code` (12-dimension matrix) |

---

## 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 Admiralty Framework is commercial software. 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 license.
- Redistribution, resale, sublicensing, and reverse engineering are strictly prohibited.
- All intellectual property rights remain with Tavis Basing (tavisbasing).

For licensing enquiries or permissions beyond the scope of the included license, contact
[tavisbasing](https://github.com/tavisbasing).
