reinamaccredy-maestro

maestro

Maestro is a local-first coordination system for human and agent work. It keeps durable work, decisions, sessions, evidence, dispatches, and handbacks in each repository's shared Git root. It is written in TypeScript, runs on Bun, and does not require a background service.

Documentation: maestro.maccredyreina.me

Version 0.108.0 is the first TypeScript release. It continues the version line after 0.107.x, the final Rust release.

Three layers

• Mechanism kernel owns the SQLite store, event log, sessions, CLI dispatch, plugin loading, and readiness projection. It does not impose workflow policy.
• Plugins provide verbs and optional policy gates. Repositories enable or disable policies such as proof and breakdown in .maestro/config.
• Recipes and skills provide prompt-first working methods as Markdown. Use maestro recipe list to browse recipes and maestro recipe show <name> to read one without copying it into a repository.

Install, update, and remove

Maestro is distributed from source. Install with one command (needs git and Bun):

curl -fsSL https://raw.githubusercontent.com/ReinaMacCredy/maestro/main/scripts/install.sh | sh

The script clones the repository into ~/.maestro/source (override with MAESTRO_SOURCE_DIR; MAESTRO_REF picks the branch, default main) and runs the installer from that checkout, which maestro update then follows. From your own checkout, run the installer directly:

bun bin/maestro.ts install
maestro version

Install copies the runtime to ~/.maestro/runtime, writes the shim at ~/.local/bin/maestro, records the source checkout in ~/.maestro/source.json, and wires the current repository. When replacing an older executable, it preserves that executable as maestro-legacy if no rollback executable already exists.

Install also scaffolds ~/maestro, the Supervisor room, and registers the current repository there, and writes the shared method to ~/maestro/WORKFLOW.md. It materializes ten managed skills under ~/maestro/skills: maestro-bundle, maestro-design, maestro-work, maestro-verify, maestro-improve, maestro-council, and the read-only maestro-explore, maestro-diagnose, maestro-coach, and maestro-questionnaire. The installer links those skills for Claude without overwriting unmanaged skills.

Use maestro update to fetch the recorded source checkout, accept only a fast-forward, and resync the runtime. It refuses dirty, diverged, missing, or unreachable sources without partially updating the runtime. Use maestro install from the source checkout for an offline resync.

Use maestro uninstall to remove Maestro-managed hooks, settings keys, and mirror blocks from the current repository. It is idempotent and does not delete repository data, the machine runtime, the shim, or the Supervisor room.

maestro doctor inspects the shim, runtime stamp, recorded source, repository wiring, permissions, and store access without repairing them. A healthy report exits zero; a reported problem names the next command when the repair is mechanical.

SLP supervised teams

SLP v2 uses one direct Herdr workspace per running team generation:

flowchart TB
  Hub["Hub Supervisor"] <--> Team["Team Supervisor"]
  Team <--> Lead
  Team <--> PeerA["Peer A"]
  Team <--> PeerB["Peer B"]
  Lead <--> PeerA
  Lead <--> PeerB
  PeerA <--> PeerB

In the supported SLP flow, the Hub Supervisor reaches the team only through its Team Supervisor. Inside the team, the Team Supervisor, Lead, and Peers communicate directly. Every seat launches as a native harness profile (claude --agent maestro-<seat> or codex --profile maestro-<seat>) rendered by maestro install from a maestro-owned profile file, so its mandate is its system prompt and survives /clear. Attention is the seat's own work note --blocked, pushed one seat up; there is no Observer, Advisor, scheduler, or background agent role.

SLP is a cooperative-agent protocol, not a shell security sandbox. Maestro checks the nine SLP operations at their supported boundaries: Hub operations must run from the Hub room, while project role operations require the current generation's stored Herdr pane binding. It does not block native commands, administrative Maestro commands, or direct Herdr calls; topology and external-effect limits remain obligations enforced by the Human and host policy.

The canonical Workspace Pack lives at ~/maestro/SLP.md. Starting a team copies its exact bytes to <project>/.maestro/SLP.md, pins its version and digest for that generation, creates exactly one Team Supervisor and one Lead, and creates initial OPEN work for the Lead. Peers are opened lazily by assigned work. Install seeds the Hub pack only when it is absent; later installs and updates preserve owner edits.

SLP roles use exactly nine operations:

maestro team start
maestro team stop
maestro status [work-id]
maestro work add
maestro work take
maestro work note
maestro work return
maestro work accept
maestro decide

Work moves only through OPEN -> ACTIVE -> RETURNED -> DONE. Lead accepts Peer returns; Team Supervisor accepts Lead returns. Settled choices use one immutable maestro decide record and explicit replacement.

team start opens one runtime pane per generation through Maestro's Herdr plugin (maestro install links it). The runtime pane is not an agent: it holds the generation's Herdr event subscription, renders the team's pane output, and records a blocked pane or an idle pane that still holds ACTIVE work as a stall:dialog or stall:silence entry by the actor runtime, nudging the stuck seat once per item and kind until the store changes. A seat that needs a fact from above records work note --blocked; Maestro pushes the BLOCKED line one seat up without changing the work state.

