maestro-flow 0.4.9 → 0.4.11

package/.agents/skills/maestro-help/index/catalog.json

@@ -0,0 +1,184 @@
+{
+  "_metadata": {
+    "version": "1.0.0",
+    "generated": "2026-05-11",
+    "description": "Maestro Flow command/skill/agent catalog — single source of truth for maestro-help"
+  },
+  "commands": [
+    {"name": "maestro", "command": "/maestro", "category": "core", "description": "智能协调器 — 根据意图和项目状态自动选择最优命令链", "source": "../../commands/maestro.md"},
+    {"name": "maestro-init", "command": "/maestro-init", "category": "core", "description": "项目初始化 — 创建 .workflow/ 目录结构和状态文件", "source": "../../commands/maestro-init.md"},
+    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图生成 — 基于目标创建里程碑和 Phase 分解", "source": "../../commands/maestro-roadmap.md"},
+    {"name": "maestro-brainstorm", "command": "/maestro-brainstorm", "category": "core", "description": "多角色头脑风暴 — 生成分析文档和功能规格", "source": "../../commands/maestro-brainstorm.md"},
+    {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "多维度分析 — Phase 分析、CLI 辅助探索、gap 分析", "source": "../../commands/maestro-analyze.md"},
+    {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 生成执行计划、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
+    {"name": "maestro-execute", "command": "/maestro-execute", "category": "pipeline", "description": "任务执行 — wave 并行执行、delegate 编排、自动提交", "source": "../../commands/maestro-execute.md"},
+    {"name": "maestro-verify", "command": "/maestro-verify", "category": "pipeline", "description": "验证确认 — 成果检查、gap 发现、下一阶段建议", "source": "../../commands/maestro-verify.md"},
+    {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过 Phase 管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
+    {"name": "maestro-overlay", "command": "/maestro-overlay", "category": "core", "description": "Overlay 管理 — 创建、查看、删除命令补丁", "source": "../../commands/maestro-overlay.md"},
+    {"name": "maestro-amend", "command": "/maestro-amend", "category": "core", "description": "修正补丁 — 从工作流信号自动生成 overlay", "source": "../../commands/maestro-amend.md"},
+    {"name": "maestro-fork", "command": "/maestro-fork", "category": "worktree", "description": "Worktree 分叉 — 基于 milestone 创建隔离开发环境", "source": "../../commands/maestro-fork.md"},
+    {"name": "maestro-merge", "command": "/maestro-merge", "category": "worktree", "description": "Worktree 合并 — 同步变更回主线", "source": "../../commands/maestro-merge.md"},
+    {"name": "maestro-collab", "command": "/maestro-collab", "category": "team", "description": "人类团队协作 — .workflow/collab/ 目录管理", "source": "../../commands/maestro-collab.md"},
+    {"name": "maestro-milestone-audit", "command": "/maestro-milestone-audit", "category": "milestone", "description": "里程碑审计 — 检查 Phase 完成度和质量", "source": "../../commands/maestro-milestone-audit.md"},
+    {"name": "maestro-milestone-complete", "command": "/maestro-milestone-complete", "category": "milestone", "description": "里程碑完成 — 归档里程碑并推进下一个", "source": "../../commands/maestro-milestone-complete.md"},
+    {"name": "maestro-milestone-release", "command": "/maestro-milestone-release", "category": "milestone", "description": "里程碑发布 — 生成发布说明和变更日志", "source": "../../commands/maestro-milestone-release.md"},
+    {"name": "maestro-composer", "command": "/maestro-composer", "category": "core", "description": "编排器 — compose + play 工作流组合执行", "source": "../../commands/maestro-composer.md"},
+    {"name": "maestro-guard", "command": "/maestro-guard", "category": "core", "description": "编辑边界治理", "source": "../../commands/maestro-guard.md"},
+    {"name": "maestro-player", "command": "/maestro-player", "category": "core", "description": "播放器 — 执行已编排的工作流", "source": "../../commands/maestro-player.md"},
+    {"name": "maestro-ralph", "command": "/maestro-ralph", "category": "ralph", "description": "Ralph 引擎 — 自适应生命周期决策节点管理", "source": "../../commands/maestro-ralph.md"},
+    {"name": "maestro-ralph-execute", "command": "/maestro-ralph-execute", "category": "ralph", "description": "Ralph 执行 — 运行自适应决策链", "source": "../../commands/maestro-ralph-execute.md"},
+    {"name": "maestro-learn", "command": "/maestro-learn", "category": "core", "description": "学习 — 从执行中提取知识和模式", "source": "../../commands/maestro-learn.md"},
+    {"name": "maestro-impeccable", "command": "/maestro-impeccable", "category": "ui", "description": "UI 生产 — 设计系统生成 + impeccable 链式编排 + 质量门控", "source": "../../commands/maestro-impeccable.md"},
+    {"name": "maestro-ui-codify", "command": "/maestro-ui-codify", "category": "ui", "description": "UI 固化 — 将设计产出转化为知识资产", "source": "../../commands/maestro-ui-codify.md"},
+    {"name": "maestro-update", "command": "/maestro-update", "category": "core", "description": "版本更新 — 检查并安装最新版本", "source": "../../commands/maestro-update.md"},
+    {"name": "maestro-tools-register", "command": "/maestro-tools-register", "category": "tools", "description": "MCP 工具注册 — 注册外部工具到 Maestro", "source": "../../commands/maestro-tools-register.md"},
+    {"name": "maestro-tools-execute", "command": "/maestro-tools-execute", "category": "tools", "description": "MCP 工具执行 — 调用已注册的外部工具", "source": "../../commands/maestro-tools-execute.md"},
+    {"name": "manage-issue", "command": "/manage-issue", "category": "manage", "description": "Issue 管理 — CRUD 操作、状态追踪", "source": "../../commands/manage-issue.md"},
+    {"name": "manage-issue-discover", "command": "/manage-issue-discover", "category": "manage", "description": "Issue 发现 — 按提示词或代码分析自动发现问题", "source": "../../commands/manage-issue-discover.md"},
+    {"name": "manage-knowhow", "command": "/manage-knowhow", "category": "manage", "description": "知识管理 — knowhow 条目查询和管理", "source": "../../commands/manage-knowhow.md"},
+    {"name": "manage-knowhow-capture", "command": "/manage-knowhow-capture", "category": "manage", "description": "知识捕获 — 从会话中捕获非显而易见的知识", "source": "../../commands/manage-knowhow-capture.md"},
+    {"name": "manage-learn", "command": "/manage-learn", "category": "manage", "description": "学习管理 — 查看、整理学习记录", "source": "../../commands/manage-learn.md"},
+    {"name": "manage-harvest", "command": "/manage-harvest", "category": "manage", "description": "收获 — 从已完成里程碑中提取可复用资产", "source": "../../commands/manage-harvest.md"},
+    {"name": "manage-status", "command": "/manage-status", "category": "manage", "description": "状态查看 — 项目和工作流状态总览", "source": "../../commands/manage-status.md"},
+    {"name": "manage-wiki", "command": "/manage-wiki", "category": "manage", "description": "Wiki 管理 — 知识图谱条目操作", "source": "../../commands/manage-wiki.md"},
+    {"name": "manage-codebase-refresh", "command": "/manage-codebase-refresh", "category": "manage", "description": "代码库刷新 — 增量更新代码库索引", "source": "../../commands/manage-codebase-refresh.md"},
+    {"name": "manage-codebase-rebuild", "command": "/manage-codebase-rebuild", "category": "manage", "description": "代码库重建 — 全量重建代码库索引", "source": "../../commands/manage-codebase-rebuild.md"},
+    {"name": "quality-review", "command": "/quality-review", "category": "quality", "description": "代码审查 — 多维度代码质量检查", "source": "../../commands/quality-review.md"},
+    {"name": "quality-auto-test", "command": "/quality-auto-test", "category": "quality", "description": "自动测试 — 智能路由 spec/gap/code 测试", "source": "../../commands/quality-auto-test.md"},
+    {"name": "quality-test", "command": "/quality-test", "category": "quality", "description": "业务测试 — 会话式 UAT 验证", "source": "../../commands/quality-test.md"},
+    {"name": "security-audit", "command": "/security-audit", "category": "quality", "description": "OWASP/STRIDE 安全审计", "source": "../../commands/security-audit.md"},
+    {"name": "quality-debug", "command": "/quality-debug", "category": "quality", "description": "质量调试 — 诊断测试失败并提供修复方案", "source": "../../commands/quality-debug.md"},
+    {"name": "quality-refactor", "command": "/quality-refactor", "category": "quality", "description": "代码重构 — 结构优化和模式改进", "source": "../../commands/quality-refactor.md"},
+    {"name": "quality-sync", "command": "/quality-sync", "category": "quality", "description": "质量同步 — 跨 Phase 质量状态对齐", "source": "../../commands/quality-sync.md"},
+    {"name": "quality-retrospective", "command": "/quality-retrospective", "category": "quality", "description": "质量复盘 — 阶段性质量回顾和改进", "source": "../../commands/quality-retrospective.md"},
+    {"name": "spec-setup", "command": "/spec-setup", "category": "spec", "description": "Spec 初始化 — 创建项目规范文件", "source": "../../commands/spec-setup.md"},
+    {"name": "spec-load", "command": "/spec-load", "category": "spec", "description": "Spec 加载 — 按关键词加载规范条目", "source": "../../commands/spec-load.md"},
+    {"name": "spec-add", "command": "/spec-add", "category": "spec", "description": "Spec 录入 — 添加新的规范条目", "source": "../../commands/spec-add.md"},
+    {"name": "spec-remove", "command": "/spec-remove", "category": "spec", "description": "Spec 移除 — 删除已有规范条目", "source": "../../commands/spec-remove.md"},
+    {"name": "learn-retro", "command": "/learn-retro", "category": "learn", "description": "统一复盘 — git + 决策双轨复盘", "source": "../../commands/learn-retro.md"},
+    {"name": "learn-follow", "command": "/learn-follow", "category": "learn", "description": "跟读学习 — 从代码变更中学习模式", "source": "../../commands/learn-follow.md"},
+    {"name": "learn-decompose", "command": "/learn-decompose", "category": "learn", "description": "模式拆解 — 将复杂模式分解为可复用组件", "source": "../../commands/learn-decompose.md"},
+    {"name": "learn-investigate", "command": "/learn-investigate", "category": "learn", "description": "系统探究 — 深入调查技术选型和架构", "source": "../../commands/learn-investigate.md"},
+    {"name": "learn-second-opinion", "command": "/learn-second-opinion", "category": "learn", "description": "多视角分析 — 多 CLI 交叉验证观点", "source": "../../commands/learn-second-opinion.md"},
+    {"name": "wiki-connect", "command": "/wiki-connect", "category": "wiki", "description": "Wiki 连接 — 发现知识条目间关系", "source": "../../commands/wiki-connect.md"},
+    {"name": "wiki-digest", "command": "/wiki-digest", "category": "wiki", "description": "Wiki 摘要 — 生成知识图谱概要", "source": "../../commands/wiki-digest.md"}
+  ],
+  "skills": [
+    {"name": "workflow-skill-designer", "category": "meta", "description": "Meta-skill: 设计 orchestrator+phases 结构的工作流 skill", "source": "../workflow-skill-designer/SKILL.md"},
+    {"name": "skill-iter-tune", "category": "meta", "description": "迭代 skill 调优: execute-evaluate-improve 反馈循环", "source": "../skill-iter-tune/SKILL.md"},
+    {"name": "team-coordinate", "category": "team", "description": "通用团队协调: 运行时动态生成 role-specs", "source": "../team-coordinate/SKILL.md"},
+    {"name": "team-executor", "category": "team", "description": "团队执行: 恢复会话执行任务", "source": "../team-executor/SKILL.md"},
+    {"name": "team-lifecycle-v4", "category": "team", "description": "完整生命周期: 8 角色 spec/impl/test/review 流水线", "source": "../team-lifecycle-v4/SKILL.md"},
+    {"name": "team-quality-assurance", "category": "team", "description": "QA 团队: 质量保障流水线", "source": "../team-quality-assurance/SKILL.md"},
+    {"name": "team-review", "category": "team", "description": "代码审查团队: 多维度扫描和漏洞审查", "source": "../team-review/SKILL.md"},
+    {"name": "team-tech-debt", "category": "team", "description": "技术债务团队: 债务识别和清理", "source": "../team-tech-debt/SKILL.md"},
+    {"name": "team-testing", "category": "team", "description": "测试团队: 测试规划和执行", "source": "../team-testing/SKILL.md"},
+    {"name": "codify-to-knowhow", "category": "knowledge", "description": "Manifest 驱动的知识资产生成器", "source": "../codify-to-knowhow/SKILL.md"}
+  ],
+  "agents": [
+    {"name": "workflow-analyzer", "description": "多维度分析 — 证据评分和推荐", "category": "workflow"},
+    {"name": "workflow-planner", "description": "任务分解和执行计划生成", "category": "workflow"},
+    {"name": "workflow-executor", "description": "原子任务执行和验证", "category": "workflow"},
+    {"name": "workflow-verifier", "description": "目标回溯验证（存在性、实质、连接）", "category": "workflow"},
+    {"name": "workflow-reviewer", "description": "多维度代码审查", "category": "workflow"},
+    {"name": "workflow-debugger", "description": "假设驱动调试和结构化证据日志", "category": "workflow"},
+    {"name": "workflow-research-agent", "description": "外部研究 — API 模式、技术验证", "category": "workflow"},
+    {"name": "workflow-roadmapper", "description": "分阶段里程碑路线图", "category": "workflow"},
+    {"name": "workflow-plan-checker", "description": "计划质量验证（最多 3 轮修订）", "category": "workflow"},
+    {"name": "workflow-phase-researcher", "description": "特定路线图阶段的实现方法研究", "category": "workflow"},
+    {"name": "workflow-project-researcher", "description": "项目初始化的领域研究", "category": "workflow"},
+    {"name": "workflow-research-synthesizer", "description": "多研究结果合并为统一摘要", "category": "workflow"},
+    {"name": "workflow-codebase-mapper", "description": "从特定焦点分析现有代码库", "category": "workflow"},
+    {"name": "workflow-nyquist-auditor", "description": "测试覆盖审计和 gap 检测", "category": "workflow"},
+    {"name": "workflow-integration-checker", "description": "跨阶段集成验证（里程碑审计）", "category": "workflow"},
+    {"name": "workflow-external-researcher", "description": "外部研究（Exa MCP）", "category": "workflow"},
+    {"name": "workflow-collab-planner", "description": "预分配任务 ID 的协作规划", "category": "workflow"},
+    {"name": "team-supervisor", "description": "管道监督 — 跨 checkpoint 质量观察", "category": "team"},
+    {"name": "team-worker", "description": "统一工作器 — 加载 role-spec 执行任务", "category": "team"},
+    {"name": "conceptual-planning-agent", "description": "多模式分析 — 角色分析和功能规格", "category": "planning"},
+    {"name": "cli-explore-agent", "description": "CLI 辅助的代码探索", "category": "cli"},
+    {"name": "ui-design-agent", "description": "UI 设计 Token 管理和原型生成", "category": "ui"}
+  ],
+  "cli_commands": [
+    {"command": "maestro install", "description": "安装 Maestro 资源（交互式）", "category": "setup"},
+    {"command": "maestro uninstall", "description": "卸载已安装资源", "category": "setup"},
+    {"command": "maestro update", "description": "检查/安装最新版本", "category": "setup"},
+    {"command": "maestro view", "description": "启动 Dashboard 看板", "category": "dashboard"},
+    {"command": "maestro stop", "description": "停止 Dashboard 服务", "category": "dashboard"},
+    {"command": "maestro delegate", "description": "委派任务给 AI 智能体", "category": "execution"},
+    {"command": "maestro coordinate", "description": "图工作流协调器（别名 coord）", "category": "execution"},
+    {"command": "maestro cli", "description": "运行 CLI 智能体工具", "category": "execution"},
+    {"command": "maestro run", "description": "执行指定工作流", "category": "execution"},
+    {"command": "maestro serve", "description": "启动工作流服务器", "category": "execution"},
+    {"command": "maestro launcher", "description": "Claude Code 启动器", "category": "setup"},
+    {"command": "maestro spec", "description": "项目 Spec 管理", "category": "knowledge"},
+    {"command": "maestro wiki", "description": "Wiki 知识图谱查询", "category": "knowledge"},
+    {"command": "maestro hooks", "description": "Hook 管理与运行", "category": "config"},
+    {"command": "maestro overlay", "description": "命令 Overlay 管理", "category": "config"},
+    {"command": "maestro collab", "description": "人类团队协作（别名 team）", "category": "team"},
+    {"command": "maestro agent-msg", "description": "智能体团队消息总线（别名 msg）", "category": "team"},
+    {"command": "maestro knowhow", "description": "知识复用管理（别名 kh）", "category": "knowledge"},
+    {"command": "maestro brainstorm-visualize", "description": "头脑风暴可视化服务器（别名 bv）", "category": "visualization"},
+    {"command": "maestro ext", "description": "扩展管理", "category": "config"},
+    {"command": "maestro tool", "description": "工具交互（list/exec）", "category": "config"}
+  ],
+  "categories": {
+    "commands": ["core", "pipeline", "milestone", "manage", "quality", "spec", "learn", "wiki", "worktree", "team", "ralph", "ui", "tools"],
+    "skills": ["meta", "team", "knowledge"],
+    "agents": ["workflow", "team", "planning", "cli", "ui"]
+  },
+  "guide_files": [
+    {"file": "guide/quick-start-guide.md", "title": "快速入门", "description": "10 分钟了解核心功能"},
+    {"file": "guide/cli-commands-guide.md", "title": "CLI 命令参考", "description": "21 个终端命令详解"},
+    {"file": "guide/command-usage-guide.md", "title": "Slash 命令使用", "description": "49 个 slash 命令分类和衔接"},
+    {"file": "guide/mcp-tools-guide.md", "title": "MCP 工具参考", "description": "9 个 MCP 工具详解"},
+    {"file": "guide/delegate-async-guide.md", "title": "Delegate 异步指南", "description": "异步任务委派和生命周期"},
+    {"file": "guide/hooks-guide.md", "title": "Hook 系统", "description": "12 个 Hook、4 个安装级别"},
+    {"file": "guide/knowledge-management-guide.md", "title": "知识管理", "description": "Spec + Wiki 知识体系"},
+    {"file": "guide/knowledge-management-intro.md", "title": "知识管理导论", "description": "设计理念和产品结构"},
+    {"file": "guide/maestro-coordinator-guide.md", "title": "/maestro 协调器", "description": "静态链选择器和意图路由"},
+    {"file": "guide/maestro-ralph-guide.md", "title": "/maestro-ralph 引擎", "description": "自适应生命周期决策节点"},
+    {"file": "guide/overlay-guide.md", "title": "Overlay 系统", "description": "非侵入式命令补丁"},
+    {"file": "guide/role-routing-guide.md", "title": "角色路由", "description": "基于 --role 的工具选择"},
+    {"file": "guide/skill-config-guide.md", "title": "Skill 配置", "description": "参数默认值配置"},
+    {"file": "guide/spec-system-guide.md", "title": "Spec 系统", "description": "条目格式和自动注入"},
+    {"file": "guide/statusline-guide.md", "title": "Statusline", "description": "多行状态栏定制"},
+    {"file": "guide/team-lite-guide.md", "title": "Team Lite", "description": "2-8 人团队协作"},
+    {"file": "guide/worktree-guide.md", "title": "Worktree", "description": "Git worktree 里程碑并行"}
+  ],
+  "essential_commands": [
+    "/maestro",
+    "/maestro-init",
+    "/maestro-roadmap",
+    "/maestro-analyze",
+    "/maestro-plan",
+    "/maestro-execute",
+    "/maestro-verify",
+    "/maestro-quick",
+    "/quality-review",
+    "/manage-issue"
+  ],
+  "workflows": {
+    "main_pipeline": {
+      "name": "主干管线",
+      "phases": ["analyze", "plan", "execute", "verify"],
+      "quality": ["quality-auto-test", "quality-review", "quality-test"],
+      "close": ["maestro-milestone-audit", "maestro-milestone-complete"]
+    },
+    "quick": {
+      "name": "快速渠道",
+      "entry": "/maestro-quick",
+      "modes": ["default (analyze+execute)", "--full (analyze+plan+execute+verify)", "--discuss (multi-cli讨论)"]
+    },
+    "issue_loop": {
+      "name": "Issue 闭环",
+      "phases": ["manage-issue-discover", "manage-issue create", "maestro-analyze --gaps", "maestro-plan --gaps", "maestro-execute", "manage-issue close"]
+    },
+    "init_paths": {
+      "name": "初始化路径",
+      "minimal": "/maestro-init → /maestro-roadmap",
+      "from_brainstorm": "/maestro-brainstorm → /maestro-init --from-brainstorm → /maestro-roadmap",
+      "full_spec": "/maestro-init → /maestro-spec-generate"
+    }
+  }
+}

package/.agents/skills/maestro-help/phases/01-parse-intent.md

@@ -0,0 +1,122 @@
+# Phase 1: Parse Intent
+
+解析用户输入，确定操作模式和查询参数。
+
+## Objective
+
+- 分析 `$ARGUMENTS` 确定用户意图
+- 路由到正确的 Operation Mode
+- 提取搜索关键词 / 命令名 / 分类过滤
+
+## Execution
+
+### Step 1.1: 空参数处理
+
+若 `$ARGUMENTS` 为空或仅包含空白字符：
+- 默认进入 **Mode 5: Beginner Onboarding**
+- 展示核心命令列表和快速入门指引
+
+### Step 1.2: 关键词匹配
+
+按优先级匹配关键词到 Operation Mode：
+
+```javascript
+const text = $ARGUMENTS.toLowerCase().trim()
+
+const modeMap = [
+  // Mode 7: CLI Reference
+  { patterns: ["cli", "终端", "terminal", "maestro 命令"], mode: 7 },
+  // Mode 6: Skill & Agent Browsing
+  { patterns: ["skill", "agent", "技能", "有哪些 skill", "团队 skill"], mode: 6 },
+  // Mode 5: Beginner Onboarding
+  { patterns: ["新手", "入门", "getting started", "常用命令", "入门指南"], mode: 5 },
+  // Mode 4: Workflow Guide
+  { patterns: ["工作流", "workflow", "怎么开始", "用什么流程", "流程", "pipeline", "管线"], mode: 4 },
+  // Mode 3: Smart Recommendations
+  { patterns: ["下一步", "what's next", "推荐", "继续", "next step", "然后呢"], mode: 3 },
+  // Mode 1: Search (explicit)
+  { patterns: ["搜索", "search", "查找", "find"], mode: 1 },
+]
+
+// Match first pattern hit
+let matchedMode = null
+for (const { patterns, mode } of modeMap) {
+  if (patterns.some(p => text.includes(p))) {
+    matchedMode = mode
+    break
+  }
+}
+```
+
+### Step 1.3: 命令名检测
+
+若未匹配任何模式关键词，检测是否为命令名：
+
+```javascript
+// Strip common prefixes for matching
+const commandPrefixes = ["/", "maestro-", "manage-", "quality-", "spec-", "learn-", "wiki-"]
+
+// Known command names from catalog (without prefix)
+const knownCommands = [
+  "maestro", "analyze", "plan", "execute", "verify", "init", "roadmap",
+  "brainstorm", "quick", "overlay", "amend", "fork", "merge", "collab",
+  "milestone-audit", "milestone-complete", "milestone-release",
+  "composer", "player", "ralph", "ralph-execute", "learn",
+  "impeccable", "ui-codify", "update",
+  "tools-register", "tools-execute",
+  "issue", "issue-discover", "knowhow", "knowhow-capture",
+  "status", "wiki", "harvest", "codebase-refresh", "codebase-rebuild",
+  "review", "auto-test", "test", "debug", "refactor", "sync", "retrospective",
+  "setup", "load", "add", "remove",
+  "retro", "follow", "decompose", "investigate", "second-opinion",
+  "connect", "digest"
+]
+
+const normalizedName = text.replace(/^\//, "").replace(/-/g, "-")
+if (knownCommands.some(cmd => normalizedName === cmd || normalizedName.endsWith("-" + cmd))) {
+  matchedMode = 2  // Mode 2: Documentation
+}
+```
+
+### Step 1.4: 兜底搜索
+
+若以上均未匹配，进入 **Mode 1: Command Search**（模糊搜索）。
+
+### Step 1.5: 上下文检测
+
+对于 Mode 3 (Smart Recommendations)，额外检测项目状态：
+
+```javascript
+// Check project state
+const hasWorkflow = glob.sync(".workflow/state.json").length > 0
+const hasActiveSession = glob.sync(".workflow/active/*/state.json").length > 0
+
+// Read state if exists
+let projectState = null
+if (hasWorkflow) {
+  const state = JSON.parse(readFileSync(".workflow/state.json", "utf8"))
+  projectState = {
+    milestone: state.currentMilestone,
+    phase: state.currentPhase,
+    phaseStatus: state.phaseStatus,
+    hasIssues: glob.sync(".workflow/issues.jsonl").length > 0
+  }
+}
+```
+
+## Output
+
+```
+{
+  mode: number (1-7),
+  query: string,
+  category?: string,
+  commandName?: string,
+  projectState?: { milestone, phase, phaseStatus, hasIssues }
+}
+```
+
+## Next Phase
+
+- Mode 1/2/3/6/7 → [Phase 2: Search & Present](02-search-present.md)
+- Mode 4/5 → [Phase 3: Workflow Guide](03-workflow-guide.md)

package/.agents/skills/maestro-help/phases/02-search-present.md

@@ -0,0 +1,181 @@
+# Phase 2: Search & Present
+
+查询 catalog.json 并格式化呈现结果。覆盖 Mode 1/2/3/6/7。
+
+## Objective
+
+- 根据 Phase 1 输出的 mode 和 query 搜索 catalog
+- 读取 source 文件获取详情（Mode 2）
+- 检测项目状态提供智能推荐（Mode 3）
+- 格式化呈现搜索结果
+
+## Execution
+
+### Mode 1: Command Search
+
+```
+1. Read catalog.json
+2. Search commands[] + cli_commands[]:
+   - Filter by: name contains query (case-insensitive)
+   - OR: description contains query
+   - OR: category matches query
+3. Sort by relevance (exact name match > starts with > contains)
+4. Present top 5 results:
+```
+
+**输出格式**:
+
+```markdown
+找到 {N} 个匹配命令：
+
+**/{command-name}** — {description}
+  分类: {category} | 详细: {source file exists? → "查看详情 →" : "catalog only"}
+
+**/{command-name-2}** — {description}
+  ...
+```
+
+### Mode 2: Command Documentation
+
+```
+1. Locate command in catalog.json commands[] by name
+2. Read the source file (e.g., "../../commands/maestro-analyze.md")
+3. Extract key sections:
+   - <purpose> content
+   - argument-hint
+   - usage examples from <context>
+4. If a guide file references this command, read relevant section
+5. Present structured documentation:
+```
+
+**输出格式**:
+
+```markdown
+## /{command-name}
+
+**用途**: {description}
+
+**参数**: {argument-hint}
+
+**用法**:
+{extracted examples or usage patterns}
+
+**分类**: {category}
+
+**相关 Guide**: {guide file name if applicable}
+```
+
+**Guide 映射**:
+
+| 命令 | Guide 文档 |
+|------|-----------|
+| maestro-analyze/plan/execute/verify | `guide/command-usage-guide.md` (主干管线) |
+| maestro-init/roadmap | `guide/quick-start-guide.md` |
+| maestro-ralph | `guide/maestro-ralph-guide.md` |
+| maestro (协调器) | `guide/maestro-coordinator-guide.md` |
+| manage-* | `guide/command-usage-guide.md` (管理) |
+| quality-* | `guide/command-usage-guide.md` (质量) |
+| delegate | `guide/delegate-async-guide.md` |
+| overlay/amend | `guide/overlay-guide.md` |
+
+### Mode 3: Smart Recommendations
+
+```
+1. Detect project state from Phase 1
+2. Match state to workflow template from catalog.workflows
+3. Present recommendations with WHY:
+```
+
+**状态 → 推荐映射**:
+
+| 当前状态 | 推荐命令 | 原因 |
+|---------|---------|------|
+| 无 .workflow/ | `/maestro-init` | 项目未初始化，需要先创建工作区 |
+| init 完成，无 roadmap | `/maestro-roadmap` | 需要路线图指导后续 Phase |
+| roadmap 完成，phase=pending | `/maestro-analyze` | 准备开始分析阶段 |
+| analyze 完成 | `/maestro-plan` | 分析完成，进入规划 |
+| plan 完成 | `/maestro-execute` | 规划完成，开始执行 |
+| execute 完成 | `/maestro-verify` | 执行完成，验证成果 |
+| verify 有 gaps | `/maestro-analyze --gaps` | 发现差距，重新分析 |
+| verify 通过 | `/quality-review` | 进入质量管线 |
+| quality 全通过 | `/maestro-milestone-audit` | 准备里程碑审计 |
+| 所有 Phase 完成 | `/maestro-milestone-complete` | 里程碑可以关闭 |
+
+### Mode 6: Skill & Agent Browsing
+
+**Skills**:
+```
+1. Read catalog.json skills[]
+2. If category specified: filter by category
+3. Group by category: meta / team / knowledge
+4. Present:
+```
+
+```markdown
+## Skills ({total} 个)
+
+### Meta (2)
+- **workflow-skill-designer** — 设计 orchestrator+phases 工作流 skill
+- **skill-iter-tune** — 迭代 execute-evaluate-improve 调优
+
+### Team (6)
+- **team-coordinate** — 通用团队协调，动态生成 role-specs
+- **team-executor** — 团队执行，恢复会话
+- **team-lifecycle-v4** — 8 角色完整生命周期
+- **team-quality-assurance** — QA 质量保障流水线
+- **team-review** — 多维度代码审查
+- **team-tech-debt** — 技术债务识别和清理
+- **team-testing** — 测试规划和执行
+
+### Knowledge (1)
+- **codify-to-knowhow** — Manifest 驱动的知识资产生成
+```
+
+**Agents**:
+```
+1. Read catalog.json agents[]
+2. Group by category: workflow / team / planning / cli / ui
+3. Present with category headers
+```
+
+### Mode 7: CLI Command Reference
+
+```
+1. Read catalog.json cli_commands[]
+2. Group by category: setup / dashboard / execution / knowledge / config / team / visualization
+3. Present table with command, alias, description:
+```
+
+```markdown
+## CLI 终端命令 (21 个)
+
+### 安装与更新 (setup)
+| 命令 | 别名 | 用途 |
+|------|------|------|
+| `maestro install` | — | 安装 Maestro 资源 |
+| `maestro uninstall` | — | 卸载已安装资源 |
+| `maestro update` | — | 检查/安装最新版本 |
+| `maestro launcher` | — | Claude Code 启动器 |
+
+### 任务执行 (execution)
+| 命令 | 别名 | 用途 |
+|------|------|------|
+| `maestro delegate` | — | 委派任务给 AI 智能体 |
+| `maestro coordinate` | `coord` | 图工作流协调器 |
+| `maestro cli` | — | 运行 CLI 智能体工具 |
+| `maestro run` | — | 执行指定工作流 |
+| `maestro serve` | — | 启动工作流服务器 |
+...
+```
+
+## Error Handling
+
+| 场景 | 处理 |
+|------|------|
+| 搜索无结果 | 模糊匹配最近命令，建议使用 `/maestro-help` 查看全部 |
+| Source 文件不存在 | 仅提供 catalog 描述，标注 "详细信息不可用" |
+| Catalog 读取失败 | 回退到 Glob 扫描 .claude/commands/*.md |
+
+## Output
+
+格式化的搜索/文档/推荐结果，直接展示给用户。