Maestro-Flow
Intent-Driven Workflow Orchestration for the Multi-Agent Era
Describe what you want. Maestro figures out how to get there.
Most AI coding tools let you run one agent on one task. Maestro-Flow orchestrates multiple agents across an entire development lifecycle — from brainstorming to deployment — with an adaptive decision engine, a self-reinforcing knowledge graph, and a real-time visual dashboard.
Two Pillars
Maestro-Flow is built on two interconnected systems that reinforce each other:
┌─────────────────────────────────────┐
│ Maestro-Flow │
│ │
┌──────────────┴──────────────┐ ┌──────────────────┴───────────────┐
│ Workflow Orchestration │ │ Knowledge System │
│ │ │ │
│ Intent Router │ │ MaestroGraph (SQLite) │
│ └─ 40+ chain types │ │ └─ Code + Knowledge unified │
│ Ralph Decision Engine │ │ Spec Injection (Hooks) │
│ └─ 11-state FSM │ │ └─ Auto-inject into prompts │
│ Quality Pipeline │ │ Wiki + BM25 Search │
│ └─ verify → review → test│ │ └─ Backlinks + health score │
│ Multi-Agent Dispatch │ │ Learning Loop │
│ └─ Claude, Gemini, Codex │ │ └─ retro → persist → inject │
│ │ │ │
└─────────────┬───────────────┘ └──────────────────┬───────────────┘
│ ▲ │ ▲
│ │ knowledge │ │
│ │ injection │ │
│ └──────────────┘ │
│ execution results │
└──────────────────────────────────────┘
Workflows generate knowledge. Knowledge improves future workflows. Agents learn from each session, persist discoveries as specs and knowhow, and future agents automatically receive that context through hook injection — creating a self-reinforcing cycle.
Install
npm install -g maestro-flow
maestro install
Prerequisites: Node.js ≥ 18, Claude Code CLI. Optional: Codex CLI, Gemini CLI for multi-agent workflows.
maestro install provides an interactive component selector — choose which assets (commands, hooks, MCP, agents) to install. Use maestro workspace link to share knowledge (specs, knowhow, domain) across multiple projects.
Quick Start
The Ralph Engine
/maestro-ralph is the primary entry point — a closed-loop lifecycle engine that reads project state, infers your position in the development lifecycle, and builds an adaptive command chain:
/maestro-ralph "implement OAuth2 authentication with refresh tokens"
Ralph automatically determines where you are (brainstorm → plan → execute → verify → review → test → milestone) and builds the appropriate chain. Decision nodes at key checkpoints evaluate results and dynamically insert debug → fix → retry loops when needed.
/maestro-ralph status # View session progress
/maestro-ralph continue # Resume after decision pause
/maestro-ralph -y "build a REST API" # Full auto — no pauses
Other Entry Points
| Command | When to Use |
|---|---|
/maestro "..." |
Describe intent, let AI route to the optimal command chain |
/maestro-quick |
Quick fixes, small features (analyze → plan → execute) |
/maestro-* |
Step-by-step: brainstorm, blueprint, analyze, plan, execute, verify |
Odyssey — Long-Running Iterative Cycles
Odyssey commands run extended, self-correcting loops that combine archaeology, diagnosis, fix, verification, and knowledge persistence until acceptance criteria are met:
| Command | Focus |
|---|---|
odyssey-debug |
Debug cycle — archaeology, diagnosis, fix, confirmation, generalization |
odyssey-planex |
Requirement-driven cycle — plan, execute, strict verify, fix loop |
odyssey-improve |
Codebase improvement — multi-dimensional audit, targeted fix, verify |
odyssey-review-test-fix |
Deep review + fix — multi-dimensional review, targeted fix, generalization |
odyssey-ui |
UI optimization — visual survey, audit, divergent exploration, fix |
Workflow Orchestration
Adaptive Lifecycle Engine
Ralph is an 11-state finite state machine that decides but never executes. It reads project state, infers lifecycle position, builds a command chain with quality gates, and hands off execution to maestro-ralph-execute. At each decision node (◆), Ralph evaluates actual results and decides: proceed, or insert a debug → fix → retry loop.
brainstorm → blueprint(opt) → init → analyze(macro) → roadmap(opt) → analyze(micro) → plan → execute → verify
◆ decision
review ─── ◆ ─── test ─── ◆ ─── milestone-audit → milestone-complete
◆ → next milestone
Three quality modes control thoroughness:
| Mode | Pipeline | Use Case |
|---|---|---|
full |
verify → business-test → review → test-gen → test | Production, security-critical |
standard |
verify → review → test | Default, balanced |
quick |
verify → CLI-review | Prototyping, quick fixes |
Intent-Driven Routing
You don't write pipeline YAML. You describe intent in natural language, and Maestro classifies it into one of 40+ chain types, each a pre-composed sequence of commands. The same intent produces different chains depending on project state:
/maestro "add user profile page"
# → New project: brainstorm → blueprint → analyze → plan → execute → verify
# → Existing project: analyze → plan → execute → verify
# → Quick fix: plan → execute → verify
Layered Command Topology
Commands are organized in four layers:
| Layer | Purpose | Commands |
|---|---|---|
| Origin | Diverge ideas, converge direction | brainstorm, blueprint |
| Understanding | Explore scope (macro) + deep-dive (micro) | analyze (dual-mode) |
| Orchestration | Structure into milestones and phases | roadmap |
| Execution | Plan, implement, verify | plan, execute, verify, review, test |
Six canonical paths (A–F) cover everything from full greenfield projects to single-line fixes.
Multi-Agent Dispatch
Maestro coordinates Claude Code, Codex, Gemini, Qwen, and OpenCode through four composable orchestration patterns:
| Pattern | How It Works |
|---|---|
| Delegate | Dispatch to any CLI tool via maestro delegate with SQLite-backed job broker, async execution, and message injection for follow-up chaining |
| Team | Coordinator-worker architecture — coordinators generate role-specs, spawn team-worker agents in parallel, supervised by a resident quality observer |
| Wave | Topological sort of tasks into dependency waves; independent tasks run concurrently within each wave |
| Swarm | ACO-driven multi-agent exploration for complex problem spaces with pheromone-guided convergence |
These patterns compose: a team coordinator can delegate subtasks to different LLM backends, wave execution parallelizes independent work, and the dashboard provides a real-time supervisory control loop — all sharing the broker and message bus as coordination primitives.
Knowledge System
Knowledge Graph (MaestroGraph)
MaestroGraph is the unified code index engine that replaces the former CodeGraph dependency. Built on web-tree-sitter for AST-level extraction, it stores both code structure (functions, classes, call chains) and project knowledge (specs, knowhow, domain terms, issues) in a single SQLite-backed graph with dual FTS5 indexes.
maestro kg search <symbol> # Find nodes
maestro kg context <node> # Get surrounding context
maestro kg callers <function> # Trace call chains
maestro kg callees <function> # Trace dependencies
Spec Injection
Project rules (coding standards, architecture constraints, quality criteria) are stored as <spec-entry> blocks with keyword tags. Hooks automatically inject relevant specs into every agent prompt based on keyword matching — agents receive project-specific rules without explicit loading.
Self-Reinforcing Learning Loop
Agent executes task
→ Discovers pattern/pitfall/decision
→ Persists as spec entry or knowhow doc
→ Hook system indexes new knowledge
→ Future agents auto-receive via prompt injection
→ Better execution → more discoveries → ...
Four learning tools feed this cycle: learn-retro (retrospective), learn-follow (pattern study), learn-decompose (architecture breakdown), `learn-