maestro-flow-one 0.2.7 → 0.2.9

package/maestro-flow/agents/impeccable-agent.md

@@ -64,8 +64,8 @@ These commands ask questions only "if unclear from codebase". When PRODUCT.md an
 
 1. **Load context**: Run `maestro impeccable load-context` to load PRODUCT.md and DESIGN.md
 2. **Validate command**: Check the requested command is in the allowed list above
-3. **Execute**: `Skill({ skill: "maestro-impeccable", args: "{command} {target} --skip-harvest -y" })`
-   - Always pass `-y` to auto-confirm where the skill allows
+3. **Execute**: Read `~/.maestro/workflows/impeccable/{command}.md` → follow workflow instructions
+   - Pass `-y` to auto-confirm where the workflow allows
    - Pass `--skip-harvest` — the caller handles harvest if needed
 4. **Report**: Return the command output (scores, changes made, findings)
 

package/maestro-flow/commands/lifecycle/analyze.md

@@ -79,7 +79,7 @@ Phase 4: Output context.md for downstream plan --gaps
 **Next-step routing on completion:**
 
 Phase/Milestone scope:
-- Go recommendation, UI work needed → `/maestro-ui-craft --chain build {target}`
+- Go recommendation, UI work needed → `/maestro-impeccable build {target}`
 - Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
 - No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
 
@@ -129,5 +129,5 @@ Both modes (full + quick):
 - [ ] Scope creep redirected to Deferred section
 - [ ] Deferred items auto-created as issues (if any)
 - [ ] Artifact registered in state.json with correct scope/milestone/phase
-- [ ] Next step routed (ui-craft/plan for Go, brainstorm for No-Go)
+- [ ] Next step routed (impeccable/plan for Go, brainstorm for No-Go)
 </success_criteria>

package/maestro-flow/commands/lifecycle/brainstorm.md

@@ -69,7 +69,7 @@ Auto mode:
 - Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
 - Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
 - `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
-- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-ui-craft <feature-description> --chain build` to build with the established design system"
+- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
 
 Single role mode:
 - More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })

package/maestro-flow/commands/lifecycle/impeccable.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-impeccable
-description: Production-grade UI design with knowhow accumulation — 24 commands + integrated design search for build, evaluate, refine, enhance, fix
-argument-hint: "<command> [target] [--skip-harvest] [-y] | search <query> [-d <domain>] [--design-system]"
+description: Production-grade UI design — 24 commands + chain orchestration with quality gates + design search
+argument-hint: "<command|chain|intent> [target] [flags]"
 allowed-tools:
   - Read
   - Write
@@ -9,118 +9,238 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
-  - Skill
+  - Agent
   - AskUserQuestion
+  - TodoWrite
 ---
-<purpose>
-Replaces impeccable as the primary UI design entry point. 24 commands covering the full design lifecycle:
-Build (craft, shape, teach, document, extract, explore), Evaluate (critique, audit), Refine (polish, bolder, quieter, distill, harden, onboard),
-Enhance (animate, colorize, typeset, layout, delight, overdrive), Fix (clarify, adapt, optimize), Iterate (live).
 
-Core innovation over impeccable: after each command execution, automatically harvests design decisions
-into `.workflow/knowhow/` (DCS-, AST-, TIP-, REF-) for cross-session accumulation. Other maestro commands
-consume this via `category: coding` auto-injection and keyword matching.
+<purpose>
+UI design command. Parse input → prerequisites → read workflow file → execute → track.
 
-Includes integrated `search` CLI subcommand for querying the UI/UX design knowledge base
-(BM25 search engine + 30+ CSV data files covering styles, colors, typography, UX guidelines, charts, stacks).
-Search is invoked directly via `maestro impeccable search`, not through the Skill dispatch.
+- **Direct**: single command via workflow file
+- **Chain**: orchestrate command sequence with quality gates
+- **Search**: query design knowledge base via CLI
 </purpose>
 
