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

---

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

---

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