/maestro-impeccable

name: maestro-impeccable
disable-model-invocation: true
description: Use when designing, reviewing, refining, fixing, or codifying frontend UI with Maestro's self-contained Impeccable core
argument-hint: "[command] [target] | hooks <action> | doctor | pin|unpin <command> | --codify <path>"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
  - TodoWrite
session-mode: run
contract:
  discovery: self-described
  consumes: []
  produces: []

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

If required reading was not expanded by the host, or is no longer in context, Read it explicitly before execution.

<deferred_reading> Maestro Codify extension only — do not read these files for normal Impeccable work:

• [ui-codify.md](~/.maestro/workflows/ui-codify.md) — load when `--codify` starts
• [ui-codify-extract.md](~/.maestro/workflows/ui-codify-extract.md) — load only when extraction starts
• [ui-codify-package.md](~/.maestro/workflows/ui-codify-package.md) — load only when packaging starts
• [ui-codify-knowhow.md](~/.maestro/workflows/ui-codify-knowhow.md) — load only after the knowhow confirmation gate passes

</deferred_reading>

<purpose> Self-contained Maestro UI design command. The bundled Impeccable core owns design semantics, setup, routing, references, detector behavior, and bounded verification. Maestro adds the canonical Session/Run lifecycle, progress tracking, consistent status presentation, and the optional `--codify` extension. No separately installed `impeccable` Skill or npm runtime is required. </purpose>

<embedded_contract> The bundled core is the canonical template. Resolve its base directory in this order and Read the first existing `SKILL.md`: 1. Project-local `workflows/impeccable/SKILL.md` (Maestro source checkout/development) 2. Installed `~/.maestro/workflows/impeccable/SKILL.md`

Retain the resolved parent as `<impeccable-base>` for the entire Run. Every path in the bundled Skill and references is relative to that directory; substitute the concrete path before reading a reference or running a script.

Rules: 1. Never resolve or invoke another Skill named `impeccable`. 2. Never run `npx impeccable install`, `npx impeccable update`, or depend on an external Impeccable package during execution. 3. Load the bundled `SKILL.md`, then only the single command/reference file it routes to. Respect its deferred-reading rules. 4. Run `node <impeccable-base>/scripts/context.mjs` once per session from the user's project cwd. Do not rerun it after `init`. 5. Preserve platform routing: `audit.native.md` / `adapt.native.md` for native projects; `live` and the HTML detector are web-only. 6. Preserve bounded verification: one batched inspection/fix pass and at most one confirmation pass. Do not recreate the retired open-ended refine loop. 7. If the bundled core or a required bundled file is missing, stop with E001/E003 and repair the Maestro installation; never fetch or install another Skill as recovery. 8. Impeccable core updates ship only through Maestro source/release updates. Never offer an upstream package update during design work.

Bundled core synchronized from upstream Impeccable Skill 4.1.3 (`pbakaus/impeccable@4c5243f`) and adapted for Maestro. The bundled copy remains authoritative until Maestro updates it. </embedded_contract>

Maestro Symbol Style

Use these symbols consistently in Maestro-owned displays. Do not substitute colorful success/failure emoji.

| Meaning | Display | |---|---| | Current step / transition | `→` | | Completed prerequisite or step | `✓` | | Quality or confirmation gate | `◆` | | Bounded re-check | `↺` | | Warning / degraded mode | `⚠` | | Failure | `FAIL` | | Terminal success | `Status: DONE` | | Terminal failure | `Status: FAILED` |

Upstream machine values and required report fields remain unchanged. For an upstream degraded critique banner, normalize only the symbol presentation to `⚠ DEGRADED: single-context (<reason>)`; do not weaken or omit the degraded disclosure.

Input Routing

Parse `$ARGUMENTS` without inventing a static workflow chain.

Apply this table top-to-bottom; specific routes override the generic command route.

| Input | Route | |---|---| | `--codify <source-path> ...` / `codify <source-path> ...` | Maestro Codify extension | | `hooks <action>` | Run the bundled hooks control; load `<impeccable-base>/reference/hooks.md` | | `doctor` | Run the bundled doctor; load `<impeccable-base>/reference/doctor.md` | | `pin <command>` / `unpin <command>` | Run `<impeccable-base>/scripts/pin.mjs` | | `teach ...` | Compatibility alias for `init`; no deprecation warning | | `craft ...` | Deprecated upstream alias for ordinary new-work; display W001 once | | Legacy Maestro preset (`build`, `redesign`, `improve`, `enhance`, `launch`, `foundation`) | Treat the full text as a general design request and let current upstream routing resolve it; display W002 once; never reconstruct the retired chain | | One of the remaining commands below | Invoke Impeccable with the arguments unchanged | | No arguments | Invoke current `reference/routing.md`; show 2–3 context-aware recommendations, then the full menu; never auto-run | | Other UI design text | Pass as general Impeccable work; follow current upstream routing |

`continue`, `next`, and `-c` are not Impeccable resume commands. Run/session continuation belongs to the canonical Maestro Session/Run lifecycle in `run-mode.md`.

Current Impeccable Commands

This table is a routing index only. The bundled `workflows/impeccable/SKILL.md` and its references own the full instructions.

| Command | Category | Current meaning | |---|---|---| | `craft [feature]` | Build | Deprecated alias for ordinary new-work | | `shape [feature]` | Build | Plan UX/UI before writing code | | `init` | Build | Capture durable product context in PRODUCT.md | | `document` | Build | Generate DESIGN.md from existing project code | | `extract [target