# Commands and routing

> Single `/impeccable` skill, 23 sub-commands, Setup load order, no-argument routing, craft-floor gate, and when native command variants replace web references.

- Repository: pbakaus/impeccable
- GitHub: https://github.com/pbakaus/impeccable
- Human docs: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4
- Complete Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/llms-full.txt

## Source Files

- `skill/SKILL.src.md`
- `skill/reference/routing.md`
- `skill/reference/craft-floor.md`
- `skill/scripts/command-metadata.json`
- `skill/scripts/context-signals.mjs`
- `scripts/lib/utils.js`
- `scripts/lib/skill-categories.js`

---

---
title: "Commands and routing"
description: "Single `/impeccable` skill, 23 sub-commands, Setup load order, no-argument routing, craft-floor gate, and when native command variants replace web references."
---

Impeccable exposes **one** user-invocable skill, `impeccable`, with **23** design sub-commands listed in the Commands table of `skill/SKILL.src.md` (built to provider `SKILL.md`). Invocation is always `{{command_prefix}}impeccable [subcommand] [target]` (for example `/impeccable polish src/App.tsx`). Routing is agent-driven: Setup runs once, then the agent loads the matching `skill/reference/<command>.md` playbook (or a `.native.md` variant on native platforms). Utility surfaces (`pin`, `hooks`, `doctor`) live outside that table and do not count toward 23.

## Architecture: single skill, reference playbooks

```text
User: /impeccable [arg]
        │
        ▼
┌───────────────────────────────────────┐
│ Setup (every session, once)           │
│ 1. node …/context.mjs [--target path] │
│ 2. Load playbook (command | new-work) │
│ 3. craft-floor.md only before UI edit │
└───────────────────────────────────────┘
        │
   ┌────┴────────────────────────────┐
   │ arg empty?                      │
   ▼                                 ▼
reference/routing.md          explicit / implied command
context-aware menu            → reference/<cmd>.md
(+ context-signals.mjs)         or <cmd>.native.md
never auto-run                  on ios/android/adaptive
   │                                 │
   └──────── general design ─────────┘
            missing PRODUCT.md → init then new-work
            narrow refine → incumbent + offer init
```

| Surface | Role | Counts as design command? |
|---|---|---|
| `/impeccable <cmd>` | 23-row Commands table + `command-metadata.json` | Yes |
| `reference/new-work.md` | Shared playbook for new surfaces / replacement visual worlds | No (loaded by routing, not a table row) |
| `reference/craft-floor.md` | Quality floor + bans loaded immediately before UI edits | No |
| `reference/routing.md` | Bare `/impeccable` menu | No |
| `pin` / `hooks` / `doctor` | Maintenance utilities (SKILL body + refs, not Commands table) | No |

Source of truth for the **count of 23** is the router table in `skill/SKILL.src.md` (build validates README/plugin descriptions against that match). Each row maps to `skill/reference/<name>.md`. Metadata for pin shortcuts and argument-hint text lives in `skill/scripts/command-metadata.json` (also 23 keys, including deprecated `craft`).

## Commands table (23)

Categories below match the SKILL Commands table (user-facing labels). Build-time argument-hint grouping uses a separate map in `scripts/lib/skill-categories.js` (`create` / `evaluate` / `refine` / `simplify` / `harden` / `system`); `craft` is intentionally unmapped there so it stays out of the generated hint while still routing.

| Command | Category | Reference | Notes |
|---|---|---|---|
| `craft [feature]` | Build | `craft.md` | Deprecated alias for ordinary new-work; no extra behavior |
| `shape [feature]` | Build | `shape.md` | Task discovery; enters new-work only for visual-world decisions |
| `init` | Build | `init.md` | Writes PRODUCT.md; `teach` is an alias |
| `document` | Build | `document.md` | Generate DESIGN.md from code |
| `extract [target]` | Build | `extract.md` | Tokens / components into the system |
| `critique [target]` | Evaluate | `critique.md` | UX review + scoring |
| `audit [target]` | Evaluate | `audit.md` · **native:** `audit.native.md` | Technical quality report |
| `polish [target]` | Refine | `polish.md` | Pre-ship quality pass |
| `bolder [target]` | Refine | `bolder.md` | Amplify bland designs |
| `quieter [target]` | Refine | `quieter.md` | Tone down aggressive UI |
| `distill [target]` | Refine | `distill.md` | Strip to essence |
| `harden [target]` | Refine | `harden.md` | Errors, i18n, edge cases |
| `onboard [target]` | Refine | `onboard.md` | First-run / empty states |
| `animate [target]` | Enhance | `animate.md` | Motion (platform refs on native) |
| `colorize [target]` | Enhance | `colorize.md` | Strategic color |
| `typeset [target]` | Enhance | `typeset.md` | Type hierarchy |
| `layout [target]` | Enhance | `layout.md` | Spacing / rhythm |
| `delight [target]` | Enhance | `delight.md` | Memorable touches |
| `overdrive [target]` | Enhance | `overdrive.md` | Ambitious visual techniques |
| `clarify [target]` | Fix | `clarify.md` | UX copy |
| `adapt [target]` | Fix | `adapt.md` · **native:** `adapt.native.md` | Devices / contexts |
| `optimize [target]` | Fix | `optimize.md` | UI performance |
| `live` | Iterate | `live.md` | Browser variant mode (**web only**) |

