maestro-flow 0.3.49 → 0.4.1

package/.claude/commands/maestro-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>

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

@@ -1,171 +0,0 @@
----
-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|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
----
-
-Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. Automatically harvests design knowledge to `.workflow/knowhow/` for cross-session accumulation.
-
-## Setup
-
-Before any design work or file edits:
-
-1. Load context (PRODUCT.md / DESIGN.md) via the loader script.
-2. Identify the register and load the matching register reference (brand.md or product.md).
-3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** Non-negotiable: `craft` without `craft.md` loaded means skipping the shape-and-confirm step.
-
-Skipping these produces generic output that ignores the project.
-
-### 1. Context gathering
-
-Two files, case-insensitive. PRODUCT.md and DESIGN.md are stored at `.workflow/impeccable/`.
-
-- **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles.
-- **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components.
-
-Both are registered in the spec system under category `ui` via `spec add`. Load with:
-
-```bash
-maestro spec load --category ui
-```
-
-This surfaces all design context (product + visual) from `.workflow/specs/ui-conventions.md`. If specs are not initialized, fall back to the legacy loader:
-
-```bash
-maestro impeccable load-context
-```
-
-Consume the full output. Never pipe through `head`, `tail`, `grep`, or `jq`.
-
-If the output is already in this session, don't re-run. Exceptions: you just ran `teach` or `document` (they rewrite the files and re-register specs), or the user manually edited one.
-
-`live` already warms context via `maestro impeccable live`. If you've run `live`, skip context loading.
-
-If PRODUCT.md is missing/empty/placeholder (`[TODO]`, <200 chars): run `teach`, then resume the original task. If the original task was `craft`, resume into `shape` first.
-
-If DESIGN.md is missing: nudge once per session (*"Run `/maestro-impeccable document` for more on-brand output"*), then proceed.
-
-### 2. Register
-
-Every design task is **brand** (marketing, landing, campaign: design IS the product) or **product** (app UI, admin, dashboard: design SERVES the product).
-
-Identify before designing. Priority: (1) cue in the task; (2) surface in focus; (3) `register` field in PRODUCT.md. First match wins.
-
-Load the matching reference: [brand.md](~/.maestro/workflows/impeccable/brand.md) or [product.md](~/.maestro/workflows/impeccable/product.md).
-
-## Shared design laws
-
-Apply to every design, both registers. Match complexity to vision. Vary across projects; never converge on the same choices.
-
-### Color
-
-- Use OKLCH. Reduce chroma near lightness extremes.
-- Never `#000` or `#fff`. Tint neutrals toward brand hue (chroma 0.005-0.01).
-- Pick **color strategy** first: Restrained → Committed → Full palette → Drenched.
-
-### Theme
-
-Write one sentence of physical scene before choosing dark/light. Run the sentence, not the category.
-
-### Typography
-
-- Body line length: 65-75ch.
-- Hierarchy: scale + weight contrast (≥1.25 ratio).
-
-### Layout
-
-- Vary spacing for rhythm. Cards only when truly best affordance. No nested cards.
-
-### Motion
-
-- No CSS layout property animations. Ease-out with exponential curves.
-
-### Absolute bans
-
-Match-and-refuse: side-stripe borders, gradient text, glassmorphism as default, hero-metric template, identical card grids, modal as first thought.
-
-### Copy
-
-Every word earns its place. No em dashes.
-
-### AI slop test
-
-Two-altitude category-reflex check. If someone could guess theme+palette from category alone, or guess aesthetic family from category+anti-references, rework until neither is obvious.
-
-See [~/.maestro/workflows/impeccable/brand.md](~/.maestro/workflows/impeccable/brand.md) for reflex-reject aesthetic lanes.
-
-## Commands
-
-| Command | Category | Description | Reference |
-|---|---|---|---|
-| `craft [feature]` | Build | Shape, then build end-to-end | [~/.maestro/workflows/impeccable/craft.md](~/.maestro/workflows/impeccable/craft.md) |
-| `shape [feature]` | Build | Plan UX/UI before code | [~/.maestro/workflows/impeccable/shape.md](~/.maestro/workflows/impeccable/shape.md) |
-| `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) |
-| `bolder [target]` | Refine | Amplify bland designs | [~/.maestro/workflows/impeccable/bolder.md](~/.maestro/workflows/impeccable/bolder.md) |
-| `quieter [target]` | Refine | Tone down aggressive designs | [~/.maestro/workflows/impeccable/quieter.md](~/.maestro/workflows/impeccable/quieter.md) |
-| `distill [target]` | Refine | Strip to essence | [~/.maestro/workflows/impeccable/distill.md](~/.maestro/workflows/impeccable/distill.md) |
-| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [~/.maestro/workflows/impeccable/harden.md](~/.maestro/workflows/impeccable/harden.md) |
-| `onboard [target]` | Refine | First-run flows, empty states | [~/.maestro/workflows/impeccable/onboard.md](~/.maestro/workflows/impeccable/onboard.md) |
-| `animate [target]` | Enhance | Add purposeful motion | [~/.maestro/workflows/impeccable/animate.md](~/.maestro/workflows/impeccable/animate.md) |
-| `colorize [target]` | Enhance | Add strategic color | [~/.maestro/workflows/impeccable/colorize.md](~/.maestro/workflows/impeccable/colorize.md) |
-| `typeset [target]` | Enhance | Improve typography | [~/.maestro/workflows/impeccable/typeset.md](~/.maestro/workflows/impeccable/typeset.md) |
-| `layout [target]` | Enhance | Fix spacing, rhythm, hierarchy | [~/.maestro/workflows/impeccable/layout.md](~/.maestro/workflows/impeccable/layout.md) |
-| `delight [target]` | Enhance | Add personality | [~/.maestro/workflows/impeccable/delight.md](~/.maestro/workflows/impeccable/delight.md) |
-| `overdrive [target]` | Enhance | Push past conventional limits | [~/.maestro/workflows/impeccable/overdrive.md](~/.maestro/workflows/impeccable/overdrive.md) |
-| `clarify [target]` | Fix | Improve UX copy and labels | [~/.maestro/workflows/impeccable/clarify.md](~/.maestro/workflows/impeccable/clarify.md) |
-| `adapt [target]` | Fix | Adapt for devices/screens | [~/.maestro/workflows/impeccable/adapt.md](~/.maestro/workflows/impeccable/adapt.md) |
-| `optimize [target]` | Fix | Fix UI performance | [~/.maestro/workflows/impeccable/optimize.md](~/.maestro/workflows/impeccable/optimize.md) |
-| `live` | Iterate | Browser-based variant generation | [~/.maestro/workflows/impeccable/live.md](~/.maestro/workflows/impeccable/live.md) |
-
-### Routing rules
-
-1. **No argument**: render command menu grouped by category.
-2. **First word matches command**: load its reference file, follow instructions. Rest is target.
-3. **No match**: general design invocation with full argument as context.
-
-## Harvest — Design Knowledge Accumulation
-
-After every command execution (except `live`), harvest design decisions into `.workflow/knowhow/` for cross-session reuse. Skip if `--skip-harvest` flag is set.
-
-### Harvest routing
-
-| Command | Type | Prefix | Extract |
-|---------|------|--------|---------|
-| craft | decision + asset | DCS- + AST- | Design decisions + tokens (dual entry) |
-| shape | decision | DCS- | Key decisions from brief |
-| 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 |
-| bolder/quieter/distill | decision | DCS- | Direction decisions |
-| harden/onboard | tip | TIP- | Patterns applied |
-| animate | decision | DCS- | Animation strategy |
-| colorize | decision | DCS- | Color strategy + OKLCH values |
-| typeset | decision | DCS- | Typography decisions |
-| layout | decision | DCS- | Layout/spacing decisions |
-| delight/overdrive | decision | DCS- | Creative decisions |
-| clarify/adapt/optimize | tip | TIP- | Fix points |
-
-### Harvest execution
-
-1. **Determine type** from routing table.
-2. **Extract** from output files (document, critique) or conversation context (others).
-3. **Write knowhow**:
-   - DCS-/TIP-/REF- → `store_knowhow` MCP: `{operation: "add", type, title: "maestro-impeccable <cmd>: <description>", body, tags: ["impeccable", "<cmd>", ...]}`
-   - AST- → Write to `.workflow/knowhow/AST-impeccable-<slug>-<YYYYMMDD>.md` with YAML frontmatter (`category: ui`)
-4. **Spec index** (DCS-/AST- only): `maestro spec add ui "<title>" "<summary>" --keywords impeccable,<cmd>,... --ref knowhow/<file>`
-5. **Report**: one-line summary with knowhow ID.