How AI Maestro works

A conversation is lost on the next context reset. A board is not. Work lives in board/data.json, so a run can be interrupted, resumed, handed to a different model, or split across parallel sessions without losing where things stand. Every ticket carries the information needed to execute it — which agents touch it, on which model tier, and what must be true before it can start.

A ticket names its own pipeline in agent_plan, e.g. ["pe","backend","qa","merge"]. You cannot skip review by omission: whatever you write, qa and merge are always appended if absent, and pd is added automatically when the ticket is multi-agent or carries a human_gate.

Project plan   the boundary — nothing outside it may run
└── Initiative an independently valuable outcome, several epics — OPTIONAL
    └── Epic   a demonstrable delivery outcome, made of tickets
        └── Ticket  the executable, independently verifiable unit

my-app/
  src/ …                        your application code — never touched
  maestro/                      the kit + your settings
    config.json                 roster, skills, areas, model policy
    context.md                  the brief every agent reads
    board/
      data.json                 live epics + tickets
      archive.json              completed tickets + evidence
      specs/<id>.md             long-form spec for a ticket
      reports/                  generated reports, shown in the web dashboard
    custom/                     YOUR agents & skills — never touched by an update
      agents/*.md
      skills/<name>/SKILL.md
    agents/ skills/ render/ …   kit files — replaced wholesale on update
  .claude/ + CLAUDE.md          GENERATED — Claude agents, skills & guidance
  .agents/ + .codex/ + AGENTS.md GENERATED — Codex skills, subagents & guidance
  .maestro.lock                 content hashes of everything generated

The lock file is what makes the renderer safe: it records exactly which files this tool produced, so it only ever removes its own. Unmanaged runtime files are either adopted into custom/ or left alone — never silently overwritten.

Check the board's integrity any time with maestro validate. It verifies the schema, the dependency graph, agent codes against the roster, status consistency, and id uniqueness across both files.

Each agent is one role with one handoff contract. agent_plan routes by the short code, which is not always the filename — that mapping is the one thing worth memorising.

Skills are procedures an agent (or you) invokes by name — several are also slash commands in your coding tool. Agents are who; skills are how.

Everything of your own lives in maestro/custom/. It is not a kit folder, so an update cannot reach it. What differs between the three options is what happens to your work the next time the kit improves.

sync reports these separately — N added, N replacing a kit agent, N extended — and warns on each replacement, because a replacement is invisible in the output afterwards: it looks exactly like a kit agent.

# set up in your repo — asks a short questionnaire and renders Claude + Codex targets
npx @mychiefmind/ai-maestro setup

# re-render after editing config.json or context.md (from the maestro/ folder)
npm run sync

# bring the kit up to date; your config, context, board and custom/ are kept
npx @mychiefmind/ai-maestro@latest update

# check the board
maestro validate

# change the board — locked, validated, atomic. Never edit data.json by hand.
maestro ticket set-status T-010 in-progress
maestro ticket archive   T-010 --evidence "merged abc123: suite green"

Why a command and not an editor: reading data.json, changing a ticket and writing the file back destroys any change another writer made in between — silently, with no conflict and no error, leaving valid JSON that passes validation. maestro ticket applies the change to the file as it is at write time, under a lock. Exit 2 means someone beat you to it: run the same command again.

What an update touches: only the kit's own folders. Anything of yours it finds among them — an agent you added, or a kit file you hand-edited — is moved into custom/ and named in the output before anything is replaced. Nothing is ever deleted.

A registry lists the projects that cross-project commands operate on. It replaces "the repos that happen to sit in the same parent folder" with an explicit list — and it is the allowlist: a tool may only touch a project named in it.

// maestro-registry.json
{ "projects": [
  { "name": "my-app",   "path": "~/code/my-app" },
  { "name": "platform", "path": "~/code/platform", "kind": "ops" },
  { "name": "old-tool", "path": "~/code/old-tool", "status": "parked" },
  { "registry": "./labs/maestro-registry.json" }        ← a group of groups
] }

• status: parked keeps a repo on the list but out of every sweep — use it instead of deleting the entry, so "deliberately not being worked" stays recorded.
• kind: ops marks portfolio tooling that has no delivery pipeline of its own.
• An entry with registry includes another registry, resolved relative to the file naming it. Names must be unique across the whole tree; cycles are reported with the chain that formed them.

maestro drift  --registry maestro-registry.json        version + hand-edit report per project
maestro update --all --registry maestro-registry.json  update every project (--dry-run to preview)
node maestro/render/sync.mjs --all --registry maestro-registry.json --check

Each project runs in its own subprocess, so one broken project reports and the batch continues. A repo that hasn't adopted the kit is skipped, not counted as a failure.