Team

One command becomes a plan you approve, workers in their own git worktrees, and a review of each diff by a different vendor’s CLI. The run is done only when every gate is green.

You give Team a single instruction. A planning model decomposes it into worker tasks, each owning a disjoint set of files. You approve or edit that plan. Each approved task gets its own git worktree and its own pane, and each finished task’s diff is reviewed before anything merges. Team prefers a different model family and labels same-model fallback when the installed roster cannot provide one. Nothing is taken on a model’s word: “done” is a predicate over worker status, review verdicts and your own verification checks.

Before a run will start

Team refuses early and says why. Each of these is checked before the run row is created.

The states a run moves through

The status is stored, not held in memory. Every transition is an atomic claim, so the driver and a background actor can never advance the same run at once — and the status survives quitting the app.

The plan gate

A run parks at awaiting_plan and stays there. No worktree is created, no CLI is launched, nothing is written to your repo until you approve. This is the only human gate the driver will never skip — on restart, a run at the gate is adopted read-only and waits for you again.

At the gate you can change these, per task, before approving:

• Title — the task text the worker receives.
• Provider — which installed CLI runs it.
• Model — Auto, or a specific Claude model for Claude workers.
• Effort — Auto, Std, High or Ultra.
• Drop it — the task is skipped, and so is its injected reviewer.
• Worker autonomy for the whole run — Walk-away, Accept edits or Ask.

Approve is disabled if you drop every worker. The gate also shows two warnings when they apply: which tasks were reassigned because the brain picked a provider you have not installed, and which reviews fell back to the same model that wrote the code.

A plan the brain returns is validated before it reaches the gate. These rejections fail the run rather than silently degrading it:

• At least one task; keys unique and non-empty.
• depends_on may only name other keys in the same plan. Dependency cycles are rejected.
• Keys r1, r2 … are reserved for injected reviewers. A plan using one is rejected.
• A plan task of kind review is rejected — reviewers are injected by the app, never authored by the brain. A brain-written reviewer would collide with the real one and quietly disable cross-model review for that worker.

Routing hints are the exception: an unusable model or effort value degrades to the provider default instead of failing the plan.

Workers

Each approved task gets a branch maestro/<run-id>/<key>, a git worktree on that branch, and a pane. Your own checkout is never touched — merges happen inside a separate integration worktree.

Workers report progress on their own stdout using protocol lines — SIGMA::STATUS, SIGMA::BLOCKED, SIGMA::DONE. The launch prompt also tells each worker to stay inside its owned files, and not to drive a browser, run end-to-end tests, or leave a dev server running: verification belongs to the run’s gates, not to a worker.

Each worker starts as its own agent process. If startup is refused, its terminal and error remain available to inspect. A reviewer retry reserves a new launch, stops the previous worker, and starts a fresh process in the same worktree. It resumes the exact CLI conversation when a pinned session is available; otherwise it carries the saved task and reviewer findings into a new conversation.

The sentinel

A background watcher checks each active run’s current worker process, terminal output and validated message reports every two seconds. A quiet terminal stays live until its process exits. The watcher identifies activity, input requests and idle workers, then follows this escalation ladder.

The sentinel never kills a process and never marks a task failed. A completion report on the message bus must match the saved task attempt and its worker process. Old conversation history and echoed prompt examples do not count. Delayed judgments are discarded if the worker, output, run owner or pause state changes. Queuing a nudge means it entered the terminal; it does not prove the agent read it.

Review the exact worker changes

Team adds one reviewer task per worker when review is enabled. It chooses among installed CLIs with a supported non-interactive review mode: Claude, Codex and agy. Worker selection is separate. If no supported reviewer is available, preparing the plan fails with a setup message.

Same-family fallback is shown as degraded in the plan and report. It still needs an approval; a second invocation of the same family is not presented as an independent model review.

How a review actually runs

