Maestro Help

Maestro Help

Maestro Flow 命令帮助系统，提供命令搜索、技能浏览、工作流推荐、新手引导功能。

Trigger Conditions

• 关键词: "maestro-help", "帮助", "命令", "怎么用", "maestro 怎么用", "工作流", "skill", "workflow", "有哪些命令", "用什么命令"
• 场景: 询问命令用法、搜索命令、请求下一步建议、选择工作流、浏览 Skill/Agent 目录
• 斜杠: /maestro-help, /maestro-help search <keyword>, /maestro-help skills, /maestro-help guide

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│  Maestro Help (SKILL.md) — Orchestrator                          │
│  → Parse intent → Route to mode → Execute phase → Present        │
└────────────────────────┬─────────────────────────────────────────┘
                         │
    ┌────────────────────┼────────────────────────┐
    ↓                    ↓                        ↓
┌──────────┐      ┌──────────────┐         ┌──────────┐
│ Phase 1  │      │  Phase 2     │         │ Phase 3  │
│ Parse    │─────→│  Search &    │────────→│ Workflow │
│ Intent   │      │  Present     │         │ Guide    │
└──────────┘      └──────────────┘         └──────────┘
                       ↑       ↗                │
                       └──────┘                  ↓
                    (refine search)          present guide

Key Design Principles

1. Catalog 驱动: 所有查询基于 index/catalog.json，不做硬编码
2. Guide 深度链接: 命令详情链接到 guide/ 目录中的参考文档
3. 上下文感知: 根据项目状态（.workflow/ 是否存在、当前 Phase）调整推荐
4. 中英双语: 命令名英文，说明和示例中文

Data Source

Single source of truth: index/catalog.json

Operation Modes

Mode 1: Command Search

Triggers: "搜索命令", "find command", "search", 命令名关键词

Process:

1. Read Ref: phases/01-parse-intent.md — 解析搜索意图
2. Query catalog.json commands[] + cli_commands[]
3. Filter by name, description, category
4. Present top 5 相关结果，含命令名、描述、分类

Mode 2: Command Documentation

Triggers: "怎么用", "how to use", "详情", 具体命令名

Process:

1. Locate command in catalog.json
2. Read source file via source path（从 catalog 相对路径）
3. 若有对应 guide 文档，读取并提取相关段落
4. 提供上下文相关的用法示例

Mode 3: Smart Recommendations

Triggers: "下一步", "what's next", "推荐", "继续"

Process:

1. 检测当前项目状态（.workflow/state.json）
2. 根据 workflows 配置推荐后续命令
3. Explain WHY 每个推荐适合当前状态

Mode 4: Workflow Guide

Triggers: "工作流", "workflow", "怎么开始", "用什么流程"

Process:

1. Read Ref: phases/03-workflow-guide.md
2. 分析用户任务类型和复杂度
3. 推荐匹配的工作流（主干管线/Companion 轻量入口/Issue 闭环）
4. 给出具体命令序列

Mode 5: Beginner Onboarding

Triggers: "新手", "getting started", "常用命令", "入门"

Process:

1. Query catalog.json essential_commands[]
2. 逐个展示核心命令的简要说明
3. 引导用户完成首次项目初始化

Mode 6: Skill & Agent Browsing

Triggers: "skill", "agent", "技能", "有哪些 skill", "团队"

Process:

1. Read Ref: phases/02-search-present.md
2. Query catalog.json skills[] 或 agents[]
3. Filter by category
4. 呈现分类列表，含描述

Mode 7: CLI Command Reference

Triggers: "终端命令", "CLI", "maestro 命令", "terminal"

Process:

1. Query catalog.json cli_commands[]
2. 按分类分组呈现
3. 含别名和常用选项

Execution Flow

Input: $ARGUMENTS (free text)

Phase 1: Parse Intent
   └─ Ref: phases/01-parse-intent.md
      ├─ 分析关键词确定 operation mode
      ├─ 提取搜索词 / 命令名 / 分类过滤
      └─ Output: { mode, query, category?, context? }

Phase 2: Search & Present  (Mode 1/2/3/6/7)
   └─ Ref: phases/02-search-present.md
      ├─ 查询 catalog.json
      ├─ 按模式过滤和排序
      ├─ 读取 source 文件（Mode 2）
      └─ Output: 格式化结果