Full argument hints and catalog copy: [Skill commands reference](/skill-commands-reference).

### Placeholders and suggestion lists

| Placeholder / list | Built from | Purpose |
|---|---|---|
| `{{command_hint}}` in skill frontmatter `argument-hint` | Keys of `command-metadata.json` grouped by `SKILL_CATEGORIES` | Autocomplete-style hint on the parent skill |
| `{{available_commands}}` | `IMPECCABLE_SUB_COMMANDS` in `scripts/lib/utils.js` (subset: design refine/evaluate/enhance names, not `init`/`document`/`live`/etc.) | In-body “next command” suggestions after transforms |
| `pin.mjs` `VALID_COMMANDS` | Same 23 names (incl. `craft`) | Standalone `/audit`-style shortcuts |

## Setup load order

Setup is non-optional and runs once per session before design work.

<Steps>
<Step title="Run context.mjs">
Execute `node {{scripts_path}}/context.mjs` once (keep cwd at the user project). Optional: `--target <path-or-route>` for a named surface. Loads PRODUCT.md, DESIGN.md, the matching surface brief, and inlines native platform guidance when `## Platform` is `ios`, `android`, or `adaptive`. Follow emitted directives; do not rerun. After `init` writes PRODUCT.md mid-session, resume **without** rerunning context; init loads the native platform reference itself for the platform it recorded.
</Step>
<Step title="Load the owning playbook">
Before acting: load the Commands-table reference for an explicit or clearly implied sub-command, **or** `reference/new-work.md` for a new surface / replacement visual world. Then inspect the target and at least one incumbent visual source (tokens, theme, CSS, component, or asset).
</Step>
<Step title="Load craft-floor only when editing UI">
After analysis and direction are resolved, load `reference/craft-floor.md` immediately before editing UI. Skip it for planning-only work.
</Step>
</Steps>

<Note>
`context.mjs` may emit `NO_PRODUCT_MD`, platform `WARNING` for unrecognized `## Platform` values (fallback: web), `CONTEXT_STALE` (Tier-1 drift; act only as directed—do not repair drift as a side quest of a design task unless severity is `auto`), and web-only detector/hook guidance.
</Note>

## Routing rules

From the Commands section of SKILL:

| Condition | Agent behavior |
|---|---|
| **No argument** | Load `reference/routing.md`; present a context-aware menu. **Never auto-run** a command. |
| **Explicit or clearly implied command** | Load its reference; on native platforms, load the native variant when one exists. Ask once if two commands fit. |
| **Otherwise (general design)** | Treat as general design work. Missing PRODUCT.md for a new surface / replacement world → `init` then new-work. Narrow refinement of existing code proceeds on the incumbent implementation as `context.mjs` directs; offer `init` afterward rather than blocking. |
| **Aliases** | `teach` → `init`. `craft` → ordinary new-work (deprecated, no extra steps). `shape` owns discovery, then new-work only for visual-world / surface-concept decisions. |

### No-argument path (`routing.md` + `context-signals.mjs`)

1. Setup has already run `context.mjs`.
2. If output reported `NO_PRODUCT_MD`: lead with `/impeccable init` (one-line why), still show the full menu; do not silently enter init.
3. Else run `node {{scripts_path}}/context-signals.mjs` once and reason over its JSON (no scores; agent ranks).
4. Lead with **2–3** highest-value commands + one-line reasons, then the full Commands table by category.
5. Optionally, if `scan.targets` is non-empty and platform is not native: run `node {{scripts_path}}/detect.mjs --json <targets>` once and fold hits into picks. On error or slow trees, skip; never block the menu.

#### `context-signals.mjs` JSON shape

| Field | Type | Use in menu reasoning |
|---|---|---|
| `setup.hasProduct` / `hasDesign` / `hasCode` | boolean | Missing design + has code → lead `document` |
| `setup.platform` | `web` \| `ios` \| `android` \| `adaptive` \| null | Gate `live` / detect; native skips HTML tooling |
| `critique.latest` | object \| null | `null` → offer critique; low `score` / non-zero `p0`/`p1` → polish or re-critique |
| `git.changedFiles` | string[] | Scope audit/polish to those files |
| `devServer.running` / `ports` | boolean / number[] | Lead with `live` only when running (web) |
| `scan.targets` / `scan.via` | string[] / `git-changes`\|`source-dir`\|`html`\|`root`\|null | Detect input; dirty markup wins |

Signals probes are best-effort and always print valid JSON. The script does **not** run the detector or score commands.

### Example bare invocation flow

