maestro-help

Maestro Help

Maestro Flow command help system, providing command search, skill browsing, workflow recommendations, and beginner guidance features.

Trigger Conditions

Keywords: "maestro-help", "帮助", "命令", "怎么用", "maestro 怎么用", "工作流", "skill", "workflow", "有哪些命令", "用什么命令"
Scenarios: Asking about command usage, searching for commands, requesting next-step suggestions, choosing a workflow, browsing the Skill/Agent catalog
Slash: /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

Catalog-driven: All queries are based on index/catalog.json, no hardcoding
Guide deep links: Command details link to reference documents in the guide/ directory
Context-aware: Adjusts recommendations based on project state (whether .workflow/ exists, current Phase)
Bilingual Chinese-English: Command names in English, descriptions and examples in Chinese

Data Source

Single source of truth: index/catalog.json

Field	Purpose
`commands[]`	64 slash commands, including categories and descriptions
`skills[]`	23 Skills (including 10 optional scholar-*, marked `optional: true`), including categories and descriptions
`agents[]`	24 Agents, including categories and descriptions
`cli_commands[]`	21 terminal commands
`guide_files[]`	17 Guide document indexes (planned, not yet created)
`essential_commands[]`	10 core commands (for beginners)
`workflows`	Main pipeline, Companion lightweight entry, Issue closed loop, initialization path

Operation Modes

Mode 1: Command Search

Triggers: "搜索命令", "find command", "search", command name keywords

Process:

Read Ref: phases/01-parse-intent.md — Parse search intent
Query catalog.json commands[] + cli_commands[]
Filter by name, description, category
Present top 5 relevant results, including command name, description, category

Mode 2: Command Documentation

Triggers: "怎么用", "how to use", "详情", specific command name

Process:

Locate command in catalog.json
Read source file via source path (relative path from catalog)
If a corresponding guide document exists, read it and extract relevant paragraphs
Provide context-relevant usage examples

Mode 3: Smart Recommendations

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

Process:

Detect current project state (.workflow/state.json)
Recommend follow-up commands based on workflows configuration
Explain WHY each recommendation suits the current state

Mode 4: Workflow Guide

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

Process:

Read Ref: phases/03-workflow-guide.md
Analyze the user's task type and complexity
Recommend matching workflows (main pipeline/Companion lightweight entry/Issue closed loop)
Give a specific command sequence

Mode 5: Beginner Onboarding

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

Process:

Query catalog.json essential_commands[]
Show a brief description of each core command one by one
Guide the user through their first project initialization

Mode 6: Skill & Agent Browsing

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

Process:

Read Ref: phases/02-search-present.md
Query catalog.json skills[] or agents[]
Filter by category
Present a categorized list, including descriptions

Mode 7: CLI Command Reference

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

Process:

Query catalog.json cli_commands[]
Present grouped by category
Include aliases and common options

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	Intent parsing and mode routing
2	phases/02-search-present.md	Search and presentation
3	phases/03-workflow-guide.md	Workflow recommendation and guidance

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

Upstream origin + core (core)

Bare names are first-tier steps: via /maestro "<意图>" Automatic routing, or execute directly via the v3 receipt chain:session open → fenced session chain insert --command <step> --arg "<domain text>" → fenced run next. The birth packet embeds prepare guidance and returns resolved task and structured continuation；--input Only sealed same-Session Artifact IDs are accepted./ The prefix is a standalone command.

Command	Purpose
`/maestro`	Intelligent coordinator, automatic routing
`/maestro-init`	Project initialization
`brainstorm`	Brainstorming — divergent exploration, multi-role creativity
`blueprint`	Formal specification documentation — 7-phase convergent specification chain
`roadmap`	Roadmap orchestration — consumes upstream context, pure Milestone > Phase decomposition
`/maestro-companion`	Lightweight task direct execution
`/maestro-overlay`	Overlay management — natural language creation, or `--amend` automatically generates correction patches from signals
`grill`	Stress testing — stress-test plans or requirements against codebase reality
`/maestro-next`	Intelligent navigation — detects state and recommends the optimal next command
`/maestro-ralph --engine swarm`	Swarm parallel accelerator — multi-agent concurrent execution
`/maestro-ralph --engine universal`	Dynamic adversarial workflow generator

Understanding layer + execution pipeline (pipeline)

Command	Purpose
`analyze`	Dual-layer analysis — macro (text argument) explores impact surface / micro (numeric argument) Phase-level depth
`plan`	Task planning — supports `--from analyze:ANL-xxx` direct
`execute`	Task execution

Quality pipeline (quality)

Command	Purpose
`review`	Code review
`auto-test`	Automated testing
`test`	Business testing
`debug`	Quality debugging
`retrospective`	Retrospective

Management commands (manage)

