By 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
/reviewfor 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