maestro-flow 0.3.45 → 0.3.47

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

@@ -207,9 +207,11 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 4. **Build tasks.csv**: For each pending task per wave, read `.task/TASK-{NNN}.json` and extract: title, description, scope (from files), convergence.criteria, hints, execution_directives. Set `deps` from task dependency, `context_from` = deps, `wave` from plan.json.
 
-5. **Load project specs**: Read `.workflow/specs/` for coding conventions and architecture constraints (passed to all agents)
+5. **Load project specs + tools**: Run `maestro spec load --category coding` to load coding conventions, architecture constraints, AND discoverable knowhow tools (passed to all agents)
 
-6. **Load codebase + wiki context** (optional, passed to all agents):
+6. **Load UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro spec load --category ui` and include in agent context.
+
+7. **Load codebase + wiki context** (optional, passed to all agents):
    - If `.workflow/codebase/ARCHITECTURE.md` exists: read and include as `codebase_context` in agent instructions
    - Run `maestro wiki search "<phase keywords>" --json 2>/dev/null`; if results: include top 5 entries as `wiki_context`
    - Both are optional — proceed without if unavailable

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-impeccable/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: maestro-impeccable
+description: Production-grade UI design with knowhow accumulation -- 23 commands for build, evaluate, refine, enhance, fix
+argument-hint: "[craft|shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target] [--skip-harvest] [-y]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+<purpose>
+Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
+After each command, automatically harvests design knowledge to `.workflow/knowhow/` (category: ui) for cross-session accumulation.
+
+Replaces the standalone impeccable skill. 23 commands covering the full design lifecycle.
+</purpose>
+
+<context>
+$ARGUMENTS -- sub-command + target + optional flags.
+
+**Sub-commands** (23):
+
+| Category | Commands |
+|----------|----------|
+| Build | craft, shape, teach, document, extract |
+| Evaluate | critique, audit |
+| Refine | polish, bolder, quieter, distill, harden, onboard |
+| Enhance | animate, colorize, typeset, layout, delight, overdrive |
+| Fix | clarify, adapt, optimize |
+| Iterate | live |
+
+**Flags:**
+- `--skip-harvest` -- Execute command without knowhow capture
+- `-y` -- Auto-confirm where the skill allows
+</context>
+
+<execution>
+
+## Setup
+
+Before any design work:
+
+1. Load context (PRODUCT.md / DESIGN.md) via spec system:
+   ```bash
+   maestro spec load --category ui
+   ```
+   This surfaces all design context (product + visual) from `.workflow/specs/ui-conventions.md`.
+
+   If specs are not initialized, fall back to the legacy loader:
+   ```bash
+   maestro impeccable load-context
+   ```
+   The loader searches `.workflow/impeccable/` first, then the project root, then `.agents/context/` and `docs/`.
+   PRODUCT.md and DESIGN.md are stored at `.workflow/impeccable/`.
+
+2. Identify register (brand vs product) and load matching reference from `~/.maestro/workflows/impeccable/brand.md` or `product.md`.
+3. If sub-command invoked, load its reference file from `~/.maestro/workflows/impeccable/{command}.md`.
+
+If PRODUCT.md missing → run `teach` first, then resume original task.
+
+## Command Execution
+
+Route by first argument:
+1. **Matches command** → load `~/.maestro/workflows/impeccable/{command}.md`, follow instructions
+2. **No argument** → show command menu grouped by category
+3. **No match** → general design invocation with full argument as context
+
+## Harvest (Post-Execution)
+
+After command completes (except `live`), unless `--skip-harvest`:
+
+| Command | Knowhow Type | Prefix |
+|---------|-------------|--------|
+| craft | decision + asset | DCS- + AST- |
+| shape | decision | DCS- |
+| teach | reference | REF- |
+| document, extract | asset | AST- |
+| critique, audit, polish, harden, onboard, clarify, adapt, optimize | tip | TIP- |
+| colorize, typeset, layout, animate, bolder, quieter, distill, delight, overdrive | decision | DCS- |
+
+Write knowhow with `category: ui`. For DCS-/AST- types, also create spec index:
+```bash
+maestro spec add ui "<title>" "<summary>" --keywords impeccable,<cmd>,... --ref knowhow/<file>
+```
+
+</execution>
+
+<shared_design_laws>
+
+- **Color**: OKLCH only. Never #000/#fff. Pick color strategy first (Restrained → Committed → Full palette → Drenched).
+- **Theme**: Write physical scene sentence before choosing dark/light.
+- **Typography**: Body 65-75ch. Hierarchy via scale + weight (>=1.25 ratio).
+- **Layout**: Vary spacing for rhythm. Cards only when truly best. No nested cards.
+- **Motion**: No CSS layout animations. Ease-out exponential curves.
+- **Bans**: Side-stripe borders, gradient text, glassmorphism default, hero-metric template, identical card grids, modal as first thought.
+- **Copy**: Every word earns its place. No em dashes.
+- **AI slop test**: Two-altitude category-reflex check.
+
+</shared_design_laws>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | error | Invalid sub-command |
+| E002 | error | No intent or target specified |
+| W001 | warning | Harvest failed (command still succeeded) |
+| W002 | warning | PRODUCT.md missing, auto-triggering teach |
+</error_codes>
+
+<success_criteria>
+- [ ] Sub-command recognized and reference file loaded
+- [ ] Context loaded from .workflow/impeccable/ (PRODUCT.md, register identified)
+- [ ] Design changes applied to target files
+- [ ] Knowhow entry created in .workflow/knowhow/ with category: ui (unless --skip-harvest or live)
+- [ ] Spec index entry created for DCS-/AST- types
+</success_criteria>