autonomic-bot
346ed31acb
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>
56 lines
3.1 KiB
Markdown
56 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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 `name`s 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`.
|