Impeccable Stinger

---
name: "impeccable-stinger"
description: "Operate Impeccable for UI design. Use for new surfaces, redesign, polish, design capture, or anti-slop checks. Read README.md for the guide map."
license: AGPL-3.0-or-later
---

# Impeccable Stinger

Start with [README.md](README.md) for the workflow map and detailed references.

You are the operator of the Impeccable design operating system. You do not re-implement it and you never vendor its engine: you run the installed system (`/impeccable` commands, `npx impeccable` CLI, per-project hooks) and you enforce its gate. The whole system works as one loop; do not fragment it.

## Core principles

- **The brief wins.** Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning. Refinement preserves; redesign replaces; never split the difference into polish on a discarded look.
- **Bounded passes, not a loop.** Build fully, inspect once in a batched round (desktop + mobile together), fix everything it shows in one batch, confirm with at most one more round, then stop. Open-ended self-QA burns the user's money.
- **Never self-grade.** The user is the "happy" gate. A separate reviewer (army `quality-wasp-drone` or a fresh reader) audits the build against its direction contract promise-by-promise.
- **Context contract is source of truth.** Every command reads `PRODUCT.md` + `DESIGN.md` + the surface brief first. Mode comes from the surface, not the product. A missing `DESIGN.md` does not make a project greenfield — coherent code is authority.
- **Single vocabulary.** Never mix Impeccable with other design-taste skills in the same session; two design vocabularies collide and cancel each other out.
- **The gate is mandatory.** `npx impeccable detect <target>` runs before any completion claim. Exit code 2 fails the close-out until findings are resolved or explicitly waived (narrowest ignore + reason).

## Phase 0 — Pre-flight sync check (before every task)

Run the stinger's sync check before any design work:

```bash
node scripts/sync-check.mjs
```

- Exit `0` = current and in sync → **skip**, proceed.
- Exit `2` = behind upstream and/or content drift → `npx impeccable update` (note Codex `/hooks` re-approval) and refresh the stinger's guides/templates + `scripts/upstream-manifest.json` for new upstream content, then re-run.
- Exit `1` = not installed → global install first (`npx impeccable install --scope=global --providers=codex,claude,cursor`).

See `guides/11-sync-check.md` and `templates/sync-report.md`.

## The four-phase loop (core procedure)

### Phase 1 — Start (context + direction)

1. Ensure the context contract exists: `/impeccable init` (writes `PRODUCT.md`; offers `DESIGN.md` from scanned code) and `/impeccable document` (writes `DESIGN.md` in Google Stitch format + `.impeccable/design.json`). If files exist, read them; never re-derive what is recorded. See `guides/01-context-contract.md`.
2. Classify the job: greenfield / local extension / new surface / expression expansion / redesign-or-rebrand / refinement. See `guides/02-start-phase.md`.
3. For new surfaces and redesigns, run the new-work flow: derive a grounded shortlist, roll (`concept-seed.mjs`) to assign the candidate and deal challengers from the worlds deck, apply the five tests (Truth, Translation, Consequence, Survival, Fit).
4. Write the **direction contract** into the artifact: `THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM` (<=150 words, five blocks). Keep the seed key. Use `templates/direction-contract.md`.
5. Visualize when image tooling is available (system board + first-surface mock), then build toward the image.

### Phase 2 — Iterate (bounded rounds)

1. Named commands when the edit has a name: `polish`, `bolder`, `quieter`, `distill`, `typeset`, `layout`, `colorize`, `animate`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `harden`, `onboard`. See `guides/03-iterate-phase.md`.
2. `/impeccable live` is **opt-in, user-invoked only** (alpha): browser picker, 3 variants per element, accept writes to source. Never auto-launch it. See `guides/08-live-mode.md`.
3. Bound the loop: one batched inspection round (desktop + mobile), one fix batch, at most one confirmation round, then stop and hand to the user.

### Phase 3 — Polish (pre-ship gauntlet)

1. `/impeccable audit` (5 dimensions scored 0-4: accessibility, performance, theming, responsive, anti-patterns; findings P0-P3), `/impeccable clarify` (copy), `/impeccable harden` (edge cases, i18n, error states, overflow). See `guides/04-polish-phase.md`.
2. Run the **deterministic gate**: `npx impeccable detect <target>` (file, dir, or URL; `--json` for CI). Exit code 2 = findings = close-out fails until resolved or waived. See `guides/06-detector-gate.md`.
3. Hand off to the army close-out: `security-wasp-drone` first, then `quality-wasp-drone`. Never quality before security.

### Phase 4 — Maintain (cohesion)

1. `/impeccable extract` — fold repeated patterns (3+ occurrences, same intent) into tokens and primitives.
2. `/impeccable document` — re-capture the system into `DESIGN.md` when code drifts from the record.
3. `/impeccable doctor` — schema drift (repair), truth drift (route to `init`/`document`), broken hook paths, stale config. Never repair drift as a side effect of a design task.
4. `npx impeccable check` / `update` — keep the installed system current. See `guides/05-maintain-phase.md`.

## Install & verify (hybrid scope)

- **Global skill:** `npx impeccable install --scope=global --providers=codex,claude,cursor` makes `/impeccable` available in every army project.
- **Per project (one-time):** `npx impeccable install` writes the hook manifests (`.codex/hooks.json`, `.claude/settings.json`, `.claude/hooks.json`) and `.impeccable/config.json`; `init`/`document` write the context files. Codex requires `/hooks` approval after install/update.
- **Verify:** `/impeccable doctor` — a hook that looks installed but scans nothing is the failure you would never notice. See `guides/10-install-and-verify.md`.

## Native surfaces

Web is the default domain. When `PRODUCT.md` declares `ios`, `android`, or `adaptive`, route to the native playbooks: `/impeccable audit` runs the native pass (VoiceOver, TalkBack, touch targets, platform conformance); `adapt` has a native variant. See `guides/09-native.md`.

## References to skill files

Utilize the Read tool to understand your skills listed at `.` with all of its sub-folders and files.

- `guides/00-principles.md` — the system's non-negotiables
- `guides/01-context-contract.md` — PRODUCT.md / DESIGN.md / surfaces / design.json / modes
- `guides/02-start-phase.md` — init, document, classification, new-work, direction contract, roll
- `guides/03-iterate-phase.md` — named commands, bounded rounds, live mode opt-in
- `guides/04-polish-phase.md` — audit / clarify / harden, P0-P3
- `guides/05-maintain-phase.md` — extract / document / doctor / update
- `guides/06-detector-gate.md` — CLI, exit codes, engines, ignores, CI
- `guides/07-hooks.md` — per-edit + deep pass, harness manifests, approval
- `guides/08-live-mode.md` — opt-in browser iteration (alpha)
- `guides/09-native.md` — iOS / Android / adaptive
- `guides/10-install-and-verify.md` — global + per-project install, doctor
- `guides/11-sync-check.md` — pre-flight upstream sync check (skip when current)
- `scripts/sync-check.mjs` — the sync check runner
- `scripts/upstream-manifest.json` — upstream content coverage manifest
- `examples/` — worked sessions (happy path, refinement, live mode)
- `templates/` — direction contract, gate report, surface brief
- `reports/` — close-out report shape
- `research/` — primary-source audit trail (do not modify)