Maestro

/execute

The Maestro is a pure bash state machine — no LLM invoked. It owns all pipeline git (branch + draft PR), reads the wave plan from the issue, determines which tasks are done, and dispatches the next wave of Developers in parallel.

Type: Bash (deterministic, no LLM) · Script: .autoducks/agents/maestro/run.sh · Verbs: execute, run, work (on an issue with Tactics:done)

flowchart LR
  Triggers@{ shape: bolt, label: "Triggers" }
  Maestro["Maestro"]
  Issue@{ shape: notch-rect, label: "Issue\nlabel: Tactics:done" }
  Developers@{ shape: processes, label: "Developers" }

  Triggers --triggers--> Maestro
  Maestro -. depends on .-> Issue
  Maestro -- dispatches --> Developers

  class Triggers triggersOrange
  class Maestro waveGreen
  class Developers executionBlue

  classDef triggersOrange fill:#ffe8d4,stroke:#d66a28,color:#d66a28
  classDef waveGreen fill:#d4f8d4,stroke:#28a745,color:#28a745
  classDef executionBlue fill:#cfe8ff,stroke:#0366d6,color:#0366d6

Triggers

Event	Condition
Issue comment	/execute (or run/work) on a non-Task issue with the Tactics:done label
PR merged	PR merged into a branch starting with feature/ or fix/ — the advancement trigger
Workflow dispatch	feature_issue number — chain dispatch from the Engineer, or manual

Advancement is event-driven: every task PR merged into the pipeline branch re-triggers the Maestro, which recomputes wave state and continues. No polling, no hidden state.

Definition of Ready

Requires Tactics:done. Without it there is nothing to orchestrate — the Maestro posts a 🔁 status and dispatches the Engineer with #auto:execute, so execution resumes automatically when planning finishes (and the Engineer itself cascades to the Architect if the design is missing).

Owns the pipeline git

The Maestro — not the Engineer — creates and maintains:

• the pipeline branch, cut from base_branch: feature/<id>-<slug> for Features, fix/<id>-<slug> for Bugs;
• the draft PR from that branch into integration_branch.

Both are idempotent — re-runs reuse what exists.

Behavior

1. Reacts 👀; posts a status comment for human-triggered runs. Event-driven re-runs maintain a single, in-place-edited orchestration status comment reflecting current wave state instead of stacking new comments — dispatched, skipped, and blocked tasks appear in it as clickable #N references.
2. Checks the Definition of Ready; ensures branch + draft PR.
3. Parses the wave plan from the tactical zone. No waves block? Single-task plan — dispatches the Developer on the issue itself and finishes when its PR merges.
4. Detects completed tasks by scanning merged PRs into the pipeline branch for fixes/closes/resolves #N; ticks the ## Progress checkboxes.
5. Computes wave states; finds the first pending wave whose predecessors are all done.
6. Next wave found → applies Work:orchestrating and dispatches one Developer per unfinished task (in parallel), forwarding any model:/effort:/turns: overrides and the original command author. Updates the orchestration comment in place with the 🌊 wave summary, linking each dispatched task as #N.
7. All waves done → assembles the final PR: Closes #… for every task and the issue, plus a Work Log harvested from each task PR’s Implementation Summary. Marks the PR ready, requests review from the issue assignees, Work:orchestrating → Work:done, assigns the command author, updates the orchestration comment in place with 🎉.
8. Blocked (earlier wave still open) → updates the orchestration comment in place with ⏳, listing the still-blocked #N tasks, and waits for the next merge event.

Topology

The Maestro supports two dispatch topologies for the wave plan:

Mode	Behavior
waves (default)	Every unfinished task in a ready wave dispatches to its own Developer in parallel; the next wave starts only once every task in the current wave is done
sequential	Tasks dispatch one at a time, in dependency order — the wave grouping in the tactical plan is ignored, and only a single Developer runs at once

Resolution order (highest to lowest):

1. A mode: directive on the triggering comment — see Slash commands → mode:
2. A Mode:waves / Mode:sequential label on the issue — see Labels → Orchestrator mode labels
3. orchestrator.mode in .autoducks/autoducks.json — see Configuration → orchestrator.mode
4. Hard default: waves

Reach for sequential when the wave plan’s parallelism doesn’t fully capture a cross-task ordering risk, or to bound how many Developers run concurrently against the same pipeline branch.

Duplicate-dispatch protection

Three independent guards prevent a task from running twice when merge events race:

1. The Maestro skips tasks that already have an open PR claiming them.
2. The Developer’s pre-flight skips if any open or merged PR claims the task.
3. A per-task concurrency group serializes same-task workflow runs.

Required permissions

permissions:
  contents: write
  issues: write
  pull-requests: write
  actions: write

Note

The Maestro is 100% deterministic. Every decision — which wave is next, which tasks to skip, when the PR is ready — is derived from ITS and Git state: merged PRs, labels, branch existence. There is no hidden state; an interrupted pipeline resumes by re-triggering with the same comment.