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
`@tdd`	TDD implementation (kraken)
`@spark`	Quick fixes
`@oracle`	Strategic advisor (opus)
`@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	opus	No	Yes (self-claim)
`explore`	Codebase search	sonnet	No	Yes (self-claim)
`leviathan`	Deep plan reviewer	opus	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)	opus	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

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
```
Quality:
```
/ultraqa
```
,
```
/review
```
Knowledge:
```
/note
```
,
```
/learner
```
Setup:
```
/setup
```

maestro

NPX Install

Tags

SKILL.md Content