maestro-flow 0.3.48 → 0.3.49

package/.claude/commands/maestro-ui-craft.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-ui-craft
 description: Chain maestro-impeccable commands with intelligent routing and quality gate loops for automated UI production
-argument-hint: "<intent|target> [--chain build|improve|enhance|harden|live] [--enhance <cmd>] [--threshold <score>] [--max-loops <n>] [-y] [-c]"
+argument-hint: "<intent|target> [--chain build|improve|enhance|harden|live] [--enhance <cmd>] [--threshold <score>] [--max-loops <n>] [--skip-design-explore] [--skip-design] [--styles <N>] [--stack <stack>] [-y] [-c]"
 allowed-tools:
   - Read
   - Write
@@ -22,11 +22,20 @@ Core innovation: critique/audit scores drive automatic command selection and ite
 Impeccable has 23 commands across 6 categories — this command chains them into automated pipelines
 with quality gates that loop until design quality meets the threshold.
 
+Includes integrated design-explore: multi-variant design system generation (via ui-search BM25 engine + CSV knowledge base),
+HTML prototype rendering for visual comparison, interactive user review with mix support,
+and automatic bridge to impeccable's DESIGN.md format. Replaces the former maestro-ui-design command.
+
 Prerequisite: maestro-impeccable skill available (auto-discovered by harness).
 
 Session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
 </purpose>
 
+<deferred_reading>
+- [impeccable harvest workflow](~/.maestro/workflows/impeccable.md) — read after command execution for harvest logic
+- [design stage workflow](~/.maestro/workflows/impeccable/design.md) — read when S_DESIGN_EXPLORE or S_BRIDGE state entered
+</deferred_reading>
+
 <invariants>
 1. **Session before execution** — status.json created before any chain step runs
 2. **All steps via Skill** — every impeccable command dispatched through `Skill({ skill: "maestro-impeccable" })`
@@ -46,6 +55,9 @@ $ARGUMENTS — intent description or target path, with optional flags.
 - `--max-loops <n>` — Maximum quality gate iterations (default: 3)
 - `-c` / `--continue` — Resume previous ui-craft session
 - `-y` — Auto mode: auto-select at ambiguous routing, skip confirmations where impeccable allows
+- `--skip-design-explore` / `--skip-design` — Skip design-explore (prototype comparison) and bridge (use existing DESIGN.md or full shape interview)
+- `--styles <N>` — Number of design system variants to generate and compare (2-5, default 3). Only used in build chain design-explore step
+- `--stack <stack>` — Tech stack for supplementary guidelines (default: html-tailwind). Passed to ui-search
 </context>
 
 <chains>
@@ -54,13 +66,14 @@ $ARGUMENTS — intent description or target path, with optional flags.
 
 | Chain | Sequence | Gate Condition |
 |-------|----------|----------------|
-| **build** | teach? → shape → craft → **critique** → [refine loop] → audit → polish | critique ≥ threshold AND P0 == 0 |
+| **build** | teach? → **design_explore?** → shape → craft → **critique** → [refine loop] → audit → polish | critique ≥ threshold AND P0 == 0 |
 | **improve** | **critique** → [refine loop] → polish → audit | critique ≥ threshold AND P0 == 0 |
 | **enhance** | {cmd} → **critique** → polish (if needed) | critique ≥ threshold |
 | **harden** | harden → **audit** → polish | audit ≥ threshold×0.5 |
 | **live** | live | — (interactive, no gate) |
 
 - `teach?` — conditional: only if PRODUCT.md missing/placeholder
+- `design_explore?` — conditional: only if DESIGN.md missing AND `--skip-design-explore` not set. Delegates to `Skill("maestro-impeccable", "explore")` which handles variant generation, prototype rendering, visual comparison, user selection/mix, AND bridge to DESIGN.md internally
 - `[refine loop]` — quality gate loop: extract suggested commands from critique → execute → re-critique
 
 ### Intent → Chain Routing
