maestro

Maestro executes luthier scaffold plans by delegating each commit-sized implementation step to a coding agent (Claude Code by default). It verifies each step with the project's own build tooling, optionally reviews changes with a local LLM, and commits on success — with retry logic and a full audit trail.

Prerequisites

• Go 1.26+
• just
• Claude Code CLI (claude) on your $PATH — required for the default claude coder

Build & Install

just build    # compiles to bin/maestro
just install  # installs to ~/.local/bin/maestro

Usage

maestro [flags] <project-dir>

<project-dir> must contain a plans/ subdirectory with at least one markdown plan file (e.g. generated by luthier).

Flags

Flag	Default	Description
--dry-run	false	Log what would happen without executing steps or committing
--verbose	false	Stream coding agent output in real-time; enables debug logging
--resume-from <step>	""	Skip steps before this title or step number and resume from here
--coder <name>	"claude"	Coding agent to use (claude or noop)
--summary-file <path>	""	Write the final status report to this file in addition to stderr

Examples

Run all plan steps against a luthier scaffold:

maestro ~/dev/myproject

Preview what would happen without making changes:

maestro --dry-run ~/dev/myproject

Stream agent output and debug logs:

maestro --verbose ~/dev/myproject

Resume a failed run from step 5:

maestro --resume-from "Step 5" ~/dev/myproject
# or by step number
maestro --resume-from 5 ~/dev/myproject

Write the final report to a file:

maestro --summary-file results.txt ~/dev/myproject

Running Against a Luthier Scaffold

Luthier generates a scaffold with a plans/ directory. Pass the scaffold root to maestro:

# Generate a scaffold with luthier
luthier my-app.md

# Execute the plan with maestro
maestro my-app/

Maestro reads the most recently dated plan file in plans/, parses its steps, and executes them in order.

Plan File Format

Maestro expects markdown plan files in <project-dir>/plans/ with this structure:

## Step 1 — Set up CLI argument parsing

Create main.go with cobra...

Commit: `feat: set up CLI with cobra`

## Step 2 — Build plan file parser

Implement parsing logic...

Commit: `feat: implement plan parser`

• Steps are headed ## Step N — Title
• Each step ends with a Commit: line containing the conventional commit message
• Maestro picks the alphabetically last .md file in plans/

Coding Agents

claude (default)

Delegates to Claude Code via claude -p <prompt>. The prompt includes the step title, description, and commit message. On retry, feedback from the failed attempt is appended.

Allowed tools: Bash, Read, Write, Edit, Grep, Glob

Requires claude on $PATH and a valid Claude Code session.

noop

Records invocations without executing. Used for testing and dry-run simulation.

Verification

After each agent invocation, maestro runs the project's own test suite. It auto-detects the build tool by scanning the project root:

File found	Command run
justfile / Justfile	just test
Makefile / GNUmakefile	make test
mix.exs	mix compile && mix test
Gemfile	bundle exec rake test
Cargo.toml	cargo test
pyproject.toml	python -m pytest
package.json	npm test
go.mod	go vet ./... && go test ./...

If the verification command fails, the step is retried (up to 3 attempts). Failure output is fed back to the agent as context.

Retry Behaviour

Each step is attempted up to 3 times. On each retry, accumulated feedback (agent errors, verification output, review rejections) is included in the agent prompt so the agent can correct its approach.

If all retries are exhausted, maestro exits non-zero and reports which step failed.

LLM Review (optional)

When a reviewer is configured, maestro runs a semantic review of the git diff after each successful verification. The reviewer uses a local Ollama instance by default:

• URL: http://localhost:11434 (Ollama)
• Model: llama3.2

If the review fails or errors, the step is retried with the reviewer's feedback. Maestro does not require a reviewer; it is disabled by default when running via the CLI.

Event Audit Trail

Maestro emits structured events for each stage of orchestration (step started, agent invoked, verification run, commit succeeded, etc.) to an axon-fact event store when one is configured. This provides a full audit trail of every run that can be replayed or queried.

Events include: StepStarted, AgentInvoked, AgentSucceeded, AgentFailed, VerificationPassed, VerificationFailed, ReviewPassed, ReviewFailed, CommitSucceeded, StepCompleted, StepFailed, and more.

Status Report

At the end of a run, maestro prints a summary to stderr (and to --summary-file if set):

  [+] [1] set up CLI argument parsing        completed  1 attempt    2.3s
  [+] [2] build plan file parser             completed  1 attempt    1.8s
  [!] [3] wire coding agent delegation      failed     2 attempts   5.1s

  Total:     3 steps
  Completed: 2 steps
  Failed:    1 step (step 3: wire coding agent delegation)

  Retries:   1 step needed retries (1 extra attempt)
  Time:      9.2s

Icons: + completed, ! failed, - skipped.

Development

just test   # go test ./...
just vet    # go vet ./...

Project Layout

cmd/maestro/        CLI entry point and flag parsing
internal/agent/     Coding agent interface (claude, noop)
internal/git/       Git operations (commit, diff, status)
internal/logger/    Leveled logger
internal/orchestrate/ Orchestration loop, retry logic, events
internal/plan/      Plan file parser
internal/report/    Status report formatting
internal/review/    LLM semantic review
internal/verify/    Build tool detection and execution
plans/              Commit-sized implementation plan for maestro itself