maestro

1 core skill · 25 commands · 7 domain references · memory layer · audit trail

Quick Start · Commands · What's New in v2 · Supported Tools · Contributing

What is Maestro?

AI agents are only as good as the workflows they operate in. Without guidance, you get the same predictable mistakes: unstructured prompts, context window overflows, tool sprawl, no error handling, and multi-agent systems for single-agent problems.

Maestro fights that pattern with:

• A comprehensive agent-workflow skill with 7 domain-specific reference files (view source)
• 25 commands to diagnose, evaluate, refine, streamline, fortify, capture, reflect, and more
• Persistent memory — decisions, audit trail, and session history survive across sessions
• Curated anti-patterns that explicitly tell the AI what NOT to do
• A context gathering protocol (.maestro.md or .maestro/context.md) that ensures every command has project-specific awareness
• Every command recommends a next step — no dead ends

Quick Start

npx skills add sharpdeveye/maestro

Then use any command in your AI coding agent:

/diagnose          # Find workflow issues
/streamline        # Remove unnecessary complexity
/fortify           # Add error handling
/refine            # Final quality pass

Most commands accept an optional argument to focus on a specific area:

/diagnose prompts
/fortify payment-workflow
/specialize legal

Combine Commands

/diagnose /calibrate /refine    # Full workflow: audit → standardize → polish
/evaluate /fortify /accelerate  # Review → harden → optimize

The Skill: agent-workflow

A comprehensive workflow design skill with 7 domain references (view skill):

25 Commands

Analysis — read-only, generate reports

Fix & Improve — make targeted changes

Enhancement — add capabilities

Utility

What's New in v2

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

{"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.

/reflect — Effectiveness Scorecard

Analyze your command history to see which skills work, which fail, and where to improve:

╔══════════════════════════════════════════╗
║          MAESTRO EFFECTIVENESS           ║
╠══════════════════════════════════════════╣
║ Commands Run         23 (7 unique)       ║
║ Completion Rate      87%                 ║
║ Most Used            /fortify (6×)       ║
║ Total Cost           ~$0.47              ║
╚══════════════════════════════════════════╝

Anti-Patterns ("Workflow Slop")

The skill includes explicit guidance on what to avoid:

• Don't dump entire codebases/databases into context
• Don't use multi-agent systems for single-agent problems
• Don't skip error handling (happy path only = production failure)
• Don't retry the same prompt hoping for different results
• Don't deploy without cost controls
• Don't use vague tool descriptions that confuse the model
• Don't ship without evaluation ("it seems to work" ≠ tested)

Supported Tools

MCP Server

Use Maestro as a live MCP server instead of static skill files. Any MCP-com