/maestro-impeccable

name: maestro-impeccable
disable-model-invocation: true
description: Use when designing, auditing, polishing, improving, or codifying frontend UI — websites, dashboards, landing pages, components, design systems
argument-hint: "build|redesign|improve|enhance|launch|harden|foundation|live [target] [--codify <path>]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - Skill
  - AskUserQuestion
  - TodoWrite
session-mode: run
contract:
  discovery: self-described
  consumes: []
  produces: []

<required_reading> @~/.maestro/workflows/run-mode.md </required_reading>

<deferred_reading> Codify mode only (read when `--codify` and the corresponding phase starts):

• [ui-codify.md](~/.maestro/workflows/ui-codify.md) — read always in codify mode (main workflow orchestrator)
• [ui-codify-extract.md](~/.maestro/workflows/ui-codify-extract.md) — read when Codify Phase 2 starts (style extraction with 3 agents)
• [ui-codify-package.md](~/.maestro/workflows/ui-codify-package.md) — read when Codify Phase 3 starts (reference package generation)
• [ui-codify-knowhow.md](~/.maestro/workflows/ui-codify-knowhow.md) — read when Codify Phase 4 starts (knowledge asset generation)

</deferred_reading>

<purpose> UI design command: direct single-command, chain multi-step with quality gates, codify a design system from existing code, or search design knowledge. Parse input → prerequisites → read workflow file → execute → track. </purpose>

Input

$ARGUMENTS first word determines mode:

| First Word | Mode | |------------|------| | `--codify` / `codify` | Codify — extract design system from existing code (see `<codify_mode>`) | | Known command (see routing table) | Direct |

> Disambiguation for overlapping names (`harden`, `live`): bare keyword without target → Chain; keyword + explicit target/path → Direct. Override: `--chain` forces Chain, `--direct` forces Direct.

| Chain name: build, redesign, improve, enhance, launch, harden, foundation, live | Chain | | continue / next / -c | Resume | | search | Search: `maestro impeccable search "$REST"` | | Free text (any) | Free Text Routing (3-layer system below) | | (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 step names below reuse Command Routing names but resolve through the chain runner. To avoid ambiguity with Direct command invocation, internal display, todo items, and session status records always tag chain steps with the `impeccable:` prefix (e.g. `impeccable:craft`, `impeccable:critique`). The bare names in this table refer to the workflow file at `~/.maestro/workflows/impeccable/{name}.md` that the chain step reads.

| Chain | Steps | Scenario | |-------|-------|----------| | build | teach? → explore? → shape → craft → critique → [refine] → audit → polish | New from scratch | | redesign | document → explore → shape → craft → critique → [refine] → audit → polish | Redesign existing code | | improve | critique → [refine] → polish → audit | Iterative improvement | | enhance | {cmd...} → critique → [refine] → polish | Targeted enhancement (multi-command) | | launch | harden → adapt → optimize → audit → polish | Full production readiness | | harden | harden → audit → polish | Edge case hardening | | foundation | teach? → explore → document → extract | Design system setup | | live | live | Real-time iteration |

• `?` = conditional: teach if PRODUCT.md missing; explore if