maestro-flow 0.3.47 → 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

@@ -16,10 +16,6 @@ Entry points:
 - **`$maestro --super "intent"`** — Production-ready mode (read maestro-super.md)
 </purpose>
 
-<required_reading>
-@~/.maestro/workflows/maestro.codex.md — authoritative `detectTaskType`, `detectNextAction`, `chainMap` (35+ intent patterns, 40+ chain types). Read before executing any step.
-</required_reading>
-
 <deferred_reading>
 - [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag is active
 </deferred_reading>
@@ -51,7 +47,7 @@ $ARGUMENTS — user intent text, or special flags.
 <states>
 S_PARSE         — 解析参数、检测 flags              PERSIST: —
 S_CONTINUE      — 加载已有 session，定位 resume 点   PERSIST: session (loaded)
-S_CLASSIFY      — 意图分类、解析 chain               PERSIST: —
+S_CLASSIFY      — 意图分类、解析 chain (A_CLASSIFY)   PERSIST: —
 S_CREATE        — 创建 session + status.json         PERSIST: session.status, session.steps[]
 S_DRY_RUN       — 显示 chain 后结束                  PERSIST: —
 S_CONFIRM       — 用户确认（auto_mode 跳过）          PERSIST: —
@@ -73,7 +69,7 @@ S_CONTINUE:
   → S_FALLBACK    WHEN: no session found
 
 S_CLASSIFY:
-  → S_CREATE      WHEN: chain resolved (keyword match or maestro.codex.md lookup)
+  → S_CREATE      WHEN: chain resolved                      DO: A_CLASSIFY
   → S_FALLBACK    WHEN: no match AND auto_mode
   → S_CLASSIFY    WHEN: no match AND not auto_mode          DO: A_CLARIFY_INTENT
                    GUARD: max 1 clarification attempt → S_FALLBACK
@@ -113,7 +109,7 @@ S_FALLBACK:
 ### A_CREATE_SESSION
 
 1. Read `.workflow/state.json` for project context (current phase, milestone, workflow_name)
-2. Resolve chain's skill list from chain_map or maestro.codex.md
+2. Resolve chain's skill list from Chain Map (see appendix)
 3. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`:
    ```json
    { "session_id", "source": "maestro", "intent", "task_type", "chain_name",
@@ -132,6 +128,85 @@ S_FALLBACK:
 2. Find first pending step → set as resume point
 3. Rebuild `update_plan` from status.json (completed→"completed", current→"in_progress", rest→"open")
 
+### A_CLASSIFY
+
+**Layer 1: Exact-match (fast path)**
+- `--chain <name>` flag → validate against chainMap, use directly (E002 if not found)
+- `continue`/`next`/`go`/`继续`/`下一步` → `state_continue`
+- `status`/`状态`/`dashboard` → `status`
+
+If matched, skip to chain resolution.
+
+**Layer 2: Structured intent extraction**
+
+Extract tuple from intent using LLM semantic understanding:
+```json
+{
+  "action":    "<create|fix|analyze|plan|execute|verify|review|test|debug|refactor|explore|manage|transition|continue|sync|learn|retrospect>",
+  "object":    "<feature|bug|issue|code|test|spec|phase|milestone|doc|performance|security|ui|memory|codebase|config>",
+  "scope":     "<module/file/area or null>",
+  "issue_id":  "<ISS-XXXXXXXX-NNN or null>",
+  "phase_ref": "<integer or null>",
+  "urgency":   "<low|normal|high>"
+}
+```
+
+Disambiguation: "问题"/"issue"/"problem" as broken → `object: "bug"` (→ debug); as tracked item (with ISS-ID or management context) → `object: "issue"` (→ issue management). When ambiguous, prefer `"bug"`.
+
+**Layer 3: action × object routing matrix**
+
+If `issue_id` present → issue pipeline directly.
+
+| action | object-specific overrides | default |
+|--------|--------------------------|---------|
+| fix | bug/code/perf/security→`debug`, issue→`issue` | `debug` |
+| create | feature→`quick`, issue→`issue`, test→`test_gen`, spec→`spec_generate`, ui→`ui_design`, config→`init` | `quick` |
+| analyze | bug/code→`analyze`, issue→`issue_analyze`, codebase→`spec_map` | `analyze` |
+| explore | issue→`issue_discover`, feature/ui→`brainstorm`/`ui_design` | `brainstorm` |
+| plan | issue→`issue_plan`, spec→`spec_generate` | `plan` |
+| execute | issue→`issue_execute` | `execute` |
+| manage | issue→`issue`, milestone→`milestone_audit`, phase→`phase_transition`, memory/doc/codebase→`memory`/`sync`/`codebase_refresh` | `status` |
+| transition | phase→`phase_transition`, milestone→`milestone_complete` | `phase_transition` |
+| verify, review, test, debug, refactor, continue, sync, learn, retrospect, release, amend, compose | — | self-named |
+
+**Clarity scoring**: 3=action+object+scope, 2=action+object, 1=action only, 0=empty.
+If `clarity < 2` and not `auto_mode` → transition to A_CLARIFY_INTENT.
+
+**Layer 4: State-based routing** (when `taskType === 'state_continue'`)
+
+Read `.workflow/state.json` and route by condition:
+
+| Condition | Chain |
+|-----------|-------|
+| Not initialized | `init` |
+| No phases, no roadmap, has accumulated_context | `next-milestone` |
+| No phases | `brainstorm-driven` |
+| pending + has context | `plan` |
+| pending, no context | `analyze` |
+| exploring/planning + has plan | `execute-verify` |
+| exploring/planning, no plan | `plan` |
+| executing, all tasks done | `verify` |
+| executing, tasks remain | `execute` |
+| verifying, passed + no review | `review` |
+| verifying, passed + BLOCK | `review-fix` |
+| verifying, passed + UAT pending | `test` |
+| verifying, passed + UAT passed | `milestone-close` |
+| verifying, passed + UAT failed | `debug` |
+| verifying, not passed | `quality-loop-partial` |
+| testing, UAT passed | `milestone-close` |
+| testing, UAT not passed | `debug` |
+| completed | `milestone-close` |
+| blocked | `debug` |
+| fallback | `status` |
+
+**Chain resolution order:**
+1. `forceChain` → `chainMap[forceChain]` (E002 if not found)
+2. `state_continue` → Layer 4 state routing → `{ chain, argsOverride? }`
+3. `taskToChain[taskType]` → alias lookup (see Chain Aliases below)
+4. `chainMap[taskType]` → direct lookup
+
+**Phase resolution**: structured extraction `phase_ref` → fallback regex (`phase N` or bare number) → `projectState.current_phase`.
+
 ### A_CLARIFY_INTENT
 
 1. `AskUserQuestion` with available chain types
@@ -177,29 +252,96 @@ S_FALLBACK:
 
 <appendix>
 
-### Chain Map (Quick Reference)
-
-| Intent keywords | Chain | Steps |
-|----------------|-------|-------|
-| fix, bug, error, broken | `quality-fix` | analyze --gaps → plan --gaps → execute → verify |
-| test, spec, coverage | `quality-test` | quality-test |
-| refactor, cleanup, debt | `quality-refactor` | quality-refactor |
-| feature, implement, add | `feature` | plan → execute → verify |
-| review, check, audit | `quality-review` | quality-review |
-| deploy, release, ship | `deploy` | verify → milestone-release |
-| brainstorm, explore, ideate | `brainstorm-driven` | brainstorm → plan → execute → verify |
-| plan, design, architect | `plan` | plan |
-| debug, diagnose | `debug` | quality-debug |
-| continue, next | `state_continue` | (from project state) |
-| status, dashboard | `status` | manage-status |
-
-Full chain map (40+ chains): `@~/.maestro/workflows/maestro.codex.md` §3c
+### Chain Map (Full)
+
+**Single-step chains:**
+
+| Chain | Command + Args |
+|-------|---------------|
+| `status` | `manage-status` |
+| `init` | `maestro-init` |
+| `analyze` | `maestro-analyze {phase}` |
+| `ui_design` | `maestro-ui-craft "{phase}" --chain build` |
+| `plan` | `maestro-plan {phase}` |
+| `execute` | `maestro-execute {phase}` |
+| `verify` | `maestro-verify {phase}` |
+| `test_gen` | `quality-auto-test {phase}` |
+| `auto_test` | `quality-auto-test {phase}` |
+| `test` | `quality-test {phase}` |
+| `debug` | `quality-debug "{description}"` |
+| `integration_test` | `quality-auto-test {phase}` |
+| `refactor` | `quality-refactor "{description}"` |
+| `review` | `quality-review {phase}` |
+| `retrospective` | `quality-retrospective {phase}` |
+| `learn` | `maestro-learn "{description}"` |
+| `sync` | `quality-sync` |
+| `milestone_audit` | `maestro-milestone-audit` |
+| `milestone_complete` | `maestro-milestone-complete` |
+| `codebase_rebuild` | `manage-codebase-rebuild` |
+| `codebase_refresh` | `manage-codebase-refresh` |
+| `spec_setup` | `spec-setup` |
+| `spec_add` | `spec-add "{description}"` |
+| `spec_load` | `spec-load` |
+| `spec_map` | `manage-codebase-rebuild` |
+| `spec_remove` | `spec-remove "{description}"` |
+| `knowhow_capture` | `manage-knowhow-capture "{description}"` |
+| `knowhow` | `manage-knowhow "{description}"` |
+| `issue` | `manage-issue "{description}"` |
+| `issue_discover` | `manage-issue-discover "{description}"` |
+| `issue_analyze` | `maestro-analyze --gaps "{description}"` |
+| `issue_plan` | `maestro-plan --gaps` |
+| `issue_execute` | `maestro-execute` |
+| `quick` | `maestro-quick "{description}"` |
+| `harvest` | `manage-harvest "{description}"` |
+| `wiki` | `manage-wiki` |
+| `wiki_connect` | `wiki-connect` |
+| `wiki_digest` | `wiki-digest` |
+| `business_test` | `quality-auto-test {phase}` |
+| `amend` | `maestro-amend "{description}"` |
+| `release` | `maestro-milestone-release` |
+| `compose` | `maestro-composer "{description}"` |
+| `play` | `maestro-player "{description}"` |
+| `update` | `maestro-update` |
+| `overlay` | `maestro-overlay "{description}"` |
+| `link_coordinate` | `maestro-link-coordinate "{description}"` |
+
+**Multi-step chains:**
+
+| Chain | Steps (→ = sequential, [B] = barrier) |
+|-------|---------------------------------------|
+| `feature` | [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `quality-fix` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → maestro-verify |
+| `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-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 |
+| `execute-verify` | [B] maestro-execute → maestro-verify |
+| `analyze-plan-execute` | [B] maestro-analyze -q → [B] maestro-plan --dir {scratch_dir} → [B] maestro-execute --dir {scratch_dir} |
+| `quality-loop` | maestro-verify → quality-review → quality-test → quality-debug --from-uat → [B] maestro-plan --gaps → [B] maestro-execute |
+| `quality-loop-partial` | [B] maestro-plan --gaps → [B] maestro-execute → maestro-verify |
+| `review-fix` | [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
+| `milestone-close` | maestro-milestone-audit → maestro-milestone-complete |
+| `milestone-release` | maestro-milestone-audit → maestro-milestone-release |
+| `phase_transition` | maestro-milestone-audit → maestro-milestone-complete |
+| `issue-full` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → quality-review → manage-issue close |
+| `issue-quick` | [B] maestro-plan --gaps → [B] maestro-execute → manage-issue close |
+
+**Chain Aliases** (taskType → chain):
+
+| taskType | Chain |
+|----------|-------|
+| `spec_generate` | `spec-driven` |
+| `brainstorm` | `brainstorm-driven` |
+| `issue_execute` | `issue-full` |
 
 ### Auto-Yes Flag Map
 
 | 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`