AI Maestro turns AI-assisted coding from improvised chat sessions into a managed delivery process. Instead of one developer prompting one AI, a portfolio of specialized AI agents works a visible board of tasks — each task routed to the right agent and the right (cost-appropriate) model, executed in isolation, and quality-gated before it lands. The result: AI development that is trackable, parallelizable, and safe to hand off — the difference between hiring a freelancer and running a team.

👉 Try the step-by-step demo — a click-through walkthrough of setting up a new project, no install required.

AI Maestro runs software delivery as an orchestra of AI agents instead of a single chat session. The idea in three sentences:

| # | The idea | | :--: | --- | | 1 | You keep a board of epics and tickets, bounded by a project plan. | | 2 | Every ticket declares which agents work it (a pipeline like plan → build → qa → merge) and which model each stage runs on. | | 3 | An orchestrator picks the next unblocked ticket, runs it through that pipeline in an isolated git worktree, gates it, and lands it. The default is one ticket per run; optional swarm mode continuously replenishes a bounded lane pool. |

It's the distilled, product-neutral version of a system I've been running across a multi-repo portfolio for months. This repo shares the structure so you can adopt the same way of working.

How it flows

Capabilities

AI Maestro is more than a ticket runner. The board is the control plane for planning, safe parallel delivery, evidence, and integrations — while the project remains a normal Git repository that you own.

| Capability | Use it for | Start here | | --- | --- | --- | | Plan and board | Turn a product goal into scoped requirements, epics, dependencies, and testable tickets. | Project plan → /plan-update | | Specialist delivery pipeline | Route each ticket through planning, implementation, independent QA, delivery approval, and merge. | /orchestrator | | TPM | Get an evidence-backed readiness call, recover from delivery drift, and judge project health. | Delivery control → tpm | | Lanes and Swarm | Run safe independent work in parallel, then continuously replenish a bounded delivery pool. | Swarm mode | | Web dashboard | Manage one or many projects visually: board, operations, plan, roster, usage, and reports. | Web dashboard | | Specs and public APIs | Safely read or update ticket specs and integrate with stable board, plan, spec, and registry APIs. | Public APIs | | Usage and value reporting | Attribute agent and application usage to tickets, models, providers, and projects. | Usage reporting |

Delivery control: when the board needs a decision

Most tickets can flow directly through planning, implementation, QA, and delivery. When the board and repository state disagree — or a release needs an explicit readiness call — run $tpm in Codex or /tpm in Claude. It is the evidence-driven delivery-control skill, paired with the tpm agent stage. It does not write product code, review its own implementation, merge, deploy, or silently clean up work.

| Use it when | TPM checks | TPM returns | | --- | --- | --- | | A high-risk or cross-team ticket must be ready before build work starts | Acceptance criteria, dependencies, expected PR, verification command, and repository reality | Proceed with the next stage, or one concrete blocker | | A swarm starts, recovers, or has merge/lane contention | Board health, active worktrees, agent state, maestro swarm status, and safe lanes | A pool-wide proceed/hold decision — not a TPM agent per healthy lane | | A worktree, branch, PR, or board status is messy or stale | Ownership, commits, merge state, QA/delivery evidence, and drift | Resume, Finish landing, Blocked, or Owner decision required | | You need an honest delivery snapshot | Current board, worktrees, branches, PRs, and gate evidence | A qualitative project judgment plus the next highest-leverage action |

For an explicit per-ticket checkpoint, put tpm first in that ticket's plan:

"agent_plan": ["tpm", "pe", "backend", "qa", "merge"]

TPM produces a short, evidence-backed report rather than a status narrative:

| Scope | Done / evidence | Missing | Blocker / owner | Next | | --- | --- | --- | --- | --- | | Project judgment — Healthy / At risk / Blocked | Facts that support the judgment | Unmet gates or unknowns | Concrete issue and owner, or — | One highest-leverage action | | Active ticket — ID, title, stage | Completed criteria, revision, checks | Specific remaining criterion or gate | Exact blocker and owner, or — | One next stage/action | | Other affected ticket or lane | Evidence, or — | What it needs | Blocker and owner, or — | Next action |

The judgment is qualitative on purpose: no invented percentages, no “almost done,” and no claim that a ticket is complete merely because a branch or PR exists. A ticket is done only after its applicable acceptance, verification, QA, delivery, merge, and board-reconciliation gates complete.

Swarm mode

Swarm mode keeps a bounded pool of agents busy on the board, continuously and safely. It is off by default; turn it on per project:

