maestro

maestro

Agent-optimized development orchestrator -- an MCP plugin that gives AI coding agents structured memory, workflow guardrails, and a plan-first pipeline.

Features are discovered, researched, planned, approved, then executed by agents with all state persisted under .maestro/.

Quick Start

maestro init                                    # initialize project
maestro feature-create my-feature               # create feature
maestro plan-write --feature my-feature \
  --content "## Discovery\n..."                 # write plan
maestro plan-approve --feature my-feature       # approve plan
maestro task-sync --feature my-feature          # generate tasks from plan
maestro task-next --feature my-feature          # find next runnable task
maestro task-claim --feature my-feature \
  --task 01-example                             # claim task for an agent
maestro task-done --feature my-feature \
  --task 01-example --summary "What changed"    # mark task complete

Prerequisites

• bun (runtime and package manager)
• git (repo state and audit capture)

Optional integrations

The following tools from Dicklesworthstone power optional adapters. maestro degrades gracefully when any are absent.

Tool	Adapter	Purpose
br (beads_rust)	sync backend	Task tracking and bead persistence
bv (beads viewer)	bv-graph	Dependency graph insights, next-task recommendations, execution plans
cass (Coding Agent Session Search)	cass-search	Full-text search across coding agent sessions (Claude Code, Codex, Cursor, Gemini)
agent-mail (MCP Agent Mail)	agent-mail-handoff	Cross-agent handoff notifications via HTTP API

Building

bun install
bun run build

Produces ./dist/cli.js (CLI) and ./dist/server.bundle.mjs (MCP server). Development mode: bun src/cli.ts <command>.

Architecture

maestro is a pure MCP plugin -- Claude Code is the orchestrator (spawning agents natively), maestro is the filing cabinet with opinions.

commands/  -->  usecases/  -->  ports/  <--  adapters/
(CLI I/O)       (rules)        (interfaces)  (implementations)

server/    -->  usecases/  -->  ports/  <--  adapters/
(MCP tools)     (rules)        (interfaces)  (implementations)

src/
  adapters/     # Filesystem, br, graph, search, verification
  commands/     # CLI commands organized by domain
  hooks/        # Claude Code hooks (session-start, pre-agent, pre-compact)
  lib/          # Output, errors, signals, truncation
  plugins/      # Plugin registry and loader (built-in: br, git, rg, tilth)
  ports/        # Interfaces (tasks, plans, features, memory, doctrine, search, graph, handoff)
  server/       # MCP tool registration (one file per domain)
  skills/       # Skill loader and registry generator
  templates/    # Plan scaffolding
  usecases/     # Business rules
  utils/        # Paths, git, plan parser, spec builder
skills/         # Bundled SKILL.md workflow guides
hooks/          # Installable Claude Code hooks

Pipeline

discovery --> research --> planning --> approval --> execution --> done

Stages are skippable. Hooks inject pipeline context automatically.

Task Model

6 states: pending --> claimed --> done | blocked | review --> revision

Stale claims expire after a configurable timeout (default 120 min) and auto-reset to pending on task-next.

MCP Tools (39)

All tools are prefixed maestro_ in MCP (e.g., maestro_task_claim).

Group	Tools	Count
Feature	feature_create, feature_list, feature_complete	3
Plan	plan_write, plan_read, plan_approve, plan_comment	4
Task	tasks_sync, task_next, task_claim, task_done, task_accept, task_reject, task_block, task_unblock, task_list	9
Memory	memory_write, memory_read, memory_list, memory_promote	4
Doctrine	doctrine_list, doctrine_read, doctrine_write, doctrine_deprecate, doctrine_approve	5
Meta	status, skill, ping, init, dcp_preview, execution_insights	6
Graph	graph_insights, graph_next, graph_plan	3
Handoff	handoff_send, handoff_receive, handoff_ack	3
Search	search_sessions, search_related	2

CLI Commands (58)

All commands accept --json for machine-readable output. Use maestro <command> --help for full usage.