Normal stop uses one transient foreground non-agent helper pane in the Hub so the Team Supervisor can close itself safely. This is internal, not another SLP operation: STOPPED is recorded only after the team workspace is absent, and a partial close remains RUNNING for retry.

Read the compact operating guide with maestro recipe show slp and the full setup at SLP setup and storage.

Work, decisions, and evidence

• maestro status shows session identity, held work, and live peers; maestro ready shows work that can start and the gates blocking other work.
• maestro work manages work trees, dependencies, leases, notes, cancellation, claims, and proof.
• Method rules live in WORKFLOW.md, installed to ~/maestro/WORKFLOW.md. Inspect the task before choosing quickfix, Light, or Full by risk and coordination needs. Session changes use checkpoints, not automatic bundles. Verification is required; new tests need a concrete gap in existing checks. Completion and delivery are separate.
• maestro decision records draft, locked, and superseded choices with their rationale and work links. Supersession takes effect when the replacement is locked, not while it is still a draft.
• Cross-role decisions are drafted in the store before a Herdr prompt names the sender role and decision id. The answer is the locked or superseding record; non-decision questions and answers are work notes.
• maestro dispatch stores lane contracts and council state; maestro handback stores shape-checked return packets, including explicit dependency, council, challenge, reopen, unknown, and failure outcomes.
• maestro search searches native work, decisions, notes, terms, memory facts, events, bundles, and imported Rust records, in this store and in the Hub room at ~/maestro; --local stays in this store.
• maestro term keeps the glossary in the store so a term answers the same search as the work and decisions that use it.
• maestro memory runs in the Hub room: ingest promotes facts from the Claude auto-memory and Codex ad-hoc buffers through supersession, dedup and evidence gates, retract retires one for good, and render writes the injected global index from the store and refuses to overwrite a hand edit.

Proof is layered as source, artifact, installed, live, and journey. Claims stop at the last proven layer and name untested links rather than rounding them up to completion. Repeated failures route by holder: Peer-held work reaches the Lead through the repository brief; Lead-held work reaches the Supervisor through the room brief.

Failed commands emit a JSON error envelope on stderr and exit nonzero. Empty or whitespace-only required arguments are rejected rather than interpreted as missing identities or targets.

Verb tour

• maestro status shows sessions and leases; maestro ready shows startable and gated work.
• maestro work add|start|note|done|show|list manages the work lifecycle.
• maestro decision draft|lock|show|list manages durable choices.
• maestro dispatch open|accept|show|list stores lane contracts, while maestro handback file|show stores and reads return packets.
• maestro attention scans the current repository and maestro brief summarizes every registered repository.
• maestro term add|list|show keeps the glossary; maestro memory ingest|list|show|retract|render runs the Hub memory.
• maestro bundle open|close|pause|resume|list|show|save|import runs design bundles; import brings a .waymark/ tree in with an item-by-item report and a dry run.
• maestro recipe list|show serves methods; maestro plugin list|enable|disable manages the configured extension set.
• maestro graph run|next|result|show|list|trust drives a pre-known multi-agent path from one graph markdown file; maestro executes the deterministic nodes and hands the agent nodes back to whichever harness is driving.
• maestro import rust imports preserved Rust data; maestro legacy show reads imported cards and files.
• maestro install, maestro update, maestro uninstall, and maestro doctor manage and diagnose the source-installed runtime.
• maestro version reports the package version and installed commit.

Attention and brief

maestro attention computes current attention packets at read time. It detects stalled leases, repeated failures, stale decisions, scope collisions, unreturned dispatches, and returned handbacks that have not been reviewed. It records no mailbox message and runs no daemon.

maestro brief reads the registry in ~/maestro/registry, opens each project in observer mode, and reports only what needs attention. Missing repositories are named and skipped. When every registered project is running normally, the brief says so in one line. The hm shell function focuses the Supervisor room and prints this brief; it does not start an agent.

Observer mode

This is the read-only store mode for administrative inspection. It is not an SLP seat and does not create a background process.

Set MAESTRO_READ_ONLY=1 to run Maestro as an observer. Pure commands such as status, search, recipes, and read-only list/show operations remain available. Mutating commands fail with READ_ONLY; external plugins are not loaded; and session, lease, and liveness state is not persisted. Search fails closed if its index cannot be refreshed rather than returning stale results as current.

Harness integration

maestro install writes managed adapters for Claude and Codex and merges only the managed hook entries. SessionStart and UserPromptSubmit record the session and print its current brief. Small managed blocks in CLAUDE.md and AGENTS.md point agents to status, ready work, and recipes. No hook sends mail, pushes a dispatch into another session, or delivers PostToolUse packets.

Recipes, skills, and plugins