Maestro-Flow

<div align="center">

# Maestro-Flow

### The Orchestration Layer for the Multi-Agent Era

**Don't just run agents. Orchestrate them.**

[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-≥18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Protocol-8B5CF6)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[English](README.md) | [简体中文](README.zh-CN.md)

</div>

---

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

```bash
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:

```bash
/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.

```bash
/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 Dashboa

... (truncated)