maestro swarm enable --agents 10 --worktrees 5 --wave-minutes 30
maestro swarm status
maestro swarm disable

Then run $swarm in Codex or /swarm in Claude. The session you run it in is the single coordinator. Every wave it:

| Step | What happens | | --- | --- | | Schedule | Starts only tickets that maestro lanes next says can run together — no overlapping files, dependencies met. | | Staff | Delegates each stage to the right specialist: planning, implementation, independent QA, delivery approval, and repair. | | Gate | No change lands without QA by an agent that did not write it, then the delivery gate. | | Split stale work | A ticket past its size budget is checkpointed and split into smaller tickets, never discarded. | | Land | Approved PRs merge one at a time. Automatic merge stays off until a real exclusive merge lock exists, so PRs wait for you. | | Report | Each wave reports lanes, gate queues, merges, blockers, and target vs. actual capacity. |

--agents is a target, not a promise: the pool never exceeds what your agent host can actually run, and the TPM makes one pool-wide proceed/hold call at startup and after recovery. Details: docs/SWARM.md.

Why work this way

| Principle | What it buys you | | --- | --- | | The board is the source of truth, not the chat. | Work survives context resets, handoffs, and parallel sessions because it lives in board/data.json, not in a conversation you'll lose. | | The right agent and model per task. | A one-line CSS fix and a database migration should not run on the same model or the same prompt. Tickets route themselves. | | Pipelines, not heroics. | Every ticket flows through its configured agent pipeline, followed by the required review and delivery gates. Those gates are structural, not something you remember to do. | | Isolated by construction. | Each ticket runs in its own git worktree, so parallel work never collides and a bad branch never dirties main. | | Reusable skills. | Git branch conventions, worktree cleanup, landing a change, catching up a stale checkout, validating the board — packaged once, used everywhere. |

The Agile advantage

AI Maestro is an Agile delivery process adapted for a solo operator — one human conducting AI agents across one or many projects. The delivery principles map directly:

| Agile principle | How AI Maestro delivers it | | --- | --- | | Deliver working software frequently | A ticket is one independently shippable outcome, and the orchestrator lands exactly one per run — continuous small increments, not big-bang merges. | | Working software is the measure of progress | A ticket isn't done until it passes an independent QA gate and is archived with verification evidence. The board never claims progress the code can't back up. | | Continuous attention to technical excellence | Review and delivery gates are structural pipeline stages, not rituals you have to remember. | | Simplicity — maximize the work not done | Delivery-hygiene rules keep the board to shippable outcomes; specs exist only when a ticket needs more than its description. | | Welcome changing priorities | Kanban-style pull, no sprint to protect: reorder or re-scope the backlog any time, and the next run simply picks the new top eligible ticket. | | Transparency and sustainable pace | A glance at the board always shows the true state, and the one-ticket-per-run loop puts a human checkpoint between every increment. |

The team ceremonies that assume a room full of people — stand-ups, sprint planning, sprint reviews — are deliberately replaced by that between-ticket checkpoint: you review each landed increment before conducting the next. See docs/METHOD.md for the full mapping.

What's in the box

| Piece | What it is | | --- | --- | | board/ | The board + project-plan formats (board.schema.json, plan.schema.json) and this repo's own workboard. A runnable example board ships in starters/orchestrated-project/board/ instead — that's what setup seeds a new project from, never this one's. | | agents/ | A generic agent roster: orchestrator, tpm, principal-engineer, backend, frontend, devops, technical-writer, qa, principal-delivery | | skills/ | Reusable skills — the /project-plan, /plan-update, /orchestrator, /tpm, and optional /swarm entry points, plus board hygiene, release gate, security review, and the git/worktree basics | | render/ | sync.mjs — generates native Claude Code and Codex files from one config + context; --all --registry <file> does it across every project in a registry | | starters/ | Two starter capsules: full orchestrated project, or a lightweight single-area one | | bin/cli.mjs | The maestro CLI — setup, sync, validation, board/plan writes, and the triggered dev → PR → reviewer pipeline | | scripts/registry.mjs | The shared registry format behind maestro drift and sync --all — see Managing several projects | | docs/ | The method, model-routing policy, and a getting-started guide |

Quickstart

Two ways in — pick one:

| Path | What it is | Command | | --- | --- | --- | | 1 — Instant Setup with npx | Run the questionnaire yourself, then do the first steps. | npx @mychiefmind/ai-maestro setup | | 2 — Hands-Free Onboarding with an AI coding agent | Paste one prompt in Claude Code or Codex; the agent runs setup and fills things in for you. | (the prompt is below) |

