Files

autonomic-bot 346ed31acb feat: project-orchestrator — engine@v0.1.0 submodule, PO config, fleet.toml registry, mgmt scripts, docs, Nix

The PO is itself a project using the agent-orchestrator harness (engine/ submodule pinned at
v0.1.0). Adds: agents.toml (one persistent fleet-management agent) + prompts/; fleet.toml (the
sole project<->harness<->ref registry) + docs/fleet-registry.md; scripts/ (fleet.py +
create/start/stop/update-project.sh); docs/manage-projects.md + docs/bootstrap.md; flake.nix/.lock
devShell (python311+tmux+git); README.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-13 19:15:47 +00:00

3.1 KiB

Raw Blame History

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.

3.1 KiB Raw Blame History

The fleet registry — fleet.toml