project-orchestrator/docs/fleet-registry.md

The fleet registry — fleet.toml

fleet.toml is the project-orchestrator's authoritative, PO-only record of every project in the fleet. It is the single place where project ↔ harness ↔ ref ↔ location is recorded. Projects themselves carry none of this: knowledge is one-directional (PO → projects, never the reverse), so a project repo never contains a fleet.toml, a project id, or any mention of the PO.

Validate / inspect it with the helper:

python3 scripts/fleet.py validate     # parse + schema-check; exit 1 on any error
python3 scripts/fleet.py list         # one line per project
python3 scripts/fleet.py status       # list + a summary count
python3 scripts/fleet.py get <name>   # dump one project's full entry

Schema

[fleet] — registry metadata (optional)

key	type	meaning
version	integer	registry schema version; bump on a breaking change to this format

[[project]] — one block per project

key	required	type	meaning
name	yes	string	unique fleet id, kebab-case. Used by the helper scripts to address the project.
location	yes	string	where the project lives: a git URL (remote) or a local filesystem path (a working clone the PO can drive directly).
harness	yes	string	which harness runs the project (e.g. agent-orchestrator). The PO reads that harness's docs to know how to drive it.
ref	yes	string	the harness ref the project pins (its engine/ submodule pin — a tag/branch/SHA). The in-repo submodule pin is the source of truth; this mirrors it for at-a-glance fleet inventory.
enabled	yes	bool	whether this project is part of the active fleet (a bare fleet "start everything" would skip enabled = false).
secrets	yes	string	where the project's creds live (a path like .env, or a secrets-manager ref). Never the secret values themselves; secrets are never in git.
config	no	string	the project's harness config file, relative to its root (default agents.toml).
notes	no	string	free-form operator notes.

Unknown fields are rejected by fleet.py validate (typo guard). Duplicate names are rejected.

Why the registry, and only the registry, holds this

If a project repo recorded its own harness/ref/fleet-membership, that knowledge would be bidirectional and a project would "know" it belongs to a fleet — breaking isolation and making a project un-runnable standalone. Instead:

• what harness + what ref a project uses is captured in the project only as the engine/ submodule pin (a plain git fact, no fleet semantics), and in the PO as this registry's harness/ref. The project never names a PO.
• which projects exist, where, enabled lives only here. Remove a project from the fleet by deleting its [[project]] block; the project repo is unaffected and still runnable by hand.

Adding an entry

Either let scripts/create-project.sh --register append one when it scaffolds a project, or add a block by hand and run python3 scripts/fleet.py validate. See docs/manage-projects.md.