Content
<div align="center">
# Tool List
### Intent-Driven Multi-Agent Workflow Orchestration Framework
**Tell it what to do, and Maestro automatically plans, schedules, executes, and verifies.**
<br/>
[](https://www.npmjs.com/package/maestro-flow)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[English](README.en.md)
</div>
<br/>
> Most AI programming tools can only let one agent do one thing.
> Maestro-Flow enables **multiple agents to collaborate on end-to-end workflows** — an adaptive decision engine dynamically adjusts strategies based on actual results, and a knowledge graph automatically accumulates experience from each execution.
<br/>
## Core Capabilities
**Adaptive Orchestration** — Ralph v2 engine reads project state, categorizes natural language intent into 40+ command chains, and dynamically decides at key nodes: continue, rollback, or insert repair loops. No YAML, no pipeline configuration.
**Cross-Backend Scheduling** — Mix and match Claude, Codex, Gemini, Qwen, and OpenCode in the same workflow, with four orchestration modes: Delegate (asynchronous delegation), Team (role collaboration), Wave (dependency parallelism), and Swarm (ant colony exploration).
**Knowledge Self-Enhancement** — Agents discover patterns, pitfalls, and decisions during execution, which are automatically persisted as Spec and Knowhow. The Hook system injects relevant knowledge into subsequent agent prompts — projects get smarter with use.
**Long-Cycle Self-Correction** — Odyssey series commands run for hours-long autonomous loops, with each checkpoint adaptively adjusting strategies until acceptance criteria are met.
## Installation
```bash
npm install -g maestro-flow
maestro install # Interactive component selection and installation
```
Requires Node.js ≥ 18 and [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code). Multi-agent workflows optionally install Codex CLI, agy CLI.
## Quick Start
### Ralph v2 — Adaptive Lifecycle Engine
Main entry point. Tell Ralph your goal, and it automatically judges the development stage, constructs a command chain, and dynamically adjusts at decision nodes:
```bash
/maestro-ralph-v2 "Implement OAuth2 authentication with refresh token"
/# Ralph automatically builds the chain: analyze → plan → execute → verify → review → test
#/遇到失败 → 自动插入 debug → fix → retry 循环
#/遇到新项目 → 自动前置 brainstorm → blueprint
```
```bash
/maestro-ralph-v2 status # View current session progress
/maestro-ralph-v2 continue # Resume from decision pause point
/maestro-ralph-v2 -y "..." # Fully automated, no confirmation required
```
### Core Pipeline
```
Intent Input → Ralph Classification (40+ chain types)
│
▼
brainstorm → blueprint(opt) → analyze → plan → execute → verify
◆ decision
review ── ◆ ── test ── ◆ ── milestone
◆ → Next Milestone
```
Three quality modes control pipeline depth:
| Mode | Pipeline | Applicable Scenarios |
|------|------|--------------------|
| `full` | verify → business-test → review → test-gen → test | Production environment, safety-critical |
| `standard` | verify → review → test | Default balance |
| `quick` | verify → CLI-review | Prototype, hotfix |
### Other Entrances
```bash
/maestro "Add user profile page" # Intent routing, automatic chain selection
/maestro-quick "Fix redirect bug" # Shortest path: plan → execute → verify
```
### Odyssey — Long-Cycle Autonomous Loops
Suitable for large-scale debugging, deep refactoring, UI optimization, and other scenarios requiring continuous iteration:
| Command | Loop Mode |
|------|---------|
| `/odyssey-debug` | Archaeological analysis → diagnosis → repair → confirmation → generalization → knowledge sedimentation |
| `/odyssey-planex` | Demand analysis → planning → execution → strict verification → repair loop |
| `/odyssey-improve` | Multi-dimensional audit → in-depth diagnosis → targeted repair → verification → generalization |
| `/odyssey-review-test-fix` | Multi-dimensional review → targeted repair → testing → generalization → knowledge sedimentation |
| `/odyssey-ui` | Visual inspection → multi-dimensional audit → divergent exploration → repair → verification |
Each Odyssey command runs continuously until acceptance criteria are met, adaptively adjusting strategies and automatically persisting discovered knowledge.
## Documentation
### Getting Started
| | Guide | Description |
|---|------|------|
| **01** | [Quick Start Guide](guide/quick-start-guide.md) | Installation, first workflow, core concepts |
| **02** | [Installation Guide](guide/install-guide.md) | Component selection, workspace configuration |
| **03** | [Ralph Engine](guide/maestro-ralph-guide.md) | Adaptive decision-making, quality modes, session management |
| **04** | [Command Usage Guide](guide/command-usage-guide.md) | 64 command usage, flowchart, pipeline connections |
### Daily Usage
| Guide | Description |
|------|------|
| [CLI Command Reference](guide/cli-commands-guide.md) | 35+ terminal command quick reference |
| [Knowledge Management](guide/knowledge-management-guide.md) | Knowledge graph, Spec, Knowhow, Wiki panorama |
| [Spec System](guide/spec-system-guide.md) | Project rule writing, loading, and automatic injection |
| [Quality Pipeline](guide/quality-pipeline-guide.md) | verify → review → test three-level pipeline |
| [Hook Mechanism](guide/hooks-guide.md) | 17 Hook trigger timing and context budget control |
<details>
<summary><b>Advanced & Design Documents</b> (click to expand)</summary>
<br/>
| Guide | Description |
|------|------|
| [Workflow Structure](guide/workflow-structure-guide.md) | Four-layer command topology, six standard paths |
| [Multi-Agent Coordination](guide/maestro-coordinator-guide.md) | Delegate / Team / Wave / Swarm detailed explanation |
| [Delegate Asynchronous Execution](guide/delegate-async-guide.md) | Cross-CLI delegation, message injection, chained calls |
| [Overlay Extension](guide/overlay-guide.md) | Adding behavior to commands without modifying source code |
| [Worktree Parallel Development](guide/worktree-guide.md) | Milestone-level branch isolation |
| [Cross-Project Sharing](guide/workspace-guide.md) | Multi-project link/unlink knowledge base |
| [MCP Tools](guide/mcp-tools-guide.md) | 9 MCP endpoint tool references |
| [Team Collaboration](guide/team-lite-guide.md) | 2–8 person Collab mode |
| [Search System](guide/search-system-guide.md) | BM25F full-text search and KG integration |
| [Learning Tools](guide/learn-tools-guide.md) | Retrospective, reading, disassembly, and exploration four-piece set |
| [MaestroGraph Design](guide/plan-maestrograph.md) | Unified knowledge graph engine architecture |
| [Domain Knowledge Design](guide/plan-domain-knowledge.md) | Semantic vocabulary table and conceptual relationship network |
</details>
## Project Scale
333 TypeScript source files / ~80k lines of code / 64 slash commands / 45 skill packages / 23 Agent definitions / 35+ CLI commands / 92 templates
**Tech Stack** Commander.js · MCP SDK · better-sqlite3 · web-tree-sitter · React 19 · Zustand · Tailwind CSS 4 · Hono · Vite 6
<details>
<summary><b>Directory Structure</b></summary>
```
maestro/
├── src/ # Core CLI (Commander.js + MCP SDK)
│ ├── commands/ # 35+ CLI commands
│ ├── mcp/ # MCP server (stdio)
│ ├── graph/ # Knowledge graph (SQLite + tree-sitter)
│ └── core/ # Tool registration, extension loading
├── dashboard/ # Web dashboard (React 19)
├── .claude/
│ ├── commands/ # 64 slash commands
│ ├── agents/ # 23 Agent definitions
│ └── skills/ # 45 skill packages
├── workflows/ # 115 workflow definitions
└── templates/ # 92 JSON templates
```
</details>
<details>
<summary><b>Comparison with Similar Tools</b></summary>
<br/>
| | [Superpowers](https://github.com/obra/superpowers) | [OpenSpec](https://github.com/Fission-AI/OpenSpec) | [Trellis](https://github.com/mindfold-ai/trellis) | **Maestro-Flow** |
|---|---|---|---|---|
| **Positioning** | Agent skill framework | Specification-driven development | Multi-platform agent tooling | Intent-driven orchestration |
| **Architecture** | Pure `.md`, no runtime | CLI + Git | CLI + `.trellis/` | CLI + MCP + SQLite |
| **Routing** | Manual skill selection | Manual command sequence | Fixed stages | AI classification 40+ chains |
| **Multi-Agent** | Sub-agent scheduling | Single agent | Channel mode | 4 modes × 5 backends |
| **Knowledge** | Only Git | Git archive | File logging | SQLite KG + automatic injection |
| **Long-Term Work** | Context window | Manual continue | Log recovery | Stateful Odyssey loop |
| **Self-Correction** | Review-fix loop | Manual re-verification | Manual | Decision node automatic retry |
**Each has its strengths**: Superpowers' prompt engineering methodology is the most mature; OpenSpec's requirement specification is the most rigorous; Trellis' multi-platform unification is the best; Maestro-Flow focuses on end-to-end lifecycle orchestration, cross-backend scheduling, and knowledge self-enhancement.
</details>
## Acknowledgments
- **[GET SHIT DONE](https://github.com/gsd-build/get-shit-done)** — Spec-driven development and context engineering concepts
- **[Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)** — Precursor project, pioneering multi-CLI orchestration
- **[Impeccable](https://github.com/pbakaus/impeccable)** — UI design skills (Apache-2.0)
---
<div align="center">
**[@catlog22](https://github.com/catlog22)** — Creator & Maintainer
Join the WeChat group for discussion:
<img src="assets/wechat-group-qr.png" width="180" alt="WeChat Group" />
<br/><br/>
[Linux DO: Learn AI, Go to L Station!](https://linux.do/)
<br/>
MIT License
</div>
