recipe-maintainers/project-orchestrator
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
346ed31acbc0d98eeb2881a1b62998ac9544c002
project-orchestrator/docs/bootstrap.md
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.2 KiB
Raw Blame History

Bootstrap — how the first project-orchestrator is hand-scaffolded

The PO creates projects — but nothing creates the first PO. It is hand-scaffolded once. Thereafter the PO can create projects, and can even re-scaffold itself. This doc records that one-time setup so a fresh PO can be stood up from scratch (it is exactly how this repo was made).

What a PO is

A PO is just a project that uses the agent-orchestrator harness, plus two things no ordinary project has: a fleet registry (fleet.toml) and fleet-management agents/runbooks (prompts/, scripts/, docs/). Its architecture is identical to any project; only its job differs. So bootstrapping a PO = scaffolding a normal agent-orchestrator project, then adding the fleet pieces.

Prerequisites

  • git (with submodule support), python3 >= 3.11 (stdlib tomllib), tmux — all provided by nix develop (see the README's Nix section).
  • The agent CLI the PO agent uses (claude) on PATH — external, not from Nix.
  • A git host for the PO repo (this PO lives at recipe-maintainers/project-orchestrator).

Steps (one time)

  1. Create the PO repo and clone it.

    git init -b main project-orchestrator && cd project-orchestrator

  2. Vendor the harness as engine/, pinned at a release tag (the submodule pin IS the engine version):

    git submodule add https://git.autonomic.zone/recipe-maintainers/agent-orchestrator.git engine
git -C engine fetch --tags && git -C engine checkout v0.1.0
git add .gitmodules engine

  3. Write the harness config — agents.toml declaring the PO's own agent(s). A single kind = "persistent" project-orchestrator agent (backend claude) is enough to start; its startup prompt is prompts/orchestrator.md and it gets an hourly wake → prompts/supervise.md. (You can scaffold a starter with python3 engine/agents.py init . and then edit it, or copy this repo's agents.toml.)

  4. Add the fleet pieces (what makes this project a PO):

    • fleet.toml — the registry (schema: docs/fleet-registry.md), starting empty or with a sample.
    • prompts/orchestrator.md + prompts/supervise.md — the PO agent's role and periodic sweep.
    • scripts/ — fleet.py (read/validate the registry) and create/start/stop/update-project.sh.
    • docs/ — these runbooks.

  5. Add Nix + .gitignore (.ao-state/ is runtime state, never committed). Commit and push main with the submodule pinned.

  6. Bring the PO up — exactly like any project:

    nix develop -c python3 engine/agents.py status   # sanity: config parses, agent listed
nix develop -c python3 engine/agents.py up        # start the PO agent + its watchdog

That's it — the PO is live. From here it manages the fleet via the runbooks in docs/manage-projects.md, and can scaffold further projects (including a replacement PO) with scripts/create-project.sh.

Re-scaffolding the PO later

Because a PO is just a project, an existing PO can create a new PO by running the create-a-project flow with this repo's URL as the engine consumer and then adding the fleet pieces — or, more simply, by cloning this repo recursively. The bootstrap above is only needed when there is no PO at all.