maestro-flow 0.3.45 → 0.3.46

package/.codex/skills/maestro-help/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: maestro-help
+description: Maestro Flow command help system — search, browse, recommend commands, skills, agents, CLI tools, and workflows
+argument-hint: "[search <keyword>|workflow|skills|agents|cli|新手|下一步|<command-name>]"
+allowed-tools: Read, Grep, Glob, AskUserQuestion
+---
+
+<purpose>
+Maestro Flow 帮助系统。根据用户查询提供命令搜索、技能浏览、工作流推荐、CLI 参考和新手引导。
+
+支持 7 种操作模式：
+1. **Command Search** — 搜索命令名、描述、分类
+2. **Command Documentation** — 读取命令源文件，提供详细用法
+3. **Smart Recommendations** — 根据项目状态推荐下一步命令
+4. **Workflow Guide** — 根据任务类型推荐工作流和命令序列
+5. **Beginner Onboarding** — 展示核心命令和入门路径
+6. **Skill & Agent Browsing** — 浏览 Skill 和 Agent 目录
+7. **CLI Reference** — 终端命令参考
+</purpose>
+
+<context>
+
+## Mode Routing
+
+$ARGUMENTS 为空 → Mode 5 (Beginner Onboarding)
+$ARGUMENTS 匹配关键词 → 路由到对应模式：
+
+| 关键词 | Mode | 说明 |
+|--------|------|------|
+| "search", "搜索", "查找" | 1 | Command Search |
+| 命令名 (如 "analyze", "plan") | 2 | Documentation |
+| "下一步", "next", "推荐", "继续" | 3 | Smart Recommendations |
+| "工作流", "workflow", "流程", "管线" | 4 | Workflow Guide |
+| "新手", "入门", "getting started" | 5 | Beginner Onboarding |
+| "skill", "agent", "技能" | 6 | Skill & Agent Browsing |
+| "cli", "终端", "terminal" | 7 | CLI Reference |
+| 其他自由文本 | 1 | Fuzzy Search |
+
+## Data Source
+
+读取同目录下的 `catalog.json` 作为唯一数据源：
+
+| 字段 | 内容 |
+|------|------|
+| `commands[]` | 55 个 slash 命令（name, command, category, description, source） |
+| `skills[]` | 10 个 Skill（name, category, description, source） |
+| `agents[]` | 22 个 Agent（name, category, description） |
+| `cli_commands[]` | 21 个终端命令（command, description, category） |
+| `guide_files[]` | 17 个 Guide 文档索引 |
+| `essential_commands[]` | 10 个核心命令 |
+| `workflows` | 4 大工作流模板（main_pipeline, quick, issue_loop, init_paths） |
+
+## Project State Detection
+
+Mode 3 (Smart Recommendations) 需要检测项目状态：
+1. 检查 `.workflow/state.json` 是否存在
+2. 读取 currentMilestone, currentPhase, phaseStatus
+3. 根据状态映射到推荐命令
+
+</context>
+
+<invariants>
+1. **Catalog First** — 先查 catalog.json，再按需读 source 文件
+2. **Guide 链接** — 深层问题引用 guide/ 文档，告知用户具体文件名
+3. **不执行命令** — 本 skill 只提供信息和推荐，不执行 maestro 命令
+4. **精确匹配** — 搜索支持命令名（不含前缀）、分类名、关键词模糊匹配
+5. **上下文感知** — 检查 .workflow/ 状态调整推荐
+</invariants>
+
+<execution>
+
+### Mode 1: Command Search
+
+1. 读取 `catalog.json` 的 `commands[]` + `cli_commands[]`
+2. 按 name、description、category 过滤，匹配 $ARGUMENTS 中的搜索词
+3. 按 relevance 排序：exact match > starts with > contains
+4. 展示 top 5 结果：
+
+```
+找到 N 个匹配命令：
+
+/maestro-analyze — 多维度分析
+  分类: pipeline | 查看详情 →
+
+/maestro-plan — 任务规划
+  分类: pipeline | 查看详情 →
+...
+```
+
+### Mode 2: Command Documentation
+
+1. 在 `catalog.json` commands[] 中定位命令
+2. 通过 `source` 路径读取命令源文件（如 `../../commands/maestro-analyze.md`）
+3. 提取 `<purpose>`、`argument-hint`、`<context>` 中的用法示例
+4. 如有对应 guide 文档，读取相关段落
+
+Guide 映射：
+- analyze/plan/execute/verify → `guide/command-usage-guide.md`
+- init/roadmap → `guide/quick-start-guide.md`
+- ralph → `guide/maestro-ralph-guide.md`
+- maestro (协调器) → `guide/maestro-coordinator-guide.md`
+- delegate → `guide/delegate-async-guide.md`
+- overlay/amend → `guide/overlay-guide.md`
+
+### Mode 3: Smart Recommendations
+
+检测项目状态 → 推荐下一步命令：
+
+| 当前状态 | 推荐命令 | 原因 |
+|---------|---------|------|
+| 无 .workflow/ | `/maestro-init` | 项目未初始化 |
+| init 完成，无 roadmap | `/maestro-roadmap` | 需要路线图 |
+| roadmap 完成 | `/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 4: Workflow Guide
+
+根据任务类型推荐工作流和命令序列：
+
+**新项目**:
+- 最简: `/maestro-init` → `/maestro-roadmap "目标" -y`
+- 头脑风暴: `/maestro-brainstorm "描述"` → `/maestro-init --from-brainstorm ANL-xxx`
+- 完整规范: `/maestro-init` → `/maestro-spec-generate`
+
+**功能开发**:
+- 标准: analyze → plan → execute → verify
+- 快速: `/maestro-quick "功能描述"`
+- 全自动: `/maestro -y "功能描述"`
+
+**Bug 修复**:
+- 快速: `/maestro-quick "Bug 描述"`
+- Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
+
+**代码审查**:
+- `/quality-review` → `/quality-auto-test` → `/quality-test`
+- 失败循环: `/quality-debug` → `/maestro-plan --gaps` → `/maestro-execute`
+
+### Mode 5: Beginner Onboarding
+
+从 `catalog.json essential_commands[]` 读取核心命令：
+
+| 命令 | 用途 | 何时使用 |
+|------|------|---------|
+| `/maestro` | 智能协调器 | 不确定用哪个命令时 |
+| `/maestro-init` | 初始化项目 | 首次使用 |
+| `/maestro-roadmap` | 路线图 | 初始化后规划 |
+| `/maestro-analyze` | 分析 | 开始 Phase 分析 |
+| `/maestro-plan` | 规划 | 分析完成后 |
+| `/maestro-execute` | 执行 | 计划完成后 |
+| `/maestro-verify` | 验证 | 执行完成后 |
+| `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
+| `/quality-review` | 代码审查 | 执行后质量检查 |
+| `/manage-issue` | Issue 管理 | 追踪和解决 Bug |
+
+快速上手路径：
+1. `maestro install --force`
+2. `/maestro-init`
+3. `/maestro "任务描述"` — 自动选择最佳工作流
+
+### Mode 6: Skill & Agent Browsing
+
+**Skills** — 从 `catalog.json` skills[] 读取，按分类展示：
+
+- **Meta (2)**: workflow-skill-designer, skill-iter-tune
+- **Team (6)**: team-coordinate, team-executor, team-lifecycle-v4, team-quality-assurance, team-review, team-tech-debt, team-testing
+- **Knowledge (1)**: codify-to-knowhow
+
+**Agents** — 从 `catalog.json` agents[] 读取，按分类展示：
+
+- **Workflow (15)**: analyzer, planner, executor, verifier, reviewer, debugger, research-agent, roadmapper, plan-checker, phase-researcher, project-researcher, research-synthesizer, codebase-mapper, nyquist-auditor, integration-checker, external-researcher, collab-planner
+- **Team (2)**: supervisor, worker
+- **Planning (1)**: conceptual-planning-agent
+- **CLI (1)**: cli-explore-agent
+- **UI (1)**: ui-design-agent
+
+### Mode 7: CLI Reference
+
+从 `catalog.json` cli_commands[] 读取，按分类展示：
+
+| 分类 | 命令 |
+|------|------|
+| Setup | install, uninstall, update, launcher |
+| Dashboard | view, stop |
+| Execution | delegate, coordinate (coord), cli, run, serve |
+| Knowledge | spec, wiki, knowhow (kh) |
+| Config | hooks, overlay, ext, tool |
+| Team | collab (team), agent-msg (msg) |
+| Visualization | brainstorm-visualize (bv) |
+
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | catalog.json 读取失败 | 回退到 Glob 扫描 .claude/commands/*.md |
+| W001 | warning | 搜索无结果 | 模糊匹配最近命令，建议查看全部 |
+| W002 | warning | Source 文件不存在 | 仅展示 catalog 描述 |
+| W003 | warning | 项目未初始化 | 推荐先运行 /maestro-init |
+</error_codes>
+
+<success_criteria>
+- [ ] 正确路由到对应操作模式
+- [ ] 搜索结果包含命令名、描述、分类
+- [ ] 文档模式展示了命令源文件的关键内容
+- [ ] 推荐模式基于项目状态提供了合理的下一步建议
+- [ ] 工作流推荐包含具体命令序列
+</success_criteria>

package/.codex/skills/maestro-help/catalog.json

@@ -0,0 +1,182 @@
+{
+  "_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-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-ui-design", "command": "/maestro-ui-design", "category": "ui", "description": "UI 设计 — 设计系统原型和 Token 管理", "source": "../../commands/maestro-ui-design.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": "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/.codex/skills/maestro-roadmap/SKILL.md

@@ -220,7 +220,7 @@ Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
 1. **Input parsing**: Parse `{requirementArg}` -- direct text or `@file` reference
 2. **Brainstorm import**: If `--from-brainstorm`, read `guidance-specification.md` for enriched context
 3. **Codebase detection**: Check for source files; if found, add context to analysis/research prompts
-4. **Load project specs**: Read `.workflow/specs/` for constraint awareness
+4. **Load project specs**: Run `maestro spec load --category arch` for constraint awareness and discoverable knowhow tools
 
 **Light mode specific**:
 5. **Uncertainty assessment**:

package/.codex/skills/maestro-tools-register/SKILL.md

@@ -8,11 +8,12 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 <purpose>
 Codify reusable business processes as knowhow documents with `tool: true` in YAML frontmatter. Once registered, entries are auto-discovered by downstream agents via `spec load --category` — plan agents pick up design/architecture flows, test agents pick up verification methods, coding agents pick up execution steps.
 
-Three modes:
+Four modes:
 
 1. **Extract** — Pull reusable processes from conversations/code/docs
 2. **Generate** — Create new tool definitions from user description
 3. **Optimize** — Improve existing tool spec steps, structure, clarity
+4. **Promote** — Convert existing knowhow document to tool (add `tool: true` + category in place)
 
 Short processes (<10 steps) inline; long processes (>=10 steps or with code examples) use ref mode with knowhow detail doc (RCP-/DOC-).
 </purpose>
@@ -25,6 +26,8 @@ $maestro-tools-register "extract OAuth PKCE token exchange flow from src/auth/"
 $maestro-tools-register "generate Stripe webhook idempotency verification"
 $maestro-tools-register "generate E2E checkout flow with payment gateway mock setup"
 $maestro-tools-register "optimize e2e-checkout tool"
+$maestro-tools-register "promote RCP-db-migration-rollback as test tool"
+$maestro-tools-register "promote knowhow-auth-api to coding tool"
 ```
 
 **Tool registration**: Creates knowhow documents in `knowhow/` folder with `tool: true` in YAML frontmatter. Tools are auto-discovered by `spec load` based on category + tool flag.
@@ -50,6 +53,7 @@ Step content...
 Parse $ARGUMENTS to determine mode:
 - Contains "extract" → extract mode
 - Contains "optimize/improve" → optimize mode
+- Contains "promote" or references existing knowhow doc (path/ID) → promote mode
 - Other → generate mode
 - Empty → ask user with AskUserQuestion
 
@@ -67,16 +71,34 @@ Parse $ARGUMENTS to determine mode:
 - Load existing tool: `maestro spec load --category coding --keyword <name>`
 - Analyze improvement points (step splitting, prerequisites, error handling)
 
+**Promote mode** (existing knowhow → tool):
+- Locate document: `maestro wiki list --keyword <name>` or by path in `.workflow/knowhow/`
+- Read document, verify it contains actionable steps (numbered list or ## Steps section)
+- If no actionable steps, suggest extract mode instead
+- Determine category (Step 3) and summary ("Use when ...")
+- Update frontmatter via: `maestro wiki update <id> --frontmatter '{"tool": true, "category": "<cat>", "summary": "<summary>"}'`
+- Do NOT recreate the document — modify in place
+
 **For all modes** — identify the usage timing: when should an agent or user invoke this tool? This becomes the first line of the entry description (see Step 5).
 
 ### Step 3: Determine Category
 
-Infer applicable category from context, or ask user:
-- coding — execution tools (build, deploy, integrate)
-- test — testing tools (test flows, verification steps)
-- review — review tools (checklists, audit standards)
-- arch — planning tools (design flows, analysis steps)
-- debug — analysis tools (diagnostic flows, investigation steps)
+**Core principle**: `category` = **who consumes this tool** (which agent type discovers and uses it), not what the content is about.
+
+| Category | Consumer Agent | Decision Question | Signal Words |
+|---|---|---|---|
+| `coding` | code-developer, workflow-executor | 开发者实现时需要这个流程吗？ | build, deploy, integrate, configure, setup, migrate, api-contract |
+| `test` | tdd-developer, test-fix-agent | 测试者验证行为时需要这个流程吗？ | verify, validate, assert, e2e, regression, coverage, idempotency |
+| `review` | workflow-reviewer | 审查者需要这个作为 checklist 吗？ | audit, checklist, compliance, quality-gate, standard |
+| `arch` | workflow-planner | 规划者设计方案时需要这个吗？ | design, architecture, decompose, trade-off, migration-strategy |
+| `debug` | debug-explore-agent | 调试者排查问题时需要这个吗？ | diagnose, trace, investigate, root-cause, reproduce |
+
+**Multi-consumer split**: If content serves multiple consumers (e.g., API doc for both dev and test), split into separate documents:
+- API contract (what endpoints look like) → `category: coding` (AST-*, tool: false)
+- API verification steps (how to test) → `category: test` (RCP-*, tool: true)
+- Ask user when ambiguous: "This tool content serves both developers and testers. Split into separate documents?"
+
+**Ambiguous cases**: Choose the **primary consumer** — the agent that would fail without this knowledge.
 
 ### Step 4: Decide Inline vs Ref
 

package/.codex/skills/manage-knowhow-capture/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>
-Capture reusable knowledge into `.workflow/knowhow/`. Six content types: `session` (full session recovery), `template` (code/config pattern), `recipe` (step-by-step guide), `reference` (external doc summary), `decision` (ADR), `tip` (quick note). Auto-detects type or asks user.
+Capture reusable knowledge into `.workflow/knowhow/`. Nine content types: `session` (full session recovery), `template` (code/config pattern), `recipe` (step-by-step guide), `reference` (external doc summary), `decision` (ADR), `tip` (quick note), `asset` (API contract, data model, etc.), `blueprint` (architecture design with code paths), `document` (general long-form). Auto-detects type or asks user.
 </purpose>
 
 <context>
@@ -22,13 +22,16 @@ $manage-knowhow-capture "reference Stripe API --source https://docs.stripe.com/a
 $manage-knowhow-capture "decision Use PostgreSQL over MongoDB --status accepted"
 ```
 
-**Types**: `compact` | `template` | `recipe` | `reference` | `decision` | `tip`
+**Types**: `compact` | `template` | `recipe` | `reference` | `decision` | `tip` | `asset` | `blueprint` | `document`
 
 **Flags**:
 - `--lang <lang>` — Language for templates (typescript, python, bash, yaml, ...)
 - `--source <url>` — Source URL for references
 - `--tag tag1,tag2` — Categorization tags
 - `--title <title>` — Explicit title
+- `--asset-type <type>` — Asset subtype (api-contract, data-model, prompt, config, ...)
+- `--code-paths <paths>` — Related source paths for asset/blueprint (comma-separated)
+- `--category <cat>` — Spec category for agent discovery (coding, arch, test, debug, review, learning)
 </context>
 
 <execution>
@@ -49,6 +52,9 @@ Parse first token as type. If absent or ambiguous, ask user via AskUserQuestion.
 | `reference`, `ref`, `参考` | reference |
 | `decision`, `dcs`, `决策` | decision |
 | `tip`, `note`, `记录` | tip |
+| `asset`, `ast`, `资产`, `契约` | asset |
+| `blueprint`, `blp`, `蓝图` | blueprint |
+| `document`, `doc`, `文档` | document |
 
 ### Step 3: Capture Content by Type
 
@@ -70,6 +76,15 @@ Prompt for or extract: context, decision, alternatives (at least 2), rationale,
 **tip** (TIP-{YYYYMMDD}-{HHMM}.md):
 Content from remaining arguments. Auto-detect context from recent conversation files. Sections: Content, Context, Tags, Timestamp.
 
+**asset** (AST-{YYYYMMDD}-{HHMM}.md):
+Prompt for or extract: asset subtype (`--asset-type`), related code paths (`--code-paths`), category (`--category`). Sections: Overview, Structure (tables/schemas), Usage, Related Code Paths. Common asset subtypes: `api-contract`, `data-model`, `prompt`, `config`, `ui-prototype`.
+
+**blueprint** (BLP-{YYYYMMDD}-{HHMM}.md):
+Prompt for or extract: system scope, code paths (`--code-paths`), category (`--category`). Sections: Overview, Components, Interactions, Code Paths, Constraints, Trade-offs.
+
+**document** (DOC-{YYYYMMDD}-{HHMM}.md):
+General long-form fallback. No specific structure enforced.
+
 ### Step 4: Write File
 
 Write to `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter:
@@ -82,7 +97,7 @@ category: {type}
 created: {ISO timestamp}
 tags: [{tags}]
 ```
-Plus type-specific: `lang` (template), `source` (reference), `status` (decision).
+Plus type-specific: `lang` (template), `source` (reference), `status` (decision), `assetType` + `codePaths` (asset), `codePaths` (blueprint). `category` written when `--category` provided.
 
 ### Step 5: Confirm
 

package/.codex/skills/quality-debug/SKILL.md

@@ -184,7 +184,8 @@ mkdir -p {sessionFolder}
 2b. **Load codebase + wiki context** (optional, informs hypothesis generation):
    - If `.workflow/codebase/ARCHITECTURE.md` exists: read module boundaries to scope impact analysis
    - Run `maestro wiki search "<symptom keywords>" --json 2>/dev/null`; if results: check for prior investigations on similar issues
-   - Both are optional — proceed without if unavailable
+   - Run `maestro spec load --category debug --keyword "<symptom keywords>"`; if tools found: extract known issues, workarounds, and root-cause notes to inform hypotheses
+   - All are optional — proceed without if unavailable
 
 3. **Symptom collection**:
 

package/.codex/skills/quality-review/SKILL.md

@@ -184,7 +184,7 @@ Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
 
 If `--dimensions` flag provided, override with explicit list.
 
-6. **Specs loading**: Read `.workflow/specs/` for project conventions (unless `--skip-specs`)
+6. **Specs loading**: Run `maestro spec load --category review` to load review standards, checklists, AND discoverable knowhow tools (unless `--skip-specs`)
 7. **CSV generation**: One row per dimension + one aggregation row
 
 **Wave computation**: Simple 2-wave -- all dimension tasks = wave 1, aggregation = wave 2.

package/.codex/skills/quality-test/SKILL.md

@@ -163,7 +163,17 @@ Record in `uat.md` under `## Smoke Tests`. If any fails: **E003** — abort, sug
 
 Read from target directory: `verification.json`, `validation.json`, `index.json`, `plan.json`, `.summaries/TASK-*.md`. Build testable list from user-observable outcomes.
 
-### Step 4.5: Load Quality Context (Cross-Artifact Integration)
+### Step 4.5: Load Test Tools (Knowhow Discovery)
+
+Load registered test tools to supplement verification-based scenarios:
+
+```bash
+maestro spec load --category test --keyword <feature>
+```
+
+If tools are found, extract their steps as additional test scenarios marked `source: "tool"`. Tool steps map to UAT scenarios: each numbered step becomes a test with its assertion as `expected` behavior. This enables tools registered via `/maestro-tools-register` to drive UAT verification.
+
+### Step 4.6: Load Quality Context (Cross-Artifact Integration)
 
 Query `state.json.artifacts[]` for all artifacts matching current phase and milestone: