# Impeccable Stinger

> Operates the entire Impeccable design system (pbakaus/impeccable, Apache-2.0) for the Bee Army: the four-phase loop (Start to Iterate to Polish to Maintain), the context contract (PRODUCT.md + DESIGN.md + surface briefs), the 23-command vocabulary, the deterministic 59-rule anti-slop detector gate, hooks, live mode, and native playbooks. Use when impeccable-worker-bee is invoked, or for ANY frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture that must stay cohesive and free of AI-slop tells. Do NOT use for backend-only or non-UI tasks, or for product-specific design-system token enforcement (that is design-system-stinger / ux-ui-svelte-stinger).

- Skill: `legioncodeinc/impeccable-stinger` (Agent Skill, multi-file: 41 files)
- Install (CLI): `npx skillmds@latest add legioncodeinc/impeccable-stinger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/legioncodeinc/impeccable-stinger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- License: Apache-2.0 (upstream impeccable)
- Author: legioncodeinc (https://skillmd.com/u/legioncodeinc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/legioncodeinc/impeccable-stinger

---


# Impeccable Stinger

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-worker-bee` 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-worker-bee` first, then `quality-worker-bee`. 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)