Maestro-Flow
June 24, 2026 · View on GitHub
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, agy (Antigravity) 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 |
Knowledge Management
# Search across wiki + code (BM25F ranking)
maestro search "user authentication"
# Load specific knowledge types
maestro load --type spec --category coding
maestro load --type knowhow --list
# Explore codebase via API endpoints
maestro explore "Find all database query patterns"
# Manage domain terminology
maestro domain add "API Gateway" "Unified entry point for all API requests"
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-investigate (deep dive).
Domain Knowledge
A semantic glossary layer that defines what things mean in your project. Domain terms (maestro domain) standardize terminology, map concept relationships, and serve as a MaestroGraph knowledge source — bridging the gap between code-level symbols and business-level concepts.
Wiki & Search
WikiIndexer walks the .workflow/ directory, parses frontmatter, builds backlink graphs, and creates a BM25 inverted index for full-text search across all project knowledge — specs, knowhow, issues, and KG nodes as virtual entries.
Issue Closed-Loop
Issues aren't just tickets. They're a self-healing pipeline:
discover → analyze → plan → execute → close
▲ │
└────── quality commands auto-create ─┘
Quality commands (review, test, verify) automatically create issues for problems they find. Issue fixes flow back into the phase pipeline.
Visual Dashboard
Real-time dashboard at http://127.0.0.1:3001 — Kanban board, Gantt timeline, sortable table, and command center. Pick an agent on any issue card and dispatch.
maestro serve # Launch web dashboard
maestro view # Terminal TUI alternative
maestro command-help # Interactive command reference (alias: ch)
Built with React 19, Zustand, Tailwind CSS 4, Framer Motion, Hono, WebSocket.
At a Glance
| Metric | Count |
|---|---|
| Source files (TypeScript) | 333 |
| Lines of code | ~80,700 |
| Slash commands | 64 |
| Workflow definitions | 115 |
| Skill packages | 45 |
| Agent definitions | 23 |
| CLI commands | 35+ |
| Templates | 92 |
| Guides (bilingual) | 76 |
Tech Stack
| Layer | Technology |
|---|---|
| CLI | Commander.js, TypeScript, ESM |
| MCP | @modelcontextprotocol/sdk (stdio) |
| Knowledge Graph | better-sqlite3, Drizzle ORM, web-tree-sitter |
| Frontend | React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI |
| Backend | Hono, WebSocket, SSE |
| Agents | Claude Agent SDK, Codex CLI, agy (Antigravity) CLI, OpenCode |
| Build | Vite 6, TypeScript 5.7, Vitest |
Architecture
maestro/
├── bin/ # CLI entry points
├── src/ # Core CLI (Commander.js + MCP SDK)
│ ├── commands/ # 35+ CLI commands
│ ├── mcp/ # MCP server (stdio transport)
│ ├── graph/ # Knowledge Graph (SQLite + tree-sitter)
│ └── core/ # Tool registry, extension loader
├── dashboard/ # Real-time web dashboard
│ └── src/
│ ├── client/ # React 19 + Zustand + Tailwind CSS 4
│ ├── server/ # Hono API + WebSocket + SSE
│ └── shared/ # Shared types
├── .claude/
│ ├── commands/ # 64 slash commands (.md)
│ ├── agents/ # 23 agent definitions (.md)
│ └── skills/ # 45 skill packages
├── workflows/ # 115 workflow definitions (.md)
├── templates/ # 92 JSON templates
└── extensions/ # Plugin system
Documentation
Getting Started
- Quick Start Guide — Install, first workflow, key concepts
- Install Guide — Step-by-step installation, component selection, workspace setup
- Maestro Ralph Guide — Adaptive lifecycle engine, decision nodes, quality modes
Workflow
- Command Usage Guide — All 64 commands with workflow diagrams and pipeline chaining
- CLI Commands Reference — All 35+ terminal commands
- Workflow Structure Guide — Command topology, chain composition
- Quality Pipeline Guide — Verify, review, test pipeline
- Maestro Coordinator Guide — Multi-agent coordination patterns
Knowledge
- Knowledge Management Guide — KG, specs, knowhow, wiki
- Search System Guide — Unified BM25F search, MaestroGraph integration, type filtering
- MaestroGraph Plan — Unified KG engine design, CodeGraph replacement, tree-sitter integration
- Domain Knowledge Plan — Semantic glossary, term relationships, concept layer
- Spec System Guide — Spec entries, keyword loading, validation hooks
- Hooks Guide — 17 hooks, spec injection, context budget
- Learning Tools Guide — Retro, follow, decompose, investigate
Advanced
- Delegate Async Guide — Multi-CLI delegation, message injection, chaining
- Overlay Guide — Non-invasive command extensions
- Worktree Guide — Milestone-level parallel development
- Workspace Guide — Cross-workspace knowledge sharing, link/unlink
- MCP Tools Reference — All 9 MCP endpoint tools
- Collab Guide — 2-8 person team collaboration
Acknowledgments
- GET SHIT DONE by TACHES — The spec-driven development model and context engineering philosophy.
- Claude-Code-Workflow — The predecessor that pioneered multi-CLI orchestration and skill-based workflow routing.
- Impeccable by @pbakaus — UI design skill integrated as
maestro-impeccable. Licensed under Apache License 2.0.
Contributors
@catlog22 — Creator & Maintainer
Community
Join the WeChat group for discussion and feedback:
Buy Me a Coffee
If this project helps you, consider buying me a coffee:
Links
License
MIT