maestro-flow 0.3.48 → 0.4.1

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

@@ -1,364 +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>] [-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.
-
-Prerequisite: maestro-impeccable skill available (auto-discovered by harness).
-
-Session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
-</purpose>
-
-<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
-</context>
-
-<chains>
-
-### Chain Definitions
-
-| Chain | Sequence | Gate Condition |
-|-------|----------|----------------|
-| **build** | teach? → 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
-- `[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 |
-| 改进, 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_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_GATE       WHEN: current step is gate command (critique/audit)
-  → S_CHAIN      WHEN: step is normal command → execute → advance
-  → S_REPORT     WHEN: all steps complete
-
-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_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`.
-
-**Rules:**
-- `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
-
-## 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 |
-
-</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 |
-</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/commands/maestro-ui-design.md

@@ -1,104 +0,0 @@
----
-name: maestro-ui-design
-description: Generate UI design prototypes, select and solidify as code
-argument-hint: "<phase|topic> [--styles N] [--stack <stack>] [--targets <pages>] [--layouts N] [--refine] [--persist] [--full] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Generate UI design prototypes for a phase or topic. Two workflow paths, auto-selected by skill availability:
-
-1. **Primary (ui-style.md):** Delegates design to ui-ux-pro-max skill. Generates multiple style variants via `--design-system`, user selects, solidifies as code reference. Lightweight and fast.
-2. **Fallback (ui-design.md):** Self-contained 4-layer pipeline (style → animation → layout → assembly) with 6D attribute space, OKLCH tokens, layout templates, and full prototype matrix. Used when ui-ux-pro-max is unavailable or `--full` is requested.
-
-Both paths produce the same output contract: MASTER.md + design-tokens.json + animation-tokens.json + selection.json for downstream plan/execute consumption.
-
-Position in pipeline: analyze -> **ui-design** -> plan -> execute -> verify
-</purpose>
-
-<deferred_reading>
-- [ui-style.md](~/.maestro/workflows/ui-style.md) — read when SKILL_PATH found (primary path)
-- [ui-design.md](~/.maestro/workflows/ui-design.md) — read when SKILL_PATH empty or --full (fallback path)
-- [index.json](~/.maestro/templates/index.json) — read when updating phase metadata
-- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
-</deferred_reading>
-
-<context>
-$ARGUMENTS — phase number for phase mode, topic text for scratch mode, with optional flags.
-
-Flags, workflow routing, scope modes, and output artifacts defined in the routed workflow (ui-style.md or ui-design.md).
-
-**Phase mode** (number): resolves phase directory, reads context.md/brainstorm for requirements.
-**Scratch mode** (text): creates `.workflow/scratch/{YYYYMMDD}-ui-design-{slug}/` for standalone exploration.
-</context>
-
-<execution>
-## 1. Load UI Specs
-
-Load project UI conventions before generating designs:
-
-```bash
-maestro spec load --category ui
-```
-
-If specs not initialized, continue without — the workflow still produces valid output.
-
-## 2. Workflow Routing
-
-Detect ui-ux-pro-max skill availability and route to the appropriate workflow:
-
-- **`--full` flag present** → Follow '~/.maestro/workflows/ui-design.md' completely (forced full pipeline)
-- **ui-ux-pro-max found** → Follow '~/.maestro/workflows/ui-style.md' completely (lightweight delegation)
-- **ui-ux-pro-max not found** → Follow '~/.maestro/workflows/ui-design.md' completely (self-contained fallback)
-
-Skill detection logic, report format, and complete pipeline steps defined in the routed workflow file.
-
-**Next-step routing on completion:**
-- Plan with design reference → /maestro-plan {phase}
-- Refine selected design → /maestro-ui-design {phase} --refine
-- Analyze before planning → /maestro-analyze {phase}
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | Phase or topic argument required | parse_input |
-| E002 | error | Phase directory not found | parse_input |
-| E003 | error | Python not available (both paths need Python for ui-ux-pro-max or agent fallback) | setup |
-| E004 | error | --refine requires existing design-ref/ | parse_input |
-| W001 | warning | Design system generation returned partial results | generate |
-| W002 | warning | Prototype rendering failed for one variant | render |
-| W003 | warning | No context.md found, using phase goal only | context |
-| W004 | warning | ui-ux-pro-max not found, falling back to full pipeline | routing |
-</error_codes>
-
-<success_criteria>
-**Both paths (common):**
-- [ ] UI specs loaded via `spec load --category ui` (if available)
-- [ ] Requirements extracted from phase context (context.md, brainstorm, spec, or user input)
-- [ ] N style variants generated with contrasting design directions
-- [ ] User selected preferred variant (or auto-selected in -y mode)
-- [ ] MASTER.md written with complete design system specification
-- [ ] design-tokens.json written with production-ready tokens (OKLCH colors, component_styles)
-- [ ] animation-tokens.json written (duration, easing, transitions, keyframes)
-- [ ] selection.json recorded with choice metadata
-- [ ] index.json updated with design_ref status
-
-**ui-style.md path (primary):**
-- [ ] ui-ux-pro-max --design-system called with product/industry/style keywords
-- [ ] Tokens extracted from ui-ux-pro-max output into structured JSON
-
-**ui-design.md path (--full or fallback):**
-- [ ] 6D attribute space used for maximum contrast between variants
-- [ ] Layout templates generated per target (dom_structure + css_layout_rules)
-- [ ] HTML prototypes assembled: styles x layouts x targets
-- [ ] compare.html generated as interactive matrix viewer
-</success_criteria>
-</output>

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

@@ -1,169 +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 · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · teach|document|extract|live] [target] [--skip-harvest] [-y]"
-allowed-tools:
-  - 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) |
-| `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 |
-| 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.