maestro-impeccable

> **Plan tracking**: codex 无 TaskCreate/TaskUpdate/TodoWrite 任务板。进度清单用 `update_plan({ explanation?, plan: [{ step, status }] })` 维护（整体提交步骤数组，status: `pending` | `in_progress` | `completed`），权威状态始终在 session 工件中；依赖/认领（addBlockedBy/owner）是工件字段，不是工具参数。

<required_reading>
@~/.maestro/workflows/run-mode.md
@~/.maestro/workflows/codex-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>
Maestro adapter for the current installed `impeccable` skill. Impeccable 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.
</purpose>

<upstream_contract>
The installed Impeccable skill is the canonical template. First resolve and invoke it through the `Skill` tool with name `impeccable`; its loaded base directory owns `SKILL.md`, `reference/`, and `scripts/`.

If Skill resolution is unavailable, try these fallbacks in order and Read the first existing `SKILL.md`; its parent directory becomes the skill base directory:
1. Project-local `.claude/skills/impeccable/SKILL.md`
2. User-level `~/.claude/skills/impeccable/SKILL.md`

Rules:
1. Never use the retired copied templates under `~/.maestro/workflows/impeccable/{command}.md` for normal execution.
2. Never copy `skill/SKILL.src.md` directly: it is a build source with unresolved provider placeholders.
3. Load the installed `SKILL.md`, then only the single command/reference file it routes to. Respect its deferred-reading rules.
4. Run the skill's context setup once per session from the loaded skill base directory. Do not rerun it after `init`.
5. Preserve upstream platform routing: `audit.native.md` / `adapt.native.md` for native projects; `live` and the HTML detector are web-only.
6. Preserve upstream bounded verification: one batched inspection/fix pass and at most one confirmation pass. Do not recreate the retired open-ended refine loop.
7. Only when Skill resolution and both fallback paths fail, stop with E001. Recommend `npx impeccable install` (or Maestro's Impeccable add-on installer). Do not silently install or vendor it.
8. If the user explicitly asks to update the installed skill, use `npx impeccable update`; do not update it as a side effect of design work.

Baseline checked against upstream Impeccable Skill 4.1.2. The installed skill remains authoritative when newer.
</upstream_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>` | Invoke Impeccable hooks control; load `reference/hooks.md` |
| `doctor` | Invoke Impeccable doctor; load `reference/doctor.md` |
| `pin <command>` / `unpin <command>` | Invoke the installed skill's pin script |
| `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 installed Skill 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]` | Build | Pull reusable tokens and components into a design system |
| `critique [target]` | Evaluate | UX design review with applicable heuristic scoring |
| `audit [target]` | Evaluate | Technical a11y, performance, and responsive checks |
| `polish [target]` | Refine | Final bounded quality pass before shipping |
| `bolder [target]` | Refine