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>
This commit is contained in:
96
README.md
Normal file
96
README.md
Normal file
@ -0,0 +1,96 @@
|
||||
# project-orchestrator (PO)
|
||||
|
||||
The **project-orchestrator** manages a *fleet* of independent projects — creating, starting,
|
||||
stopping, updating, and monitoring them. It is itself **just a project** that uses the
|
||||
[`agent-orchestrator`](https://git.autonomic.zone/recipe-maintainers/agent-orchestrator) harness
|
||||
(vendored as the `engine/` submodule). What makes it the PO is its *job*, not its architecture: there
|
||||
is no special "control-plane" code path.
|
||||
|
||||
```
|
||||
project-orchestrator/
|
||||
agents.toml this project's harness config (one persistent fleet-management agent)
|
||||
engine/ the agent-orchestrator harness, pinned as a submodule @ v0.1.0
|
||||
prompts/ the PO agent's role (orchestrator.md) + periodic sweep (supervise.md)
|
||||
fleet.toml THE fleet registry — the only record of project ↔ harness ↔ ref ↔ location
|
||||
scripts/ fleet.py + create/start/stop/update-project.sh — the management helpers
|
||||
docs/ runbooks: manage-projects.md, fleet-registry.md, bootstrap.md
|
||||
flake.nix/.lock a Nix devShell (python311 + tmux + git)
|
||||
.ao-state/ runtime state + logs (gitignored)
|
||||
```
|
||||
|
||||
## The one rule: knowledge is one-directional (PO → projects, never the reverse)
|
||||
|
||||
A project repo contains **nothing** about the PO or the fleet — no fleet metadata, no `fleet.toml`,
|
||||
no mention of a PO. A project can be run and inspected entirely by hand and would have no idea a PO
|
||||
exists. The *only* record of which projects exist, where, which harness, what ref, and whether
|
||||
they're enabled is this repo's **`fleet.toml`**. The PO knows the projects; the projects never know
|
||||
the PO.
|
||||
|
||||
What a project *does* carry is its `engine/` submodule pin — a plain git fact (this harness, this
|
||||
ref) with no fleet semantics. The PO's `fleet.toml` mirrors that for fleet inventory.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
nix develop # python311 + tmux + git on PATH (see "Nix")
|
||||
|
||||
python3 engine/agents.py status # the PO's own agents (reads agents.toml)
|
||||
python3 scripts/fleet.py status # the fleet registry: projects, enabled, harness@ref
|
||||
|
||||
python3 engine/agents.py up # start the PO agent + its watchdog (needs claude on PATH)
|
||||
python3 engine/agents.py down # stop everything
|
||||
```
|
||||
|
||||
The PO agent itself is one persistent `claude` session (`prompts/orchestrator.md`) with an hourly
|
||||
fleet sweep (`prompts/supervise.md`), supervised by the harness watchdog. See `engine/README.md`
|
||||
for the full harness reference.
|
||||
|
||||
## Managing the fleet
|
||||
|
||||
Full runbooks in [`docs/manage-projects.md`](docs/manage-projects.md). In short:
|
||||
|
||||
```bash
|
||||
# create a new project: scaffolds engine/ submodule + harness config, NO PO/fleet metadata inside it
|
||||
scripts/create-project.sh my-new-project --ref v0.1.0 [--register]
|
||||
|
||||
# drive an existing fleet project's harness (resolves location via fleet.toml)
|
||||
scripts/start-project.sh <name>
|
||||
scripts/stop-project.sh <name>
|
||||
scripts/update-project.sh <name> <new-ref> # bump that project's engine pin (per-project, opt-in)
|
||||
|
||||
# inspect the fleet
|
||||
python3 scripts/fleet.py list | status | validate | get <name>
|
||||
```
|
||||
|
||||
The fleet registry schema is documented in [`docs/fleet-registry.md`](docs/fleet-registry.md).
|
||||
|
||||
## Nix
|
||||
|
||||
A `flake.nix` provides a reproducible devShell with the runtime deps (`python311` for stdlib
|
||||
`tomllib`, plus `tmux` and `git` incl. submodule support):
|
||||
|
||||
```bash
|
||||
nix develop # enter the shell
|
||||
nix develop -c python3 -c 'import tomllib' # sanity: the runtime python has tomllib
|
||||
nix develop -c python3 engine/agents.py status # run a command in the shell
|
||||
nix flake check # evaluate + build the devShell
|
||||
```
|
||||
|
||||
The agent CLI the PO uses (`claude`) is an **external, non-Nix tool** — install it per its own docs
|
||||
and ensure it is on `PATH` before launching the live agent.
|
||||
|
||||
## First-time setup / re-scaffolding
|
||||
|
||||
Nothing creates the *first* PO — it is hand-scaffolded once.
|
||||
[`docs/bootstrap.md`](docs/bootstrap.md) records exactly how (it is how this repo was made), and how
|
||||
an existing PO can later re-scaffold itself.
|
||||
|
||||
## Cloning
|
||||
|
||||
Because the harness is a submodule, clone recursively:
|
||||
|
||||
```bash
|
||||
git clone --recurse-submodules https://git.autonomic.zone/recipe-maintainers/project-orchestrator.git
|
||||
# or, after a plain clone:
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
Reference in New Issue
Block a user