Maestro
Multi-agent development orchestration platform — 22 specialists, 4-phase orchestration, native parallel subagents, persistent sessions, and standalone review/debug/security/perf/seo/a11y/compliance commands. Runs on both Gemini CLI and Claude Code.
Table of Contents
- Overview
- Features
- Getting Started
- Commands
- Configuration
- Architecture
- Agents
- Skills
- Parallel Execution
- Session State & Project Output
- Documentation
- Troubleshooting
- License
Overview
Maestro is a multi-agent orchestration platform for Gemini CLI and Claude Code. Instead of a single AI session handling everything, Maestro delegates work to 22 specialized subagents -- each with its own context, tools, and expertise -- coordinated by a TechLead orchestrator. For simple tasks, Maestro uses an Express workflow that collapses design and planning into a single brief before executing. For medium and complex tasks, Maestro follows a structured 4-phase Standard workflow: Design, Plan, Execute, Complete.
The same orchestration engine, agents, and quality gates run on both platforms. Gemini CLI uses the extension at the repo root; Claude Code uses the plugin in the claude/ subdirectory.
Maestro classifies every task by complexity before choosing a workflow. Simple tasks (single concern, few files) get the Express path. Medium tasks (multi-component, clear boundaries) and complex tasks (cross-cutting, multi-service) enter the Standard path with full design dialogue, implementation planning, and phased execution across 22 agents spanning 8 editorial domains.
Features
- Express Workflow -- Simple tasks skip ceremony: 1-2 clarifying questions, a structured brief, single-agent delegation, code review, and archival. No design document or implementation plan is created.
- Guided Design Dialogue -- Standard workflow includes structured requirements gathering with multiple-choice questions, depth-selectable reasoning (Quick, Standard, Deep), and architectural approach proposals with trade-offs.
- Native Parallel Execution -- Independent phases run concurrently through the active runtime's native subagent scheduler, batching phases at the same dependency depth with non-overlapping file ownership.
- Session Persistence -- All orchestration state is tracked in YAML+Markdown files with machine-readable frontmatter and human-readable logs, enabling reliable resumption after interruptions.
- Hooks-Based Lifecycle Middleware -- Lifecycle hooks for active-agent tracking, session context injection, and handoff validation.
- Least-Privilege Security -- Each subagent receives only the tools required for its role through a 4-tier access model enforced via agent frontmatter declarations.
- Standalone Commands -- Direct access to code review, debugging, security audit, performance analysis, SEO audit, accessibility audit, and compliance check without full orchestration.
- 8-Domain Coverage -- Agents span Engineering, Product, Design, Content, SEO, Compliance, Internationalization, and Analytics domains, selected proportionally to task complexity.
- MCP-First State Management -- Session state operations use MCP tools for structured I/O and atomic transitions, with filesystem fallback when MCP is unavailable.
- Codebase Investigation -- Built-in codebase investigator grounds designs and plans in the actual repository structure, conventions, and integration points before proposing approaches.
Getting Started
Prerequisites
Gemini CLI requires the experimental subagent system. Claude Code users can skip to Installation — subagents are available by default.