-<deferred_reading>
-- [impeccable harvest workflow](~/.maestro/workflows/impeccable.md) — read after command execution for harvest logic
-</deferred_reading>
-
-<context>
-$ARGUMENTS — sub-command + target + optional flags.
-
-**Sub-commands** (24):
-
-| Category | Commands |
-|----------|----------|
-| Build | craft, shape, teach, document, extract, explore |
-| 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
-
-**Harvest behavior**: After command completion, the harvest workflow extracts design decisions
-and writes knowhow entries. DCS-/AST- types also get spec index entries for discoverability.
-`live` command is exempt (too ephemeral). Use `--skip-harvest` to suppress.
-</context>
-
-<execution>
-
-## 1. Route
-
-If first argument is `search` → direct CLI dispatch (no Skill, no harvest):
-
-```bash
-maestro impeccable search "<query>" [options]
-```
-
-Options: `-d <domain>`, `-s <stack>`, `-n <max>`, `--design-system`, `-p <name>`, `-f <fmt>`, `--persist`, `--page <page>`, `-o <dir>`
-
-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, + more.
-
-Search uses `workflows/impeccable/ui-search/search.py` (BM25 engine + 30+ CSV knowledge files).
-Output goes to stdout. No Skill invocation, no harvest. Return after output.
-
-## 2. Invoke Skill (all other sub-commands)
-
-```
-Skill({ skill: "maestro-impeccable", args: "$ARGUMENTS" })
-```
-
-The skill handles: context loading (spec load --category ui, with load-context fallback), register detection (brand/product),
-reference file loading, and command execution.
-
-## 3. Harvest
-
-After the skill completes, read `~/.maestro/workflows/impeccable.md` and follow the harvest workflow.
-
-Skip harvest if:
-- `--skip-harvest` flag is set
-- Sub-command is `live` (interactive, no harvestable output)
-- Sub-command is unrecognized
-
-## 4. Post-Execution Routing
-
-After harvest (or skip), 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 command result (output, scores, artifacts produced) and **stop**
-- Do NOT suggest next-step commands — the calling flow owns what happens next
-
-**Standalone invocation** (user directly ran `/maestro-impeccable`):
-- Show next-step suggestions based on what was executed:
-  - `teach` → suggest `explore` or `shape`
-  - `explore` → suggest `shape` → `craft`
-  - `shape` → suggest `craft`
-  - `craft` → suggest `critique`
-  - `critique`/`audit` → suggest commands from findings
-  - Enhancement/fix commands → suggest `critique` to re-evaluate
-
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | error | Invalid sub-command (not in 24 valid commands) |
-| E002 | error | No intent or target specified |
-| W001 | warning | Harvest failed — design knowledge not captured (command still succeeded) |
-| W002 | warning | PRODUCT.md missing — skill will auto-trigger teach |
-</error_codes>
-
-<success_criteria>
-- [ ] Sub-command recognized and routed to maestro-impeccable skill
-- [ ] Skill executed with context (spec load --category ui or load-context fallback, register identified)
-- [ ] Design changes applied to target files
-- [ ] Knowhow entry created in .workflow/knowhow/ (unless --skip-harvest or live)
-- [ ] Spec index entry created for DCS-/AST- types
-</success_criteria>
+## Input
+
+$ARGUMENTS first word determines mode:
+
+| First Word | Mode |
+|------------|------|
+| Known command (see routing table) | Direct |
+| Chain name: build, redesign, improve, enhance, launch, harden, foundation, live | Chain |
+| continue / next / -c | Resume |
+| search | Search: `maestro impeccable search "$REST"` |
+| Free text (concrete task) | Direct craft — has specific target + specs/reference |
+| Free text (project intent) | Intent → classify → chain |
+| (empty) | Menu: show commands by category |
+
+## Command Routing
+
+All workflows at `~/.maestro/workflows/impeccable/{command}.md`:
+
+| Command | Category | Description |
+|---------|----------|-------------|
+| craft | Build | Shape then build end-to-end — full page/component implementation |
+| shape | Build | Plan UX/UI before code — information architecture, wireframe, visual direction |
+| teach | Build | Set up PRODUCT.md — users, brand, tone, anti-references, principles |
+| document | Build | Generate DESIGN.md from existing code — extract tokens, typography, colors |
+| extract | Build | Pull tokens/components into reusable design system |
+| explore | Build | Multi-style comparison — generate variants, render prototypes, visual compare, select/mix |
+| critique | Evaluate | UX heuristic review with Nielsen scoring (/40) + P0/P1 findings |
+| audit | Evaluate | Technical quality checks — a11y, performance, responsive, code quality (/20) |
+| polish | Refine | Final quality pass — micro-adjustments, pixel perfection |
+| bolder | Refine | Amplify bland/safe designs — stronger personality, more contrast |
+| quieter | Refine | Tone down aggressive/overwhelming designs — reduce visual noise |
+| distill | Refine | Strip to essence — remove clutter, reduce cognitive load |
+| harden | Refine | Production-ready — error states, i18n, edge cases, overflow, empty states |
+| onboard | Refine | First-run flows, empty states, activation paths, progressive disclosure |
+| animate | Enhance | Add purposeful motion — transitions, micro-interactions, scroll effects |
+| colorize | Enhance | Add strategic color — OKLCH palette, contrast, color strategy |
+| typeset | Enhance | Improve typography — scale, hierarchy, font pairing, line length |
+| layout | Enhance | Fix spacing, rhythm, visual hierarchy, alignment, grid |
+| delight | Enhance | Add personality — memorable details, joy, surprise moments |
+| overdrive | Enhance | Push past conventional limits — ambitious visual effects |
+| clarify | Fix | Improve UX copy — labels, error messages, microcopy, CTAs |
+| adapt | Fix | Adapt for devices/screens — responsive, touch targets, breakpoints |
+| optimize | Fix | Fix UI performance — loading, rendering, bundle, paint/layout jank |
+| live | Iterate | Browser-based variant iteration — real-time design in DevTools |
+
+Reference files (loaded by workflow as needed, not standalone commands):
+brand.md, product.md, design.md, codex.md, heuristics-scoring.md, cognitive-load.md,
+color-and-contrast.md, interaction-design.md, motion-design.md, personas.md,
+responsive-design.md, spatial-design.md, typography.md, ux-writing.md
+
+## Chains
+
+| Chain | Steps | Scenario |
+|-------|-------|----------|
+| build | teach? → explore? → shape → craft → critique → [refine] → audit → polish | 从零新建 |
+| redesign | document → explore → shape → craft → critique → [refine] → audit → polish | 基于现有代码重设计 |
+| improve | critique → [refine] → polish → audit | 迭代改进 |
+| enhance | {cmd...} → critique → [refine] → polish | 定向增强（支持多命令） |
+| launch | harden → adapt → optimize → audit → polish | 全方位上线准备 |
+| harden | harden → audit → polish | 边界加固 |
+| foundation | teach? → explore → document → extract | 纯设计系统建设 |
+| live | live | 实时迭代 |
+
+- `?` = conditional: teach if PRODUCT.md missing; explore if DESIGN.md missing and --skip-design not set
+- `[refine]` = quality gate loop: gate fails → auto-select fix commands from findings → re-gate
+- `{cmd...}` = enhance 支持多命令，逗号分隔：`enhance colorize,typeset landing-page`
+
+Chain flags: --threshold <N> (default 26/40), --max-loops <N> (default 3), --skip-design, --styles <N>, -y
+
+## Free Text Routing
+
+Free text 按优先级三层匹配。命中即停，不继续向下。
+
+### Layer 1: 意图匹配单个命令 → Direct
+
+将用户描述与 Command Routing 表的 Description 列语义匹配。匹配最接近的**一个**命令。
+
+| Intent signal | Command |
+|---------------|---------|
+| 评审, review, 检查UX, 评分, heuristic | critique |
+| 审计, a11y, 可访问性, 技术检查, performance audit, 代码质量 | audit |
+| 加动画, 动效, transitions, micro-interactions, 过渡 | animate |
+| 配色, 颜色, palette, 色彩, OKLCH, contrast | colorize |
+| 字体, 排版, typography, font, 字号, 行高 | typeset |
+| 布局, 间距, spacing, grid, 对齐, alignment, 视觉层次 | layout |
+| 太花, 太吵, tone down, 视觉噪音, 简洁点 | quieter |
+| 太平淡, 加强, 更大胆, more personality, 更有个性 | bolder |
+| 太复杂, 简化, strip, 去掉多余, cognitive load | distill |
+| 打磨, 微调, pixel perfect, final pass, 最终润色 | polish |
+| 文案, copy, 标签, 错误提示, UX writing, microcopy | clarify |
+| 响应式, mobile, 适配, breakpoints, touch targets | adapt |
+| 性能, loading, bundle, 卡顿, jank, 速度 | optimize |
+| 边界, error states, i18n, 溢出, 空状态加固 | harden |
+| 引导, 新手, 首次使用, onboarding, empty state, 激活 | onboard |
+| 趣味, 惊喜, personality, memorable, joy | delight |
+| 炫酷, 极限, extraordinary, 超常规, 技术极限 | overdrive |
+| 规划, plan UX, wireframe, 信息架构, 视觉方向 | shape |
+| 多风格, 变体, variants, compare styles, 风格对比 | explore |
+| 品牌定义, PRODUCT.md, 产品上下文 | teach |
+| 提取设计, DESIGN.md, 设计文档化 | document |
+| 提取组件, pull tokens, 设计系统提取 | extract |
+| 实时, browser iteration, 浏览器迭代 | live |
+
+### Layer 2: 具体构建任务 → Direct craft
+
+Layer 1 未命中，但意图是"构建/创建某个具体东西"：
+- 包含具体文件路径或目标（`d:\path`, `src/pages/`, `index.html`）
+- 包含详细视觉规格（布局、风格、配色方案）
+- 包含参考素材（`参考...`, `based on...`, `like...`）
+
+→ 路由到 **craft**（Direct）
+
+### Layer 3: 项目意图 → Chain
+
+Layer 1+2 未命中，意图是泛泛的项目方向：
+
+| Pattern | Chain |
+|---------|-------|
+| 新建, create, build, new, 从零开始 | build |
+| 重做, redesign, 重新设计, rethink, 换风格, 改版 | redesign |
+| 改进, improve, iterate, better, 迭代 | improve |
+| 增强, enhance, 视觉升级, visual upgrade | enhance |
+| 上线, launch, deploy, ship, 发布准备, production-ready | launch |
+| 加固, harden, 生产化, 边界情况 | harden |
+| 设计系统, design system, tokens, 设计规范, 设计基建 | foundation |
+| 实时, live, browser | live |
+
+Ambiguous + no `-y` → AskUserQuestion.
+
+## Prerequisites
+
+Before reading any command workflow:
+
+1. **Context**: `maestro spec load --category ui` → if empty → `maestro impeccable load-context`
+2. **PRODUCT.md**: missing/placeholder (<200 chars / `[TODO]`) → execute teach first, then resume original task
+3. **Register**: identify brand/product → Read `~/.maestro/workflows/impeccable/{brand|product}.md`
+
+## Direct Execution
+
+1. Prerequisites ✓
+2. **显示执行信息**：
+   ```
+   ── Command: {command} ────────────────────
+   Category: {category} | Target: {target}
+   ─────────────────────────────────────────
+   ```
+3. Read `~/.maestro/workflows/impeccable/{command}.md`
+4. **TodoWrite 跟踪**：按 workflow 文件中的主要阶段创建 todo 项
+   - 格式：`[{command}] {phase description}`
+   - 每个阶段完成后立即标记 completed
+5. Follow workflow file instructions
+6. Post: suggest logical next command (teach→shape, shape→craft, craft→critique, etc.)
+
+## Chain Execution
+
+1. Prerequisites ✓
+2. **显示执行链**：解析 chain 定义，输出完整步骤预览：
+   ```
+   ── Chain: build ──────────────────────────
+    1. teach        (conditional: PRODUCT.md missing)
+    2. explore      (conditional: DESIGN.md missing)
+    3. shape
+    4. craft
+    5. critique     ◆ quality gate (threshold: 26/40)
+    6. [refine]     ↺ auto-fix loop (max: 3)
+    7. audit        ◆ quality gate (threshold: 14/20)
+    8. polish
+   ─────────────────────────────────────────
+   Target: {target}
+   ```
+   - `◆` 标记 quality gate 步骤，显示阈值
+   - `↺` 标记 refine loop，显示最大循环次数
+   - conditional 步骤注明触发条件
+   - 跳过的 conditional 步骤标记 `(skipped)`
+3. Create session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
+   ```json
+   { "chain_type": "...", "target": "...", "steps": [...], "current_step": 0,
+     "gate_history": [], "loop_count": 0, "status": "running" }
+   ```
+4. **TodoWrite 初始化**：为 chain 所有步骤创建 todo 项
+   - 每步一项，格式：`[chain] step N: {command} — {description}`
+   - conditional 步骤若跳过，立即标记 completed
+   - quality gate 步骤标注阈值：`[chain] step 5: critique ◆ gate ≥26/40`
+5. For each step:
+   - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
+   - **步骤开始**：TodoWrite 标记当前步骤 in_progress
+   - **步骤完成**：TodoWrite 标记 completed + update status.json (`current_step`, step `status`)
+   - **步骤失败**：TodoWrite 标记 completed(with note) + 记录原因
+6. **Quality gate** (critique/audit steps):
+   - Parse score: critique `**Total** | | **N/40**`, audit `**Total** | | **N/20**`
+   - Count `[P0]` / `[P1]` tags
+   - Pass: score ≥ threshold AND P0 == 0 → advance
+   - Fail: collect suggested commands from findings → execute → re-gate
+   - Max loops exceeded → force advance with warning
+   - TodoWrite：gate 结果记入当前步骤备注（score, P0/P1 count, pass/fail）
+7. Final report: scores + trend + commands executed
+
+## Resume
+
+Scan `.workflow/.maestro/ui-craft-*/status.json` for `status == "running"` → most recent → resume from `current_step`.
+
+## Quality Gate — Finding → Command Fallback
+
+When findings lack explicit suggested command:
+
+| Finding Category | Command |
+|-----------------|---------|
+| Layout, spacing, hierarchy, alignment | layout |
+| Color, contrast, palette | colorize |
+| Typography, font, readability | typeset |
+| Animation, motion, transitions | animate |
+| Copy, labels, UX writing | clarify |
+| Responsive, mobile, breakpoints | adapt |
+| Performance, loading, speed | optimize |
+| Complexity, overload, clutter | distill |
+| Bland, safe, generic | bolder |
+| Aggressive, overwhelming | quieter |
+| Onboarding, empty state | onboard |
+| Edge cases, i18n, error handling | harden |
+| Personality, memorability | delight |
+
+Never auto-select: teach, shape, craft, live, document, extract, overdrive, critique, audit.