Phase 3: Workflow Guide  (Mode 4/5)
   └─ Ref: phases/03-workflow-guide.md
      ├─ 检测项目状态
      ├─ 匹配工作流模板
      ├─ 生成推荐命令序列
      └─ Output: 引导信息

Phase Reference Documents (read on-demand):

Input Processing

$ARGUMENTS → Parse:
  ├─ "search <keyword>"  → Mode 1: Command Search
  ├─ 命令名 (如 "analyze") → Mode 2: Documentation
  ├─ "下一步" / "next"     → Mode 3: Smart Recommendations
  ├─ "工作流" / "workflow" → Mode 4: Workflow Guide
  ├─ "新手" / "入门"       → Mode 5: Beginner Onboarding
  ├─ "skill" / "agent"    → Mode 6: Skill & Agent Browsing
  ├─ "CLI" / "终端"        → Mode 7: CLI Reference
  ├─ 空参数               → Mode 5: Beginner Onboarding
  └─ 其他自由文本          → Mode 1: Command Search (fuzzy)

Command Catalog Quick Reference

上游起源 + 核心 (core)

裸名称为 first-tier step：经 /maestro "<意图>" 自动路由，或按 v3 receipt chain 直接执行：session open → fenced session chain insert --command <step> --arg "<domain text>" → fenced run next。birth packet 内嵌 prepare guidance，并返回 resolved task 与 structured continuation；--input 仅接受 sealed same-Session Artifact ID。/ 前缀为独立命令。

理解层 + 执行管线 (pipeline)

质量管线 (quality)

管理命令 (manage)

Odyssey 长周期循环 (odyssey)

单入口 /maestro-odyssey <intent> --mode <name>（--mode 可省略，从 intent 关键词自动识别）：

Workflow Mapping

层级模型

Roadmap > Milestone > Phase > Task

• Roadmap = 项目级常驻规划文档
• Milestone = 可独立交付的版本节点（v0.1.0-rc1, v0.2.0）
• Phase = Milestone 内的同步屏障执行阶段
• Task = Phase 内的具体代码修改单元（wave DAG 管理并行）

命令拓扑

上游起源层（并列，可选）
  brainstorm（发散/轻量）  |  blueprint（收敛/重型）  |  grill（压力测试）

理解层
  analyze 双层: 宏观(文本参数) → scope_verdict | 微观(数字参数) → Phase 级决策

编排层（可选）
  roadmap — 消费上游 context，纯 Milestone > Phase 分解

执行层
  plan → execute

Odyssey 长周期循环（独立路径）
  maestro-odyssey --mode debug|improve|review|planex|ui

自适应引擎（高级）
  ralph → 自运行决策循环
  swarm-workflow / universal-workflow → 多 agent 并行执行

合法路径

注：Path A/B 中 analyze 1 / plan 1 的数字 1 指 milestone 编号（第 1 个里程碑），下游以 milestone 为入口。

Core Rules

1. Catalog First: 先查 catalog.json，再按需读 source 文件
2. Guide 链接: 对深层问题引用 guide/ 文档，告知用户具体文件名
3. 上下文感知: 检查 .workflow/ 存在性和 state.json 当前状态
4. 精确匹配: 搜索时支持命令名（不含前缀）、分类名、关键词
5. 不执行命令: 本 skill 只提供信息和推荐，不执行任何 maestro 命令

Error Handling

Related Resources

• Guide 目录: guide/ — 17 个专题指南文档
• Delegate 参考: ~/.maestro/workflows/delegate-usage.md
• Coding 哲学: ~/.maestro/workflows/coding-philosophy.md
• CLI 工具配置: ~/.maestro/cli-tools.json

Statistics

• Slash 命令: 64 个（13 个分类：core/pipeline/milestone/manage/quality/spec/learn/worktree/team/ralph/ui/tools/odyssey）
• CLI 命令: 21 个
• Skills: 23 个（3 个分类：meta/team/scholar；scholar-* 为选装，标 optional: true）
• Agents: 24 个（4 个分类：workflow/team/cli/ui）
• Guide 文档: 17 个（planned，尚未创建）
• 工作流路径: 7 个合法路径 (Path A-G) + 4 个辅助流程