Starting from an empty folder, or showing someone else how this works? The new-project demo walks the whole path in plain language, written for a complete beginner — install, answer a few questions about your project, review the generated epics and dependency-ordered tickets, then run the orchestrator.

Path 1 — Instant Setup with npx

One command in your project — no clone, no install:

cd ~/code/my-app     # your project
npx @mychiefmind/ai-maestro setup # asks about your project; Enter accepts every default

setup asks for your project brief — outcome, users, stack, constraints, and how to run and test it — then copies the kit into ./maestro/, writes your config.json + context.md from those answers, runs git init if the folder isn't a repo yet, renders native Claude Code and Codex agents & skills at your repo root, checks the board, and asks if you'd like to open the visual board (say no and nothing is left running). The six project-brief questions default to propose one, which hands those decisions to the agents and has them show you what they chose; the project name and work areas have concrete defaults.

Now open the repo in Claude Code or Codex and run /project-plan — it writes the project plan first (goal, scope, deliverables, use cases, functional and non-functional requirements), stops for your review, then turns it into epics and dependency-ordered tickets that each trace back to a plan item. Approve them, then run /orchestrator; it picks up the first unblocked ticket and runs it — and refuses anything the plan doesn't cover. (Plain language works too: "plan the project", "run the board".)

Path 2 — Hands-Free Onboarding with an AI coding agent

Prefer not to answer the questionnaire yourself? Open your project in Claude Code, Codex, or another compatible agentic tool and paste this prompt — it runs setup with answers drawn from your real codebase, then plans a board for you to review:

Add AI Maestro — the AI-agent orchestration kit — to this project.

1. From the repo root, run setup non-interactively, filling each answer
   from the ACTUAL codebase (README, package manifests, configs) — not
   guesses. Show me the answers before you run it:

   npx @mychiefmind/ai-maestro setup --yes --no-board \
     --name "<project name>" --areas "<areas, e.g. frontend,backend,infra>" \
     --outcome "<what this project does>" --users "<who it's for>" \
     --stack "<languages, frameworks, database, hosting>" \
     --constraints "<real conventions and guardrails>" \
     --run "<real dev command>" --test "<real test command>"

   This vendors the kit into ./maestro/ and renders Claude files into ./.claude/
   plus Codex skills/subagents into ./.agents/ and ./.codex/ at the repo root.
   It must NOT touch my application code.

2. Then plan the work: propose a few real starter tickets based on
   near-term work you can see (TODOs, missing tests, rough edges), keep
   every ticket status "todo", and validate the board.

3. Report back: the answers you used, the agent roster, the proposed
   tickets, and whether I should commit maestro/ or gitignore it.

Do NOT start executing tickets. Stop after planning so I can review —
then I'll run /orchestrator myself.

First steps after setup

Open your project in Claude Code or Codex and run these once, in order:

| Step | Do this | Why | | :--: | --- | --- | | 1 | Run:/project-plan | Writes the project plan from your brief — goal, scope, deliverables, use cases, functional and non-functional requirements — and proposes an answer for anything you left as propose one. It stops for your review; nothing is implemented. | | 2 | Review the plan; fill in what's thin with /plan-update or the board's Plan tab | The plan reports a completeness percentage and says which sections are missing. It's the contract every later agent works from — and the scope boundary the orchestrator enforces. | | 3 | Approve it; /project-plan then writes 3-6 epics and 5-15 dependency-ordered tickets, each tracing to a plan item | A ticket that traces to nothing is out of scope by definition, and won't run. | | 3b | Large project only: group the epics under 2-6 initiatives | Optional, and most projects skip it. Use it when the project holds several outcomes that are each independently worth shipping and each need multiple epics. | | 4 | Commit the approved starting point, then run:/orchestrator | The first commit gives worktrees a stable base; the orchestrator then builds one ticket per run. |

Going further

Adopting this into an existing codebase, tuning models and areas, alternative layouts, and troubleshooting: docs/GETTING-STARTED.md.

Already set up and a new version is out? npx @mychiefmind/ai-maestro@latest update refreshes the kit in maestro/ and re-renders — your config, brief, and board are kept (details).

Running several projects? The web dashboard shows them all in one local browser tab.

How the levels nest

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

Initiatives are optional and most projects do not need them. Reach for them only when a project holds several independently valuable outcomes that each need multiple epics — then each one gets its own outcome, boundary, metrics, and its own slice of the plan's requirements. A ticket never stores an initiative; it derives one through its epic, and a trace that crosses initiatives is refused. A project that defines none behaves exactly as it did before the layer existed.