```text
/impeccable
  → Setup: context.mjs
  → if NO_PRODUCT_MD → recommend init
  → else context-signals.mjs
  → optional detect.mjs --json <scan.targets>  (web only)
  → present 2–3 picks + full menu
  → wait for user confirmation
```

## Craft-floor gate

`reference/craft-floor.md` is the quality floor: verify checks (contrast, depth, spacing, type, motion, states, browser surfaces, copy, brief coverage) and refuse lists (scaffold defaults and surface habits). Load it **after** direction is settled and **immediately before** editing UI—not for planning-only work.

| Rule | Behavior |
|---|---|
| Brief wins | Pinned aesthetics override floor defaults; habit does not |
| Hook active | Design hook already enforces mechanical checks; act on findings instead of re-auditing each rule |
| Planning | Do not load craft-floor for analysis-only steps |
| Detector blind spots | Floor covers reflexes the detector does not catch |

When no automatic design hook is active and platform is web, `context.mjs` may emit `MANUAL_DETECTOR_REQUIRED` so the agent runs `detect.mjs` once after UI changes.

## Native command variants

Platform is orthogonal to visitor mode. PRODUCT.md `## Platform` is a bare value: `web` (default if missing), `ios`, `android`, or `adaptive`. Unrecognized values fall back to web with a WARNING. Setup inlines `reference/ios.md` and/or `reference/android.md` for native platforms.

| Situation | Reference loaded |
|---|---|
| `audit` + platform web | `audit.md` only |
| `audit` + `ios` / `android` / `adaptive` | **`audit.native.md` instead of** `audit.md` |
| `adapt` + platform web | `adapt.md` only |
| `adapt` + native | **`adapt.native.md` instead of** `adapt.md` |
| Other commands on native | Shared command ref; per-OS detail from platform refs already loaded by Setup (e.g. motion in `animate`) |
| `live`, bundled `detect.mjs`, design hook | **Web only** — do not lead with or apply on native platforms |

Web files for `audit` and `adapt` open with a one-line web-only guard that redirects native readers to the `.native.md` variant. One native variant covers all three native platform values; OS-specific rules stay in `ios.md` / `android.md`. Report skeleton changes for audit must stay in sync across web and native files.

```text
setup.platform
  web      → reference/audit.md | adapt.md | live OK | detect OK
  ios      → audit.native.md | adapt.native.md | + ios.md   | no live/detect/hook scan
  android  → audit.native.md | adapt.native.md | + android.md
  adaptive → audit.native.md | adapt.native.md | + ios.md + android.md
```

## Utilities outside the 23

| Invocation | Load | Role |
|---|---|---|
| `node {{scripts_path}}/pin.mjs <pin\|unpin> <command>` | — | Create/remove standalone harness shortcuts (e.g. `/audit` → `/impeccable audit`) |
| `/impeccable hooks <on\|off\|status|…>` | `reference/hooks.md` | Design detector hook for the project |
| `/impeccable doctor` | `reference/doctor.md` | Schema/config/proxy drift report and `--fix` for `auto` findings |

These are **not** in `IMPECCABLE_SUB_COMMANDS`, `command-metadata.json` command menus as design entries (doctor is excluded), `SKILL_CATEGORIES` design rows, or the 23-row table. Do not route them as craft commands.

## Constraints and failure modes

| Case | Expected behavior |
|---|---|
| Two commands fit equally | Ask once; do not run both |
| Auto-running after bare `/impeccable` | Incorrect — menu only until user confirms |
| Native project + `live` / detect lead | Incorrect — skip; browser overlay and HTML rules do not apply |
| Loading craft-floor during pure planning | Incorrect — load only before UI edit |
| Replacing design world via polish | Incorrect — redesign uses new-work and replaces DESIGN.md; refinement preserves identity |
| Acting on every `CONTEXT_STALE` finding during craft | Incorrect — report unless user asks; only `auto` applies on next write |
| Adding a 24th design command | Update SKILL table, `IMPECCABLE_SUB_COMMANDS` if needed, `VALID_COMMANDS`, `command-metadata.json`, `SKILL_CATEGORIES`, pin rules, and count validators — see contributing docs |

## Related pages

<CardGroup>
<Card title="Modes and platform" href="/modes-and-platform">
Visitor modes and orthogonal platform values, including native reference loading.
</Card>
<Card title="Skill commands reference" href="/skill-commands-reference">
Catalog of sub-commands, argument hints, categories, and native variants.
</Card>
<Card title="Run design commands" href="/run-design-commands">
Invoke evaluate and refine commands with targets and verification signals.
</Card>
<Card title="Initialize product context" href="/init-and-document">
Init interview, PRODUCT.md Platform, and document DESIGN.md.
</Card>
<Card title="Pin shortcuts" href="/pin-shortcuts">
Standalone harness shortcuts that redirect to `/impeccable <command>`.
</Card>
<Card title="Doctor" href="/doctor">
Artifact drift report and auto fixes outside the design menu.
</Card>
</CardGroup>