my-chiefmindmy-chiefmind/ai-maestro/docs/AGENTS.md

ai-maestro

AGENTS.md6 starsChanged 47 days agoMITView on GitHub

AI Maestro ships a small, generic roster. Each agent has one job and a clear handoff — what it receives and what it produces. The orchestrator wires them together per the ticket's agent_plan. One agent sits outside the pipeline — it answers a question about a repo rather than advancing a ticket, so it takes no agent_plan slot: A ticket's agent_plan is an ordered list of these codes: Add tpm before planning or implementation when a ticket needs an explicit…

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository24 other files it gives its agents.
- atomic-reportSkill
- board-validateSkill
- data-modelSkill
- delivery-hygieneSkill
- dev-reportSkill
- dev-setupSkill
- frontend-qualitySkill
- gcSkill
- git-branchSkill
- land-and-archiveSkill
- orchestration-healthSkill
- orchestratorSkill
- pipeline-qualitySkill
- plan-updateSkill
- project-planSkill
- release-gateSkill
- repo-auditSkill
- scaleSkill
- security-reviewSkill
- swarmSkill
- test-coverageSkill
- tpmSkill
- trackerSkill
- worktree-cleanupSkill

The file

We split this AGENTS.md into the rules it gives an agent

7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Add tpm before planning or implementation when a ticket needs an explicit delivery-control checkpoint, for example ["tpm", "pe", "backend"].
line 35
Very specific:
Use tpm for a high-risk or cross-team ticket, a delivery state that does not agree with the board, or a swarm startup/recovery checkpoint.
line 41
Very specific:
Ticket: add tpm first in agent_plan when readiness needs an explicit decision.
line 45
Distinctive:
Swarm: run one TPM checkpoint before filling lanes and again only for drift, stale work, merge contention, or changed gate evidence.
line 47
Very specific:
Messy worktree: run orchestration-health first, preserve the worktree, then have TPM choose resume, finish landing, block, or request an …
line 49
Very specific:
Use the $tpm skill (or /tpm in Claude) to run this assessment against the current board, a named ticket, swarm readiness, or a messy …
line 54
Very specific:
Use single-agent execution mode for small tickets (one implementer, light gate) and multi-agent for full-pipeline work.
line 61

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

The agent roster

AI Maestro ships a small, generic roster. Each agent has one job and a clear handoff — what it receives and what it produces. The orchestrator wires them together per the ticket's agent_plan.

Code	Agent	Role	Receives	Produces
`orchestrator`	orchestrator	Runs the board loop: pick → dispatch → gate → land. Implements nothing itself.	The board	An advanced board + a clear status
`pe`	principal-engineer	Turns a ticket into a concrete implementation plan.	A ticket	A plan the build agent can follow
`backend`	backend-developer	Implements server/data/API work against the plan.	Ticket + plan	A branch with the change
`frontend`	frontend-developer	Implements UI/client work against the plan.	Ticket + plan	A branch with the change
`pipeline`	pipeline-developer	Implements data-pipeline work against the plan, holding the idempotency invariant.	Ticket + plan	A branch with the change
`devops`	devops	Infra, CI, build/release tooling (writing it, not running prod).	Ticket + plan	A branch with the change
`docs`	technical-writer	Writes the document a ticket asks for, when the document is the deliverable.	Ticket + plan	A branch with the document
`qa`	qa	Independent review of the diff vs. acceptance criteria.	A branch + the ticket	Pass, or a specific list of defects
`pd`	principal-delivery	Final delivery validation and landing decision.	A reviewed branch	Merge, or a blocker with a reason
`tpm`	tpm	Reconciles delivery reality and enforces ticket readiness/WIP; it does not implement, QA, or land.	Board + ticket + repository state	A proceed-or-block delivery directive

One agent sits outside the pipeline — it answers a question about a repo rather than advancing a ticket, so it takes no agent_plan slot:

Code	Agent	Role	Receives	Produces
`repo-audit`	repo-audit	Audits exactly one repo — security findings, gaps, a ranked improvement plan. Read-only against code.	A repo	A graded report under the board's `reports/`

Agent-plan shorthand

A ticket's agent_plan is an ordered list of these codes:

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

Add tpm before planning or implementation when a ticket needs an explicit delivery-control checkpoint, for example ["tpm", "pe", "backend"]. It is an evidence and flow-control role; the orchestrator still dispatches work and pd still makes the final landing decision.

When to use Delivery TPM

Use tpm for a high-risk or cross-team ticket, a delivery state that does not agree with the board, or a swarm startup/recovery checkpoint. It is not a status-update stage to attach to every healthy ticket.

Ticket: add tpm first in agent_plan when readiness needs an explicit decision. TPM returns proceed or a single concrete blocker; a blocker stops implementation.
Swarm: run one TPM checkpoint before filling lanes and again only for drift, stale work, merge contention, or changed gate evidence. Do not allocate one TPM per healthy lane.
Messy worktree: run orchestration-health first, preserve the worktree, then have TPM choose resume, finish landing, block, or request an owner decision. An inactive/deferred/ blocked ticket with live work is delivery drift; it is never safe to silently recreate or delete it.

Use the $tpm skill (or /tpm in Claude) to run this assessment against the current board, a named ticket, swarm readiness, or a messy worktree. The tpm agent-plan stage is the ticket-level handoff that follows a proceed decision.

merge is a terminal action handled by the delivery stage, not a separate persona.
Terminal gates (qa, pd, merge) are appended automatically if you omit them, so a minimal plan like ["backend"] still gets reviewed and landed.
Use single-agent execution mode for small tickets (one implementer, light gate) and multi-agent for full-pipeline work.

Extending the roster

In a project, add an agent as maestro/custom/agents/<code>.md with name + description frontmatter and a crisp role/handoff definition, then reference its code in agent_plan. custom/ is the one folder maestro update never touches, and it needs no roster entry — roster selects which kit agents you take; your own are always rendered. To change a kit agent rather than add one, prefer custom/agents/<code>.overlay.md, which appends to it and keeps the kit's half updating; a full custom/agents/<code>.md replaces it and opts the project out of every later improvement to it.

In the kit itself, the same file goes in agents/. Either way, keep roles non-overlapping — if two agents could each do a task, the handoff is unclear.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free