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](index/catalog.json)** | Field | Purpose | |-------|---------| | `commands[]` | 64 个 slash 命令，含分类和描述 | | `skills[]` | 23 个 Skill（含 10 个选装 scholar-*，标 `optional: true`），含分类和描述 | | `agents[]` | 24 个 Agent，含分类和描述 | | `cli_commands[]` | 21 个终端命令 | | `guide_files[]` | 17 个 Guide 文档索引（planned，尚未创建） | | `essential_commands[]` | 10 个核心命令（新手用） | | `workflows` | 主干管线、Companion 轻量入口、Issue 闭环、初始化路径 | ## 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): | Phase | Document | Purpose | |-------|----------|---------| | 1 | [phases/01-parse-intent.md](phases/01-parse-intent.md) | 意图解析和模式路由 | | 2 | [phases/02-search-present.md](phases/02-search-present.md) | 搜索和呈现 | | 3 | [phases/03-workflow-guide.md](phases/03-workflow-guide.md) | 工作流推荐和引导 | ## 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。`/` 前缀为独立命令。 | 命令 | 用途 | |------|------| | `/maestro` | 智能协调器，自动路由 | | `/maestro-init` | 项目初始化 | | `brainstorm` | 头脑风暴 — 发散探索，多角色创意 | | `blueprint` | 正式规格文档化 — 7-phase 收敛规格链 | | `roadmap` | 路线图编排 — 消费上游 context，纯 Milestone > Phase 分解 | | `/maestro-companion` | 轻量任务直接执行 | | `/maestro-overlay` | Overlay 管理 — 自然语言创建，或 `--amend` 从信号自动生成修正补丁 | | `grill` | 压力测试 — 对计划或需求进行代码库现实性压力测试 | | `/maestro-next` | 智能导航 — 检测状态并推荐下一步最优命令 | | `/maestro-ralph --engine swarm` | Swarm 并行加速器 — 多 agent 并发执行 | | `/maestro-ralph --engine universal` | 动态对抗工作流生成器 | ### 理解层 + 执行管线 (pipeline) | 命令 | 用途 | |------|------| | `analyze` | 双层分析 — 宏观(文本参数)探索影响面 / 微观(数字参数)Phase 级深入 | | `plan` | 任务规划 — 支持 `--from analyze:ANL-xxx` 直达 | | `execute` | 任务执行 | ### 质量管线 (quality) | 命令 | 用途 | |------|------| | `review` | 代码审查 | | `auto-test` | 自动测试 | | `test` | 业务测试 | | `debug` | 质量调试 | | `retrospective` | 复盘 | ### 管理命令 (manage) | 命令 | 用途 | |------|------| | `/maestro-issue` | Issue 管理（意图驱动：报告/列出/关闭/关联） | | `/maestro-issue discover` | Issue 发现 | | `/maestro-knowledge` | 知识存储管理（意图驱动：audit/harvest/wiki/extractors/domain） | | `/maestro-knowhow` | KnowHow 沉淀（意图驱动：按类型捕获可复用知识） | ### Odyssey 长周期循环 (odyssey) 单入口 `/maestro-odyssey <intent> --mode <name>`（`--mode` 可省略，从 intent 关键词自动识别）： | 模式 | 用途 | |------|------| | `--mode debug` | 长周期调试 — 考古、诊断、修复、泛化 | | `--mode improve` | 长周期代码改进 — 多维审计、深度诊断、定向修复 | | `--mode review` | 深度审查修复循环 | | `--mode planex` | 需求驱动迭代 — 计划/执行/验证/修复循环 | | `--mode ui` | 长周期 UI 优化 — 视觉调研、多维审计、修复 | ## 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 | 完整新项目 | `brainstorm` → `blueprint`(可选) → `analyze "topic"` → `roadmap` → `analyze 1` → `plan 1` → `execute` | | Path B | 旧项目大功能 | `analyze "feature X"` → `roadmap` → `analyze 1` → `plan 1` → `execute` | | Path C | 中等功能 | `analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute` | | Path D | 小改动 | `plan "fix auth bug"` → `execute` | | Path E | 纯规格文档 | `blueprint "project idea"` → (供人阅读) | | Path F | 纯探索 | `brainstorm "idea"` → (供人决策) | | 轻量修复 | 已知简单问题 | `/maestro-companion "修复描述"` | | Bug 追踪 | Issue 闭环 | `/maestro-issue discover` → `/maestro-issue create` → analyze/plan/execute → close | | 全自动 | /maestro 入口 | `/maestro -y "任务描述"` | | 代码审查 | 质量管线 | `review` → `auto-test` → `test` | | 多 CLI 交叉验证 | Collab step | `collab "需求描述"` | | 长周期调试 | Odyssey 深度循环 | `/maestro-odyssey "问题描述" --mode debug` | | 长周期改进 | Odyssey 深度循环 | `/maestro-odyssey "改进目标" --mode improve` | | 需求迭代 | Odyssey 深度循环 | `/maestro-odyssey "需求描述" --mode planex` | > 注：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 | 场景 | 处理 | |------|------| | 命令未找到 | 模糊搜索最近匹配，提示正确命令名 | | 项目未初始化 | 推荐先运行 `/maestro-init` | | Guide 文件不存在 | 跳过，仅提供 catalog 中的描述 | | 参数为空 | 默认进入 Beginner Onboarding 模式 | ## 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 个辅助流程