Back to Details

maestro

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Maestro Workflow

Maestro工作流

"Spend tokens once on a good plan; reuse it many times."
"在优质规划上投入一次Token，便可多次复用。"

Triggers

触发命令

TriggerAction
/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
触发命令操作
/design <需求>
启动Prometheus访谈模式（支持
--quick
快速模式）
/work
通过Agent Teams执行规划（支持
--resume
恢复执行）
/setup-check
验证Maestro前置依赖
/status
显示当前Maestro状态
/review
执行后规划验证
/styleguide
将代码风格指南注入项目CLAUDE.md文件
/setup
搭建项目上下文（产品、技术栈、规范）
/reset
清理过期的Maestro状态
/analyze <问题或主题>
深度只读调研并生成结构化报告
/note [--priority <P0-P3>] <文本>
将决策、上下文和约束条件保存至持久记事本
/learner [--from-session | --from-diff | <主题>]
从实践中提取可复用的经验技能
/security-review [<文件> | --diff [范围]]
委托式安全分析并生成严重等级评级
/ultraqa [--tests|--build|--lint|--typecheck|--custom '<命令>']
迭代式修复与验证循环（最多5轮）
/research <主题> [--depth shallow|deep]
多Agent调研并支持会话持久化
@tdd
TDD实现（kraken）
@spark
快速修复
@oracle
战略顾问（opus）
@explore
代码库搜索

Planning Flow

规划流程

/design → prometheus (team lead) → detect libraries → fetch docs (Context7/WebSearch) → spawns explore/oracle → interview → leviathan (review) → plan file
  1. User triggers 
    /design <description>
  2. 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)
  3. Spawns explore for codebase research (and web research when relevant)
  4. Spawns oracle for architectural decisions
  5. Conducts structured interview (one question at a time, multiple-choice options, incremental validation)
  6. Draft updates in 
    .maestro/drafts/{topic}.md
  7. When clear, generate plan to 
    .maestro/plans/{name}.md
  8. Spawn leviathan to validate plan quality
  9. Cleanup team
Quick mode (
--quick
) streamlines to: team → 1 explore → 1-2 questions → plan
/design → prometheus (团队负责人) → 检测依赖库 → 获取文档 (Context7/WebSearch) → 启动explore/oracle → 访谈 → leviathan (审核) → 规划文件
  1. 用户触发
    /design <需求描述>
  2. 若需调研，Prometheus会创建协作团队 2.5. 加载
    .maestro/wisdom/
    中的历史经验（如有） 2.7. 检测外部库/框架提及，并通过Context7 MCP获取文档（ fallback至WebSearch/WebFetch）
  3. 启动explore进行代码库调研（相关时同步进行网络调研）
  4. 启动oracle进行架构决策
  5. 开展结构化访谈（逐个问题提问，提供多选选项，逐步验证）
  6. 在
    .maestro/drafts/{topic}.md
    中更新草稿
  7. 需求明确后，生成规划文件至
    .maestro/plans/{name}.md
  8. 启动leviathan验证规划质量
  9. 清理协作团队
快速模式（
--quick
）简化流程：团队 → 1次explore → 1-2个问题 → 生成规划

Execution Flow

执行流程

/work → orchestrator (team lead) → spawn workers in parallel → workers self-claim tasks
  1. User triggers 
    /work
  2. 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)
  3. Creates tasks via TaskCreate with dependencies
  4. Spawns 2-4 workers in parallel (kraken, spark)
  5. Assigns first round, workers self-claim remaining via TaskList
  6. Orchestrator verifies results, extracts wisdom to 
    .maestro/wisdom/
  7. Suggests 
    /review
    for post-execution verification
