maestro

---

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

Reference	Domain
prompt-engineering	Prompt structure, few-shot, CoT, output schemas
context-management	Window optimization, memory, state management
tool-orchestration	Tool design, chaining, error handling, sandboxing
agent-architecture	Topologies, handoffs, multi-agent patterns
feedback-loops	Evaluation, self-correction, regression detection
knowledge-systems	RAG, chunking, embeddings, source attribution
guardrails-safety	Validation, prompt injection, cost ceilings

---

25 Commands

Analysis — read-only, generate reports

Command	Purpose
/diagnose	Systematic workflow quality audit with scored dimensions
/evaluate	Holistic review of workflow interaction quality
/reflect	🆕 Analyze command history — which skills work, which fail

Fix & Improve — make targeted changes

Command	Purpose
/refine	Final quality pass on prompts, tools, and configuration
/streamline	Remove unnecessary complexity, flatten over-engineering
/calibrate	Align workflow components to project conventions
/fortify	Add error handling, retries, fallbacks, circuit breakers
/zero-defect	Activate maximum precision mode — zero mistakes allowed

Enhancement — add capabilities

Command	Purpose
/amplify	Boost capabilities with better tools and context
/compose	Design multi-agent orchestration and delegation
/enrich	Add knowledge sources, RAG, and grounding
/accelerate	Optimize for speed, reduce latency and cost
/chain	Build effective tool chains and pipelines
/guard	Add safety constraints and security boundaries
/iterate	Set up feedback loops and evaluation cycles
/temper	Reduce over-engineering, simplify overbuilt workflows
/turbocharge	Push past conventional limits — advanced techniques

Utility

Command	Purpose
/extract-pattern	Extract reusable patterns from working workflows
/adapt-workflow	Adapt workflows for different providers/contexts
/onboard-agent	Set up new agent configurations from scratch
/specialize	Make workflows domain-specific (legal, medical, etc.)
/teach-maestro	One-time context gathering, saves to .maestro.md
/capture	🆕 Save a session summary — persist what happened
/recap	🆕 Quick summary of the last session

---

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

Tool	Directory
Cursor	.cursor/skills/
Claude Code	.claude/skills/
Gemini CLI	.gemini/skills/
Codex CLI	.codex/skills/
VS Code Copilot / Antigravity	.agents/skills/
Kiro	.kiro/skills/
Trae	.trae/skills/
Trae China	.trae-cn/skills/
OpenCode	.opencode/skills/
Pi	.pi/skills/

---

MCP Server

Use Maestro as a live MCP server instead of static skill files. Any MCP-compatible client can connect — no file copying required.

Local (stdio)

Add to your MCP client config (Claude Desktop, Cursor, VS Code, etc.):

{
  "mcpServers": {
    "maestro": {
      "command": "npx",
      "args": ["-y", "maestro-workflow-mcp"]
    }
  }
}

Remote (HTTP)

Host Maestro as a public MCP endpoint:

npx maestro-workflow-mcp --http --port 3001

Clients connect to http://your-server:3001/mcp.

What the MCP Server Exposes

Type	Count	Description
Prompts	25	One per command — select from the prompt picker
Tools	10	list_commands, run_command, read_context, init, wave_start, wave_advance, wave_status, write_decision, read_decisions, read_audit
Resources	8	Core skill + 7 domain references

---

Manual Installation

If npx skills add doesn’t work for your setup, copy the appropriate provider directory to your project root:

# Example for Claude Code
cp -r .claude/skills/ your-project/.claude/skills/

# Example for Cursor
cp -r .cursor/skills/ your-project/.cursor/skills/

---

Project Structure

maestro/
├── source/skills/           # 25 source skill definitions
│   ├── agent-workflow/      # Core skill + 7 reference files
│   │   └── reference/       # Domain-specific guidance
│   ├── diagnose/            # Analysis commands
│   ├── evaluate/
│   ├── reflect/             # 🆕 Effectiveness analysis
│   ├── refine/              # Fix & improve commands
│   ├── streamline/
│   ├── calibrate/
│   ├── fortify/
│   ├── zero-defect/
│   ├── amplify/             # Enhancement commands
│   ├── compose/
│   ├── enrich/
│   ├── accelerate/
│   ├── chain/
│   ├── guard/
│   ├── iterate/
│   ├── temper/
│   ├── turbocharge/
│   ├── extract-pattern/     # Utility commands
│   ├── adapt-workflow/
│   ├── onboard-agent/
│   ├── specialize/
│   ├── teach-maestro/
│   ├── capture/             # 🆕 Session persistence
│   └── recap/               # 🆕 Session recovery
├── packages/core/           # Shared utilities
│   └── src/
│       ├── context-utils.ts  # Section parser + matcher
│       ├── token-estimator.ts # Token estimation
│       ├── decisions.ts      # 🆕 Decision log
│       ├── audit.ts          # 🆕 Audit trail
│       └── cost-estimator.ts # 🆕 Cost estimation
├── maestro-extension/       # VS Code extension
├── mcp-server/              # MCP server package
│   ├── src/
│   │   ├── index.ts         # Entry point (stdio + HTTP)
│   │   ├── http.ts          # HTTP transport wrapper
│   │   ├── tools.ts         # 10 MCP tools
│   │   ├── prompts.ts       # 25 MCP prompts
│   │   └── resources.ts     # 8 MCP resources
│   └── package.json
├── scripts/
│   ├── build.js             # Multi-provider build pipeline
│   ├── bundle-skills.js     # MCP skill bundler
│   └── validate.js          # Skill validation checks
└── package.json

---

Contributing

Contributions welcome! Please ensure:

• All content is original (no copying from other skill projects)
• SKILL.md files have valid YAML frontmatter with description starting with “Use when…”
• All code fences have a language specifier
• Run npm run check to validate before submitting

---

License

MIT — see LICENSE.