package/maestro-flow/commands/lifecycle/roadmap.md

@@ -104,7 +104,7 @@ Follow `~/.maestro/workflows/spec-generate.md` completely.
 |-----------|-----------|
 | Roadmap approved, need analysis | /maestro-analyze 1 |
 | Simple project, ready to plan | /maestro-plan 1 |
-| Need UI design first | /maestro-ui-craft --chain build |
+| Need UI design first | /maestro-impeccable build |
 | View project dashboard | /manage-status |
 | Need project setup (full mode) | /maestro-init |
 </execution>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"

package/maestro-flow/commands/lifecycle/ui-craft.md

@@ -1,416 +0,0 @@
----
-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>] [--skip-design-explore] [--skip-design] [--styles <N>] [--stack <stack>] [-y] [-c]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - Skill
-  - AskUserQuestion
-  - TodoWrite
----
-<purpose>
-Orchestrate maestro-impeccable skill commands via intelligent intent routing + quality gate auto-iteration.
-Chain: Build → Evaluate → Auto-Refine → Re-evaluate → Verify.
-
-Core innovation: critique/audit scores drive automatic command selection and iteration loops.
-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" })`
-3. **Gate scores drive loops** — refine loop auto-selects commands from P0/P1 findings, never from hardcoded lists
-4. **Interactive gates respected** — teach, shape, craft retain their user gates; never suppress
-</invariants>
-
-<context>
-$ARGUMENTS — intent description or target path, with optional flags.
-
-**Keywords:** `continue`/`next` → resume previous session
-
-**Flags:**
-- `--chain <type>` — Force chain type: build, improve, enhance, harden, live
-- `--enhance <cmd>` — Specific enhance command for enhance chain (animate|colorize|typeset|layout|delight|overdrive|bolder)
-- `--threshold <score>` — Critique pass threshold (default: 26/40). Audit threshold auto-computed as threshold×0.5
-- `--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>
-
-### Chain Definitions
-
-| Chain | Sequence | Gate Condition |
-|-------|----------|----------------|
-| **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
-
-| 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 |
-| 实时, live, browser, 浏览器, variant | live |
-
-Explicit `--chain` overrides routing. Ambiguous + no `-y` → AskUserQuestion.
-
-</chains>
-
-<state_machine>
-
-<states>
-S_PARSE      — 解析参数、意图分类、chain 选择                PERSIST: —
-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
-S_REPORT     — 最终报告 + 趋势                               PERSIST: final scores, status
-</states>
-
-<transitions>
-
-S_PARSE:
-  → S_RESUME     WHEN: -c / --continue flag OR keyword "continue"/"next"
-  → S_SETUP      WHEN: chain selected (explicit or routed)
-  → S_PARSE      WHEN: ambiguous AND not -y          DO: AskUserQuestion
-  → END          WHEN: no intent AND no target → E002
-
-S_RESUME:
-  → S_CHAIN      WHEN: session found                  DO: A_LOCATE_SESSION
-  → S_FALLBACK   WHEN: no session found → E005
-
-S_SETUP:
-  → S_CREATE     DO: A_LOAD_CONTEXT
-
-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)
-  → S_CHAIN      WHEN: max loops exceeded → W002 → force advance
-
-S_REFINE:
-  → S_GATE       DO: execute auto-selected commands → re-run gate command
-                  GUARD: loop_count < max_loops
-
-S_REPORT:
-  → END          DO: A_FINAL_REPORT
-
-</transitions>
-
-<actions>
-
-### A_LOCATE_SESSION
-
-1. Scan `.workflow/.maestro/ui-craft-*/status.json`, filter `status == "running"`, sort DESC
-2. Take most recent; load into context as current session
-3. Resume from `current_step` position
-
-### A_LOAD_CONTEXT
-
-1. Trigger impeccable context loading by invoking: `Skill({ skill: "maestro-impeccable", args: "teach" })`
-   - Impeccable's own setup will auto-discover and load PRODUCT.md / DESIGN.md
-   - If PRODUCT.md missing/placeholder, impeccable teach handles the interview
-2. If teach was not in the chain but PRODUCT.md is missing:
-   - Prepend `teach` to chain start
-   - Announce: W001
-3. Context is now in conversation for subsequent commands
-
-### A_CREATE_SESSION
-
-1. Read `.workflow/state.json` for project context (phase, milestone)
-2. Create `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`:
-   ```json
-   { "session_id": "ui-craft-{ts}", "source": "ui-craft", "intent": "...",
-     "chain_type": "build|improve|enhance|harden|live", "target": "...",
-     "auto_mode": false, "threshold": 26, "max_loops": 3,
-     "steps": [{ "index": 0, "command": "shape", "status": "pending" }],
-     "gate_history": [], "loop_count": 0,
-     "current_step": 0, "status": "running",
-     "created_at": "ISO-8601", "updated_at": "ISO-8601" }
-   ```
-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)
-2. Update status.json with `status: "completed"` and final scores
-3. Present summary table with scores, iterations, commands executed
-
-</actions>
-
-</state_machine>
-
-<execution>
-
-## 1. Parse & Route
-
-1. If `-c` / `--continue` or keyword "continue"/"next" → S_RESUME
-2. If `--chain` present → use directly
-3. Otherwise → match $ARGUMENTS against intent patterns
-4. If `--enhance` present → chain = enhance, cmd = --enhance value
-5. For enhance chain without `--enhance` → infer from intent ("动画" → animate, "颜色" → colorize, etc.)
-6. Ambiguous + no `-y` → ask user to pick chain
-
-Create TodoWrite with chain steps.
-
-## 2. Setup Context
-
-1. If chain starts with `teach` → execute it first, impeccable handles context loading internally
-2. Otherwise → invoke `Skill({ skill: "maestro-impeccable" })` with no args to trigger setup (context + register)
-3. If impeccable reports PRODUCT.md missing → prepend teach, execute, then resume
-
-## 3. Create Session
-
-Write `.workflow/.maestro/ui-craft-{ts}/status.json` with chain steps before any execution.
-
-## 4. Execute Chain
-
-For each step in chain, sequentially:
-
-```
-▸ Step {n}/{total}: /maestro-impeccable {command} {target}
-```
-
-Execute via: `Skill({ skill: "maestro-impeccable", args: "{command} {target}" })`
-
-After each step: update status.json `current_step` and step `status`.
-
-**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 (Section 5)
-
-## 5. Quality Gate
-
-When chain reaches a gate step (critique or audit):
-
-### 5a. Execute Gate Command
-
-```
-Skill({ skill: "maestro-impeccable", args: "critique {target}" })
-```
-or
-```
-Skill({ skill: "maestro-impeccable", args: "audit {target}" })
-```
-
-### 5b. Parse Score
-
-From critique output, extract:
-- **score**: Nielsen's total (N/40) — from "**Total** | | **N/40**" row
-- **P0_count**: count of `[P0]` tagged findings
-- **P1_count**: count of `[P1]` tagged findings
-- **suggested_commands**: list of "/maestro-impeccable <cmd>" from "Suggested command" fields
-
-From audit output, extract:
-- **score**: dimension total (N/20) — from "**Total** | | **N/20**" row
-- **P0_count**: count of `[P0]` findings
-
-### 5c. Evaluate
-
-```
-critique_pass = (score >= threshold) AND (P0_count == 0)
-audit_pass    = (score >= threshold * 0.5) AND (P0_count == 0)
-```
-
-### 5d. On PASS
-
-```
-✓ Gate passed: {score}/{max} (P0: 0)
-```
-→ advance to next chain step
-
-### 5e. On FAIL
-
-```
-⟳ Loop {n}/{max_loops}: {score}/{max}, P0={count}
-  Running: {command_list}
-```
-
-1. Collect suggested commands from P0/P1 findings
-2. If no suggestions found → use fallback mapping (see quality_gate_routing)
-3. De-duplicate, cap at 3 commands per iteration
-4. Sort: P0-suggested first
-5. Execute each: `Skill({ skill: "maestro-impeccable", args: "{cmd} {target}" })`
-   - Pass issue context: the specific findings that triggered this command are already in conversation
-6. Re-run gate command (critique/audit)
-7. Increment loop_count
-8. Append to status.json `gate_history`
-
-### 5f. On Max Loops Exceeded
-
-```
-⚠ Max iterations ({max_loops}) reached. Score: {score}/{max}, P0: {count}
-  Continuing chain with remaining issues.
-```
-→ force advance to next chain step
-
-## 6. Final Report
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Chain complete: {chain_type}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
- Critique : {score}/40 (trend: {trend_line})
- Audit    : {score}/20
- Loops    : {total_iterations}
- Commands : {executed_command_list}
-
- Status   : {PASS | PARTIAL — N issues remain}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Update status.json: `status: "completed"`, `final_scores`, `completed_at`.
-
-If issues remain → suggest: "Run `/maestro-ui-craft --chain improve {target}` to continue iteration."
-
-</execution>
-
-<quality_gate_routing>
-
-### Finding → Command Fallback Mapping
-
-When critique/audit findings lack explicit "Suggested command", map by category:
-
-| Finding Category | Command |
-|-----------------|---------|
-| Visual hierarchy, layout, spacing, alignment | layout |
-| Color, contrast, palette, monochromatic | colorize |
-| Typography, font, readability, hierarchy | typeset |
-| Animation, motion, transitions, micro-interaction | animate |
-| Copy, labels, error messages, UX writing | clarify |
-| Responsive, mobile, breakpoints, touch targets | adapt |
-| Performance, loading, speed, bundle, jank | optimize |
-| Complexity, overload, clutter, cognitive load | distill |
-| Bland, safe, generic, lacks personality | bolder |
-| Aggressive, overwhelming, loud, overstimulating | quieter |
-| Onboarding, empty state, first-run, activation | onboard |
-| Edge cases, i18n, error handling, overflow | harden |
-| Personality, memorability, joy, delight | delight |
-
-### Commands Never Auto-Selected
-
-These are structural/interactive — never picked by the refine loop:
-
-| Command | Reason |
-|---------|--------|
-| teach | Project setup (run in S_SETUP only) |
-| shape | Requires user interview |
-| craft | Full build with multiple gates |
-| live | Interactive browser mode |
-| document | Generates DESIGN.md (setup) |
-| extract | Design system extraction (setup) |
-| 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>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | error | Impeccable skill not found in project |
-| E002 | error | No intent or target specified |
-| E003 | error | Invalid --chain type |
-| E004 | error | Invalid --enhance command |
-| E005 | error | Resume session not found |
-| 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>
-- [ ] Intent classified and chain type selected
-- [ ] Context loaded (PRODUCT.md present or taught)
-- [ ] Session dir created with status.json before execution
-- [ ] All chain steps executed via Skill("maestro-impeccable", ...)
-- [ ] Quality gate evaluated with parsed scores
-- [ ] Refine loop executed when gate failed (if applicable)
-- [ ] Gate history and scores persisted to status.json
-- [ ] Final report with scores and trend presented
-- [ ] Progress tracked via TodoWrite throughout
-</success_criteria>