maestro

# Why it exists

A single generalist model reviewing a pull request tends to produce a long, flat list of remarks with no sense of priority. Human review doesn’t work that way. Security, architecture, product intent and UI are different lenses, and good teams bring the right lens to the right change.

maestro reviews pull requests with a crew of specialist agents instead of one generalist. It watches GitHub, builds an isolated environment for each PR, runs product, security, architecture and UI/UX reviewers in parallel, and merges what they find into one comment.

# How it works

The whole pipeline is a versioned playbook stored in the database: the graph of steps, the agents with their editable personas and per-agent model bindings, the routing rules and the environment spec. Adding a reviewer, or pointing one at a different model, is a configuration change, not a code change. The playbook is edited visually in Playbook Studio, a React Flow admin UI.

The product agent reads the linked Linear ticket so it can check the change against its acceptance criteria. A fair scheduler shares capacity across reviews, so a 40-file pull request cannot starve a 2-file one.

maestro can also review the way a particular developer reviews. A calibration battery of 100 real diffs, each with four defensible responses, builds a profile of that person’s judgement, and the triage step gates findings against it.

# Design decisions

• Agents cannot act. Reviewers get read-only tools, no network and no GitHub credential. Commands go through an exact-string allowlist, and only the orchestrator posts.
• Two sandbox postures. analyze runs with --network none, a read-only root and every capability dropped. prepare runs on a per-review internal network whose only exit is an allowlist proxy.
• Layered prompts. Fixed preamble, then the editable persona, then a fixed output contract, so editing a persona can never remove the prompt-injection defences.
• Its own agent loop. The Vercel AI SDK is used only for provider calls. The loop, the tools and the limits belong to maestro.
• Honest calibration. The battery is described as a synthetic instrument, not a validated psychometric one, with hard invariants on top of it.

# Status

All ten phases of the implementation plan have landed. The repository keeps a STATUS.md that separates what is built from what is verified end to end, because those are not the same thing.