Maestro (josstei/maestro-orchestrate) — Summary

One-line description

Multi-agent development orchestration platform with 39 specialist agents, Express + Standard 4-phase workflows, persistent session state, and a single canonical source tree compiled to Gemini CLI, Claude Code, Codex, and Qwen Code runtimes.

Vital stats

What it is

Maestro is a cross-runtime orchestration platform that runs one canonical src/ codebase and generates runtime-specific adapters for four AI coding tools: Gemini CLI (primary), Claude Code, Codex, and Qwen Code. It provides 39 specialist agents (from accessibility_specialist to zos_sysprog), 12 user-facing commands, persistent session state, and an MCP server that serves agent methodology, skill content, and runtime context at delegation time.

Core value proposition

A single design → plan → execute → complete workflow usable without modification across all four major CLI coding agents, with session state persisted across CLI restarts, parallel or sequential subagent execution, and approval gates at design and code review phases.

Architecture in 3 bullets

• src-first, generated-runtime: one canonical src/ tree; generate.js builds runtime-specific outputs into ./ (Gemini), claude/, plugins/maestro/ (Codex), qwen/
• MCP server as intelligence backbone: 12 handler modules serve agent methodology, skills, session state, and workspace context; agents are thin stubs that delegate to MCP at runtime
• Two workflow paths: Express (1 question, 1 agent, sequential) for simple tasks; Standard 4-phase (Design/Plan/Execute/Complete) with hard-gated approval points for medium/complex tasks

Maestro (josstei/maestro-orchestrate) — Overview

Problem statement

Different AI coding tools (Gemini CLI, Claude Code, Codex, Qwen Code) require incompatible agent definition formats, hook systems, command surfaces, and delegation syntax. Building an orchestration layer means maintaining four separate codebases. Maestro solves this by authorizing once in src/ and generating all four runtime targets from a single manifest.

Target users

• Solo developers who switch between AI coding tools
• Teams standardizing on a multi-agent development workflow
• Projects that need persistent session state across CLI restarts

Design goals

1. Runtime portability: one workflow, four runtimes — no feature divergence between Claude and Gemini
2. Specialist depth: 39 pre-defined agents covering the full engineering function from UX to mainframe COBOL
3. Session persistence: design documents, implementation plans, phase outcomes survive CLI restart via docs/maestro/ state directory
4. Hard approval gates: no agent dispatched until design is explicitly approved; no session closed until code review passes Critical/Major finding check

Non-goals

• Maestro is not an AI coding tool itself — it orchestrates tools
• No hosted cloud service, no issue-tracker integration (unlike AO)
• No autonomous PR creation (human drives the CLI)

Install surface

Public command surface (Claude, 19 skills)

Core (3): /orchestrate, /execute, /resume-session

Entry-point (9): /review-code, /debug-workflow, /archive, /status, /security-audit, /perf-check, /seo-audit, /a11y-audit, /compliance-check

Infrastructure (7, user-invocable: false): code-review, delegation, design-dialogue, execution, implementation-planning, session-management, validation

Gemini / Qwen commands (12 TOML commands)

/maestro:orchestrate, /maestro:execute, /maestro:resume, /maestro:status, /maestro:archive, /maestro:review-code, /maestro:debug-workflow, /maestro:security-audit, /maestro:perf-check, /maestro:seo-audit, /maestro:a11y-audit, /maestro:compliance-check

Maestro (josstei/maestro-orchestrate) — Architecture

Principle: src-first, generated-runtime

src/              ← canonical source of truth
├── manifest.js   ← mapping: src files → (transforms, runtimes)
├── platforms/    ← Gemini | Claude | Codex | Qwen runtime configs
├── mcp/          ← MCP server (12 handler modules, 3 tool packs, 17 tools)
├── skills/       ← 7 shared skills (delegation, execution, validation, etc.)
├── templates/    ← design-document.md, implementation-plan.md
├── transforms/   ← 6 transform functions (parse-frontmatter, agent-stub, etc.)
├── hooks/        ← hook logic (session-start, before-agent, after-agent, session-end)
└── references/   ← architecture.md, orchestration-steps.md

generate.js       ← build boundary: runs transforms, emits to runtime dirs
  ↓
./               ← Gemini CLI (TOML commands, snake_case agents)
claude/          ← Claude Code plugin (kebab-case agents, 19 skills)
plugins/maestro/ ← Codex plugin (Markdown skills, spawn_agent)
qwen/            ← Qwen Code extension (Gemini-compatible format)

Runtime target comparison

MCP server (17 tools across 3 packs)

Content pack (3): get_agent, get_skill_content, get_runtime_context

Workspace pack (4): initialize_workspace, assess_task_complexity, resolve_settings, validate_plan

Session pack (10): create_session, get_session_status, update_session, transition_phase, archive_session, enter_design_gate, get_design_gate_status, record_design_approval, scan_phase_changes, reconcile_phase

Transform pipeline

Agent format (source)

---
name: coder
kind: local
description: "Implementation specialist..."
tools: [read_file, list_directory, glob, grep_search, write_file, replace,
        run_shell_command, write_todos, activate_skill, read_many_files, ask_user]
