The thirteen phases of a mission
You give MAESTRO a task and a repository. What happens next is a fixed sequence, with one place where it stops and waits for you.
Most coding agents are a loop: read the task, edit files, run something, report. MAESTRO is a pipeline. Each phase has one job, writes down what it did, and hands over. The point of the structure is not ceremony — it is that a phase which cannot do its job has somewhere to say so, instead of passing an unchecked result to the next step as though it were checked.
Before anything is written
- preflight The repository is synced to the latest commit on its branch and a baseline snapshot is taken, so that the diff at the end is the mission's own work and nothing else. The working tree is also scanned for secrets before any of its content is sent anywhere.
- context_prewarm The structural index for the repository is brought up to date so the research phase has something to query.
- pm_agent The specification is written here, and it is written by argument rather than by a single model. A proposer drafts an approach; two independent challengers attack it; a synthesis step resolves what survived. On the deeper mission modes the research behind that debate includes a live web search, so it is grounded in current library documentation rather than in whatever the model remembered; the fastest mode skips the search to stay fast, and the record says which happened.
- spec_validation The draft specification is checked against the repository it claims to describe: do the files it names exist, do the symbols it plans to call exist, would the change it describes actually ship to a user. A specification that fails here does not reach an executor.
- reasoning_audit A separate pass asks whether the plan's reasoning holds up — whether each claim it rests on was verified or merely asserted.
- user_approval The mission stops. You read the specification and approve it, ask for a revision, or reject it. Nothing in your repository has changed yet.
The approval gate sits after the plan and before the edit because that is the last moment at which disagreeing with the agent is cheap. Once an executor has run, reviewing its work means reading a diff; before it runs, it means reading a paragraph.
Writing the code
- execute One executor implements the approved specification inside an isolated Firecracker microVM with a copy of your project mounted into it. Your project's own test suite runs here, inside the same VM, as part of this phase rather than after it.
- safety The diff is checked for destructive operations and for secrets that the change itself would introduce. Findings are reported per file and line; a blocking finding stops the mission and asks you what to do.
- review The change is reviewed against the specification that was approved — not against a general notion of good code. Findings above a severity threshold force a rejection regardless of the reviewer's own verdict, so a reviewer that says "approve" while listing a critical problem does not get the last word.
- commit_or_retry A deterministic gate decides whether to commit. It compares the test result against the baseline taken in preflight: a change that introduces a new test failure is not committed, and the mission retries or stops.
Afterwards
- publish The commit is pushed and a pull request is opened on GitHub or a merge request on GitLab. If the remote has no commits yet there is no base branch to open a pull request against, so the commit is pushed to the default branch instead and the record says that is what happened.
- browser_verify Where the change has a visible surface, it is exercised in a headless browser.
- archive Everything the mission did is written to the record: the specification, the debate, the diff, the test output, the review findings, the cost, and whether verification happened. This is the phase that produces the verification record.
What runs the code, and what argues about it
A mission uses exactly one executor, chosen per mission: Codex
(gpt-5.4, the default) or Claude
(claude-opus-4-6). The planning phases are deliberately not
the same model as each other — a proposer, two challengers and a
synthesis step drawn from different model families — because a debate in
which every participant shares the same blind spot is not a debate.
The research those phases do is not generic retrieval. Every function, class, method and import relationship in the repository is parsed with Tree-sitter into a structural graph, which can be asked who calls this, what depends on it, and what breaks if it changes. Alongside it runs a full-text BM25 search over every symbol, and the two result sets are fused. There is no embedding model and no vector search anywhere in the system: retrieval is lexical and structural, which makes it fast, deterministic and explainable. The structural graph currently parses Python, TypeScript, JavaScript, Java and Go; other languages are searched lexically and run in the sandbox, but are not graphed.
Outcomes are kept per project. What was attempted, what failed and what was learned on earlier missions is retrieved into the debate on later ones, so the system's knowledge of your repository accumulates rather than resetting each time.
The part most agents skip
A pipeline is only worth the phases that can say no. Three of them can:
spec_validation refuses a plan that does not match the
repository, safety refuses a diff that does something
destructive, and commit_or_retry refuses a change that
broke a test that used to pass. And when the test suite could not be run
at all — no runner in the sandbox, a suite that collected nothing, output
the parser could not read — the mission does not quietly report success.
It completes with the status completed_unverified, and the
record carries the reason.
That is the whole argument for the structure. What the record contains and how the sandbox is isolated are each worth their own page.