by catlog22
Intent-driven workflow orchestration for multi-agent AI development — adaptive lifecycle engine, self-reinforcing knowledge graph, and visual dashboard for Claude Code, Gemini, Codex & more
# Add to your Claude Code skills
git clone https://github.com/catlog22/maestro-flowLast scanned: 6/22/2026
{
"issues": [
{
"type": "npm-audit",
"message": "@hono/node-server: @hono/node-server: Middleware bypass via repeated slashes in serveStatic",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "express-rate-limit: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "fast-uri: fast-uri vulnerable to path traversal via percent-encoded dot segments",
"severity": "high"
},
{
"type": "npm-audit",
"message": "hono: Hono missing validation of cookie name on write path in setCookie()",
"severity": "high"
},
{
"type": "npm-audit",
"message": "ip-address: ip-address has XSS in Address6 HTML-emitting methods",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "path-to-regexp: path-to-regexp vulnerable to Denial of Service via sequential optional groups",
"severity": "high"
},
{
"type": "npm-audit",
"message": "postcss: PostCSS has XSS via Unescaped </style> in its CSS Stringify Output",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "qs: qs has a remotely triggerable DoS: qs.stringify crashes with TypeError on null/undefined entries in comma-format arrays when encodeValuesOnly is set",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "vite: launch-editor: NTLMv2 hash disclosure via UNC path handling on Windows",
"severity": "high"
},
{
"type": "npm-audit",
"message": "ws: ws: Uninitialized memory disclosure",
"severity": "high"
}
],
"status": "WARNING",
"scannedAt": "2026-06-22T09:48:40.890Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}maestro-flow is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by catlog22. Intent-driven workflow orchestration for multi-agent AI development — adaptive lifecycle engine, self-reinforcing knowledge graph, and visual dashboard for Claude Code, Gemini, Codex & more. It has 391 GitHub stars.
maestro-flow returned warnings in SkillsLLM's automated security scan. It has no critical vulnerabilities, but review the flagged issues in the Security Report section before adding it to your workflow.
Clone the repository with "git clone https://github.com/catlog22/maestro-flow" and add it to your Claude Code skills directory (see the Installation section above).
maestro-flow is primarily written in TypeScript. It is open-source under catlog22 on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh maestro-flow against similar tools.
No comments yet. Be the first to share your thoughts!
Requires a passing catalog security scan. Resolve the flagged issues and resubmit to enable featuring.
Describe what you want. Maestro figures out how to get there.
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.
Maestro-Flow is built on two interconnected systems that reinforce each other:
┌─────────────────────────────────────┐
│ Maestro-Flow │
│ │
┌──────────────┴──────────────┐ ┌──────────────────┴───────────────┐
│ Workflow Orchestration │ │ Knowledge System │
│ │ │ │
│ Intent Router │ │ MaestroGraph (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.
npm install -g maestro-flow
maestro install
Prerequisites: Node.js ≥ 18, Claude Code CLI. Optional: Codex CLI, Gemini CLI for multi-agent workflows.
maestro install provides an interactive component selector — choose which assets (commands, hooks, MCP, agents) to install. Use maestro workspace link to share knowledge (specs, knowhow, domain) across multiple projects.
/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
| 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: brainstorm, blueprint, analyze, plan, execute, verify |
Odyssey commands run extended, self-correcting loops that combine archaeology, diagnosis, fix, verification, and knowledge persistence until acceptance criteria are met:
| Command | Focus |
|---|---|
odyssey-debug |
Debug cycle — archaeology, diagnosis, fix, confirmation, generalization |
odyssey-planex |
Requirement-driven cycle — plan, execute, strict verify, fix loop |
odyssey-improve |
Codebase improvement — multi-dimensional audit, targeted fix, verify |
odyssey-review-test-fix |
Deep review + fix — multi-dimensional review, targeted fix, generalization |
odyssey-ui |
UI optimization — visual survey, audit, divergent exploration, fix |
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:
| Mode | Pipeline | Use Case |
|---|---|---|
full |
verify → business-test → review → test-gen → test | Production, security-critical |
standard |
verify → review → test | Default, balanced |
quick |
verify → CLI-review | Prototyping, quick fixes |
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
Commands are organized in four layers:
| Layer | Purpose | Commands |
|---|---|---|
| Origin | Diverge ideas, converge direction | brainstorm, blueprint |
| Understanding | Explore scope (macro) + deep-dive (micro) | analyze (dual-mode) |
| Orchestration | Structure into milestones and phases | roadmap |
| Execution | Plan, implement, verify | plan, execute, verify, review, test |
Six canonical paths (A–F) cover everything from full greenfield projects to single-line fixes.
Maestro coordinates Claude Code, Codex, Gemini, Qwen, and OpenCode through four composable orchestration patterns:
| Pattern | How It Works |
|---|---|
| Delegate | Dispatch to any CLI tool via maestro delegate with SQLite-backed job broker, async execution, and message injection for follow-up chaining |
| Team | Coordinator-worker architecture — coordinators generate role-specs, spawn team-worker agents in parallel, supervised by a resident quality observer |
| Wave | Topological sort of tasks into dependency waves; independent tasks run concurrently within each wave |
| Swarm | ACO-driven multi-agent exploration for complex problem spaces with pheromone-guided convergence |
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.
MaestroGraph is the unified code index engine that replaces the former CodeGraph dependency. Built on web-tree-sitter for AST-level extraction, it stores both code structure (functions, classes, call chains) and project knowledge (specs, knowhow, domain terms, issues) in a single SQLite-backed graph with dual FTS5 indexes.
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
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.
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-