---

Maestro-Flow is a workflow orchestration framework for multi-agent development with Claude Code, Codex, Gemini, and other AI agents. Describe your intent, and Maestro-Flow routes to the optimal command chain, drives parallel agent execution, and closes the loop through adaptive decision-making, a real-time dashboard, and an evolving knowledge graph.

---

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

/maestro-ralph is the primary entry point — a closed-loop lifecycle engine that reads project state, infers your position, builds an adaptive command chain, and drives it to completion:

/maestro-ralph "implement OAuth2 authentication with refresh tokens"

Ralph automatically determines where you are in the lifecycle (brainstorm → roadmap → analyze → plan → execute → verify → review → test → milestone-complete) and builds the appropriate chain. Decision nodes at key checkpoints evaluate results and dynamically insert debug+fix 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 mode — 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: init, roadmap, analyze, plan, execute, verify

---

Key Features

1. Adaptive Lifecycle Engine (maestro-ralph)

Reads project state → infers lifecycle position → builds command chain with decision nodes. At each checkpoint, Ralph reads actual execution results and decides: continue, or insert a debug → fix → retry loop. The chain grows and shrinks dynamically based on outcomes.

brainstorm → init → roadmap → analyze → plan → execute → verify
                                              ◆ post-verify
                                              business-test
                                              ◆ post-business-test
                                              review
                                              ◆ post-review
                                              test
                                              ◆ post-test
                                              milestone-audit → milestone-complete
                                              ◆ post-milestone → next milestone

Three quality modes — control how thorough each phase is:

Mode	Stages	When
full	verify → business-test → review → test-gen → test	Production features, security-critical code
standard	verify → review → test	Default, balanced quality
quick	verify → CLI-review	Quick fixes, prototyping

Full pipeline explained — each stage serves a distinct quality gate:

1. verify — goal-backward verification: checks that all plan requirements are implemented, validates architectural constraints, anti-pattern scan, Nyquist test coverage
2. business-test — PRD-forward business testing: requirement traceability, fixture generation, multi-layer execution against acceptance criteria
3. review — multi-dimensional code review: correctness, readability, performance, security, testing, architecture
4. test-gen — coverage gap analysis and automatic test generation (TDD/E2E classification, L0-L3 progressive layers)
5. test — conversational UAT: interactive exploratory testing with session persistence and gap-plan closure

At each ◆ decision node, Ralph evaluates outcomes and decides: pass through, or insert a debug → fix → retry loop. Max retries configurable per decision point.

2. Structured Pipeline

49 slash commands across 6 categories power every stage — from project initialization to quality retrospective. All artifacts live in .workflow/scratch/, tracked by state.json.

3. Issue Closed-Loop

Issues aren't just tickets — they're a self-healing pipeline: discover → analyze → plan → execute → close. Quality commands automatically create issues for problems they find. Issue fixes flow back into the phase pipeline.

4. Visual Dashboard

Real-time dashboard at http://127.0.0.1:3001 with Kanban board, Gantt timeline, sortable table, and command center. Pick an agent on any issue card and dispatch. Built with React 19, Tailwind CSS 4, WebSocket live updates.

maestro serve                  # → http://127.0.0.1:3001
maestro view                   # Terminal TUI alternative

5. Multi-Agent Engine

Coordinates Claude Code, Codex, Gemini, Qwen, and OpenCode in parallel via wave-based execution. Independent tasks run concurrently; dependent tasks wait for predecessors.

6. Smart Knowledge Base

Wiki knowledge graph with BM25 search, backlink traversal, and health scoring. Learning toolkit (retro, follow, decompose, investigate, second-opinion) feeds into a unified lessons.jsonl store.

7. Hook & Overlay System

11 context-aware hooks inject project specs into agent prompts, monitor context usage, and track delegate execution. The overlay system enables non-invasive patches for .claude/commands/*.md that survive upgrades.

---

Commands & Agents

Category	Count	Prefix	Purpose
Core Workflow	18	maestro-*	Full lifecycle — ralph, init, roadmap, analyze, plan, execute, verify, milestones, overlays
Management	12	manage-*	Issue lifecycle, codebase docs, knowledge capture, memory, status
Quality	9	quality-*	Review, test, debug, test-gen, integration-test, business-test, refactor, sync
Learning	5	learn-*	Retro, follow-along, pattern decompose, investigate, second opinion
Specification	3	spec-*	Setup, add, load
Wiki	2	wiki-*	Connection discovery, knowledge digest

21 specialized agent definitions in .claude/agents/ — each a focused Markdown file that Claude Code loads on demand.

---

Architecture

maestro/
├── bin/                     # CLI entry points
├── src/                     # Core CLI (Commander.js + MCP SDK)
│   ├── commands/            # 11 CLI commands (serve, run, cli, ext, tool, ...)
│   ├── mcp/                 # MCP server (stdio transport)
│   └── 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/            # 49 slash commands (.md)
│   └── agents/              # 21 agent definitions (.md)
├── workflows/               # 45 workflow implementations (.md)
├── templates/               # JSON templates (task, plan, issue, ...)
└── extensions/              # Plugin system

Layer	Technology
CLI	Commander.js, TypeScript, ESM
MCP	@modelcontextprotocol/sdk (stdio)
Frontend	React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI
Backend	Hono, WebSocket, SSE
Agents	Claude Agent SDK, Codex CLI, Gemini CLI, OpenCode
Build	Vite 6, TypeScript 5.7, Vitest

---

Documentation

• Maestro Ralph Guide — Adaptive lifecycle engine: position inference, decision nodes, quality modes, retry escalation
• Command Usage Guide — All 51 commands with workflow diagrams, pipeline chaining, Issue closed-loop
• CLI Commands Reference — All 21 terminal commands: install, delegate, coordinate, wiki, hooks, overlay, collab
• Spec System Guide — Project specs with <spec-entry> format, keyword-based loading, validation hooks
• Delegate Async Guide — Async task delegation: CLI & MCP usage, message injection, chaining
• Overlay Guide — Non-invasive command extensions: format, section injection, bundle/import
• Hooks Guide — Hook system architecture, 11 hooks, spec injection, context budget
• Worktree Guide — Milestone-level parallel development: fork, sync, merge, dashboard integration
• Collab — User Guide — Multi-person collaboration for 2-8 person teams
• Collab — Design — Architecture, data model, namespace boundaries
• MCP Tools Reference — All 9 MCP endpoint tools

---

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.

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