# Maestro — Workflow Fluency for AI Agents Maestro is an open-source AI workflow skill with 25 commands, persistent memory, audit trail, and curated anti-patterns for building reliable, production-grade AI agent workflows. It's a meta-workflow layer that teaches AI agents *how to behave* across complex, multi-step tasks — not just *what to do*. **Website:** https://maestroskills.dev **GitHub:** https://github.com/sharpdeveye/maestro **npm:** https://www.npmjs.com/package/maestro-workflow-mcp **License:** MIT **Version:** 2.0.0 **Author:** SharpDevEye --- ## Installation Install Maestro in seconds: ```bash npx skills add sharpdeveye/maestro ``` This installs all 25 commands, 7 reference files, and curated anti-patterns into your AI development environment. After installation, run `/teach-maestro` to scan your project and generate a `.maestro.md` context file that all commands read. --- ## What Maestro Does Rather than giving your AI agent a task-specific skill (like "write SQL" or "format docs"), Maestro installs a meta-workflow layer that shapes how the agent handles the entire lifecycle of any agentic task. ### Key Pillars 1. **25 Workflow Commands** — covering planning, execution, checkpointing, task transitions, session memory, and handoffs between steps 2. **7 Reference Domains** — prompt engineering, context management, tool orchestration, agent architecture, feedback loops, knowledge systems, guardrails & safety 3. **Persistent Memory Layer** — decisions, audit trail, and session history survive across sessions via `.maestro/` directory 4. **Cost Estimation** — approximate cost tracking for Claude, GPT-4, Gemini, o3, o4-mini (±20% accuracy) 5. **Curated Anti-Patterns** — a documented list of common agent failure modes that should be actively avoided 6. **MCP Server Compatibility** — designed to work alongside MCP servers so agents can interact with external tools, file systems, APIs, and runners through a unified protocol --- ## What's New in v2.0.0 ### Memory Layer Maestro now remembers what happened across sessions: ``` .maestro/ ├── context.md ← project context (replaces .maestro.md) ├── decisions.jsonl ← append-only decision log ├── audit.jsonl ← every command with cost + duration └── sessions/ └── 2026-04-26_fix_auth.md ``` - Backward compatible — `.maestro.md` users change nothing - Opt-in — `.maestro/` is created only when you use `/capture` ### 3 New Commands - `/reflect` — Analyze command history to see which skills work, which fail, and where to improve - `/capture` — Save a session summary — persist decisions, context, and what happened - `/recap` — Quick summary of the last session — commands run, files changed, next steps ### Cost Estimation Approximate cost tracking for Claude, GPT-4, Gemini, and more. Accuracy: ±20% — useful for trends, not invoicing. ### 6 New MCP Tools (4 → 10) - `wave_start`, `wave_advance`, `wave_status` — wave-based execution tracking - `write_decision`, `read_decisions`, `read_audit` — decision and audit log access --- ## All 25 Commands ### Analysis Commands (3) #### /diagnose Systematic workflow quality audit with scored dimensions across 5 areas. Evaluates your current workflow quality and identifies what's broken before fixing anything. #### /evaluate Holistic review of workflow interaction quality, user journey, and effectiveness. Provides a comprehensive assessment of the entire workflow lifecycle. #### /reflect Analyze command history — which skills work, which fail, and where to improve. Generates an effectiveness scorecard showing commands run, completion rate, most used commands, and total cost. ### Fix & Improve Commands (5) #### /refine Final quality pass on prompts, tool descriptions, error messages, and logging. Ensures every piece of text in your workflow is precise and effective. #### /streamline Remove unnecessary complexity — flatten pipelines, eliminate redundant steps. Simplifies workflows that have grown too complex. #### /calibrate Align workflow components to project conventions and standards. Ensures consistency across all parts of your workflow. #### /fortify Add error handling, retries, fallbacks, circuit breakers, and recovery paths. Hardens your workflow against failure modes. #### /zero-defect Model-agnostic precision protocol — 8 execution rules, pre-commit verification gate, and anti-pattern correction table. Enforces maximum discipline in AI outputs with zero assumptions and verified results. This is Maestro's most rigorous command. ### Enhance Commands (9) #### /amplify Boost capabilities with better tools, context sources, and model features. Upgrades what your workflow can do. #### /compose Design multi-agent orchestration, delegation patterns, and coordination. For workflows that genuinely need multiple agents working together. #### /enrich Add knowledge sources, retrieval pipelines (RAG), and grounding. Connects your workflow to external knowledge. #### /accelerate Optimize for speed, reduce latency, minimize token usage, lower costs. Makes your workflow faster and cheaper. #### /chain Build effective tool chains, data pipelines, and multi-step processes. Designs the flow of data through your workflow. #### /guard Add safety constraints, input validation, output filtering, prompt injection defense. Protects your workflow from adversarial inputs. #### /iterate Set up feedback loops, evaluation cycles, and self-correction. Enables your workflow to learn from its outputs. #### /temper Reduce over-engineering — simplify overbuilt multi-agent systems. The antidote to Agent Overkill. #### /turbocharge Push past limits — parallel orchestration, streaming, and self-healing systems. For workflows that need maximum performance. ### Utility Commands (8) #### /extract-pattern Extract reusable patterns, templates, and best practices from working workflows. Turns one-off solutions into reusable components. #### /adapt-workflow Adapt workflows for different AI providers, environments, or teams. Makes workflows portable across different setups. #### /onboard-agent Set up new agent configurations and bootstrap workflow infrastructure. The starting point for new projects. #### /specialize Make workflows domain-specific — legal, medical, financial, code, etc. Tailors generic workflows to specific fields. #### /teach-maestro One-time context gathering — scans your project and saves project workflow context to `.maestro.md`. This file is read by all other commands to provide project-aware guidance. #### /capture Save a session summary — persist what was done, what decisions were made, and what to do next. Creates session files in `.maestro/sessions/`. #### /recap Quick summary of the last session — commands run, files changed, and what to do next. Reads from the latest session file. --- ## The 6 Anti-Patterns Maestro Prevents ### 1. Context Dumping Feeding entire codebases into prompts instead of curating relevant context. Wastes tokens, confuses the model, and causes context window overflow. ### 2. Retry & Pray Retrying failed operations without changing anything. No backoff, no fallback, no learning from failures. Same broken prompt sent 5 times produces the same wrong answer. ### 3. Agent Overkill Using autonomous agents for simple, linear tasks. Over-engineering with multi-agent systems when a single prompt or tool call suffices. ### 4. Tool Sprawl Registering dozens of tools with vague descriptions like "does stuff." The model can't choose effectively from ambiguous options. ### 5. Ship & Pray Deploying AI workflows with no evaluation, no monitoring, no feedback loops. Just hope it works in production with no scored dimensions or regression detection. ### 6. No Cost Controls Running expensive model calls in tight loops with no token budgets, rate limits, or cost awareness. Runaway agent loops can burn hundreds of dollars overnight. --- ## MCP Server Maestro includes a dedicated MCP (Model Context Protocol) server that provides programmatic access to all commands without copying files. ### Installation **Local (stdio transport):** ```json { "mcpServers": { "maestro": { "command": "npx", "args": ["-y", "maestro-workflow-mcp"] } } } ``` **Remote (HTTP transport):** ```bash npx maestro-workflow-mcp --http --port 3001 ``` ### What the MCP Server Exposes - **25 Prompts** — One per command, selectable from the prompt picker in any MCP client - **10 Tools** — `list_commands`, `run_command`, `read_context`, `init`, `wave_start`, `wave_advance`, `wave_status`, `write_decision`, `read_decisions`, `read_audit` - **8 Resources** — Core skill file + 7 domain reference files (prompt engineering, context management, tool orchestration, agent architecture, feedback loops, knowledge systems, guardrails & safety) ### Architecture | Layer | Role | |---|---| | **Maestro Skill** | Defines workflow structure, commands, and anti-patterns | | **MCP Server** | Provides AI agents access to tools (filesystem, APIs, test runners, git) | | **AI Model** | Orchestrates decisions using both the skill's workflow logic and MCP tool calls | The AI uses the Maestro skill to *reason about the workflow*, and MCP servers to *execute operations* — combining behavioral guidance with real-world tool access. ### Compatible Clients - Claude Code — Native MCP support via stdio transport - Cursor — MCP integration for AI-powered code editing - VS Code — MCP support via Copilot or Antigravity extensions - Gemini CLI — Google's CLI with built-in MCP client - Antigravity — Google DeepMind's coding agent with MCP support - Kiro — AWS's AI coding agent - Trae — ByteDance's AI coding agent - OpenCode — Open-source coding agent - Pi — Developer productivity agent - Any MCP-compatible client --- ## How It Works ### Step 1: Install One command adds 25 workflow commands, 7 reference files, and curated anti-patterns to your AI harness. ### Step 2: Diagnose Audit your current workflow quality across 5 scored dimensions. Identify what's broken before fixing anything. ### Step 3: Refine Quality pass on prompts, tool descriptions, error messages, and logging. Streamline away unnecessary complexity. ### Step 4: Fortify Add error handling, retries, fallbacks, circuit breakers. Guard against prompt injection and cost overruns. ### Step 5: Ship Deploy with confidence. Push past limits with parallel orchestration, streaming, and self-healing systems. --- ## 7 Reference Domains 1. **Prompt Engineering** — Few-shot patterns, chain-of-thought, output schemas, context quality 2. **Context Management** — Token optimization, context window profiling, memory management 3. **Tool Orchestration** — Tool chain design, error handling, sandboxing, fallback paths 4. **Agent Architecture** — Single vs. multi-agent patterns, delegation, coordination 5. **Feedback Loops** — Evaluation cycles, self-correction, regression detection 6. **Knowledge Systems** — RAG pipelines, retrieval quality, grounding, knowledge integration 7. **Guardrails & Safety** — Input validation, output filtering, prompt injection defense, cost controls --- ## Memory Layer Maestro v2.0.0 introduced persistent memory across sessions: ``` .maestro/ ├── context.md ← project context (replaces .maestro.md) ├── decisions.jsonl ← append-only decision log ├── audit.jsonl ← every command invocation with cost + duration └── sessions/ └── 2026-04-26_fix_auth.md ← session summaries ``` - **Backward compatible** — `.maestro.md` users change nothing - **Opt-in** — `.maestro/` is created only when you run `/capture` or use the extension - **Git-friendly** — session data is gitignored by default, context file is versioned ### Audit Trail Every command invocation is logged with duration, token usage, and estimated cost: ```json {"command":"fortify","duration_ms":8200,"cost_estimate_usd":0.019,"exit_status":"completed"} ``` ### Cost Estimation Approximate cost tracking for Claude, GPT-4, Gemini, and more. Accuracy: ±20% — useful for trends, not invoicing. --- ## Frequently Asked Questions ### What is Maestro? Maestro is an open-source AI workflow skill that provides 25 commands, a persistent memory layer, and curated anti-patterns for building reliable, production-grade AI agent workflows. It covers 7 domains: prompt engineering, context management, tool orchestration, agent architecture, feedback loops, knowledge systems, and guardrails & safety. ### What is Maestro Skills? Maestro Skills (at maestroskills.dev) is the name for the complete Maestro ecosystem — the workflow skill, the MCP server, and the documentation. It's a Claude Code Skill that teaches your agent how to behave across complex, multi-step tasks by providing a meta-workflow layer with 25 commands, persistent memory, and curated anti-patterns. ### How do I install Maestro? Install Maestro in seconds by running: `npx skills add sharpdeveye/maestro`. This installs the skill along with all 25 commands into your AI development environment. ### What commands does Maestro include? Maestro includes 25 commands across 4 categories: Analysis (diagnose, evaluate, reflect), Fix & Improve (refine, streamline, calibrate, fortify, zero-defect), Enhance (amplify, compose, enrich, accelerate, chain, guard, iterate, temper, turbocharge), and Utility (extract-pattern, adapt-workflow, onboard-agent, specialize, teach-maestro, capture, recap). ### What is the /zero-defect command? The /zero-defect command is a model-agnostic precision protocol that enforces 8 execution rules, pre-commit verification gates, and anti-pattern correction tables. It ensures maximum discipline in AI outputs with zero assumptions and verified results. ### Does Maestro support MCP (Model Context Protocol)? Yes, Maestro fully supports the Model Context Protocol (MCP). All 25 commands are available as MCP-compatible prompts via the maestro-workflow-mcp npm package. It supports both stdio and HTTP transports, with 10 tools and 8 resources. ### How does Maestro integrate with Claude Code? Maestro follows the standard Claude Code Skills format. Install it directly into your Claude Code environment with `npx skills add sharpdeveye/maestro`. Claude auto-discovers it at startup and loads the skill metadata. When you trigger a workflow command, Claude loads the full instructions on demand. ### What anti-patterns does Maestro prevent? Maestro prevents 6 documented anti-patterns: Context Dumping (feeding entire codebases into prompts), Retry & Pray (retrying without changing anything), Agent Overkill (over-engineering with multi-agent systems), Tool Sprawl (vague tool descriptions), Ship & Pray (deploying with no evaluation), and No Cost Controls (no token budgets or rate limits). ### Is Maestro free and open-source? Yes, Maestro is completely free and open-source under the MIT license. The source code is available at https://github.com/sharpdeveye/maestro. ### What is the MCP Server for Maestro? The MCP server (maestro-workflow-mcp on npm) exposes all 25 Maestro commands as MCP-compatible prompts, plus 10 tools and 8 resources. It supports dual transport — local via stdio and remote via HTTP — enabling integration with Claude Code, Cursor, VS Code, Gemini CLI, and any MCP-compatible client. ### What's new in v2.0.0? v2.0.0 introduces a persistent memory layer (decisions, audit trail, session history), 3 new commands (/reflect, /capture, /recap), cost estimation for major models, and 6 new MCP tools for decision and audit access.