@@ -68,6 +81,7 @@ $ARGUMENTS — intent description or target path, with optional flags.
 | Intent Pattern | Chain |
 |---------------|-------|
 | 新建, create, build, new, 从零, landing, feature, page | build |
+| 设计, design, 风格, style, 设计系统, design system, 视觉, theme | build |
 | 改进, improve, fix, 优化, iterate, better, 迭代 | improve |
 | 动画, 颜色, 排版, animate, color, type, bold, delight, enhance | enhance |
 | 生产, production, harden, 上线, ship, edge case, i18n | harden |
@@ -84,6 +98,7 @@ S_PARSE      — 解析参数、意图分类、chain 选择                PERSI
 S_RESUME     — 扫描已有 ui-craft session、恢复执行           PERSIST: —
 S_SETUP      — 加载 context、检查 PRODUCT.md                PERSIST: —
 S_CREATE     — 创建 session + status.json                    PERSIST: session (全量)
+S_DESIGN_EXPLORE — 委托 impeccable explore：多变体生成、原型对比、选型/混搭、自动 bridge 到 DESIGN.md  PERSIST: explore_completed, design_md_path
 S_CHAIN      — 按序执行 chain 步骤                           PERSIST: step progress, executed commands
 S_GATE       — 质量门控：解析评分、决策                       PERSIST: scores, loop count
 S_REFINE     — 执行自动选取的 refine 命令                    PERSIST: refine commands, loop state
@@ -109,10 +124,16 @@ S_CREATE:
   → S_CHAIN      DO: A_CREATE_SESSION
 
 S_CHAIN:
+  → S_DESIGN_EXPLORE  WHEN: current step is 'design_explore' AND DESIGN.md missing AND --skip-design-explore not set AND --skip-design not set
   → S_GATE       WHEN: current step is gate command (critique/audit)
+  → S_CHAIN      WHEN: step is design_explore but skip conditions met → advance
   → S_CHAIN      WHEN: step is normal command → execute → advance
   → S_REPORT     WHEN: all steps complete
 
+S_DESIGN_EXPLORE:
+  → S_CHAIN      WHEN: explore completed (DESIGN.md produced) → advance to shape
+  → S_CHAIN      WHEN: explore failed → W004 → advance to shape (full interview fallback)
+
 S_GATE:
   → S_CHAIN      WHEN: PASS (score ≥ threshold AND P0 == 0) → advance to next step
   → S_REFINE     WHEN: FAIL (score < threshold OR P0 > 0)
@@ -160,6 +181,15 @@ S_REPORT:
    ```
 3. Write status.json before executing any step
 
+### A_DESIGN_EXPLORE
+
+Delegate to impeccable explore as a black-box command. The explore command internally handles:
+variant generation, prototype rendering, visual comparison, user review, mix protocol, rejected variant harvest, bridge to DESIGN.md, and spec registration.
+
+1. Execute: `Skill({ skill: "maestro-impeccable", args: "explore --styles {styles_count}" })`
+2. On completion: verify `.workflow/impeccable/DESIGN.md` exists
+3. Update status.json: `explore_completed: true`, `design_md_path`
+
 ### A_FINAL_REPORT
 
 1. Read critique trend if available (impeccable's critique persists snapshots automatically)
@@ -205,11 +235,26 @@ Execute via: `Skill({ skill: "maestro-impeccable", args: "{command} {target}" })
 
 After each step: update status.json `current_step` and step `status`.
 
