{"id":47814919,"url":"https://github.com/catlog22/maestro-flow","last_synced_at":"2026-05-15T03:12:16.686Z","repository":{"id":345257824,"uuid":"1184249417","full_name":"catlog22/maestro-flow","owner":"catlog22","description":"Workflow orchestration CLI with MCP endpoint support and multi-agent dashboard","archived":false,"fork":false,"pushed_at":"2026-05-08T14:36:53.000Z","size":10668,"stargazers_count":274,"open_issues_count":0,"forks_count":38,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-05-08T14:37:43.221Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://catlog22.github.io/maestro-flow/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catlog22.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-17T12:02:57.000Z","updated_at":"2026-05-08T14:37:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/catlog22/maestro-flow","commit_stats":null,"previous_names":["catlog22/maestro-flow"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/catlog22/maestro-flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catlog22%2Fmaestro-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catlog22%2Fmaestro-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catlog22%2Fmaestro-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catlog22%2Fmaestro-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catlog22","download_url":"https://codeload.github.com/catlog22/maestro-flow/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catlog22%2Fmaestro-flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33051913,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T18:25:04.415Z","updated_at":"2026-05-15T03:12:16.676Z","avatar_url":"https://github.com/catlog22.png","language":"TypeScript","funding_links":[],"categories":["Cross-Agent References"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Maestro-Flow\n\n### The Orchestration Layer for the Multi-Agent Era\n\n**Don't just run agents. Orchestrate them.**\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-≥18-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n[![MCP](https://img.shields.io/badge/MCP-Protocol-8B5CF6)](https://modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n[English](README.md) | [简体中文](README.zh-CN.md)\n\n\u003c/div\u003e\n\n---\n\nMaestro-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.\n\n---\n\n## Install\n\n```bash\nnpm install -g maestro-flow\nmaestro install\n```\n\n**Prerequisites**: Node.js \u003e= 18, Claude Code CLI. Optional: Codex CLI, Gemini CLI for multi-agent workflows.\n\n---\n\n## Quick Start\n\n**`/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:\n\n```bash\n/maestro-ralph \"implement OAuth2 authentication with refresh tokens\"\n```\n\nRalph 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.\n\n```bash\n/maestro-ralph status              # View session progress\n/maestro-ralph continue            # Resume after decision pause\n/maestro-ralph -y \"build a REST API\"  # Full auto mode — no pauses\n```\n\n### Other Entry Points\n\n| Command | When to Use |\n|---------|-------------|\n| `/maestro \"...\"` | Describe intent, let AI route to the optimal command chain |\n| `/maestro-quick` | Quick fixes, small features (analyze → plan → execute) |\n| `/maestro-*` | Step-by-step: init, roadmap, analyze, plan, execute, verify |\n\n---\n\n## Key Features\n\n### 1. Adaptive Lifecycle Engine (`maestro-ralph`)\n\nReads 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.\n\n```\nbrainstorm → init → roadmap → analyze → plan → execute → verify\n                                              ◆ post-verify\n                                              business-test\n                                              ◆ post-business-test\n                                              review\n                                              ◆ post-review\n                                              test\n                                              ◆ post-test\n                                              milestone-audit → milestone-complete\n                                              ◆ post-milestone → next milestone\n```\n\n**Three quality modes** — control how thorough each phase is:\n\n| Mode | Stages | When |\n|------|--------|------|\n| `full` | verify → business-test → review → test-gen → test | Production features, security-critical code |\n| `standard` | verify → review → test | Default, balanced quality |\n| `quick` | verify → CLI-review | Quick fixes, prototyping |\n\n**Full pipeline explained** — each stage serves a distinct quality gate:\n\n1. **verify** — goal-backward verification: checks that all plan requirements are implemented, validates architectural constraints, anti-pattern scan, Nyquist test coverage\n2. **business-test** — PRD-forward business testing: requirement traceability, fixture generation, multi-layer execution against acceptance criteria\n3. **review** — multi-dimensional code review: correctness, readability, performance, security, testing, architecture\n4. **test-gen** — coverage gap analysis and automatic test generation (TDD/E2E classification, L0-L3 progressive layers)\n5. **test** — conversational UAT: interactive exploratory testing with session persistence and gap-plan closure\n\nAt each `◆` decision node, Ralph evaluates outcomes and decides: pass through, or insert a debug → fix → retry loop. Max retries configurable per decision point.\n\n### 2. Structured Pipeline\n\n49 slash commands across 6 categories power every stage — from project initialization to quality retrospective. All artifacts live in `.workflow/scratch/`, tracked by `state.json`.\n\n### 3. Issue Closed-Loop\n\nIssues 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.\n\n### 4. Visual Dashboard\n\nReal-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.\n\n```bash\nmaestro serve                  # → http://127.0.0.1:3001\nmaestro view                   # Terminal TUI alternative\nmaestro command-help           # Open interactive command reference in browser (alias: ch)\n```\n\n### 5. Multi-Agent Engine\n\nCoordinates Claude Code, Codex, Gemini, Qwen, and OpenCode in parallel via wave-based execution. Independent tasks run concurrently; dependent tasks wait for predecessors.\n\n### 6. Smart Knowledge Base\n\nWiki 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.\n\n### 7. Hook \u0026 Overlay System\n\n11 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.\n\n---\n\n## Commands \u0026 Agents\n\n| Category | Count | Prefix | Purpose |\n|----------|-------|--------|---------|\n| **Core Workflow** | 18 | `maestro-*` | Full lifecycle — ralph, init, roadmap, analyze, plan, execute, verify, milestones, overlays |\n| **Management** | 12 | `manage-*` | Issue lifecycle, codebase docs, knowledge capture, memory, status |\n| **Quality** | 9 | `quality-*` | Review, test, debug, test-gen, integration-test, business-test, refactor, sync |\n| **Learning** | 5 | `learn-*` | Retro, follow-along, pattern decompose, investigate, second opinion |\n| **Specification** | 3 | `spec-*` | Setup, add, load |\n| **Wiki** | 2 | `wiki-*` | Connection discovery, knowledge digest |\n\n21 specialized agent definitions in `.claude/agents/` — each a focused Markdown file that Claude Code loads on demand.\n\n---\n\n## Architecture\n\n```\nmaestro/\n├── bin/                     # CLI entry points\n├── src/                     # Core CLI (Commander.js + MCP SDK)\n│   ├── commands/            # 11 CLI commands (serve, run, cli, ext, tool, ...)\n│   ├── mcp/                 # MCP server (stdio transport)\n│   └── core/                # Tool registry, extension loader\n├── dashboard/               # Real-time web dashboard\n│   └── src/\n│       ├── client/          # React 19 + Zustand + Tailwind CSS 4\n│       ├── server/          # Hono API + WebSocket + SSE\n│       └── shared/          # Shared types\n├── .claude/\n│   ├── commands/            # 49 slash commands (.md)\n│   └── agents/              # 21 agent definitions (.md)\n├── workflows/               # 45 workflow implementations (.md)\n├── templates/               # JSON templates (task, plan, issue, ...)\n└── extensions/              # Plugin system\n```\n\n| Layer | Technology |\n|-------|-----------|\n| CLI | Commander.js, TypeScript, ESM |\n| MCP | @modelcontextprotocol/sdk (stdio) |\n| Frontend | React 19, Zustand, Tailwind CSS 4, Framer Motion, Radix UI |\n| Backend | Hono, WebSocket, SSE |\n| Agents | Claude Agent SDK, Codex CLI, Gemini CLI, OpenCode |\n| Build | Vite 6, TypeScript 5.7, Vitest |\n\n---\n\n## Documentation\n\n- **[Maestro Ralph Guide](guide/maestro-ralph-guide.md)** — Adaptive lifecycle engine: position inference, decision nodes, quality modes, retry escalation\n- **[Command Usage Guide](guide/command-usage-guide.md)** — All 53 commands with workflow diagrams, pipeline chaining, Issue closed-loop\n- **[Command Reference (HTML)](guide/command-usage-guide.html)** — Interactive HTML version with search, card grid, and workflow examples (`maestro command-help` to open)\n- **[CLI Commands Reference](guide/cli-commands-guide.en.md)** — All 21 terminal commands: install, delegate, coordinate, wiki, hooks, overlay, collab\n- **[Spec System Guide](guide/spec-system-guide.md)** — Project specs with `\u003cspec-entry\u003e` format, keyword-based loading, validation hooks\n- **[Delegate Async Guide](guide/delegate-async-guide.md)** — Async task delegation: CLI \u0026 MCP usage, message injection, chaining\n- **[Overlay Guide](guide/overlay-guide.md)** — Non-invasive command extensions: format, section injection, bundle/import\n- **[Hooks Guide](guide/hooks-guide.md)** — Hook system architecture, 11 hooks, spec injection, context budget\n- **[Worktree Guide](guide/worktree-guide.md)** — Milestone-level parallel development: fork, sync, merge, dashboard integration\n- **[Collab — User Guide](guide/team-lite-guide.md)** — Multi-person collaboration for 2-8 person teams\n- **[Collab — Design](guide/team-lite-design.md)** — Architecture, data model, namespace boundaries\n- **[MCP Tools Reference](guide/mcp-tools-guide.en.md)** — All 9 MCP endpoint tools\n\n---\n\n## Acknowledgments\n\n- **[GET SHIT DONE](https://github.com/gsd-build/get-shit-done)** by TACHES — The spec-driven development model and context engineering philosophy.\n- **[Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)** — The predecessor that pioneered multi-CLI orchestration and skill-based workflow routing.\n- **[Impeccable](https://github.com/pbakaus/impeccable)** by [@pbakaus](https://github.com/pbakaus) — The UI design skill integrated as `maestro-impeccable`. Live variant mode, critique storage, design parser, and CSP detection modules are derived from this project. Licensed under [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).\n\n## Contributors\n\n\u003ca href=\"https://github.com/catlog22\"\u003e\n  \u003cimg src=\"https://github.com/catlog22.png\" width=\"60px\" alt=\"catlog22\" style=\"border-radius:50%\"/\u003e\n\u003c/a\u003e\n\n**[@catlog22](https://github.com/catlog22)** — Creator \u0026 Maintainer\n\n## Community\n\nJoin the WeChat group for discussion and feedback:\n\n\u003cimg src=\"assets/wechat-group-qr.png\" width=\"200\" alt=\"WeChat Group: Claude Code Workflow交流群 2\" /\u003e\n\n## Buy Me a Coffee\n\nIf this project helps you, consider buying me a coffee:\n\n\u003cimg src=\"assets/wechat-reward-qr.png\" width=\"200\" alt=\"WeChat Reward QR\" /\u003e\n\n## Links\n\n- [Linux DO：学AI，上L站！](https://linux.do/)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatlog22%2Fmaestro-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatlog22%2Fmaestro-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatlog22%2Fmaestro-flow/lists"}