Use 
--resume
to skip already-completed tasks.
/work → orchestrator (团队负责人) → 并行启动工作Agent → Agent自主认领任务
  1. 用户触发
    /work
  2. Orchestrator从
    .maestro/plans/
    加载规划 2.5. 验证规划结构，并在执行前与用户确认 2.7. 可选创建git工作区以隔离执行（避免与并发会话冲突）
  3. 通过TaskCreate创建带依赖关系的任务
  4. 并行启动2-4个工作Agent（kraken、spark）
  5. 分配首轮任务，剩余任务由Agent通过TaskList自主认领
  6. Orchestrator验证执行结果，将经验提取至
    .maestro/wisdom/
  7. 建议执行
    /review
    进行执行后验证
使用
--resume
可跳过已完成的任务。

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)
.maestro/
├── plans/     # 已确认的工作规划
├── drafts/    # 访谈草稿
├── wisdom/    # 积累的经验
└── context/   # 项目上下文（产品、技术栈、规范）

.worktrees/        # 用于隔离规划执行的Git工作区（项目根目录）

Agents

Agent列表

AgentPurposeModelTeam Lead?Has Team Tools?
prometheus
Interview-driven planner. Detects libraries and fetches docs via Context7 MCP. Has web research tools (WebSearch, WebFetch)sonnetYesYes (full)
orchestrator
Execution coordinatorsonnetYesYes (full)
kraken
TDD implementationsonnetNoYes (self-claim)
spark
Quick fixessonnetNoYes (self-claim)
oracle
Strategic advisoropusNoYes (self-claim)
explore
Codebase searchsonnetNoYes (self-claim)
leviathan
Deep plan revieweropusNoYes (self-claim)
wisdom-synthesizer
Knowledge consolidationhaikuNoYes (self-claim)
progress-reporter
Status trackinghaikuNoYes (self-claim)
security-reviewer
Security analysis (read-only)opusNoYes (self-claim)
All agents have 
TaskList
, 
TaskGet
, 
TaskUpdate
, 
SendMessage
for team self-coordination. Only team leads have 
Task
, 
TeamCreate
, and 
TeamDelete
for spawning.
Agent用途模型是否为团队负责人？具备团队工具？
prometheus
访谈式规划器。通过Context7 MCP检测依赖库并获取文档。具备网络调研工具（WebSearch、WebFetch）sonnet是是（完整工具集）
orchestrator
执行协调器sonnet是是（完整工具集）
kraken
TDD实现sonnet否是（可自主认领）
spark
快速修复sonnet否是（可自主认领）
oracle
战略顾问opus否是（可自主认领）
explore
代码库搜索sonnet否是（可自主认领）
leviathan
深度规划审核opus否是（可自主认领）
wisdom-synthesizer
知识整合haiku否是（可自主认领）
progress-reporter
状态跟踪haiku否是（可自主认领）
security-reviewer
安全分析（只读）opus否是（可自主认领）
所有Agent均具备
TaskList
、
TaskGet
、
TaskUpdate
、
SendMessage
以实现团队自主协作。仅团队负责人具备
Task
、
TeamCreate
和
TeamDelete
用于创建协作团队。

Agent Teams Setup

Agent团队配置

Requires experimental feature flag in 
~/.claude/settings.json
:
json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
需在
~/.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.
Maestro会自动检测已安装的技能，并将其指导内容注入工作Agent的提示词中。这使得工作Agent无需手动配置即可遵循项目特定规范。
发现路径：
  • 项目级：
    .claude/skills/
  • 全局级：
    ~/.claude/skills/
优雅降级： 若未找到任何技能，工作流将正常执行，不会注入额外内容。
详情请见docs/SKILL-INTEROP.md。

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
  • 规划：
    /design add user authentication
  • 执行：
    /work
  • 调研：
    @explore
    , 
    @oracle
    , 
    /research
  • 实现：
    @tdd
    , 
    @spark
  • 分析：
    /analyze
    , 
    /security-review
  • 质量保障：
    /ultraqa
    , 
    /review
  • 知识管理：
    /note
    , 
    /learner
  • 初始化：
    /setup