Orchestrator (run entry point)

This is the entry point for a board run — this skill invoked by name, "run the board", "work the next ticket". The loop itself lives in the orchestrator agent: it selects the ticket, dispatches each stage, enforces the gates, and lands or blocks. Your job here is to pre-flight, hand off, and report what actually happened.

Do not run the loop yourself. Don't pick tickets, write code, or merge from this skill — a run that skips the agent skips its gates.

1. Pre-flight

Check these first; each one is a common cause of a wasted or destructive run.

• The board validates. Run the board-validate skill. A broken dependency graph or an unknown agent code makes ticket selection meaningless — fix it before dispatching.
• The working tree is clean at the repo root (git status). Uncommitted work is carried into the ticket's worktree and muddies its diff. Ask before touching anything you didn't write.
• No unowned run is in flight. An in-progress ticket that no lane of this run owns means another run holds it (or one died holding it). Report it and stop rather than racing it. An in-progress ticket a lane owns is normal in lane mode and does not block the run. Claims themselves are atomic: the agent claims with maestro ticket claim <id> and the --expect-version / --expect-archive-version / --expect-plan-version snapshot guard, so a ticket that moved since it was read is refused, never double-claimed. A refusal exits 0, so the agent claims with --json and proceeds only on "claimed": true.
• Delivery drift is resolved. If the board, branch, worktree, PR, or gate evidence disagrees, run orchestration-health first and then the tpm agent for a proceed-or-block directive. Do not dispatch implementation over a stale, orphaned, or unexpectedly active worktree. The TPM preserves it and asks the owner to choose resume, archive, or cleanup when that choice is not already authorized.
• The brief is real. If context.md still has Open questions — commands or constraints left as propose one — resolve them first (see the project-plan skill). A ticket whose test command is unknown cannot pass a release gate.
• The ticket is in the plan. Run maestro plan gate --json --board {{BOARD}}/data.json: it returns gating, inScopeIds, and outIds. When gating is true, a ticket may only run when its traces_to names an id in inScopeIds. A ticket that traces to nothing, to an id the plan no longer defines, or to an OUT- id is out of scope: report it and stop. Do not fix it by inventing a trace — either the plan gains the requirement (the plan-update skill) or a human writes a scope_exception saying why this runs anyway. gating: false means the project has no plan yet and the gate is off; say so rather than staying silent about it.
• Something is eligible. If no todo ticket has all depends_on done and its human_gate cleared, report idle with the reason and stop. Never clear a human gate to make work eligible.

  "Nothing to do" and "three things to do, none of them in the plan" call for opposite responses from a human. If everything eligible is scope-blocked, report that, name the tickets, and point at the plan-update skill — never report a bare idle.

2. Hand off

Dispatch the orchestrator agent for one ticket. If the ticket needs an explicit delivery-control checkpoint, put tpm first in its agent_plan (for example, ["tpm", "pe", "backend"]); the orchestrator stops if TPM returns a blocker. Pass along anything the user asked for — a specific ticket id (resume), or "what do you see" (discovery: report the board's state and dispatch nothing).

3. Report

Relay the agent's outcome verbatim in substance — done, blocked, idle, merge-failed, or aborted — with the ticket id, what ran, and the evidence (commit SHA, test result). Then say what's eligible next.

• done → the next run picks up whatever this unblocked. Say what that is.
• blocked → surface the specific reason and the blocker ticket. Don't re-dispatch to "try again"; a blocker is a decision for the human.
• merge-failed → the branch and worktree still exist. Report the conflict; don't force-resolve it.
• aborted → the ticket is back to todo and its branch is kept (a lane worktree is kept too). Say so, so the next run knows it can resume from that branch.

Never report a status you didn't get from the agent, and never soften one. A run reported done that didn't merge is worse than a run reported blocked.

Lanes — running more than one ticket at a time

Default is one ticket per run. A project that sets orchestration.maxWorktrees above 1 opts into lanes, and then the rules below are not advice — they are the whole reason parallel work doesn't end in a merge pile-up.

A lane is a worktree that runs a queue of tickets one at a time, landing each before it starts the next. That is the load-bearing idea. A worktree per ticket gives you ten or fifteen long-lived branches nobody planned the merge order for; a single worktree gives you no parallelism at all. A small pool of lanes gives you both: the number of live branches equals the number of lanes, never the number of tickets.

Never decide the schedule yourself. Ask:

maestro lanes plan --board {{BOARD}}/data.json     # the whole schedule, and why
maestro lanes next --board {{BOARD}}/data.json     # just what may start right now

next returns the tickets that may start this instant. Start those and nothing else. It already accounts for dependencies, the plan's scope gate, declared file scopes, epics, areas, serial-only files, and the pool cap.

Then hold these invariants:

1. One lane, one ticket at a time. A lane's next ticket starts only after the current one has landed or been blocked.
2. Rebase before starting. A lane updates from the default branch before each ticket, so a lane is never more than one ticket diverged.
3. Land immediately. Merge when the ticket passes its gate; don't batch. Divergence is what turns into conflict, and every hour a branch waits adds some.
4. One merge at a time. Two lanes must never merge concurrently. If another lane is merging, wait — this is the one step that is genuinely serial.
5. Never start a ticket maestro lanes next didn't return. If you think something else should run, that is a scheduling disagreement: run maestro lanes check <a> <b> and fix the ticket's touches, don't override the answer.
6. A serial-only ticket runs alone. Migrations, lockfiles, generated schema. Drain every other lane first, run it by itself, then refill. lanes next marks these; never start one alongside anything.
7. On any conflict, stop the pool. A conflicted merge means the schedule was wrong. Report it, leave the worktrees alone, and do not start more work on top of a wrong schedule.

When you report, say which lane each ticket ran in and what is startable next — a human reading a parallel run needs to see the shape of it, not a flat list of outcomes.

One run = one ticket (the default)

With no maxWorktrees configured, stop after the ticket. That pause is the point — it's where a human sees the change before the next one starts. Continue only when asked again.