First workflow guide · v0.56.0
Inspect, approve, and check one small change
Start in the Conductor conversation. Read the evidence, agree on a narrow scope, and review the diff before changing your project.
Before you start
Follow the Quick Start to install Maestro, open a local project, and configure the Claude inspection route and required billing confirmation. Use a project you know and a small result you can verify.
The app stores its records in your project's .maestro/ directory. Model requests send selected project content to your configured provider; the desktop and its records are local.
A useful first task is to clarify one existing paragraph in your project's README. Keep the scope to that file and preserve its documented commands. Replace the example path below if your project uses a different file.
1. Understand before editing
Ask the Conductor:
Read README.md and explain the current installation steps. Cite what you read.
Watch the read/search activity and open a source citation in the companion view. Check that the answer agrees with the file. An incomplete search or an unsupported model claim is not proof that a file or behavior is absent.
You can use Steer while an inspection runs to refine the question, or Stop to interrupt it.
2. Describe the result and its limits
Edit only README.md to clarify the existing installation paragraph. Preserve every documented command.
The Conductor proposes an edit scope with allowed actions and limits. Read it carefully. Narrow it or reject it if it includes unrelated files. Approving this scope allows proposal drafting; it changes no source files.
3. Review the proposed diff
Read the diff in the companion, including removed lines. Does it meet the request? Did the commands remain intact? Use Revise proposal or Reject proposal if it needs correction.
When satisfied, choose Apply changes and complete the confirmation. This second approval authorizes Maestro to write the patch. A message saying “yes” is not a substitute for either approval.
Review the apply result and verification evidence. Partial or inconclusive results need investigation. To undo an applied change, use Roll back applied changes; Maestro checks for intervening file changes before restoring content.
4. Validate the result
For the README example, read the final paragraph and confirm the commands still match the project. For a code change, open More → Checks and select an available validation capability. Inspect its program, arguments, and any one-run risk request before starting.
Follow the output, open the logs, and read the terminal result. A stopped, blocked, or indeterminate run is not a pass. Current built-in checks focus on Cargo/Rust; use your normal development tools for checks Maestro does not yet expose.
Checks record execution and manage process lifetime, but do not fully contain filesystem or network effects. macOS process tracking can only report that no orphan was observed, not guarantee that none remains.
When you need a reviewed implementation plan
For larger work, the existing creator/reviewer workflow remains available. Describe the feature in the conversation, inspect its workflow proposal, and use the offered controls to create it. Roles configures the installed, authenticated tools used for planning, review, and implementation.
Read the plan
Check scope, target files, non-goals, implementation order, and validation. Ask the Conductor about assumptions you do not understand.
Review and address findings
Use the available review action. If findings need work, use Address with your notes, then review again. Keep unresolved decisions explicit.
Check approval before implementing
Review the plan's approval state and any carried findings before starting implementation. Maestro checks that state; a model's claim that it is ready does not replace the gate.
Follow implementation and final review
Maestro runs implementation section by section with review and retry or blocked outcomes. Inspect the final review and complete the applicable Checks and manual validation before closing the workflow.
This planned workflow and the small-edit flow above have different approval and execution paths. Completing a small edit does not mean it received independent plan or implementation review.
What to look for in the record
- The request and scope you intended.
- The approvals you gave and the proposed changes you reviewed.
- The actual apply, rollback, or implementation outcome.
- The evidence behind claims about files and validation.
- Any unresolved findings, limitations, or manual checks.
Use companions to inspect the relevant code, diff, plan, findings, or logs. Records are also saved with the project. Model explanations help interpret them; they do not replace observed results.
If something goes wrong
Read the specific status and recovery action before retrying. If files changed outside the session, use the offered fresh-inspection or proposal review path. If a tool is unavailable, check its account and installation status. Settings → Diagnostics provides local diagnostic records and source-free support packets.
Provider usage is separate from Maestro. Check the displayed route and usage information, and use your provider dashboard when usage is unknown.
Try it with a project you know
Start with a read-only question, then make one narrow, reviewable change.