Impeccable Stinger
Start with 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:
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)
- 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.
- Classify the job: greenfield / local extension / new surface / expression expansion / redesign-or-rebrand / refinement. See
guides/02-start-phase.md.
- 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).
- 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.
- Visualize when image tooling is available (system board + first-surface mock), then build toward the image.
Phase 2 — Iterate (bounded rounds)
- 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.
/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.
- 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)
/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.
- 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.
- Hand off to the army close-out:
security-wasp-drone first, then quality-wasp-drone. Never quality before security.
Phase 4 — Maintain (cohesion)
/impeccable extract — fold repeated patterns (3+ occurrences, same intent) into tokens and primitives.
/impeccable document — re-capture the system into DESIGN.md when code drifts from the record.
/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.
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.
Motion and interaction
For animate, transitions or motion accessibility, read the motion guide and use the evidence worksheet. Preserve the static task path and keyboard/focus behavior independently of motion. Record actual browser observations and unrun manual/device checks. Reduced-motion preference and detector success do not establish WCAG conformance. The research digest separates criteria levels and primitive guidance.
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)
1---2name: impeccable-stinger-33description: "Operate Impeccable for UI design. Use for new surfaces, redesign, polish, design capture, or anti-slop checks. Read README.md for the guide map."4license: AGPL-3.0-or-later5metadata:6 source: https://skillmd.com/skills/legioncodeinc/impeccable-stinger-37---89# Impeccable Stinger1011Start with [README.md](README.md) for the workflow map and detailed references.1213You 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.1415## Core principles1617- **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.18- **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.19- **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.20- **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.21- **Single vocabulary.** Never mix Impeccable with other design-taste skills in the same session; two design vocabularies collide and cancel each other out.22- **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).2324## Phase 0 — Pre-flight sync check (before every task)2526Run the stinger's sync check before any design work:2728```bash29node scripts/sync-check.mjs30```3132- Exit `0` = current and in sync → **skip**, proceed.33- 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.34- Exit `1` = not installed → global install first (`npx impeccable install --scope=global --providers=codex,claude,cursor`).3536See `guides/11-sync-check.md` and `templates/sync-report.md`.3738## The four-phase loop (core procedure)3940### Phase 1 — Start (context + direction)41421. 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`.432. Classify the job: greenfield / local extension / new surface / expression expansion / redesign-or-rebrand / refinement. See `guides/02-start-phase.md`.443. 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).454. 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`.465. Visualize when image tooling is available (system board + first-surface mock), then build toward the image.4748### Phase 2 — Iterate (bounded rounds)49501. 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`.512. `/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`.523. Bound the loop: one batched inspection round (desktop + mobile), one fix batch, at most one confirmation round, then stop and hand to the user.5354### Phase 3 — Polish (pre-ship gauntlet)55561. `/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`.572. 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`.583. Hand off to the army close-out: `security-wasp-drone` first, then `quality-wasp-drone`. Never quality before security.5960### Phase 4 — Maintain (cohesion)61621. `/impeccable extract` — fold repeated patterns (3+ occurrences, same intent) into tokens and primitives.632. `/impeccable document` — re-capture the system into `DESIGN.md` when code drifts from the record.643. `/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.654. `npx impeccable check` / `update` — keep the installed system current. See `guides/05-maintain-phase.md`.6667## Install & verify (hybrid scope)6869- **Global skill:** `npx impeccable install --scope=global --providers=codex,claude,cursor` makes `/impeccable` available in every army project.70- **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.71- **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`.7273## Native surfaces7475Web 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`.7677## Motion and interaction7879For animate, transitions or motion accessibility, read [the motion guide](guides/12-motion-and-interaction.md) and use [the evidence worksheet](templates/motion-interaction-evidence.md). Preserve the static task path and keyboard/focus behavior independently of motion. Record actual browser observations and unrun manual/device checks. Reduced-motion preference and detector success do not establish WCAG conformance. The research digest separates criteria levels and primitive guidance.8081## References to skill files8283Utilize the Read tool to understand your skills listed at `.` with all of its sub-folders and files.8485- `guides/00-principles.md` — the system's non-negotiables86- `guides/01-context-contract.md` — PRODUCT.md / DESIGN.md / surfaces / design.json / modes87- `guides/02-start-phase.md` — init, document, classification, new-work, direction contract, roll88- `guides/03-iterate-phase.md` — named commands, bounded rounds, live mode opt-in89- `guides/04-polish-phase.md` — audit / clarify / harden, P0-P390- `guides/05-maintain-phase.md` — extract / document / doctor / update91- `guides/06-detector-gate.md` — CLI, exit codes, engines, ignores, CI92- `guides/07-hooks.md` — per-edit + deep pass, harness manifests, approval93- `guides/08-live-mode.md` — opt-in browser iteration (alpha)94- `guides/09-native.md` — iOS / Android / adaptive95- `guides/10-install-and-verify.md` — global + per-project install, doctor96- `guides/11-sync-check.md` — pre-flight upstream sync check (skip when current)97- `scripts/sync-check.mjs` — the sync check runner98- `scripts/upstream-manifest.json` — upstream content coverage manifest99- `examples/` — worked sessions (happy path, refinement, live mode)100- `templates/` — direction contract, gate report, surface brief101- `reports/` — close-out report shape102- `research/` — primary-source audit trail (do not modify)