| name | maestro |
| description | AI agent workflow with interview-driven planning and team-based execution. Use /design to start planning, /work to execute. |
Maestro Workflow
"Spend tokens once on a good plan; reuse it many times."
Triggers
| Trigger | Action |
|---|
/design <request> | Start Prometheus interview mode (supports --quick) |
/work | Execute plan with Agent Teams (supports --resume) |
/setup-check | Validate Maestro prerequisites |
/status | Show current Maestro state |
/review | Post-execution plan verification |
/styleguide | Inject code style guides into project CLAUDE.md |
/setup | Scaffold project context (product, tech stack, guidelines) |
/reset | Clean stale Maestro state |
/analyze <problem or topic> | Deep read-only investigation with structured report |
/note [--priority <P0-P3>] <text> | Capture decisions, context, and constraints to persistent notepad |
/learner [--from-session | --from-diff | <topic>] | Extract hard-won principles as reusable learned skills |
/security-review [<files> | --diff [range]] | Delegated security analysis with severity ratings |
/ultraqa [--tests|--build|--lint|--typecheck|--custom '<cmd>'] | Iterative fix-and-verify loop (max 5 cycles) |
/research <topic> [--depth shallow|deep] | Multi-agent research with session persistence |
/trace | Show agent execution timeline and performance summary |
/doctor | Diagnose and fix Maestro installation issues |
/psm | Project Session Manager — isolated dev environments with git worktrees and tmux |
/release | Automated release workflow with version bump, tag, publish, and GitHub release |
@tdd | TDD implementation (kraken) |
@spark | Quick fixes |
@oracle | Strategic advisor (sonnet) |
@explore | Codebase search |
Planning Flow
/design → prometheus (team lead) → detect libraries → fetch docs (Context7/WebSearch) → spawns explore/oracle → interview → leviathan (review) → plan file
- User triggers
/design <description>
- Prometheus creates team if research needed
2.5. Loads prior wisdom from
.maestro/wisdom/ (if any)
2.7. Detects external library/framework mentions and fetches docs via Context7 MCP (falls back to WebSearch/WebFetch)
- Spawns explore for codebase research (and web research when relevant)
- Spawns oracle for architectural decisions
- Conducts structured interview (one question at a time, multiple-choice options, incremental validation)
- Draft updates in
.maestro/drafts/{topic}.md
- When clear, generate plan to
.maestro/plans/{name}.md
- Spawn leviathan to validate plan quality
- Cleanup team
Quick mode (--quick) streamlines to: team → 1 explore → 1-2 questions → plan
Execution Flow
/work → orchestrator (team lead) → spawn workers in parallel → workers self-claim tasks
- User triggers
/work
- Orchestrator loads plan from
.maestro/plans/
2.5. Validates plan structure and confirms with user before proceeding
2.7. Optionally creates a git worktree for isolated execution (prevents conflicts with concurrent sessions)
- Creates tasks via TaskCreate with dependencies
- Spawns 2-4 workers in parallel (kraken, spark)
- Assigns first round, workers self-claim remaining via TaskList
- Orchestrator verifies results, extracts wisdom to
.maestro/wisdom/
- Suggests
/review for post-execution verification
Use --resume to skip already-completed tasks.
State Directory
.maestro/
├── plans/ # Committed work plans
├── drafts/ # Interview drafts
├── wisdom/ # Accumulated learnings
└── context/ # Project context (product, tech stack, guidelines)
.worktrees/ # Git worktrees for isolated plan execution (project root)
Agents
| Agent | Purpose | Model | Team Lead? | Has Team Tools? |
|---|
prometheus | Interview-driven planner. Detects libraries and fetches docs via Context7 MCP. Has web research tools (WebSearch, WebFetch) | sonnet | Yes | Yes (full) |
orchestrator | Execution coordinator | sonnet | Yes | Yes (full) |
kraken | TDD implementation | sonnet | No | Yes (self-claim) |
spark | Quick fixes | sonnet | No | Yes (self-claim) |
oracle | Strategic advisor | sonnet | No | Yes (self-claim) |
explore | Codebase search | haiku | No | Yes (self-claim) |
leviathan | Deep plan reviewer | sonnet | No | Yes (self-claim) |
wisdom-synthesizer | Knowledge consolidation | haiku | No | Yes (self-claim) |
progress-reporter | Status tracking | haiku | No | Yes (self-claim) |
security-reviewer | Security analysis (read-only) | sonnet | No | Yes (self-claim) |
All agents have TaskList, TaskGet, TaskUpdate, SendMessage for team self-coordination. Only team leads have Task, TeamCreate, and TeamDelete for spawning.
Agent Teams Setup
Requires experimental feature flag in ~/.claude/settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Skill Interoperability
Maestro auto-detects installed skills and injects their guidance into worker prompts. This allows workers to follow project-specific conventions without manual configuration.
Discovery locations:
- Project:
.claude/skills/
- Global:
~/.claude/skills/
Graceful degradation: If no skills are found, workflows proceed normally without injection.
See docs/SKILL-INTEROP.md for full details.
Quick Reference
- Design:
/design add user authentication
- Execution:
/work
- Research:
@explore, @oracle, /research
- Implementation:
@tdd, @spark
- Analysis:
/analyze, /security-review, /trace
- Quality:
/ultraqa, /review, /doctor
- Knowledge:
/note, /learner
- Setup:
/setup, /psm, /release