-**Rules:**
+**Step-specific logic:**
+
+### 4a. Design-explore step (build chain only)
+
+When current step is `design_explore`:
+
+1. Check if `.workflow/impeccable/DESIGN.md` already exists → skip, advance to shape
+2. Check if `--skip-design-explore` or `--skip-design` is set → skip, advance to shape
+3. Otherwise → execute A_DESIGN_EXPLORE:
+   - `Skill({ skill: "maestro-impeccable", args: "explore --styles {styles_count}" })`
+   - explore handles everything internally: variant generation, prototype rendering, visual comparison, user selection/mix, bridge to DESIGN.md, spec registration
+4. On completion → verify DESIGN.md exists, advance to shape
+5. On failure → W004, advance to shape (full interview fallback, no DESIGN.md)
+
+### 4c. Normal steps
+
 - `teach`, `shape`, `craft` are interactive — do NOT suppress their user gates
 - After `teach` completes → re-run context loader for fresh PRODUCT.md
 - After `craft` completes → the build exists, ready for evaluation
-- Gate steps (critique/audit) → transition to quality gate logic
+- Gate steps (critique/audit) → transition to quality gate logic (Section 5)
 
 ## 5. Quality Gate
 
@@ -335,6 +380,8 @@ These are structural/interactive — never picked by the refine loop:
 | overdrive | Requires explicit user vision |
 | critique | Gate command, not a fix |
 | audit | Gate command, not a fix |
+| design | Design system generation (setup) |
+| bridge | Format bridging (setup) |
 
 </quality_gate_routing>
 
@@ -349,6 +396,11 @@ These are structural/interactive — never picked by the refine loop:
 | W001 | warning | PRODUCT.md missing, prepending teach to chain |
 | W002 | warning | Max quality gate loops exceeded, forcing continue |
 | W003 | warning | Could not parse score from critique/audit output |
+| E006 | error | Python 3 not available for design system generation |
+| E007 | error | ui-search scripts not found at expected path |
+| W004 | warning | Design system generation failed, skipping design+bridge, falling back to shape full interview |
+| W005 | warning | Bridge transformation failed, continuing without DESIGN.md |
+| W008 | warning | Node.js not available for prototype rendering, falling back to text-only variant comparison |
 </error_codes>
 
 <success_criteria>

package/.claude/commands/maestro.md

@@ -155,7 +155,7 @@ S_FALLBACK:
 | maestro-analyze | `-y` | Skip scoping, auto-deepen |
 | maestro-brainstorm | `-y` | Skip questions, use defaults |
 | maestro-roadmap | `-y` | Skip questions (create/revise/review) |
-| maestro-ui-design | `-y` | Skip selection, pick top variant |
+| maestro-ui-craft | `-y` | Auto-select design variant + skip confirmations |
 | maestro-plan | `-y` | Skip confirmations and clarification |
 | maestro-execute | `-y` | Skip confirmations, blocked auto-continue |
 | quality-auto-test | `-y` | Skip plan confirmation |

package/.claude/commands/manage-issue-discover.md

@@ -48,6 +48,10 @@ $ARGUMENTS -- optional. Parse first token to determine mode.
 **State files:**
 - `.workflow/issues/issues.jsonl` -- issues appended here
 - `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
+
+### Pre-load specs
+1. **Debug specs**: Run `maestro spec load --category debug` to load known antipatterns, root causes, and gotchas. Informs discovery perspectives with prior findings.
+2. Optional — proceed without if unavailable.
 </context>
 
 <execution>

package/.claude/commands/quality-refactor.md

@@ -41,6 +41,9 @@ If not provided, prompt user for scope.
 <execution>
 Follow '~/.maestro/workflows/refactor.md' completely.
 
+**Knowledge inquiry on completion:**
+After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes, persist via `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2>")`.
+
 **Next-step routing on completion:**
 - All tests pass → `/quality-sync` (update codebase docs)
 - Test failures after refactor → `/quality-debug {scope}`

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

@@ -27,7 +27,7 @@
     {"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-craft", "command": "/maestro-ui-craft", "category": "ui", "description": "UI 生产 — 设计系统生成 + impeccable 链式编排 + 质量门控", "source": "../../commands/maestro-ui-craft.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"},

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

