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              │  │  Knowledge Graph (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.

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

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:

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:

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:

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

A SQLite-backed unified graph that stores both code structure (functions, classes, call chains via tree-sitter extraction) and project knowledge (specs, knowhow, domain terms, issues) in one queryable structure.

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).

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

Tech Stack

Architecture

maestro/
├── bin/                     # CLI entry points
├── src/                     # Core CLI (Commander.js + MCP SDK)
│   ├── commands/            # 32 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
• 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 32 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
• 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
• 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

• Linux DO：学AI，上L站！

License

MIT