impeccable-stinger

# 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`. ## Motion and interaction For 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. ## 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)