1. Team checkpoints the completed worker, records its exact commit and file tree, and captures its diff against the integration history.
2. The reviewer runs with its supported review arguments and a 600-second limit. Binary changes or a diff exceeding the 60,000-byte review limit stop automatic approval; split the task or inspect and merge the work manually.
3. After the reviewer returns, Team checks that the worker files and branch still match the snapshot. The verdict and evidence are saved together.
4. Integration checks that evidence again and merges the recorded commit. Additional worker edits cannot silently enter an approved merge.

The verdict must contain a line that is exactly APPROVED or CHANGES_REQUESTED. A timeout, failed process exit or missing verdict never counts as approval. An empty diff records that there were no changes on the exact worker commit; the other completion gates still apply.

Changes requested by the reviewer enter the existing replan cycle. Team can return findings to a worker, prepare a revised plan or stop with a partial report. Repeated review failures remain visible for your attention.

What “done” requires

The decision is a single pure predicate, not a judgement call. Every gate must be green in the same round.

If a gate is red and rounds remain, the run loops: replan or redispatch, build again, re-review, re-verify. Hitting the round cap or the deadline fails the run — but a round that turns everything green at the cap still counts as done.

Configure browser verification before starting

In Tasks → Team or the Team setup form, open Browser verification. Choose when to test, enter the HTTP or HTTPS URL, and describe what the browser must prove. These settings are saved with the run and remain visible beside its plan and progress.

For a local app, optionally enter a start command such as npm run dev -- --port 3000 and a matching URL such as http://localhost:3000. The command runs in Team’s integration worktree during verification. Leave it blank for an existing site. Start commands require a local URL; credentials embedded in a URL are rejected.

Use a concrete goal: “Create an item, reload, and confirm it is still saved.” Invalid settings prevent launch. If saving fails, the form keeps your draft for retry. The saved target cannot change after the approved plan starts.

New runs use required reviews. The legacy API value if_diverse also requires approvals in the Team driver; it does not bypass the gate when diversity is unavailable. The review policy cannot change after the approved plan starts.

Open, resume and stop the exact saved Team

Open a saved Team from Tasks to inspect its run, worker rows, events, checks and report. Loading the history does not start a driver or replace the controls of another active Team. The workspace and run identity must still match when the read finishes.

Resume claims native ownership for that saved run before continuing. A plan awaiting approval still needs Approve. Interrupted intake or planning can resume with saved answers. Verification may need to run again; a historic pass is not proof of the current files. Reporting recovery requires the recorded verdict and preserves it when saving the report is retried.

Pause holds wave advancement; existing worker processes keep running. Stop first records cancellation, then cleans up the run’s owned processes. If cleanup is unconfirmed, the run remains stop_pending and exposes Retry Stop. Worktrees and reports stay available. A reused terminal ID or an old timestamp alone does not authorize killing another process.

What you are left with

• An integration branch, maestro/<run-id>/integration, holding the merged result. Nothing is merged into your working branch — the report gives you the git merge --no-ff line to run yourself.
• A report written to .deckspace/maestro/<run-id>/report.md in your repo, and shown in the room. It is rendered deterministically from the run’s facts; a model may narrate it, but never invents it.
• Worker transcripts under .deckspace/maestro/<run-id>/transcripts/.
• Every worktree, including after the kill switch. The kill switch stops all worker terminals and cancels the run, and deliberately preserves the worktrees for a post-mortem.

A note on the brain

The planning, intake, judging, replanning and reporting calls all go through one model, chosen per run. The Team room’s Brain dropdown defaults to Gemini; starting a run by voice or from the Orchestrator’s plan card defaults to the headless Claude Code CLI instead. An API brain needs its key in Settings, or the run fails with “brain ‘…’ has no API key configured”.

One brain call is capped at 300 seconds. If a call comes back with a rate, quota or usage-limit error, Team fails over to whichever of Gemini, OpenAI, Anthropic and Groq you have keys for. Intake is the only call allowed to fail quietly: a flaky brain there means the run plans without your answers rather than stopping.

The reviewer one-shot is confined by the same OS sandbox as the rest of the app, when one is available.