Command	Purpose
`/maestro-issue`	Issue management (intent-driven: report/list/close/link)
`/maestro-issue discover`	Issue discovery
`/maestro-knowledge`	Knowledge storage management (intent-driven: audit/harvest/wiki/extractors/domain)
`/maestro-knowhow`	KnowHow accumulation (intent-driven: capture reusable knowledge by type)

Odyssey long-cycle loop (odyssey)

Single entry /maestro-odyssey <intent> --mode <name>（--mode can be omitted, automatically identified from intent keywords):

Mode	Purpose
`--mode debug`	Long-cycle debugging — archaeology, diagnosis, repair, generalization
`--mode improve`	Long-cycle code improvement — multi-dimensional audit, deep diagnosis, targeted repair
`--mode review`	Deep review-repair loop
`--mode planex`	Requirement-driven iteration — plan/execute/verify/repair loop
`--mode ui`	Long-cycle UI optimization — visual research, multi-dimensional audit, repair

Workflow Mapping

Hierarchy model

Roadmap > Milestone > Phase > Task

Roadmap = project-level persistent planning document
Milestone = independently deliverable release node (v0.1.0-rc1, v0.2.0)
Phase = synchronous barrier execution stage within a Milestone
Task = specific code modification unit within a Phase (wave DAG manages parallelism)

Command topology

上游起源层（并列，可选）
  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 并行执行

Legal paths

Path	Scenario	Command sequence
Path A	Complete new project	`brainstorm` → `blueprint`(optional) → `analyze "topic"` → `roadmap` → `analyze 1` → `plan 1` → `execute`
Path B	Major feature in legacy project	`analyze "feature X"` → `roadmap` → `analyze 1` → `plan 1` → `execute`
Path C	Medium feature	`analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute`
Path D	Small change	`plan "fix auth bug"` → `execute`
Path E	Pure specification documentation	`blueprint "project idea"` → (for human reading)
Path F	Pure exploration	`brainstorm "idea"` → (for human decision-making)
Lightweight fix	Known simple issue	`/maestro-companion "修复描述"`
Bug tracking	Issue closed loop	`/maestro-issue discover` → `/maestro-issue create` → analyze/plan/execute → close
Fully automatic	/maestro entry	`/maestro -y "任务描述"`
Code review	Quality pipeline	`review` → `auto-test` → `test`
Multi-CLI cross-validation	Collab step	`collab "需求描述"`
Long-cycle debugging	Odyssey deep loop	`/maestro-odyssey "问题描述" --mode debug`
Long-cycle improvement	Odyssey deep loop	`/maestro-odyssey "改进目标" --mode improve`
Requirements iteration	Odyssey deep loop	`/maestro-odyssey "需求描述" --mode planex`

Note: In Path A/B, analyze 1 / plan 1 's number 1 refers to milestone number(the 1st milestone); downstream uses the milestone as the entry point.

Core Rules

Catalog First: First check catalog.json, then read source files as needed
Guide links: For deep issues, reference guide/ documents and tell the user the specific file name
Context awareness: Check for the existence of .workflow/ and the current state of state.json
Exact match: Search supports command names (without prefix), category names, and keywords
Does not execute commands: This skill only provides information and recommendations and does not execute any maestro commands

Error Handling

Scenario	Handling
Command not found	Fuzzy-search for the closest match and suggest the correct command name
Project not initialized	Recommend running first `/maestro-init`
Guide file does not exist	Skip; only provide the description from the catalog
Empty parameters	Enter Beginner Onboarding mode by default

Related Resources

Guide directory: guide/ — 17 topical guide documents
Delegate reference: ~/.maestro/workflows/delegate-usage.md
Coding philosophy: ~/.maestro/workflows/coding-philosophy.md
CLI tool configuration: ~/.maestro/cli-tools.json

Statistics

Slash commands: 64 (13 categories: core/pipeline/milestone/manage/quality/spec/learn/worktree/team/ralph/ui/tools/odyssey)
CLI commands: 21
Skills: 23 (3 categories: meta/team/scholar; scholar-* is optional and marked optional: true）
Agents: 24 (4 categories: workflow/team/cli/ui)
Guide documents: 17 (planned, not yet created)
Workflow paths: 7 valid paths (Path A-G) + 4 auxiliary processes

About this skill

Trigger Conditions

Architecture Overview

Key Design Principles

Data Source

Operation Modes

Mode 1: Command Search

Mode 2: Command Documentation

Mode 3: Smart Recommendations

Mode 4: Workflow Guide

Mode 5: Beginner Onboarding

Mode 6: Skill & Agent Browsing

Mode 7: CLI Command Reference

Execution Flow

Input Processing

Command Catalog Quick Reference

Upstream origin + core (core)

Understanding layer + execution pipeline (pipeline)

Quality pipeline (quality)

Management commands (manage)

Odyssey long-cycle loop (odyssey)

Workflow Mapping

Hierarchy model

Command topology

Legal paths

Core Rules

Error Handling

Related Resources

Statistics