temperature: 0.2
max_turns: 25
timeout_mins: 10
---
Agent methodology loaded via MCP tool `get_agent`.

At runtime the body becomes a stub: Call get_agent(agents: ["coder"]).

Session state storage

Default: docs/maestro/ (configurable via MAESTRO_STATE_DIR)

docs/maestro/
├── plans/          ← design document + implementation plan
└── state/
    └── active-session.md   ← session state (phases, outcomes, downstream context)

Session ID format: YYYY-MM-DD-<kebab-task-slug>

Hook state is separate: ${MAESTRO_HOOKS_DIR:-<os.tmpdir()>/maestro-hooks-<uid>}/<session-id>/ — ephemeral, not accessible to the orchestrator.

Maestro (josstei/maestro-orchestrate) — Components

39 Specialist Agents

7 Shared Skills (src/skills/shared/)

MCP server module breakdown

12 handler implementations in src/mcp/handlers/:

• get-agent.js — agent methodology serving
• get-skill-content.js — skill/template/reference serving
• get-runtime-context.js — runtime config snapshot (tool names, delegation syntax, paths)
• initialize-workspace.js — directory setup (rejects paths inside extension caches)
• assess-task-complexity.js — repo analysis signals for Express/Standard routing
• validate-plan.js — dependency DAG check, phase count limits, file overlap, agent compatibility
• resolve-settings.js — env var + .env resolution for MAESTRO_* vars
• session-state-core.js — session-state transaction helpers
• session-state-tools.js — session CRUD (create/get/update/transition/archive)
• design-gate.js — design gate lifecycle (3 tools: enter/status/record-approval)
• reconciliation.js — phase reconciliation (scan_phase_changes, reconcile_phase)
• blocker-parser.js — child-agent blocker surfacing

Templates (src/templates/)

• design-document.md — approved design document structure
• implementation-plan.md — phase-based implementation plan with YAML frontmatter
• session-state.md — active session state template

Entry-point registry (src/entry-points/registry.js)

9 entry-points: review, debug, archive, status, security-audit, perf-check, seo-audit, a11y-audit, compliance-check

3 core commands (separate registry): orchestrate, execute, resume

Note: review → review-code, debug → debug-workflow, resume → resume-session in Claude (HOST_RESERVED_NAMES collision avoidance).

Generator (scripts/generate.js + src/generator/)

Modules: entry-point-expander.js, file-writer.js, generation-session.js, manifest-curator.js, manifest-expander.js, payload-builder.js, registry-scanner.js, stale-pruner.js

Run via npm run generate. CI checks for zero-diff (tests/integration/zero-diff.test.js).

NPM binaries

Maestro (josstei/maestro-orchestrate) — Uniqueness vs Seeds

Position in taxonomy

Maestro is a cross-runtime orchestration harness — the only system in the corpus that maintains a single canonical source tree compiled to four incompatible AI coding tool runtimes. It is not a specification document generator, not a memory layer, and not an autonomous background daemon.

Differentiators vs seed frameworks

vs claude-flow / ruflo

Claude-flow is a swarm coordinator with shared SQLite memory. Maestro has no swarm topology and no shared memory. Maestro's differentiator is cross-runtime portability and structured session state persistence. Claude-flow targets Claude Code only; Maestro targets Claude Code, Gemini CLI, Codex, and Qwen Code.

vs BMAD-METHOD

BMAD produces specification documents that a human then uses to implement. Maestro skips human implementation entirely — it delegates implementation to specialist agents with bounded tool access and turn limits. Both use design-document → plan → execute phases but BMAD's consumer is a human, Maestro's consumer is an agent.

vs taskmaster-ai

Taskmaster manages a linear task list in a single CLI session. Maestro manages multi-phase, multi-agent sessions with cross-phase context chaining, blocker handling, and mandatory code review gates.

vs openspec / kiro

OpenSpec and Kiro produce requirement specifications. Maestro consumes a design dialogue to produce a design document, then autonomously implements it. The tool roles are complementary but opposite in direction.

vs agent-os

agent-os is a personal memory system with protocol files. Maestro is a workflow harness with no persistent memory beyond session state. agent-os informs single-agent behavior; Maestro coordinates 39 agents.

vs claude-conductor

claude-conductor coordinates multiple Claude instances in parallel. Maestro uses a single orchestrator dispatching to specialist agents sequentially or in parallel — the topology is similar but Maestro is cross-model and the orchestrator is stateful.

Unique primitives

What Maestro is NOT

• Not a code review tool (it delegates to code_reviewer agent)
• Not an issue tracker integration (no Linear/GitHub/GitLab polling)
• Not a background daemon (human drives every /orchestrate invocation)
• Not a memory system (no vector store, no knowledge base)
• Not production-ready for autonomous PR creation (human remains in the loop)

Closest peer in corpus

agentflow-berabuddies is structurally closest: both define DAG-based multi-agent workflows with explicit phase dependencies. Maestro differentiates on: (1) cross-runtime portability, (2) server-side approval gates, (3) 39 pre-defined specialist agents, (4) session persistence. agentflow differentiates on: (1) Python DSL with >> operator, (2) native EC2/ECS/SSH execution targets, (3) no approval gates.