@@ -62,7 +62,7 @@ const knownCommands = [
   "brainstorm", "quick", "overlay", "amend", "fork", "merge", "collab",
   "milestone-audit", "milestone-complete", "milestone-release",
   "composer", "player", "ralph", "ralph-execute", "learn",
-  "ui-design", "ui-codify", "update",
+  "ui-craft", "ui-codify", "update",
   "tools-register", "tools-execute",
   "issue", "issue-discover", "knowhow", "knowhow-capture",
   "status", "wiki", "harvest", "codebase-refresh", "codebase-rebuild",

package/.claude/skills/maestro-impeccable/SKILL.md

@@ -3,7 +3,7 @@ name: maestro-impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
 version: 1.0.0
 user-invocable: true
-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]"
+argument-hint: "[craft|shape|explore · 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] [--styles N]"
 allowed-tools:
   - Bash(maestro impeccable *)
   - Write
@@ -108,6 +108,7 @@ See [~/.maestro/workflows/impeccable/brand.md](~/.maestro/workflows/impeccable/b
 | `teach` | Build | Set up PRODUCT.md and DESIGN.md | [~/.maestro/workflows/impeccable/teach.md](~/.maestro/workflows/impeccable/teach.md) |
 | `document` | Build | Generate DESIGN.md from code | [~/.maestro/workflows/impeccable/document.md](~/.maestro/workflows/impeccable/document.md) |
 | `extract [target]` | Build | Pull tokens/components into design system | [~/.maestro/workflows/impeccable/extract.md](~/.maestro/workflows/impeccable/extract.md) |
+| `explore [--styles N]` | Build | Multi-style comparison: generate variants, render prototypes, visual compare, select/mix | [~/.maestro/workflows/impeccable/explore.md](~/.maestro/workflows/impeccable/explore.md) |
 | `critique [target]` | Evaluate | UX review with heuristic scoring | [~/.maestro/workflows/impeccable/critique.md](~/.maestro/workflows/impeccable/critique.md) |
 | `audit [target]` | Evaluate | Technical quality checks | [~/.maestro/workflows/impeccable/audit.md](~/.maestro/workflows/impeccable/audit.md) |
 | `polish [target]` | Refine | Final quality pass | [~/.maestro/workflows/impeccable/polish.md](~/.maestro/workflows/impeccable/polish.md) |
@@ -146,6 +147,7 @@ After every command execution (except `live`), harvest design decisions into `.w
 | teach | reference | REF- | Brand/user/principles from PRODUCT.md |
 | document | asset | AST- | Token system from DESIGN.md YAML |
 | extract | asset | AST- | Design system patterns |
+| explore | decision + asset | DCS- + AST- | Style selection rationale + design tokens |
 | critique | tip | TIP- | Scores + P0/P1 findings |
 | audit | tip | TIP- | 5-dimension scores |
 | polish | tip | TIP- | Polish points |

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

@@ -261,7 +261,7 @@ Read `.workflow/state.json` and route by condition:
 | `status` | `manage-status` |
 | `init` | `maestro-init` |
 | `analyze` | `maestro-analyze {phase}` |
-| `ui_design` | `maestro-ui-design {phase}` |
+| `ui_design` | `maestro-ui-craft "{phase}" --chain build` |
 | `plan` | `maestro-plan {phase}` |
 | `execute` | `maestro-execute {phase}` |
 | `verify` | `maestro-verify {phase}` |
@@ -314,7 +314,7 @@ Read `.workflow/state.json` and route by condition:
 | `deploy` | maestro-verify → maestro-milestone-release |
 | `spec-driven` | maestro-init → [B] maestro-roadmap --mode full → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → maestro-verify |
-| `ui-design-driven` | maestro-ui-design → [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `ui-craft-build` | maestro-ui-craft --chain build → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `next-milestone` | [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `full-lifecycle` | [B] maestro-plan → [B] maestro-execute → maestro-verify → quality-review → quality-test → maestro-milestone-audit → maestro-milestone-complete |
@@ -341,7 +341,7 @@ Read `.workflow/state.json` and route by condition:
 
 | Skill | Flag |
 |-------|------|
-| maestro-init, maestro-analyze, maestro-brainstorm, maestro-ui-design, maestro-roadmap | `-y` |
+| maestro-init, maestro-analyze, maestro-brainstorm, maestro-ui-craft, maestro-roadmap | `-y` |
 | maestro-plan, maestro-execute, maestro-milestone-complete | `-y` |
 | quality-auto-test, quality-retrospective | `-y` |
 | quality-test | `-y --auto-fix` |

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

@@ -49,6 +49,7 @@ S_ROLES      — 选择 roles（-y auto / interactive）        PERSIST: —
 S_CSV_GEN    — 生成 tasks.csv                              PERSIST: tasks.csv
 S_WAVE_1     — Guidance Spec (single agent)                PERSIST: guidance-specification.md
 S_CHECK_1    — Checkpoint: 用户审阅 guidance（-y 跳过）    PERSIST: —
+S_DESIGN     — 视觉风格确定 (impeccable teach + explore)   PERSIST: DESIGN.md
 S_WAVE_2     — Role Analysis (parallel spawn)              PERSIST: role analyses
 S_CHECK_2    — Checkpoint: 用户审阅 roles（-y 跳过）       PERSIST: —
 S_WAVE_3     — Synthesis + Feature Index (single agent)    PERSIST: synthesis artifacts
@@ -63,10 +64,15 @@ S_CSV_GEN → S_WAVE_1   DO: generate tasks.csv (1 guidance + N roles + 1 synthe
 S_WAVE_1 → S_CHECK_1   WHEN: completed    DO: spawn wave-1, merge results, read guidance-spec
 S_WAVE_1 → END         WHEN: failed       DO: abort pipeline
 
-S_CHECK_1 → S_WAVE_2   WHEN: -y OR user "Proceed"
+S_CHECK_1 → S_DESIGN   WHEN: (-y OR user "Proceed") AND ui-designer in selected_roles
+S_CHECK_1 → S_WAVE_2   WHEN: (-y OR user "Proceed") AND ui-designer NOT in selected_roles
 S_CHECK_1 → S_CHECK_1  WHEN: user "Revise"    DO: edit guidance-spec, re-display
 S_CHECK_1 → END        WHEN: user "Abort"
 
+S_DESIGN → S_WAVE_2    WHEN: DESIGN.md exists OR explore completed    DO: A_DESIGN_EXPLORE
+S_DESIGN → S_WAVE_2    WHEN: DESIGN.md already exists (skip explore)
+S_DESIGN → S_WAVE_2    WHEN: explore failed → W004 → continue without
+
 S_WAVE_2 → S_CHECK_2   DO: spawn wave-2 (parallel), merge results
 S_WAVE_2 → S_WAVE_3    WHEN: all failed       DO: skip synthesis
 
@@ -88,13 +94,24 @@ S_AGGREGATE → END      DO: A_AGGREGATE
 
 **Synthesis (W3)**: Cross-role consensus/conflicts/unique → conflict tags [RESOLVED]/[SUGGESTED]/[UNRESOLVED] → feature-specs or synthesis-specification.md → feature-index.json + synthesis-changelog.md. Four-layer: Direct Reference → Structured Extraction → Conflict Distillation → Cross-Feature Annotation.
 
+### A_DESIGN_EXPLORE
+
+When ui-designer is among selected roles, establish visual direction before Wave 2:
+
+1. If `.workflow/impeccable/PRODUCT.md` missing → run `$maestro-impeccable teach`
+2. If `.workflow/impeccable/DESIGN.md` missing → run `$maestro-impeccable explore`
+3. If both already exist → skip (visual direction already locked)
+
+explore generates multi-style HTML prototypes, visual comparison, user selection/mix, and produces DESIGN.md.
+ui-designer agents in Wave 2 then focus on UX analysis only (interaction flows, state design), not visual styling.
+
 ### A_AGGREGATE
 
 1. Export results.csv
 2. Generate context.md (summary, guidance, per-role findings, synthesis, feature index, next steps)
 3. Confidence scoring: 5 dimensions (role_coverage, cross_role_consistency, feature_completeness, spec_quality, design_feasibility). Quality gate: >3 UNRESOLVED → warn.
 4. Copy artifacts to target .brainstorming/
-5. Next-step routing: UI features detected → maestro-ui-design; else → maestro-analyze / maestro-plan / maestro-roadmap
+5. Next-step routing: DESIGN.md established → `maestro-ui-craft <feature> --chain build`; else UI features detected → `maestro-ui-craft <feature> --chain build`; else → maestro-analyze / maestro-plan / maestro-roadmap
 
 </actions>
 </state_machine>

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

@@ -50,6 +50,11 @@ $ARGUMENTS — natural language workflow description, or flags.
 
 **Node catalog**: Read `~/.maestro/templates/workflows/specs/node-catalog.md` at Phase 2 (deferred).
 **Template schema**: Read `~/.maestro/templates/workflows/specs/template-schema.md` at Phase 5 (deferred).
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
+2. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Informs executor argument defaults and context injection.
+3. Optional — proceed without if unavailable.
 </context>
 
 <execution>

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

@@ -27,7 +27,7 @@
     {"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-craft", "command": "/maestro-ui-craft", "category": "ui", "description": "UI 生产管线 — 设计系统原型、自动化生产和质量门控", "source": "../../commands/maestro-ui-craft.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"},

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

@@ -1,24 +1,33 @@
 ---
 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]"
+description: Production-grade UI design with knowhow accumulation -- 24 commands for build, evaluate, refine, enhance, fix
+argument-hint: "[craft|shape|explore · 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] [--styles N]"
 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.
+Replaces the standalone impeccable skill. 24 commands covering the full design lifecycle.
+
+Includes integrated `search` subcommand for querying UI/UX design knowledge base (BM25 + CSV):
+```bash
+maestro impeccable search "<query>" -d <domain>          # domain search
+maestro impeccable search "<query>" --design-system      # generate design system
+maestro impeccable search "<query>" --design-system --persist -p "Project"  # save MASTER.md
+```
+Domains: style, color, chart, landing, product, ux, typography, icons, react, web, google-fonts.
+Stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, html-tailwind, shadcn.
 </purpose>
 
 <context>
 $ARGUMENTS -- sub-command + target + optional flags.
 
-**Sub-commands** (23):
+**Sub-commands** (24):
 
 | Category | Commands |
 |----------|----------|
-| Build | craft, shape, teach, document, extract |
+| Build | craft, shape, teach, document, extract, explore |
 | Evaluate | critique, audit |
 | Refine | polish, bolder, quieter, distill, harden, onboard |
 | Enhance | animate, colorize, typeset, layout, delight, overdrive |
@@ -28,6 +37,7 @@ $ARGUMENTS -- sub-command + target + optional flags.
 **Flags:**
 - `--skip-harvest` -- Execute command without knowhow capture
 - `-y` -- Auto-confirm where the skill allows
+
 </context>
 
 <execution>
@@ -71,6 +81,7 @@ After command completes (except `live`), unless `--skip-harvest`:
 | shape | decision | DCS- |
 | teach | reference | REF- |
 | document, extract | asset | AST- |
+| explore | decision + asset | DCS- + AST- |
 | critique, audit, polish, harden, onboard, clarify, adapt, optimize | tip | TIP- |
 | colorize, typeset, layout, animate, bolder, quieter, distill, delight, overdrive | decision | DCS- |
 
@@ -79,6 +90,14 @@ Write knowhow with `category: ui`. For DCS-/AST- types, also create spec index:
 maestro spec add ui "<title>" "<summary>" --keywords impeccable,<cmd>,... --ref knowhow/<file>
 ```
 
+## Post-Execution Routing
+
+After harvest, determine whether this command was invoked as part of a larger pipeline by checking conversation context (e.g., brainstorm Step 3.5, ui-craft chain step).
+
+**Pipeline context detected** (called via Skill from brainstorm, ui-craft, etc.): Report result and stop. Do NOT suggest next-step commands — the calling flow owns what happens next.
+
+**Standalone invocation** (user directly ran the command): Show next-step suggestions based on command executed (teach→explore/shape, explore→shape→craft, craft→critique, etc.).
+
 </execution>
 
 <shared_design_laws>

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

@@ -40,6 +40,9 @@ $ARGUMENTS — milestone number and optional flags.
 <execution>
 Follow '~/.maestro/workflows/merge.md' completely.
 
+**Knowledge inquiry on completion:**
+After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `maestro spec add learning "<title>" "<insight>" --keywords <kw1>,<kw2>`.
+
 **Next steps:**
 - View dashboard → `$manage-status`
 - Audit milestone → `$maestro-milestone-audit`

package/.codex/skills/maestro-milestone-audit/SKILL.md

@@ -2,11 +2,13 @@
 name: maestro-milestone-audit
 description: Audit current milestone for cross-phase integration gaps
 argument-hint: "[milestone, e.g., 'M1']"
-allowed-tools: Read, Write, Bash, Glob, Grep, Agent
+allowed-tools: spawn_agents_on_csv, Read, Write, Bash, Glob, Grep
 ---
 
 <purpose>
-Sequential audit based on artifact registry in state.json. Checks phase coverage (ANL->PLN->EXC chains), ad-hoc completeness, execution completeness, and cross-artifact integration. Produces PASS/FAIL verdict report.
+Sequential audit based on artifact registry in state.json. Checks phase coverage (ANL->PLN->EXC chains), ad-hoc completeness, execution completeness, and cross-artifact integration via `spawn_agents_on_csv`. Produces PASS/FAIL verdict report.
+
+**Core workflow**: Load Artifacts -> Coverage Check -> Completeness Check -> CSV Wave (Integration Check) -> Verdict
 </purpose>
 
 <context>
@@ -16,14 +18,52 @@ $maestro-milestone-audit ""
 $maestro-milestone-audit "M1"
 ```
 
-**Output**: Audit report with artifact chain verification, integration analysis, and PASS/FAIL verdict
+**Output**: `.workflow/milestones/{milestone}/audit-report.md` with artifact chain verification, integration analysis, and PASS/FAIL verdict
 
+**Session**: `.workflow/.csv-wave/{YYYYMMDD}-audit-{milestone}/`
 </context>
 
+<csv_schema>
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,scope,check_targets,deps,wave,status,findings,gaps_found,severity,error
+"integ-1","Interface & dependency chains","Verify shared interfaces are consistent across phases: re-exports match, dependency chains unbroken, no circular imports between phase outputs","cross-phase imports, shared types, re-exports","grep for shared type names across phase output dirs; verify export/import consistency","","1","","","","",""
+"integ-2","Data contracts & API consistency","Verify request/response schemas match across phases: API signatures consistent, error codes aligned, no contract drift","request/response schemas, API signatures, error codes","diff API type definitions across phases; check error code enum consistency","","1","","","","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Worker identifier: `integ-{N}` |
+| `title` | Input | Integration dimension name |
+| `description` | Input | Detailed check instructions |
+| `scope` | Input | What to examine |
+| `check_targets` | Input | Specific verification commands/grep patterns |
+| `deps` | Input | Dependencies (empty — all wave 1) |
+| `wave` | Computed | Wave number (always 1 — single parallel wave) |
+| `status` | Output | `pending` -> `pass` / `fail` / `warning` |
+| `findings` | Output | Detailed findings per dimension (max 500 chars) |
+| `gaps_found` | Output | Semicolon-separated list of integration gaps |
+| `severity` | Output | `critical` / `warning` / `info` per gap |
+| `error` | Output | Error message if check failed |
+
+### Session Structure
+
+```
+.workflow/.csv-wave/{YYYYMMDD}-audit-{milestone}/
++-- tasks.csv
++-- wave-1.csv (temporary)
++-- wave-1-results.csv
+```
+</csv_schema>
+
 <invariants>
 1. **Artifact registry is source of truth** — don't scan directories, read state.json
 2. **Non-blocking warnings** — missing analyze is warning, missing execute is error
-3. **Integration check is required** — always spawn checker agent
+3. **Integration check is required** — always spawn checker via CSV wave
 4. **Clear verdict** — PASS or FAIL with specific reasons
 </invariants>
 
@@ -45,9 +85,26 @@ For each phase: check for completed analyze (optional), plan (required), execute
 
 Verify all adhoc-scoped artifacts completed. For each execute artifact, verify all tasks in plan dir completed.
 
-### Step 5: Integration Check
+### Step 5: Integration Check via CSV Wave
+
+1. Create session folder: `.workflow/.csv-wave/{dateStr}-audit-{milestone}/`
+2. Build `tasks.csv` from csv_schema — populate `scope` and `check_targets` columns using phase artifacts discovered in Step 2
+3. Write `wave-1.csv` from pending rows, then execute:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-1.csv`,
+  id_column: "id",
+  instruction: `You are an integration checker for milestone ${milestone}. For each row, examine the scope and check_targets. Search the codebase for inconsistencies, contract drift, and broken dependencies across phase outputs. Report findings with file:line references. Set status to pass/fail/warning. List specific gaps in gaps_found (semicolon-separated).`,
+  max_concurrency: 2, max_runtime_seconds: 600,
+  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
+  output_schema: { id, status: [pass|fail|warning], findings, gaps_found, severity, error }
+})
+```
 
-Spawn Agent for cross-phase validation: shared interfaces, dependency chains, data contracts, API consistency. Write report to `.workflow/milestones/{milestone}/audit-report.md`.
+4. Merge results into master `tasks.csv`
+5. Parse `gaps_found` from all workers — aggregate into `.workflow/milestones/{milestone}/audit-report.md`
+6. Any worker with `status == fail` and `severity == critical` → milestone verdict = FAIL
 
 ### Step 6: Verdict
 
@@ -81,7 +138,7 @@ Display structured audit report.
 - [ ] Artifact registry loaded and filtered by milestone
 - [ ] Phase coverage matrix generated
 - [ ] Ad-hoc and execution completeness verified
-- [ ] Integration check performed via agent
+- [ ] Integration check performed via spawn_agents_on_csv (2 parallel workers)
 - [ ] Audit report written to milestones/ directory
 - [ ] Clear PASS/FAIL verdict with specific reasons
 </success_criteria>

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

@@ -2,7 +2,7 @@
 name: maestro-quick
 description: Quick task execution, skip optional agents
 argument-hint: "\"task description\" [--discuss] [--full]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>

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

@@ -158,7 +158,7 @@ Build prev_context from wave 1. Inject strategy + --phases constraint (light mod
    +-- readiness-report.md
    ```
 7. Update state.json milestones + current_milestone
-8. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-ui-design; full mode setup -> maestro-init
+8. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-ui-craft --chain build; full mode setup -> maestro-init
 
 </actions>
 

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

@@ -2,7 +2,7 @@
 name: maestro-tools-execute
 description: Load and execute tool specs by role or name
 argument-hint: "[tool-name | --category <category>]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>

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

@@ -2,7 +2,7 @@
 name: maestro-tools-register
 description: Register tool specs - extract, generate, or optimize reusable process definitions
 argument-hint: "[description or intent]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>