The core idea in one ticket

{
  "id": "T-014",
  "epicId": "e2",
  "name": "Add rate limiting to the public API",
  "area": "backend",
  "priority": "P1",
  "swag": "M",
  "status": "todo",
  "depends_on": ["T-011"],
  "agent_plan": ["pe", "backend", "qa", "merge"],  // the pipeline
  "model": "sonnet"                                  // the model to run it on
}

The orchestrator reads that and does the rest: it won't touch T-014 until T-011 is done; when it does, it runs a principal-engineer plan, hands the plan to the backend agent in a fresh worktree, gates through QA, then merges and archives.

How it sits in your project

After setup, AI Maestro is a sidecar — the tooling lives in maestro/ and never touches your application code, and the generated agents land at your repo root so the coding tool discovers them.

my-app/
├── src/  …                    ← your real code (untouched)
├── maestro/                   ← the kit + your settings
│   ├── config.json            ← project name, areas, models   (setup writes this)
│   ├── context.md             ← the brief every agent reads    (setup writes it from your answers)
│   ├── board/data.json        ← epics + tickets (edit here or in the web dashboard)
│   └── custom/                ← optional: YOUR agents & skills (never touched by an update)
│       ├── agents/*.md
│       └── skills/*/SKILL.md
├── .claude/                   ← GENERATED — Claude agents & skills
├── CLAUDE.md                  ← GENERATED — Claude project guidance
├── .agents/skills/            ← GENERATED — Codex skills
├── .codex/agents/             ← GENERATED — Codex custom subagents
└── AGENTS.md                  ← GENERATED — Codex project guidance

You'll need git, Node.js 18+, and an agentic coding tool that can run subagents (Claude Code, Codex, or compatible). Setup is the single command from the Quickstart — then, from your coding tool at the repo root, run /project-plan, approve the plan, and run /orchestrator.

Keep your own agents/skills in one place. Drop custom agents in maestro/custom/agents/ and skills in maestro/custom/skills/<name>/SKILL.md. sync merges them into every enabled runtime target (overriding a kit file of the same name), and maestro/custom/ is the one folder an update never touches — so unlike hand-editing generated runtime files, they survive both re-renders and kit upgrades. They don't need listing in config.json: roster/skills selects which kit agents you take; your own are always included.

Keep the kit out of your project's git? npx setup vendors a plain folder — commit it or ignore it. A cloned kit brings its own .git, so either rm -rf maestro/.git or gitignore maestro/. Both variants, plus the shared-kit and vendored layouts, are in 👉 docs/GETTING-STARTED.md.

Web dashboard

@mychiefmind/ai-maestro-web-ui (Maestro) is the visual side of AI Maestro: a local web dashboard that listens on your own machine only. Each project keeps its own maestro/ folder.

One project — run it inside the project (the folder that has ./maestro):

npx @mychiefmind/ai-maestro-web-ui

Many projects in one place — make an empty folder your Maestro Hub and run the same command there. It sets the folder up, installs what it needs, and opens the dashboard:

mkdir ~/maestro-hub && cd ~/maestro-hub
npx @mychiefmind/ai-maestro-web-ui   # first time
npm start                            # every time after

Then click Add board and pick each project folder, or run npx ai-maestro-web-ui add <path>. Maestro Hub opens at http://maestro.localhost:3021.

• Board per project, with epics, specs, plan, and archive editing
• An all-projects operations view: in flight, eligible, blocked, and in review
• Token usage, reports and docs, project plan, and roster
• Light and dark themes; works on phones

Usage reports separate runtime from inference provider and combine exact Codex counters with a privacy-safe application ledger for provider calls such as DeepSeek; see docs/USAGE.md.

Token usage is recorded automatically. maestro sync adds Claude Code Stop, SubagentStop and SessionEnd hooks to .claude/settings.json (your own hooks are kept) that record count-only records — no prompts or paths — into the untracked board/.usage-pending.jsonl, so your checkout stays clean; maestro usage commit folds them into the committed board/usage.jsonl (merge=union). The hooks never block a session. Turn it off with "usage": { "record": false } in config.json and re-run maestro sync; see automatic recording.

It reads and writes project data only through AI Maestro's public APIs (board, plan, spec, registry, and usage exports), with locking — see docs/PUBLIC-DATA-API.md.

GitHub · npm

Status

Early and evolving — the structure is battle-tested; the packaging is new. Issues and ideas welcome. See CONTRIBUTING.md.

License

MIT — see LICENSE.