Goals and phases

When a prepared task starts, Maestro creates a Goal run. The run is persisted in SQLite and each provider step records its phase, output summary, timing, result and artifacts.

Phases

1. Planning — understand the repository and write an implementation plan.
2. Implementing — make changes inside the task worktree.
3. Testing — run deterministic diff, typecheck, test, build and secret checks appropriate to the project layout.
4. Reviewing — inspect the result and request changes or deliver the evidence.

Task DNA can choose a smaller or larger phase budget. A phase budget is not a promise that a task will finish in a fixed number of provider calls; the circuit breaker looks for repeated failures and lack of measurable progress.

Checkpoints and handoff

The runtime records completed steps and a checkpoint with the current phase, worktree progress, failures, tests and remaining work. A provider change receives bounded handoff context rather than an unlimited transcript.

Completion

After validation and review, the delivery handler commits and pushes the task branch, then opens a draft PR. A Goal completing is not the same as a PR being merged. See Human review.

When a Goal stops

waiting_provider means the runtime cannot currently lease a suitable provider. blocked or failed records the reason and preserves the run. Environment and permission errors are surfaced as diagnostics; they are not treated as code changes that an agent should blindly retry.