diff --git a/.agents/skills/beekeeper-suit/PAIRING-AUDIT.md b/.agents/skills/beekeeper-suit/PAIRING-AUDIT.md index 0672198c..7f43f861 100644 --- a/.agents/skills/beekeeper-suit/PAIRING-AUDIT.md +++ b/.agents/skills/beekeeper-suit/PAIRING-AUDIT.md @@ -4,16 +4,22 @@ Ground truth pulled from the filesystem on 2026-08-14, after the repair pass. Th ## Totals -- Bees (`.claude/agents/*.md`): **75** -- Stinger folders (`.claude/skills/*`): **78** +- Bees (`.claude/agents/*.md`): **76** +- Stinger folders (`.claude/skills/*`): **79** - Orchestrator-level skills with no paired Bee by design: **3** (`beekeeper-suit`, `queen-bee-stinger`, `get-started-stinger`) -- Pairable Stingers: **75** +- Pairable Stingers: **76** ## Pairing integrity Clean. Every Bee has a matching Stinger and every pairable Stinger has a matching Bee, verified in both directions by naming convention. Zero orphans. -Every Bee also has a routing guide at `guides/.md`. 75 Bees, 75 guides, one-to-one. +Every Bee also has a routing guide at `guides/.md`. 76 Bees, 76 guides, one-to-one. + +## New additions + +`impeccable-worker-bee` / `impeccable-stinger` was ported in from a prior fork and registered here: it operates the Impeccable design system (pbakaus/impeccable, Apache-2.0) as the frontend-design operating system. The Impeccable engine is installed per machine via `npx impeccable install --scope=global --providers=codex,claude,cursor`; it is not vendored in this repo. The stinger's pre-flight sync check (`scripts/sync-check.mjs`) verifies the installed engine is current. + +`impeccable-worker-bee` is the single router for frontend UI/UX/design implementation. `design-system-worker-bee` and `ux-ui-svelte-worker-bee` retain product-specific token, component-library, and accessibility enforcement on established systems. ## Path integrity @@ -41,7 +47,7 @@ All routing references to the renamed `deeplake-dataset-worker-bee` were repaire ## Validation -All 78 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 75 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. +All 79 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 76 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. ## Dead reference repair diff --git a/.agents/skills/beekeeper-suit/SKILL.md b/.agents/skills/beekeeper-suit/SKILL.md index c4fb309f..7cd38e4e 100644 --- a/.agents/skills/beekeeper-suit/SKILL.md +++ b/.agents/skills/beekeeper-suit/SKILL.md @@ -28,7 +28,7 @@ Three skills sit above the pairing law because they are orchestrator level, not ## Roster -75 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. +76 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. ### Stack and frameworks @@ -42,7 +42,7 @@ Three skills sit above the pairing law because they are orchestrator level, not | `react-worker-bee` | React 18/19 architecture: bulletproof-react patterns, Server Components, Suspense, Actions, Compiler, state layering | "review React architecture", "state management decision", "Server Components boundary", "React 19 patterns" | `react-stinger` | | `typescript-node-worker-bee` | TypeScript/Node code review and conventions: strict config, module resolution, test suites, boundary validation (body still cites a legacy package's specifics; see PAIRING-AUDIT.md) | "review this TypeScript code", "audit this Node code", "write a Vitest suite", "tighten the tsconfig" | `typescript-node-stinger` | | `python-worker-bee` | Python architecture: Django + Django Ninja + FastAPI + Celery + Channels + pytest + uv, ORM discipline, migrations, typed adoption | "review this Django code", "audit ORM patterns", "migrate DRF to Django Ninja", "set up Celery" | `python-stinger` | -| `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | +| `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract. Impeccable remains the primary router for UI/design implementation | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | | `dark-mode-theming-worker-bee` | Dark-mode theming: CSS variable token architecture, theme-provider wiring, FOWT prevention, SSR hydration safety, Tailwind v4 dark variant | "set up dark mode", "dark mode on SSR", "multi-brand theming", "FOWT fix" | `dark-mode-theming-stinger` | | `modal-toast-dialog-worker-bee` | Accessible overlay primitives: dialog, alert dialog, drawer, toast, command menu; focus trap, escape, scroll lock, aria contract | "choosing between overlay primitives", "debugging focus trap regressions", "building a command palette" | `modal-toast-dialog-stinger` | | `icon-system-worker-bee` | Icon library selection and delivery: tree-shake vs sprite, dynamic-import-by-name, custom SVG components, icon accessibility contract | "choosing an icon library", "bundle-size regressions from icon imports", "icon accessibility" | `icon-system-stinger` | @@ -50,7 +50,8 @@ Three skills sit above the pairing law because they are orchestrator level, not | `font-loading-worker-bee` | Font loading pipeline: font-display strategy, preload/crossorigin correctness, variable-font subsetting, CLS-from-font-swap elimination | "audit font loading", "fix FOIT", "CLS from font swap", "subset variable font" | `font-loading-stinger` | | `markdown-mdx-content-pipeline-worker-bee` | Markdown/MDX pipeline: compiler selection, remark/rehype chains, syntax highlighting, AST manipulation, XSS sanitization | "set up MDX", "configure Shiki", "write a remark plugin", "sanitize user markdown" | `markdown-mdx-content-pipeline-stinger` | | `csv-xlsx-import-export-worker-bee` | Spreadsheet upload and export feature: CSV/XLSX parsing, large-file streaming, column-mapping wizard, row validation, CSV injection prevention | "build a CSV import", "add XLSX upload", "column-mapping wizard", "CSV injection safe" | `csv-xlsx-import-export-stinger` | -| `design-system-worker-bee` | Bootstraps a complete design system from scratch: tokens, utility layer, per-component and per-screen specs, static HTML examples | "build a design system for X", "bootstrap UI for product Y", "create tokens and utilities for this product" | `design-system-stinger` | +| `design-system-worker-bee` | Bootstraps a complete design system from scratch: tokens, utility layer, per-component and per-screen specs, static HTML examples. Impeccable owns frontend UI/UX/design implementation and uses DESIGN.md drift rules plus its detector gate to make enforcement mechanical | "build a design system for X", "bootstrap UI for product Y", "create tokens and utilities for this product" | `design-system-stinger` | +| `impeccable-worker-bee` | Frontend-design operating system for all UI/UX/design implementation, redesign, refinement, new surfaces, components, and design-system capture. Runs Start -> Iterate -> Polish -> Maintain, the context contract, and the deterministic detector gate | "polish the pricing page", "build a dashboard", "redo this hero", "make this not look like AI slop", "design a settings screen", "audit this UI" | `impeccable-stinger` | | `http-rest-fundamentals-worker-bee` | HTTP/REST protocol correctness: method safety and idempotency, status-code honesty, headers, conditional and range requests | "is this status code correct", "why is CORS failing", "explain preflight", "PUT vs PATCH" | `http-rest-fundamentals-stinger` | | `image-optimization-worker-bee` | Image delivery: AVIF/WebP format selection, responsive srcset/sizes, blur placeholders, remote image config, CLI tooling | "optimize my images", "convert to AVIF", "fix layout shift from images", "audit our images" | `image-optimization-stinger` | @@ -208,6 +209,12 @@ Real sequences for this stack. Every sequence below closes with the Ship Gate; i 5. `seo-aeo-worker-bee` for metadata, JSON-LD, and Core Web Vitals. 6. Ship Gate. +### Frontend design / UI implementation + +1. **`impeccable-worker-bee`** is the single router for all frontend UI/UX/design implementation, redesign, refinement, new-surface, component, and design-system-capture work. It runs Start -> Iterate -> Polish -> Maintain, including the pre-flight sync check and deterministic `npx impeccable detect ` gate. +2. **`design-system-worker-bee`** and **`ux-ui-svelte-worker-bee`** own product-specific token, component-library, and accessibility enforcement on established systems. Impeccable makes that enforcement mechanical via DESIGN.md drift rules and the detector gate. +3. **`security-worker-bee`** then **`quality-worker-bee`** close out under the Plan execution loop. + ### Add auth 1. `workos-worker-bee` wires AuthKit, sessions, and SSO. @@ -251,7 +258,7 @@ Don't hand-roll a new Bee. Walk [`../queen-bee-stinger/guides/beekeeper-registra --- -**75 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `../`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. +**76 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `../`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. --- diff --git a/.agents/skills/beekeeper-suit/guides/impeccable-worker-bee.md b/.agents/skills/beekeeper-suit/guides/impeccable-worker-bee.md new file mode 100644 index 00000000..f73b2a6c --- /dev/null +++ b/.agents/skills/beekeeper-suit/guides/impeccable-worker-bee.md @@ -0,0 +1,55 @@ +# impeccable-worker-bee + +## Domain +This Bee is the frontend-design operating system operator. It owns the entire Impeccable system (pbakaus/impeccable, Apache-2.0) as a closed loop: the context contract (`PRODUCT.md` + `DESIGN.md` + per-surface briefs + `.impeccable/design.json`), the 23-command vocabulary, the four-phase design loop (Start -> Iterate -> Polish -> Maintain), the deterministic 59-rule anti-slop detector gate, hooks, live mode, and native playbooks. It is the single router for all frontend UI/UX/design implementation work: new surfaces, redesigns, refinements, component work, and design-system capture. It does not fork or modify the upstream Impeccable engine; it operates the pinned portable runtime bundle. + +**Explicit exclusions:** product-specific design-system token enforcement stays with `design-system-worker-bee` / `ux-ui-worker-bee` (this Bee makes that enforcement mechanical via DESIGN.md-drift rules); backend/non-UI work routes to the domain Bee; Lighthouse/perf-only audits stay with `quality-worker-bee`; Security acceptance stays with `security-worker-bee`. + +## Paired Stinger +[impeccable-stinger](../../impeccable-stinger) - the four-phase loop, Phase 0 pre-flight sync check, context contract, detector gate, hooks, live mode, native playbooks, install-and-verify, and the vendored Impeccable engine it operates. + +## Trigger phrases +- "polish the pricing page" +- "build a dashboard" +- "redo this hero" +- "make this not look like AI slop" +- "design a settings screen" +- "audit this UI" +- "keep the design cohesive across new pages" + +Or route proactively when the assigned work touches any frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture, or when the user wants to see the design live during development and point at issues before a PR. + +## Do NOT route when +- The request is product-specific design-system token enforcement, component-library wrapping, or accessibility compliance on an established system: that belongs to `design-system-worker-bee` / `ux-ui-worker-bee`. +- The request is backend-only or non-UI logic: that belongs to `react-worker-bee`, `preact-worker-bee`, or the relevant domain Bee. +- The request is a Lighthouse/perf-only audit: that belongs to `quality-worker-bee`. +- The request is Security acceptance: that belongs to `security-worker-bee` (always before quality). + +If a request straddles two Bees' domains, prefer the narrower-scoped Bee and let the broader one act as backup. + +## Inputs the Bee needs +- The design task: a surface or route to design/redesign/refine, a plain-English request, or a named command intent. +- Repo root and target surface(s); the surface's mode (Persuade / Operate / Read / Experience) or enough context to infer it from the surface, not the product. +- Existing context files if present: `PRODUCT.md`, `DESIGN.md`, `.impeccable/design.json`, `.impeccable/surfaces/*.md`, `.impeccable/config.json`. +- Environment: Node >= 22.18; Impeccable installed per project (`npx impeccable install`) or `npx` network access; hooks approved in Codex (`/hooks`) where applicable. +- Optional: brand kit, anti-references, screenshots, incumbent visual truth (tokens, theme, CSS, components, assets). + +## Outputs +- **Context contract files** - `PRODUCT.md`, `DESIGN.md` (Stitch format), `.impeccable/design.json`, `.impeccable/surfaces/*.md`, owned and kept current by this Bee. +- **Implemented UI** - source changes to the target surface(s), with the direction contract comment block (`THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`) at the top of new artifacts. +- **Detector evidence** - a gate result (0 findings, or resolved findings, or explicit waivers with reasons) attached to the close-out. +- **Design-system updates** - `extract` / `document` outputs that keep the system current. +- **Close-out handoff** - security -> quality verification result, then a summary to the user with what changed and what remains open. + +## Commonly sequenced with +- Plan execution loop: `impeccable-worker-bee` is the implementation Bee for frontend UI/UX/design work; it hands the final implemented state to `security-worker-bee`, reruns affected checks after security fixes, and only then hands it to `quality-worker-bee`. +- Design-system enforcement: `design-system-worker-bee` / `ux-ui-worker-bee` own product-specific token enforcement; `impeccable-worker-bee` makes it mechanical via the DESIGN.md-drift rules and the detector gate. + +## Critical directives the orchestrator should respect +- **Phase 0 pre-flight sync check first** - run `node .claude/skills/impeccable-stinger/scripts/sync-check.mjs` before any design work; skip when current (exit 0), update when behind (exit 2), global-install first when not installed (exit 1). +- **Never self-grade** - the Bee iterates in bounded rounds; 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. +- **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. +- **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 ` runs before any completion claim; exit code 2 fails the close-out until findings are resolved or explicitly waived (narrowest ignore + reason). +- **Never fork or modify the engine** - call the installed system (`/impeccable`, `npx impeccable`); follow the bee-army-update contract (no upstream script execution during install, preserve the ownership manifest, no silent overwrites). +- **Close-out order** - Security before quality, always. diff --git a/.agents/skills/impeccable-stinger/README.md b/.agents/skills/impeccable-stinger/README.md new file mode 100644 index 00000000..466a380d --- /dev/null +++ b/.agents/skills/impeccable-stinger/README.md @@ -0,0 +1,9 @@ +# impeccable-stinger + +The paired Stinger for `impeccable-worker-bee`: the Bee Army's frontend-design operating system operator. It encodes the entire Impeccable system (pbakaus/impeccable, Apache-2.0) as a four-phase loop — **Start → Iterate → Polish → Maintain** — with the deterministic 59-rule anti-slop detector gate as a mandatory close-out step. + +- Command Brief: `.claude/commands/impeccable-worker-bee-command-brief.md` +- Research: `research/research-summary.md` (repo-primary, commit `aee6ce9`, 2026-08-04) +- License: Apache-2.0 (upstream); this stinger is guidance + procedure, never vendored engine code. + +- Bee: `.claude/agents/impeccable-worker-bee.md` (agent file: `.claude/agents/impeccable-worker-bee.toml`) diff --git a/.agents/skills/impeccable-stinger/SKILL.md b/.agents/skills/impeccable-stinger/SKILL.md new file mode 100644 index 00000000..5ac690fd --- /dev/null +++ b/.agents/skills/impeccable-stinger/SKILL.md @@ -0,0 +1,94 @@ +--- +name: "impeccable-stinger" +description: "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-stinger)." +license: Apache-2.0 (upstream impeccable) +--- + +# 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 ` 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 ../impeccable-stinger/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 ` (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 `../impeccable-stinger/` 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) diff --git a/.agents/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md b/.agents/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md new file mode 100644 index 00000000..c8780789 --- /dev/null +++ b/.agents/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md @@ -0,0 +1,3 @@ +# Third-party notices + +The Impeccable Stinger documents and operates the Apache-2.0 Impeccable runtime from [pbakaus/impeccable](https://github.com/pbakaus/impeccable), version 4.0.4. It retains that attribution and is distributed as part of the Bee Army only as a reusable operating guide and portable runtime companion. diff --git a/.agents/skills/impeccable-stinger/examples/01-happy-path-new-surface.md b/.agents/skills/impeccable-stinger/examples/01-happy-path-new-surface.md new file mode 100644 index 00000000..9cf54de6 --- /dev/null +++ b/.agents/skills/impeccable-stinger/examples/01-happy-path-new-surface.md @@ -0,0 +1,13 @@ +# Example 01 — Happy Path: New Surface (greenfield → shipped → maintained) + +Demonstrates: `guides/01-context-contract.md`, `guides/02-start-phase.md`, `guides/04-polish-phase.md`, `guides/05-maintain-phase.md`. + +**Task:** "Build a pricing page for a developer tool that traces every alert back to the deploy that caused it." + +1. **Start — context.** No `PRODUCT.md` → `/impeccable init` (platform: web; users: SREs on call, reading fast, often in the dark; positioning: traces every alert back to the deploy that caused it; evidence: real incident timelines, no customer logos yet). No `DESIGN.md` → `/impeccable document` (extracts tokens from the existing app, writes Stitch-format `DESIGN.md` + `design.json`). +2. **Start — classification.** New surface inside an established world → composition open, world inherited. Mode: **Persuade** (a pricing page earns attention and action). +3. **Start — direction.** Derive a grounded shortlist (incident timeline, postmortem doc, terminal session, man page, pager timeline). Roll assigns index 3 (terminal session) and deals challengers from the worlds deck. Five tests: Truth (the terminal relationship exists in the product) ✓, Translation (strip names → a product-native relationship remains) ✓, Consequence (removing the terminal frame weakens the page) ✓, Survival (works on mobile within budget) ✓, Fit (honest tradeoff) ✓. Write the direction contract into the artifact (see `templates/direction-contract.md`), keep the seed key. +4. **Build.** Code toward the committed world. Craft floor: contrast >= 4.5:1, body measure 65-75ch, one authored motion moment, real states (hover/disabled/loading/error/empty), themed browser surfaces (selection, focus rings, scrollbars). No side-tab borders, no gradient text, no hero eyebrow, no Inter-as-display. +5. **Iterate.** One batched inspection round (desktop + mobile): fix overflow on the pricing table, tighten heading rhythm, replace one hardcoded hex with a token. One fix batch. One confirmation round. Stop. +6. **Polish.** `/impeccable audit` (a11y 4, perf 3, theming 4, responsive 3, anti-patterns 4; one P2: touch target on the plan toggle → fixed). `/impeccable clarify` (CTA copy tuned to SREs). `/impeccable harden` (60-char org names, prices in the billions, 500s). Gate: `npx impeccable detect src/` → 0 findings. Hand off to `security-worker-bee` → `quality-worker-bee`. +7. **Maintain.** `/impeccable extract` (the plan-toggle pattern appears 3x → token + primitive). `/impeccable document` (re-capture `DESIGN.md`). `/impeccable doctor` → clean. The next surface inherits the world. diff --git a/.agents/skills/impeccable-stinger/examples/02-edge-case-refinement.md b/.agents/skills/impeccable-stinger/examples/02-edge-case-refinement.md new file mode 100644 index 00000000..e49cf512 --- /dev/null +++ b/.agents/skills/impeccable-stinger/examples/02-edge-case-refinement.md @@ -0,0 +1,17 @@ +# Example 02 — Edge Case: Refinement with a Waiver + +Demonstrates: `guides/03-iterate-phase.md`, `guides/04-polish-phase.md`, `guides/06-detector-gate.md`. + +**Task:** "Polish the settings screen. Keep our sharp corners and sober palette. Remove the AI tells." + +1. **Context.** `PRODUCT.md` + `DESIGN.md` exist and are current. Mode: **Operate** (settings = task completion; scanability outranks expression). +2. **Classification.** Refinement — better, not different. No new-work flow, no roll, no direction contract. The incumbent world is preserved. +3. **Iterate.** `/impeccable polish settings` — targeted fixes: 3 off-grid elements aligned; h1 kerning tightened; one hardcoded hex → `--color-accent`; missing hover state on FAQ items; modal entrance softened to 220ms ease-out-quart; stray "Lorem" removed. One batched round, one fix batch, one confirmation. Stop. +4. **Polish.** `/impeccable audit settings` (P1: gray-on-color on the danger zone → tint from the hue instead). `/impeccable harden settings` (long German labels, offline state). Gate: `npx impeccable detect src/settings` → 1 finding: `overused-font` flags the brand font (a real brand commitment, not a default). +5. **Waiver (narrowest form, with reason):** + ```bash + npx impeccable ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md" + ``` + Re-run the gate → 0 findings. The waiver is recorded in `.impeccable/config.json` and shared with the hook. +6. **Close-out.** Hand off to `security-worker-bee` → `quality-worker-bee`. Gate result travels with the close-out (see `templates/gate-report.md`). +7. **Maintain.** No drift introduced; `doctor` clean. Nothing to extract. diff --git a/.agents/skills/impeccable-stinger/examples/03-live-mode-session.md b/.agents/skills/impeccable-stinger/examples/03-live-mode-session.md new file mode 100644 index 00000000..c1069b73 --- /dev/null +++ b/.agents/skills/impeccable-stinger/examples/03-live-mode-session.md @@ -0,0 +1,13 @@ +# Example 03 — Live Mode Session (opt-in, user-invoked) + +Demonstrates: `guides/08-live-mode.md`, `guides/07-hooks.md`. + +**Task:** "Show me the hero live — something's off but I can't name it." + +1. **Opt-in.** The user asked; the Bee launches live mode. Never auto-launched. +2. **Setup.** Dev server confirmed running (localhost:3000). `/impeccable live` — picker injected into the app. +3. **Iterate.** User picks the hero headline, types "make it feel more editorial". Three variants hot-swapped via HMR. User accepts variant 2 → written to source (manual edits captured via `live-commit-manual-edits.mjs`). +4. **Gate.** `npx impeccable detect src/` on the accepted result → 0 findings. The per-edit hook stays quiet on clean edits (non-intrusive by design). +5. **Close-out.** Hand off to `security-worker-bee` → `quality-worker-bee`. + +**Note:** during normal development the user gets live feedback from the **per-edit hook** (findings pushed back after each UI edit, quiet when clean) — that is the non-nuisance live feedback. Live mode is the on-demand visual iteration tool. diff --git a/.agents/skills/impeccable-stinger/examples/04-sync-check.md b/.agents/skills/impeccable-stinger/examples/04-sync-check.md new file mode 100644 index 00000000..30b327e2 --- /dev/null +++ b/.agents/skills/impeccable-stinger/examples/04-sync-check.md @@ -0,0 +1,10 @@ +# Example 04 — Pre-Flight Sync Check + +Demonstrates: `guides/11-sync-check.md`. + +**Task:** "Polish the billing settings page." + +1. **Pre-flight.** `node .../impeccable-stinger/scripts/sync-check.mjs` → `[sync-check] CURRENT: upstream in sync, stinger coverage matches. Skipping update.` (exit 0). Skipped; task proceeds. +2. **Later run (behind).** The check reports `BEHIND: installed 4.0.3 < published 4.0.4` and `NEW COMMANDS upstream: ` (exit 2). The Bee runs `npx impeccable update`, notes the Codex `/hooks` re-approval to the user, re-runs the check → exit 0 → proceeds. +3. **Content drift.** The check reports `NEW REFERENCE FILES upstream: typeset.native.md` (exit 2). The Bee adds a guide/template covering the new playbook, bumps `scripts/upstream-manifest.json`, re-runs → exit 0 → proceeds. +4. **Not installed.** The check reports `NOT INSTALLED` (exit 1). The Bee runs the global install, then per-project `install` + `init` + `document`, re-runs → exit 0 → proceeds. diff --git a/.agents/skills/impeccable-stinger/guides/00-principles.md b/.agents/skills/impeccable-stinger/guides/00-principles.md new file mode 100644 index 00000000..26edaa7e --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/00-principles.md @@ -0,0 +1,14 @@ +# 00 — Principles (non-negotiables) + +Derived from `research/01-system-overview.md` and `research/05-craft-floor.md`. + +1. **The brief wins.** Pinned aesthetics, eras, materials, fonts, and palettes override saturated-pattern warnings. Redirecting a clear brief toward your taste is failure. (research/01, SKILL.src.md) +2. **Refinement preserves; redesign replaces.** Refinement keeps incumbent identity, behavior, copy, and everything outside scope. Redesign keeps product truth, content, function, and constraints but treats the old look as evidence and anti-reference. Never split the difference. (research/01) +3. **Bounded passes.** Build fully → inspect once batched (desktop + mobile) → fix in one batch → confirm at most once → stop. Open-ended self-QA is waste. (research/01) +4. **Never self-grade.** The user is the "happy" gate. A fresh reviewer audits the build against its direction contract promise-by-promise. (research/04, lesson 7) +5. **Context contract is source of truth.** Read `PRODUCT.md` + `DESIGN.md` + surface brief before every command. Mode comes from the surface, not the product. Missing `DESIGN.md` ≠ greenfield. (research/02) +6. **Single vocabulary.** One design system per session. Mixing Impeccable with other design-taste skills cancels both out. (research/01, /designing) +7. **The gate is mandatory.** `npx impeccable detect` exit code 2 fails the close-out. Waivers need the narrowest ignore + a stated reason. (research/06) +8. **Never fork or modify the engine.** Call the installed system; follow the bee-army-update contract (no upstream script execution during install, preserve ownership manifest, no silent overwrites). (research/11) +9. **License discipline.** Apache-2.0 upstream; build from the repo, not the site (site robots.txt: `ai-train=no, use=reference`). Keep attribution. (research/11) +10. **Close-out order.** Security before quality, always. diff --git a/.agents/skills/impeccable-stinger/guides/01-context-contract.md b/.agents/skills/impeccable-stinger/guides/01-context-contract.md new file mode 100644 index 00000000..9021f405 --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/01-context-contract.md @@ -0,0 +1,30 @@ +# 01 — Context Contract + +Derived from `research/02-context-contract.md`. + +## Files the Bee owns per project + +| File | Role | Written by | +|---|---|---| +| `PRODUCT.md` | Strategy: platform, users, purpose, positioning, evidence, brand commitments | `/impeccable init` | +| `DESIGN.md` | Visual system: colors, type, components, radii, elevation, rules (Google Stitch format) | `/impeccable document` | +| `.impeccable/surfaces/*.md` | Per-surface: mode, job, proof sequence, chosen direction | The work itself | +| `.impeccable/design.json` | Structured sidecar for detector/hooks/Live Mode | `document` (do not hand-edit) | + +## Modes (from the surface, not the product) + +- **Persuade** — visitor decides and acts (landing, marketing, pricing). Design is the product; earn attention. +- **Operate** — visitor completes a task (app UI, dashboards, admin, tools). Scanability outranks expression. +- **Read** — visitor understands (docs, guides, help). Comprehension first. +- **Experience** — visitor is inside the work (portfolios, galleries). Artifact leads, interface recedes. + +A tool's landing page is still Persuade; a fashion house's docs are still Read. Name the mode explicitly only when genuinely ambiguous; persist it in the surface brief. + +## Rules + +- Every command reads the contract first. Never re-derive what is recorded. +- `init` scans the codebase, forms its own read, asks only what it could not work out. It does not ask about colors/type — those are decided with the surface. +- `document` auto-extracts colors, typography, spacing, radii, components, then confirms descriptive language; writes Stitch-format `DESIGN.md`. +- Missing `DESIGN.md` does not make a project greenfield: coherent code, type choices, and component behavior are authority. Scaffolds and framework defaults are not. +- If implementation is coherent but undocumented: extract invariants, confirm with the user, write `DESIGN.md` before going further. +- `context.mjs` may emit a `CONTEXT_STALE` directive — report it, do not act on it unless the user asks (except `auto` findings). diff --git a/.agents/skills/impeccable-stinger/guides/02-start-phase.md b/.agents/skills/impeccable-stinger/guides/02-start-phase.md new file mode 100644 index 00000000..a83d5663 --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/02-start-phase.md @@ -0,0 +1,39 @@ +# 02 — Start Phase (context + direction) + +Derived from `research/02-context-contract.md`, `research/03-command-vocabulary.md`, `research/04-new-work-direction.md`. + +## 1. Ensure context + +- No `PRODUCT.md` → run `/impeccable init` (discovery interview; writes `PRODUCT.md`; offers `DESIGN.md` when code exists). +- No `DESIGN.md` → run `/impeccable document` (Stitch format + `.impeccable/design.json`). +- Files exist → read them; do not re-interview. + +## 2. Classify the job + +- **Greenfield** — no coherent visual implementation; a world gets established. +- **Local extension** — a section/component inside a working page; only the new part is decided; the page's world is inherited. +- **New surface** — a whole page/flow inside an established world; composition open, world not. +- **Expression expansion** — an established brand entering a surface family it never resolved; approve a range, merge into `DESIGN.md`. +- **Redesign or rebrand** — the look is replaced; product facts, content, function, constraints are not. +- **Refinement** — better, not different; leave this flow for a scoped command like `polish`. + +"Redesign this page" = replacement (old look becomes anti-reference). "Redesign within our current system" = extension. Ask once when genuinely ambiguous; never split the difference. + +## 3. New-work flow (new surfaces + redesigns) + +1. Derive a grounded shortlist of candidate directions from the product's world (audience, evidence, cultural material). +2. **Roll** (`node /scripts/concept-seed.mjs` or the installed skill's script): assign which candidate is built; deal challengers from the worlds deck. The dice refuse the argmax rut; they never touch an ungrounded idea. +3. Apply the **five tests** to every candidate — fail one, it dies: + - **Truth** — every relationship it visualizes exists in your product. + - **Translation** — strip the source's names/materials and a product-native relationship remains (else it is a costume). + - **Consequence** — removing its best move materially weakens the page. + - **Survival** — the signature works on the primary device within a real asset/time budget. + - **Fit** — its risk is an honest tradeoff, not a probable brief violation. +4. Write the **direction contract** into the artifact (see `templates/direction-contract.md`): `THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`, <=150 words, five blocks. Keep the seed key for reproduction. +5. **Visualize** when image tooling is available: system board + first-surface mock, then build toward the image. If no native image tool, set `OPENAI_API_KEY` and render via gpt-image-2 (say so first — it spends the user's credit, ~5-25 cents each). + +## Re-roll rules + +- The user re-rolls freely, for any reason including taste. After two in a row, ask what quality is missing. +- The agent may only re-roll on named factual grounds (the assigned direction cannot carry the product's truth or the task). Its own taste is never grounds. +- In an unattended run, the assigned direction proceeds and assumptions are stated explicitly. diff --git a/.agents/skills/impeccable-stinger/guides/03-iterate-phase.md b/.agents/skills/impeccable-stinger/guides/03-iterate-phase.md new file mode 100644 index 00000000..c8354f25 --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/03-iterate-phase.md @@ -0,0 +1,33 @@ +# 03 — Iterate Phase (bounded rounds) + +Derived from `research/03-command-vocabulary.md`, `research/08-live-mode.md`. + +## Named commands (when the edit has a name) + +- **Refine:** `polish` (final pass), `bolder` / `quieter` (voice), `distill` (subtraction), `typeset` (type hierarchy), `layout` (spacing/rhythm), `colorize` (strategic color), `animate` (purposeful motion), `delight` (personality), `overdrive` (past conventional limits). +- **Fix:** `clarify` (UX copy), `adapt` (devices/contexts), `optimize` (performance). +- **Harden:** `harden` (edge cases, i18n, errors, overflow), `onboard` (first-run, empty states). +- **Evaluate:** `critique` (design review with scoring, persona tests, automated detection). + +## Bounded-round discipline + +1. Build fully. +2. Inspect once in a batched round — desktop and mobile together, one render. +3. Fix everything the round shows in one batch. +4. Confirm with at most one more round. +5. Stop. Hand to the user for approval. The user is the "happy" gate. + +## Live Mode (opt-in, user-invoked only) + +- `/impeccable live` drops a picker on the running dev server: point at an element, type/draw a change, get 3 production-quality variants hot-swapped via HMR; accept one and it writes to source. +- **Never auto-launch it.** Launch only when the user asks to iterate visually ("show me live", "let me point at it"). +- Status: **alpha** — expect rough edges on uncommon setups. Prefer named commands for the default path. +- The non-intrusive live feedback during development is the **per-edit hook** (see `guides/07-hooks.md`), not live mode. + +## When to reach for which + +- Fix something "off" you can't name → `live` (user-invoked) or `critique`. +- Apply a specific discipline → `typeset` / `layout` / `colorize` / `animate`. +- Explore three directions side by side → `live` (user-invoked). +- Ask "is this any good?" → `critique`. +- Bring a safe design to life / tone a shouting one down → `bolder` / `quieter`. diff --git a/.agents/skills/impeccable-stinger/guides/04-polish-phase.md b/.agents/skills/impeccable-stinger/guides/04-polish-phase.md new file mode 100644 index 00000000..c6ead01a --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/04-polish-phase.md @@ -0,0 +1,22 @@ +# 04 — Polish Phase (pre-ship gauntlet) + +Derived from `research/03-command-vocabulary.md`, `research/06-detector-rules.md`. + +## The three commands before anything ships + +1. **`/impeccable audit `** — 5 dimensions scored 0-4: accessibility, performance, theming, responsive, anti-patterns. Findings tagged P0-P3. Point at a narrow target: one section reviewed closely beats a whole page at a glance. Native projects route to the native pass (VoiceOver, TalkBack, touch targets, platform conformance). +2. **`/impeccable clarify `** — rewrite the copy: labels, error messages, empty-state prose, microcopy, tuned to the audience from `PRODUCT.md`. +3. **`/impeccable harden `** — stress-test reality: 60-character names, German product titles, prices in the billions, 500s, offline. Production data is messy. + +## The deterministic gate (mandatory) + +- `npx impeccable detect ` — file, dir, or URL. Plain output groups by file with rule id, snippet, explanation; `--json` for scripts/CI. +- **Exit codes:** 0 = no findings; 2 = findings; 1 = command failed. CI fails the job on 2. +- DESIGN.md-aware: with a local `DESIGN.md`, enables design-system checks (fonts, literal colors, radii, font sizes). `--no-design-system` disables; `--scope type|layout` narrows. +- **Waivers:** narrowest form only — `npx impeccable ignores add-value --reason "..."`, `add-file `, or inline `impeccable-disable` comments in the file. A waiver without a reason is a failure. +- See `guides/06-detector-gate.md` for the full rule list and CI wiring. + +## Close-out + +- Findings resolved or explicitly waived → hand off to `security-worker-bee` first, then `quality-worker-bee`. Never quality before security. +- The gate result travels with the close-out (see `templates/gate-report.md`). diff --git a/.agents/skills/impeccable-stinger/guides/05-maintain-phase.md b/.agents/skills/impeccable-stinger/guides/05-maintain-phase.md new file mode 100644 index 00000000..24f2c88e --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/05-maintain-phase.md @@ -0,0 +1,22 @@ +# 05 — Maintain Phase (cohesion) + +Derived from `research/09-maintenance-doctor.md`. + +## The two commands that close the gap + +1. **`/impeccable extract `** — find patterns used 3+ times with the same intent; propose tokens and primitives; consolidate drift before it solidifies. +2. **`/impeccable document`** — re-capture the system: scans tokens, components, and rendered routes, writes `DESIGN.md` in Stitch format. The more it points at real components and live routes, the closer it reads your design language. + +## Doctor (three kinds of "out of date") + +- **Tool version** — installed skill older than published; `npx impeccable update` fixes. +- **Schema drift** — artifact written by an older Impeccable; mechanical, doctor repairs most of it. +- **Truth drift** — code moved on and the document no longer describes it; route to `init`/`document`, never auto-repair. + +`/impeccable doctor` also checks: config unknown keys, ignored rule ids that no longer exist, ignored file paths that are gone, `projectRoots` globs matching nothing, hook script paths that stopped resolving, orphaned surface briefs, and monorepo apps inheriting a web-only root record while carrying native build files. + +## Rules + +- **Never repair drift as a side effect of a design task.** A `CONTEXT_STALE` finding is reported, not acted on, unless the user asks (except `auto` findings). +- Run `npx impeccable check` / `update` on a cadence; the installed side self-updates, the stinger's vendored reference needs a manual refresh cadence. +- Every new element or surface inherits the established world unless the classification says greenfield; the detector's design-system rules mechanically flag drift. diff --git a/.agents/skills/impeccable-stinger/guides/06-detector-gate.md b/.agents/skills/impeccable-stinger/guides/06-detector-gate.md new file mode 100644 index 00000000..06c914f9 --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/06-detector-gate.md @@ -0,0 +1,46 @@ +# 06 — Detector Gate (59 deterministic rules) + +Derived from `research/06-detector-rules.md`. + +## CLI usage + +```bash +npx impeccable detect src/ # scan a directory +npx impeccable detect src/components/Card.tsx # one file +npx impeccable detect https://example.com # rendered page (browser engine) +npx impeccable detect --json src/ # machine-readable +npx impeccable detect --scope type src/ # one design domain +npx impeccable detect --no-design-system src/ # raw scan +``` + +- **Exit codes:** 0 = no findings; 2 = findings detected; 1 = command failed. CI fails the job on 2. +- Engines: static-html (files + linked CSS), browser (URLs), regex/text (JSX/TSX/Vue/Svelte/Astro/CSS-in-JS). Server-side templates (Blade/ERB/Twig/Handlebars) need `detector.extensions` in `.impeccable/config.json`. +- Web only. Native projects route to `/impeccable audit` (native pass). + +## The 59 rules (id | category | severity) + +**slop (30):** side-tab, border-accent-on-rounded, overused-font, flat-type-hierarchy (error), gradient-text (error), ai-color-palette, cream-palette, nested-cards, monotonous-spacing, bounce-easing, pulsing-dot, blinking-cursor, shape-assembled-illustration, dark-glow, radial-halo, radial-spotlight-glow, marquee, icon-tile-stack, italic-serif-display, hero-eyebrow-chip, kicker-above-heading, numbered-section-labels, em-dash-overuse, marketing-buzzword, aphoristic-cadence, oversized-h1, extreme-negative-tracking, gpt-thin-border-wide-shadow, repeating-stripes-gradient, codex-grid-background, theater-slop-phrase, image-hover-transform. + +**quality (29):** broken-image, script-error, content-hidden-at-rest, edge-flush-cards, text-occlusion, first-viewport-column-overflow, gray-on-color, low-contrast, layout-transition, line-length, cramped-padding, body-text-viewport-edge, tight-leading, skipped-heading, heading-rhythm, justified-text, tiny-text, undersized-ui-text, all-caps-body, wide-tracking, text-overflow, repeated-container-text, clipped-overflow-container, design-system-font, design-system-color, design-system-radius, design-system-font-size. + +Severities: `error` (flat-type-hierarchy, gradient-text), `warning` (most), `advisory` (side-tab, overused-font, ai-color-palette, cream-palette, nested-cards, etc.). + +## DESIGN.md awareness + +With a local `DESIGN.md`, the detector enables the 4 design-system rules (font, color, radius, font-size outside the documented system) using `.impeccable/design.json` for richer token/ramp data. This is what makes product-token enforcement mechanical — it complements `design-system-stinger`/`ux-ui-stinger`. + +## Ignores & waivers + +- `npx impeccable ignores list|add-value|add-file|add-rule|remove-value`; `--local` for private; `--reason` for the why. +- Value ignores preferred for fonts/colors/radii/motion (keeps the rule useful elsewhere); wildcard value ignores only when scoped to a file. +- Inline comments travel with a file: ``, `impeccable-disable-line`, `impeccable-disable-next-line`. +- A waiver without a stated reason is a failure. The narrowest exception that matches the real reason is the only correct one. + +## CI wiring + +```bash +npx impeccable detect --json src/ > .impeccable/detect.json +# exit code 2 → fail the PR check; parse JSON for the findings list +``` + +Add to army projects' PR checks per the user decision (2026-08-06). diff --git a/.agents/skills/impeccable-stinger/guides/07-hooks.md b/.agents/skills/impeccable-stinger/guides/07-hooks.md new file mode 100644 index 00000000..939c3051 --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/07-hooks.md @@ -0,0 +1,37 @@ +# 07 — Hooks (per-edit + deep pass) + +Derived from `research/07-hooks-enforcement.md`. + +## What the hook does + +- Scans direct edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). +- **Claude Code / GitHub Copilot / Codex:** post-tool-use — pushes a short system reminder after the edit; findings get a correction prompt, pending issues get a re-nudge, clean files get a short ack (unless `hook.quiet`). +- **Cursor:** `preToolUse` — blocks bad proposed writes before they land; silent when clean. +- Plain `.ts`/`.js` files are scanned but stay quiet unless the detector finds something. + +## Two speeds + +- **Per edit:** only what is objectively broken or compounds if ignored (broken images, overflow/clipped text, contrast failures, tiny text, gradient text, glow, DESIGN.md drift). +- **End of session (deep pass):** the full rule set across every UI file touched, minus what was already reported; a second stop is silent. Wired for Claude Code and Codex (native Stop hook); Cursor and Copilot keep the full detector per edit. +- `hook.perEditRules: "all"` restores full rules per edit (not recommended — it makes models more conservative). + +## Harness manifests & approval + +| Harness | Manifest | Notes | +|---|---|---| +| Claude Code | `.claude/settings.local.json` | gitignored, machine-local | +| GitHub Copilot | `.github/hooks/impeccable.json` | committed, team-shared | +| Codex | `.codex/hooks.json` | **requires `/hooks` approval after install/update** | +| Cursor | `.cursor/hooks.json` | confirm enabled in Settings → Hooks | +| Grok Build | `.grok/hooks/impeccable.json` | requires `/hooks-trust` or `--trust` | + +- Installer: `npx impeccable install|update`; `--no-hooks` skips; `--force` backs up malformed manifests as `.bak`. +- Config: `hook.enabled`, `hook.quiet`, `hook.auditLog` in `.impeccable/config.json`; consent in `.impeccable/config.local.json`. Env: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, `IMPECCABLE_HOOK_LOG`. + +## The failure mode to watch + +"A hook can look installed and scan nothing: if its script path stops resolving... the manifest still registers and no findings ever arrive. Silence reads as a clean codebase." `/impeccable doctor` checks for exactly this. Treat hook silence as suspicious, not as a clean pass. + +## Why this matters for the Bee + +Hooks are the "every time" enforcement: they fire on every UI edit regardless of routing discipline. They are the non-intrusive live feedback during development — the user sees findings as code is written, without live mode being a nuisance. diff --git a/.agents/skills/impeccable-stinger/guides/08-live-mode.md b/.agents/skills/impeccable-stinger/guides/08-live-mode.md new file mode 100644 index 00000000..518bbf75 --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/08-live-mode.md @@ -0,0 +1,28 @@ +# 08 — Live Mode (opt-in browser iteration, alpha) + +Derived from `research/08-live-mode.md`. + +## What it is + +`/impeccable live` drops a picker onto the running dev server. The user points at any element, draws or types what they want, and gets **three production-quality variants** hot-swapped via HMR. Accepting one writes it back to source. + +- Requires a running dev server (localhost). +- **Status: alpha** — works end-to-end, but needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups. + +## When to use (user decision 2026-08-06) + +- **Opt-in, user-invoked only.** Never auto-launch it. The Bee launches it only when the user asks to iterate visually ("show me live", "let me point at it", "I want to see it in the browser"). +- Use it when: the user can't name what's off; they want to explore three directions side by side; they want to see the design live as code changes and point at issues before a PR. +- The default loop stays: named commands + bounded rounds + detector gate. + +## Session flow + +1. Confirm a dev server is running; start one if needed. +2. Launch `/impeccable live`; the picker is injected into the app. +3. User picks an element or steers the whole page; the Bee generates 3 variants. +4. User accepts one → it writes to source (manual edits are captured and committed via `live-commit-manual-edits.mjs`). +5. Run the detector gate on the accepted result before close-out. + +## Companion: Chrome extension + +The detector overlay runs on any live page (staging, competitor) — useful for review without touching the editor. diff --git a/.agents/skills/impeccable-stinger/guides/09-native.md b/.agents/skills/impeccable-stinger/guides/09-native.md new file mode 100644 index 00000000..3124a86e --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/09-native.md @@ -0,0 +1,24 @@ +# 09 — Native Surfaces (iOS / Android / adaptive) + +Derived from `research/10-native-platforms-harnesses.md`. + +## Rules + +- The detector is **web only** — it reads HTML and CSS. It has nothing to say about a native iOS/Android codebase. +- When `PRODUCT.md` declares `ios`, `android`, or `adaptive`: + - `/impeccable audit` runs the **native pass** (`audit.native.md`): VoiceOver, TalkBack, touch targets, platform conformance. + - `adapt` has a native variant (`adapt.native.md`). + - Per-platform rulebooks: `ios.md`, `android.md`. +- `init` detects the platform from codebase evidence and asks only when ambiguous; the platform is recorded in `PRODUCT.md`. + +## Harness builds (per-model tuning) + +- `npx impeccable install` auto-detects the harness and writes the right skill files (`.claude/skills/`, `.cursor/skills/`, `.codex/`, `.gemini/`, `.grok/`, etc.) plus provider-native hook manifests. +- Per-model rule tuning: the Gemini build kills image-on-hover motion; the Codex build refuses ghost-cards and over-rounding. The installed build may carry extra rules for the active model — expect that. +- `npx skills add pbakaus/impeccable` installs one shared build (functionally complete, not tailored). +- Claude Code plugin: `/plugin marketplace add pbakaus/impeccable`. GitHub Copilot: built in (Settings → Experimental). + +## Bee behavior + +- Default domain is web. Native surfaces route to the native playbooks and the native audit pass. +- The stinger is complete for any build: web, iOS, Android, adaptive (user decision 2026-08-06). diff --git a/.agents/skills/impeccable-stinger/guides/10-install-and-verify.md b/.agents/skills/impeccable-stinger/guides/10-install-and-verify.md new file mode 100644 index 00000000..3e527ebd --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/10-install-and-verify.md @@ -0,0 +1,42 @@ +# 10 — Install & Verify (hybrid scope) + +Derived from `research/07-hooks-enforcement.md`, `research/09-maintenance-doctor.md`, `research/10-native-platforms-harnesses.md`, `research/11-license-provenance.md`. + +## Global skill install (once per machine) + +```bash +npx impeccable install --scope=global --providers=codex,claude,cursor +``` + +- Makes `/impeccable` available in every army project (user decision 2026-08-06: global, not per-project, because the army works across many projects). +- Reload the harness afterward; `/impeccable` should appear in autocomplete. + +## Per-project setup (one-time, cheap) + +```bash +npx impeccable install # writes hook manifests + .impeccable/config.json +/impeccable init # writes PRODUCT.md +/impeccable document # writes DESIGN.md + .impeccable/design.json +``` + +- Hooks are **project-local by harness design** (`.codex/hooks.json`, `.claude/settings.json`, `.cursor/hooks.json`) — they cannot be global. Codex requires `/hooks` approval after install/update. +- Context files (`PRODUCT.md`, `DESIGN.md`, `.impeccable/`) are inherently per-project. + +## Verify + +- `/impeccable doctor` — checks schema drift, truth drift, broken hook paths, stale config, orphaned surface briefs, monorepo platform mismatches. +- A hook that looks installed but scans nothing is the failure you would never notice — doctor catches it. +- `npx impeccable check` / `update` — keep the installed system current. + +## CI gate (user decision 2026-08-06) + +```bash +npx impeccable detect --json src/ > .impeccable/detect.json # exit 2 fails the PR check +``` + +Add to army projects' PR checks. + +## Compliance + +- Build the stinger from the repo (Apache-2.0), not the site (robots.txt: `ai-train=no, use=reference`). Keep attribution. +- Never fork or modify the engine into the stinger; call the installed system. Follow the bee-army-update contract. diff --git a/.agents/skills/impeccable-stinger/guides/11-sync-check.md b/.agents/skills/impeccable-stinger/guides/11-sync-check.md new file mode 100644 index 00000000..72b8c9e4 --- /dev/null +++ b/.agents/skills/impeccable-stinger/guides/11-sync-check.md @@ -0,0 +1,43 @@ +# 11 — Pre-Flight Sync Check (upstream always in sync) + +Derived from `research/09-maintenance-doctor.md`, `research/11-license-provenance.md`, and the user decision (2026-08-06): "make sure the upstream is always in sync before a task is done. If it is current it is skipped." + +## The mechanism + +Before any design task starts, run the stinger's sync check: + +```bash +node .claude/skills/impeccable-stinger/scripts/sync-check.mjs +``` + +**Exit codes:** +- `0` — current and in sync → **skip**, proceed with the task. +- `2` — behind upstream and/or content drift → update/refresh before the task (see below). +- `1` — not installed or check failed → install first. + +## What it verifies + +1. **Installed skill present** — searches the harness skill dirs (`~/.agents/skills/impeccable`, `~/.codex/skills/impeccable`, `~/.claude/skills/impeccable`, `~/.claude/skills/impeccable`, and project-local equivalents). Codex's primary skill dir is `.agents/skills/`. +2. **Version currency** — reads the installed `SKILL.md` frontmatter `version:` and compares it to the published version at `https://impeccable.style/api/version` (same endpoint the skill's own `context.mjs` uses). Behind → `npx impeccable update`. +3. **Content coverage** — compares the installed skill's `reference/` files and `scripts/command-metadata.json` commands against the stinger's `scripts/upstream-manifest.json` (forged against upstream 4.0.4 / commit `aee6ce9`). New commands or reference files upstream → the stinger needs a refresh (new guide/template), not just an update. + +## When behind (exit 2) + +1. Run `npx impeccable update` (or `node .../sync-check.mjs --update`). **Note:** Codex may require `/hooks` re-approval after an update — tell the user. +2. If content drift: add the missing guide/template for the new command or reference file, then update `scripts/upstream-manifest.json` to the new version/commit. +3. Re-run the check → exit 0 → proceed. + +## When not installed (exit 1) + +```bash +npx impeccable install --scope=global --providers=codex,claude,cursor +``` + +Then per project: `npx impeccable install` (hooks) + `/impeccable init` + `/impeccable document` (context). See `guides/10-install-and-verify.md`. + +## Rules + +- The check is a **pre-flight gate**: run it before Phase 1, skip when current, never skip when behind. +- Never fork or modify the engine; the check only compares versions and file coverage. +- A stale stinger manifest is a real finding: upstream added content the Bee does not know how to operate. +- Report the result in the close-out (see `templates/sync-report.md`). diff --git a/.agents/skills/impeccable-stinger/reports/README.md b/.agents/skills/impeccable-stinger/reports/README.md new file mode 100644 index 00000000..8d036cab --- /dev/null +++ b/.agents/skills/impeccable-stinger/reports/README.md @@ -0,0 +1,3 @@ +# reports/ + +Close-out reports from impeccable-worker-bee runs. Template: `gate-report-template.md`. Past runs accumulate here over time. diff --git a/.agents/skills/impeccable-stinger/reports/gate-report-template.md b/.agents/skills/impeccable-stinger/reports/gate-report-template.md new file mode 100644 index 00000000..d387c841 --- /dev/null +++ b/.agents/skills/impeccable-stinger/reports/gate-report-template.md @@ -0,0 +1,22 @@ +# Detector Gate Report + +| Field | Value | +|---|---| +| Target | `` | +| Command | `npx impeccable detect ` | +| Exit code | `0` (no findings) / `2` (findings) / `1` (failed) | +| Findings | `` | +| Resolved | `` | +| Waived | `` | + +## Findings + +| Rule id | Severity | File:line | Resolution (fix or waiver + reason) | +|---|---|---|---| +| `side-tab` | advisory | `src/components/Card.tsx:52` | Fixed — removed inset stripe | +| `overused-font` | advisory | `src/styles/global.css:14` | Waived — `ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md"` | + +## Verdict + +- [ ] Gate clean (0 findings) — close-out may proceed +- [ ] Gate failed (exit 2) — close-out blocked until resolved or waived diff --git a/.agents/skills/impeccable-stinger/research/01-system-overview.md b/.agents/skills/impeccable-stinger/research/01-system-overview.md new file mode 100644 index 00000000..eee5730b --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/01-system-overview.md @@ -0,0 +1,39 @@ +# 01 — System Overview + +**Source:** `README.md`, `PRODUCT.md`, `skill/SKILL.src.md`, `package.json`, `impeccable.style/designing` (reference) + +## What it is + +Impeccable is a design-guidance skill + toolchain for AI coding agents: "1 skill, 23 commands, live browser iteration, and 59 deterministic detector rules for AI-generated frontend design" (`README.md`). It started from Anthropic's `frontend-design` skill and adds a setup flow, a shared command vocabulary, and deterministic enforcement. + +- **License:** Apache-2.0 (`LICENSE`, `package.json` `"license": "Apache-2.0"`). +- **Runtime:** Node >= 22.18 (`package.json` `"engines"`). +- **Distribution:** npm package `impeccable` (bin `impeccable` → `cli/bin/cli.js`), installed per project via `npx impeccable install`, which writes harness-tailored builds (`.claude/`, `.cursor/`, `.codex/`, `.gemini/`, `.grok/`, `.trae/`, `.opencode/`, `.qoder/`, `.rovodev/` folders exist in the repo). +- **Per-model builds:** "builds for models with known tells carry extra slop rules banning that model's habits. The Gemini build kills its image-on-hover motion; the Codex build refuses ghost-cards and over-rounding" (`README.md`; ``/`` sections in `skill/reference/craft-floor.md`). + +## The seven layers (whole system) + +1. **Context contract** — `PRODUCT.md` (strategy) + `DESIGN.md` (visual system, Google Stitch format) + `.impeccable/surfaces/*.md` (per-surface mode/job/proof) + `.impeccable/design.json` (structured sidecar). Loaded by `skill/scripts/context.mjs` on every command. +2. **One vocabulary** — 23 commands under `/impeccable` (`skill/scripts/command-metadata.json`). v3.0 consolidated 18 standalone skills into one. +3. **Direction machinery** — new-work flow: job classification, five tests, direction contract, worlds deck + roll (`skill/scripts/concept-seed.mjs`, `skill/scripts/lib/concept-catalog.mjs`). +4. **Craft floor** — `skill/reference/craft-floor.md`: quality floor, absolute bans, reflexes, per-model sections. +5. **Deterministic enforcement** — 59 rules (`cli/engine/registry/antipatterns.mjs`), CLI `npx impeccable detect` (JSON, exit codes 0/2/1), hooks, Chrome extension, slop catalog. +6. **Live iteration** — `/impeccable live` (`skill/scripts/live/*`): browser picker, 3 variants per element, HMR, accept writes to source. Status: alpha. +7. **Maintenance** — `doctor` (tool/schema/truth drift), config/ignores, `update`/`check`, `extract`/`document`. + +## The four-phase loop (the Bee's core procedure) + +From `impeccable.style/designing` (reference; same content as the skill's routing): + +- **Start** — `init` (context) → `shape`/new-work (brief, direction, visualize, build). +- **Iterate** — named commands (`polish`, `bolder`, `typeset`, `layout`, `colorize`, `animate`, ...) or `live`; bounded rounds. +- **Polish** — pre-ship gauntlet: `audit` (5 dims, P0-P3), `clarify` (copy), `harden` (edge cases); detector gate in CI (`npx impeccable detect src/`, exit code fails the build). +- **Maintain** — `extract` (consolidate drift into tokens/primitives) + `document` (re-capture `DESIGN.md`) before debt solidifies. + +## Key evidence + +- "Verify in bounded passes, not a loop... Build fully, inspect once with a batched round (desktop and mobile together), fix everything it shows in one batch, confirm with at most one more round, and stop polishing. Open-ended self-QA burns the user's money" (`skill/SKILL.src.md`). +- "The brief wins. Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning" (`skill/SKILL.src.md`). +- "Refinement preserves; redesign replaces... Never split the difference into polish on the discarded look" (`skill/SKILL.src.md`). +- "Visual authority is evidence, not a filename. Missing DESIGN.md alone does not make a project greenfield" (`skill/SKILL.src.md`). +- "Running both Impeccable and Anthropic's frontend-design skill... Two skills with different design vocabularies collide and cancel each other out. Pick one" (`impeccable.style/designing`). diff --git a/.agents/skills/impeccable-stinger/research/02-context-contract.md b/.agents/skills/impeccable-stinger/research/02-context-contract.md new file mode 100644 index 00000000..d3fe7933 --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/02-context-contract.md @@ -0,0 +1,28 @@ +# 02 — Context Contract (PRODUCT.md / DESIGN.md / surfaces / design.json) + +**Source:** `skill/scripts/context.mjs`, `skill/reference/init.md`, `skill/reference/document.md`, `skill/reference/context.md` (site), `impeccable.style/docs/context` (reference) + +## Files and roles + +| File | What it answers | Updated when | +|---|---|---| +| `PRODUCT.md` | Platform, users, purpose, positioning, evidence, brand commitments | Strategy changes | +| `DESIGN.md` | Colors, type stacks, components, radii, elevation, visual rules | Visual system changes | +| `.impeccable/surfaces/*.md` | One page/route: mode, job, proof sequence, chosen direction | Written by the work itself | +| `.impeccable/design.json` | Structured design data for automation (detector, hooks, Live Mode) | Regenerated by `document`; do not hand-edit | + +## Key rules + +- Every command reads both files before generating, plus the brief for the named surface (`skill/SKILL.src.md` Setup: "It loads PRODUCT.md, DESIGN.md, the matching surface brief, and native-platform guidance when applicable"). +- **Mode comes from the surface, not the product:** "A tool's landing page is still Persuade; a fashion house's documentation is still Read; a docs index is Read, not Persuade" (`skill/SKILL.src.md`). +- Four modes: **Persuade** (decides and acts; design is the product), **Operate** (completes a task; scanability outranks expression), **Read** (understands; comprehension first), **Experience** (inside the work; artifact leads, interface recedes) (`skill/SKILL.src.md` lines 35-38). +- `init` scans the codebase, forms its own read of platform/product, asks only what it could not work out, writes `PRODUCT.md`, and offers `DESIGN.md` when code exists. It does not ask about colors/type — those are decided with the surface (`skill/reference/init.md`). +- `document` auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language; writes `DESIGN.md` in the **Google Stitch format** so the file is tool-compatible (`skill/scripts/command-metadata.json`). +- `context.mjs` also performs a staleness check against `https://impeccable.style/api/version` (`skill/scripts/context.mjs` line 77, 1007) and can emit a `CONTEXT_STALE` directive; "Never repair drift as a side effect of a design task" (`skill/SKILL.src.md`). +- `PRODUCT.md` carries a schema stamp; `DESIGN.md` follows the external design.md spec and gets no stamp (`skill/reference/doctor.md`). + +## Evidence for the stinger + +- The Bee owns these files per project; they are the source of truth every phase reads. +- A missing `DESIGN.md` does not make a project greenfield: "Coherent code, type choices, and component behavior are authority whether or not anyone wrote them down. Scaffolds, framework defaults, and stray utility classes are not" (`skill/reference/new-work.md`). +- If implementation is coherent but undocumented, extract invariants, confirm with the user, write `DESIGN.md` before going further (`skill/reference/new-work.md`). diff --git a/.agents/skills/impeccable-stinger/research/03-command-vocabulary.md b/.agents/skills/impeccable-stinger/research/03-command-vocabulary.md new file mode 100644 index 00000000..e030359f --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/03-command-vocabulary.md @@ -0,0 +1,53 @@ +# 03 — Command Vocabulary (23 commands) + +**Source:** `skill/scripts/command-metadata.json`, `skill/SKILL.src.md`, `impeccable.style/docs` (reference) + +All commands run through `/impeccable `; `pin`/`unpin` creates standalone shortcuts (e.g., `/audit`). Commands grouped by intent (from `command-metadata.json`): + +## Create +- `impeccable` — next-step recommendation or plain-English design work; inspects project state, recommends 2-3 commands, asks before running. +- `shape` — "Think before you build. Produce a design brief through discovery, not guesswork." +- `init` — one-time setup: discovery interview, writes `PRODUCT.md`, offers `DESIGN.md`, pre-configures live mode, recommends next commands. +- `document` — generate a spec-compliant `DESIGN.md` (Google Stitch format) from existing code. +- `extract` — pull reusable patterns, components, and tokens into the design system (drift consolidation). + +## Evaluate +- `audit` — 5-dimension technical quality check (a11y, performance, theming, responsive, anti-patterns), scored 0-4, findings P0-P3. Native variant: `audit.native`. +- `critique` — design review with scoring, persona tests, and automated detection. + +## Refine +- `polish` — "The meticulous final pass between good and great." +- `bolder` / `quieter` — amplify safe designs / tone down shouting designs (two halves of voice). +- `distill` — ruthless subtraction; strip to essence. +- `animate` — purposeful motion that conveys state, not decoration. +- `colorize` — strategic color for monochrome UIs. +- `typeset` — fix typography hierarchy and fonts. +- `layout` — fix layout, spacing, visual rhythm. +- `delight` — small moments of personality. +- `overdrive` — push past conventional limits (shaders, physics, 60fps, cinematic transitions). + +## Simplify / Fix +- `adapt` — cross-device/context adaptation (breakpoints, fluid layouts, touch targets). Native variant: `adapt.native`. +- `clarify` — rewrite confusing UX copy. +- `optimize` — diagnose and fix UI performance (LCP to bundle size). + +## Harden +- `harden` — production-ready: edge cases, i18n, error states, overflow. +- `onboard` — first-run flows, empty states, activation paths. + +## System +- `live` — interactive live variant mode (browser picker, 3 variants, HMR, accept writes to source). Alpha. +- `hooks` — manage the design detector hook (`on|off|status|ignore-rule|ignore-file|ignore-value|reset`). +- `doctor` — report/repair drift between project artifacts and what this version reads. + +## Routing rules (`skill/SKILL.src.md`) + +- No argument → read `routing.md`, present context-aware menu; never auto-run a command. +- Explicit or clearly implied command → load its reference and follow it; ask once if two fit. +- Otherwise → treat as general design work; missing `PRODUCT.md` routes new surfaces through `init` then `new-work`; narrow refinement proceeds on the incumbent implementation. +- `teach` aliases `init`; `craft` is a deprecated alias for ordinary new-work. + +## Evidence for the stinger + +- The Bee's procedure maps the four phases to these commands: Start (`init`/`shape`/new-work), Iterate (refine commands + `live`), Polish (`audit`/`clarify`/`harden` + detector gate), Maintain (`extract`/`document`/`doctor`/`hooks`). +- Pin only 2-3 daily commands; pinning everything re-explodes the `/` menu (`impeccable.style/designing`). diff --git a/.agents/skills/impeccable-stinger/research/04-new-work-direction.md b/.agents/skills/impeccable-stinger/research/04-new-work-direction.md new file mode 100644 index 00000000..595fa14f --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/04-new-work-direction.md @@ -0,0 +1,51 @@ +# 04 — New-Work Direction Machinery (classification, five tests, direction contract, roll) + +**Source:** `skill/reference/new-work.md`, `skill/scripts/concept-seed.mjs`, `skill/scripts/lib/concept-catalog.mjs`, `impeccable.style/research` (reference) + +## Job classification + +- **Greenfield** — no coherent visual implementation; a world gets established. +- **Local extension** — a section/component inside a page that already works; only the new part is decided; the page's world is inherited. +- **New surface** — a whole page/flow inside an established world; composition open, world not. +- **Expression expansion** — an established brand entering a surface family it never resolved; a range is approved and merged into `DESIGN.md`. +- **Redesign or rebrand** — the look is replaced; product facts, content, function, constraints are not. +- **Refinement** — better, not different; leaves this flow for a scoped command like `polish`. + +"Redesign this page" authorizes replacement (old look becomes evidence and anti-reference). "Redesign this within our current system" is an extension. Ask once when genuinely ambiguous; never split the difference. + +## The five tests (every candidate must pass all) + +1. **Truth** — every relationship it visualizes exists in your product. Resemblance is not evidence. +2. **Translation** — strip the source's names and materials and a product-native relationship remains; otherwise it is a costume. +3. **Consequence** — removing its best move materially weakens the page. +4. **Survival** — the signature still works on the primary device, within a real asset and time budget. +5. **Fit** — its risk is an honest tradeoff, not a probable violation of your brief. + +## The direction contract (written into the artifact, <=150 words, five blocks) + +- `THESIS` — the one idea this page owns, and the category default it refuses. +- `OWN-WORLD` — palette and component language, recognizable with all content removed. +- `STORY` — what the visitor understands, believes, and does. +- `FIRST VIEWPORT` — the exact composition and where the primary action sits. +- `FORM` — the chosen form and the seed key. + +The contract exists so intent is inspectable and a **separate reviewer agent** can audit the built page against it promise-by-promise. "A page that promised a radical composition and shipped the usual template does not pass quietly" (`skill/reference/new-work.md`). + +## The roll / dice (external variance) + +- Problem (measured): "Ask a coding model for something creative and it builds its favorite idea, every run. Sixteen different 'be creative' framings returned the identical concept in thirty of thirty-five runs" (`skill/reference/new-work.md`; `impeccable.style/research`). +- Fix: a script rolls which of the model's own resonance-ordered shortlist gets built, and deals challengers from a reviewed catalog of ~188 visual worlds (`concept-seed.mjs` header; site says 177-188 worlds). +- "The dice never touch an ungrounded idea. They only refuse the argmax rut" (`concept-seed.mjs`). +- Re-roll: user re-rolls freely; the agent may only re-roll on named factual grounds (assigned direction cannot carry the product's truth or the task). "Its own taste is never grounds." +- Reproduction: the script prints a seed key; `--reroll ` recomputes prior rounds and excludes them. +- Fallback chain: local catalog (`IMPECCABLE_CATALOG_DIR`) → roll API (`https://impeccable.style/api`, `IMPECCABLE_API_URL`) → degraded local mode (`concept-seed.mjs` lines 63-99). + +## Research lessons (from `impeccable.style/research`, reference) + +1. The model lacks variance, not creativity (30/35 identical concepts). +2. Rejection advances a queue — "be different" lands on the #2 idea. +3. Argmax is deterministic; dice must **assign** the index, not nominate a menu (27/30 revert to option 1 when a chooser is involved). +4. Derivation is bounded by the subject's cultural depth; assigned foreign forms win over thin categories. +5. Anti-gimmick guards are the ceiling — commit first, then clarify (biggest single quality jump). +6. Committed skin hides template bones — "borrow the form's skeleton, not its clothes"; skin-blind review is a review instrument, never the builder grading itself. +7. Models describe brilliantly and build conservatively — hold them to the direction contract with a fresh reviewer. diff --git a/.agents/skills/impeccable-stinger/research/05-craft-floor.md b/.agents/skills/impeccable-stinger/research/05-craft-floor.md new file mode 100644 index 00000000..9238cc34 --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/05-craft-floor.md @@ -0,0 +1,32 @@ +# 05 — Craft Floor (quality floor, bans, reflexes) + +**Source:** `skill/reference/craft-floor.md` (verbatim structure) + +Loaded immediately before editing UI (not for planning-only work). "A pinned brief or the committed visual world overrides anything here; your own habit does not." + +## Verify (checks on the built result, run together in batched rounds) + +- **Contrast:** body/placeholder >= 4.5:1, large text >= 3:1; on colored surfaces tint secondary text from that hue or the foreground; never gray. +- **Depth:** shadows carry an offset and a soft blur; a zero-offset colored halo is decoration. +- **Spacing:** tight groups, generous separation, more space above a heading than below it; read computed values. +- **Type:** body measure 65-75ch, display max 6rem, tracking floor -0.04em, balanced headings, obvious scale/weight steps; run real copy at every breakpoint. +- **Motion:** one authored moment, not scattered effects; exponential ease-out from an already-visible default; reach past transform/opacity (blur, backdrop-filter, clip-path, mask, shadow). +- **States:** hover, disabled, loading, error, empty; real content, working controls, responsive composition, keyboard focus. +- **Browser surfaces:** text selection, caret, custom scrollbars, focus rings, underline offset, tabular numerals — "the cheapest signal that a page was built rather than assembled, and the one models skip most reliably." +- **Copy:** the product's own language; controls name their action; errors name the problem and the recovery. +- **Coverage:** every brief requirement present and findable within seconds. + +## Refuse (category defaults, not bans — the brief's own words can earn any of them) + +Page scaffolds: same-size icon+heading+text card grids (cards are the lazy container; nested cards always wrong); hero-metric template; kicker/eyebrow above a heading (a ban, not a default); section numbers 01/02/03 unless the sequence carries information; modal for a task needing neither interruption nor protected focus. + +Surface habits: gradient text; glass/blur as decoration; colored `border-left`/`border-right` above 1px; hard offset shadows outside a real neobrutalist world; sparklines/progress rings/soft-shadowed rounded rectangles standing in for content; monospace as a "technical" costume; system display faces as the display voice; unicode glyphs/emoji standing in for an icon system; light/dark picked by category instead of use scene. + +## Per-model sections + +- ``: tracking stops at -0.04em (-0.02 to -0.03 usually reads better); declare elevation once (border or shadow — 1px border under a wide soft shadow is the ghost card); card radii 12-16px, pills for small controls; real illustration or none (bans sketch-style SVG, `loose-sketch`/`doodle` class names, `feTurbulence` grain); backgrounds are surfaces (bans `repeating-linear-gradient` stripes and two-axis grid overlays without a real canvas/map/blueprint); claims come from supplied truth, label illustrative values honestly. +- ``: never animate an image on hover, directly or through its parent; give the container the feedback. + +## Closing principle + +"The floor holds the mechanics; it never picks the direction. With every check green, spend the page on the committed world, and when torn between refined and committed, commit." diff --git a/.agents/skills/impeccable-stinger/research/06-detector-rules.md b/.agents/skills/impeccable-stinger/research/06-detector-rules.md new file mode 100644 index 00000000..c42b75fd --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/06-detector-rules.md @@ -0,0 +1,84 @@ +# 06 — Detector Rules (59 deterministic rules) + +**Source:** `cli/engine/registry/antipatterns.mjs` (authoritative), `impeccable.style/slop` (public catalog, reference) + +## Engine facts + +- 59 rules, each with `id`, `category` (`slop` | `quality`), `severity` (`error` | `warning` | `advisory`). +- Runs via `npx impeccable detect `; plain output groups by file with rule id, snippet, explanation; `--json` for scripts/CI. +- **Exit codes:** 0 = no findings; 2 = findings detected; 1 = command failed. CI fails the job on 2. +- Engines: static-html (`engines/static-html/detect-html.mjs`), browser/URL (`engines/browser/detect-url.mjs`), regex/text for CSS-in-JS and framework files (`engines/regex/detect-text.mjs`), plus `node/file-system.mjs` (walk, import graph, framework config detection). +- DESIGN.md-aware: when a local `DESIGN.md` exists, enables design-system checks (fonts, literal colors, radii, font sizes) using `.impeccable/design.json` for richer token/ramp data. `--no-design-system` disables; `--scope type|layout` narrows. +- Ignores: `npx impeccable ignores ...` (shared `config.json` / local `config.local.json`), inline `impeccable-disable` / `-line` / `-next-line` comments. +- Web only: native projects route to `/impeccable audit` (native pass). + +## Full rule list (id | category | severity) + +### slop (30) +side-tab | slop | advisory — thick colored border on one side of a card (most recognizable AI tell) +border-accent-on-rounded | slop | advisory — accent border clashes with radius +overused-font | slop | advisory — Inter, Geist, Space Grotesk, Instrument Serif, etc. +flat-type-hierarchy | slop | error — font sizes too close (aim >= 1.25 ratio) +gradient-text | slop | error — decorative gradient text +ai-color-palette | slop | advisory — purple/violet gradients, cyan-on-dark +cream-palette | slop | advisory — warm cream/beige default surface +nested-cards | slop | advisory — cards inside cards +monotonous-spacing | slop | advisory — same spacing everywhere +bounce-easing | slop | advisory — bounce/elastic easing on interface elements +pulsing-dot | slop | advisory — decorative pulse on static status +blinking-cursor | slop | advisory — fake caret on non-editable hero copy +shape-assembled-illustration | slop | advisory — sketch-style SVG scenes +dark-glow | slop | warning — dark bg with colored box-shadow glows +radial-halo | slop | warning — saturated radial glow on dark page +radial-spotlight-glow | slop | warning — accent haze behind a section +marquee | slop | warning — auto-scrolling marquee +icon-tile-stack | slop | warning — rounded-square icon tile above heading +italic-serif-display | slop | warning — oversized italic serif hero +hero-eyebrow-chip | slop | warning — tiny uppercase label above hero headline +kicker-above-heading | slop | warning — tracked uppercase label above heading +numbered-section-labels | slop | warning — tiny 01/02/03 labels +em-dash-overuse | slop | warning +marketing-buzzword | slop | warning +aphoristic-cadence | slop | warning +oversized-h1 | slop | warning — full-sentence headline at display size +extreme-negative-tracking | slop | warning — crushed letter spacing +gpt-thin-border-wide-shadow | slop | warning — hairline border + wide diffuse shadow (ghost card) +repeating-stripes-gradient | slop | warning — decorative stripe backgrounds +codex-grid-background | slop | warning — two-axis grid overlays without a real canvas +theater-slop-phrase | slop | warning — "x-theater" naming/irony +image-hover-transform | slop | warning — image animated on hover (Gemini-tuned rule) + +### quality (29) +broken-image | quality | warning +script-error | quality | warning +content-hidden-at-rest | quality | warning +edge-flush-cards | quality | warning — scroller cards lose one edge +text-occlusion | quality | warning — opaque layer covers readable text +first-viewport-column-overflow | quality | warning +gray-on-color | quality | warning — gray text on colored background +low-contrast | quality | warning +layout-transition | quality | warning +line-length | quality | warning — > ~80ch +cramped-padding | quality | warning +body-text-viewport-edge | quality | warning +tight-leading | quality | warning +skipped-heading | quality | warning +heading-rhythm | quality | warning — heading closer to previous block than its content +justified-text | quality | warning +tiny-text | quality | warning +undersized-ui-text | quality | warning — functional text under 11px +all-caps-body | quality | warning +wide-tracking | quality | warning +text-overflow | quality | warning +repeated-container-text | quality | warning +clipped-overflow-container | quality | warning — positioned child clipped by overflow container +design-system-font | quality | warning — font outside DESIGN.md +design-system-color | quality | warning — literal color outside DESIGN.md palette +design-system-radius | quality | warning — radius outside documented shape scale +design-system-font-size | quality | warning — font size between documented steps + +## Evidence for the stinger + +- The gate is the Bee's mandatory close-out step: `npx impeccable detect `; exit code 2 fails until resolved or explicitly waived (narrowest ignore + reason). +- The 4 design-system rules make product-token enforcement mechanical — they complement `design-system-stinger`/`ux-ui-stinger`. +- Verified live during research: `node cli/bin/cli.js detect tests/fixtures` returned line-numbered findings (side-tab, design-system-color, etc.) with remediation text. diff --git a/.agents/skills/impeccable-stinger/research/07-hooks-enforcement.md b/.agents/skills/impeccable-stinger/research/07-hooks-enforcement.md new file mode 100644 index 00000000..5282b89b --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/07-hooks-enforcement.md @@ -0,0 +1,41 @@ +# 07 — Hooks & Enforcement (per-edit + deep pass) + +**Source:** `skill/reference/hooks.md`, `skill/scripts/hook-admin.mjs`, `skill/scripts/hook-lib.mjs`, `impeccable.style/docs/hooks` (reference) + +## What the hook does + +- Scans direct edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). +- **Claude Code, GitHub Copilot, Codex:** post-tool-use hook pushes a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, clean UI-ish files get a short ack (unless `hook.quiet`). +- **Cursor:** `preToolUse` blocks bad proposed writes before they land; silent when it allows a clean write. +- Plain `.ts`/`.js` files are scanned but stay quiet unless the detector finds something. + +## Two speeds + +- **Per edit:** only what is objectively broken or compounds if ignored (broken images, overflow/clipped text, contrast failures, tiny text, gradient text, glow, DESIGN.md drift). +- **End of session (deep pass):** the full rule set across every UI file touched, minus what was already reported; a second stop is silent (findings remembered). Wired for Claude Code and Codex (native Stop hook); Cursor and Copilot keep the full detector per edit. +- Rationale: "Reporting every rule on every edit made models measurably more conservative rather than more careful" (one copy-level rule fired ~97x in a single session). +- `hook.perEditRules: "all"` restores full rules per edit. + +## Harness manifests & approval + +- Claude Code: `.claude/settings.local.json` (gitignored, machine-local). +- GitHub Copilot: `.github/hooks/impeccable.json` (committed, team-shared; activates on default branch). +- Codex: `.codex/hooks.json` — **requires one extra approval step**: open `/hooks` in Codex and approve the project hook; updates that change the hook definition can require approval again. +- Cursor: `.cursor/hooks.json`; confirm hooks enabled in Cursor Settings → Hooks. +- Installer/updater: `npx impeccable install|update`; `--no-hooks` skips hook setup; `--force` backs up malformed manifests as `.bak`. + +## Config & env + +- `hook.enabled`, `hook.quiet`, `hook.auditLog` (NDJSON) in `.impeccable/config.json`; per-developer consent in `.impeccable/config.local.json`. +- Env overrides: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, `IMPECCABLE_HOOK_LOG`. +- Detector filters live under `detector` (shared by hook and CLI): `ignoreRules`, `ignoreFiles`, `ignoreValues`, `designSystem.enabled`. +- Server-side templates: declare under `detector.extensions` (e.g., `{ "ext": ".blade.php", "engine": "html" }`). + +## Failure mode to watch + +"A hook can look installed and scan nothing: if its script path stops resolving... the manifest still registers and no findings ever arrive. Silence reads as a clean codebase." `/impeccable doctor` checks for exactly this (`skill/reference/hooks.md`). + +## Evidence for the stinger + +- The Bee verifies hook health (`doctor`) and treats hook silence as suspicious, not as a clean pass. +- Hooks are the "every time" enforcement: they fire on every UI edit regardless of routing discipline. diff --git a/.agents/skills/impeccable-stinger/research/08-live-mode.md b/.agents/skills/impeccable-stinger/research/08-live-mode.md new file mode 100644 index 00000000..41709208 --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/08-live-mode.md @@ -0,0 +1,23 @@ +# 08 — Live Mode (browser iteration) + +**Source:** `skill/reference/live.md`, `skill/reference/live-setup.md`, `skill/scripts/live/*`, `impeccable.style/docs/live` (reference) + +## What it is + +`/impeccable live` drops a picker onto the running dev server. The user points at any element, draws or types what they want, and gets **three production-quality variants** hot-swapped via HMR. Accepting one writes it back to source. + +- Requires a running dev server (localhost). +- Status: **alpha** — "works end-to-end and is ready to try, but it still needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups" (`impeccable.style/docs/live`). +- Scripts: `skill/scripts/live/*` (live.mjs, live-accept.mjs, live-complete.mjs, live-poll.mjs, live-status.mjs, live-wrap.mjs, live-target.mjs, live-resume.mjs, live-browser.js, live-inject.mjs, live-insert.mjs, live-copy-edit-agent.mjs, live-commit-manual-edits.mjs, live-manual-edit-evidence.mjs, live-discard-manual-edits.mjs, live-browser-dom.js, live-browser-session.js, live/manual-edits-buffer.mjs, live/vocabulary.mjs, live/svelte-ast.mjs, live/event-validation.mjs, live/insert-ui.mjs, live/manual-apply.mjs, live/completion.mjs, live/poll-lanes.mjs, live/accept-css.mjs, live/roots.mjs). +- `live-browser.js` is ~500KB (bundled browser automation). + +## When to reach for it + +- Fix something "off" you can't name. +- Explore three directions side by side. +- Point-at-it iteration beats command-naming when the user doesn't know the design word. + +## Evidence for the stinger + +- Live Mode is an Iterate-phase tool, not the core loop. Given alpha status, the Bee should treat it as optional/experimental and prefer named commands for the default path. +- Accept writes to source; manual edits are captured and committed via `live-commit-manual-edits.mjs`. diff --git a/.agents/skills/impeccable-stinger/research/09-maintenance-doctor.md b/.agents/skills/impeccable-stinger/research/09-maintenance-doctor.md new file mode 100644 index 00000000..35f24025 --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/09-maintenance-doctor.md @@ -0,0 +1,37 @@ +# 09 — Maintenance: Doctor, Config, Ignores, Update + +**Source:** `skill/reference/doctor.md`, `skill/reference/hooks.md`, `skill/scripts/doctor.mjs`, `impeccable.style/docs/doctor`, `impeccable.style/docs/config` (reference) + +## Doctor — three kinds of "out of date" + +1. **Tool version** — installed skill older than published; reported at boot; `npx impeccable update` fixes. +2. **Schema drift** — artifact written by an older Impeccable (fields nothing reads, fields now expected, retired locations). Mechanical; doctor repairs most of it. This is doctor's job. +3. **Truth drift** — code moved on and the document no longer describes it. Routed to `init`/`document`, not repaired. + +## What doctor checks + +- `PRODUCT.md` schema stamp (vintage, not release version). +- `DESIGN.md` (no stamp — follows external design.md spec) and the `.impeccable/design.json` sidecar (older than DESIGN.md, outdated schema, legacy path). +- Config: unknown keys, unknown detector keys, ignored rule ids that no longer exist, ignored file paths that are gone, `projectRoots` globs matching nothing. +- Design hook: script path that stopped resolving; enabled/disabled conflict. +- Surface briefs: records orphaned from the file/route they describe. +- Monorepos: which apps carry their own `PRODUCT.md`/`DESIGN.md` vs inherit the root's; flags a workspace with native build files inheriting a web-only root record. + +## Config & ignores + +- `.impeccable/config.json` (shared, commit when team intent) + `.impeccable/config.local.json` (private, gitignored). +- `npx impeccable ignores list|add-value|add-file|add-rule|remove-value`; `--local` for private; `--reason` for the why. +- Value ignores preferred for fonts/colors/radii/motion (keeps the rule useful elsewhere); wildcard value ignores only when scoped to a file. +- Inline comments travel with a file: ``, `impeccable-disable-line`, `impeccable-disable-next-line`. +- `projectRoots` for repos where design boundaries don't line up with package-manager workspaces. +- A config file fails quietly when wrong (misspelled key never read; stale rule id suppresses nothing) — doctor catches all three. + +## Update flow + +- `npx impeccable check` (behind?) → `npx impeccable update` (from project root); plugin users update from `/plugin` menu; `npx skills update` for the shared build. +- `stalenessCheck: false` in config or `IMPECCABLE_NO_STALENESS_CHECK=1` silences the boot notice; `doctor` still works. + +## Evidence for the stinger + +- Maintain phase = `extract` (consolidate drift) + `document` (re-capture system) + `doctor` (schema/truth/tool drift) + `check`/`update` (upstream). +- "Never repair drift as a side effect of a design task" — a `CONTEXT_STALE` finding is reported, not acted on, unless the user asks (`skill/SKILL.src.md`). diff --git a/.agents/skills/impeccable-stinger/research/10-native-platforms-harnesses.md b/.agents/skills/impeccable-stinger/research/10-native-platforms-harnesses.md new file mode 100644 index 00000000..96b1ff82 --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/10-native-platforms-harnesses.md @@ -0,0 +1,23 @@ +# 10 — Native Platforms & Harness Builds + +**Source:** `skill/reference/ios.md`, `skill/reference/android.md`, `skill/reference/audit.native.md`, `skill/reference/adapt.native.md`, `docs/HARNESSES.md`, repo `.claude/ .cursor/ .codex/ .gemini/ .grok/ .trae/ .opencode/ .qoder/ .rovodev/` builds + +## Native (iOS / Android / adaptive) + +- The detector is **web only** ("The engine reads HTML and CSS, so it has nothing to say about a native iOS or Android codebase" — `impeccable.style/docs/detector`). +- When `PRODUCT.md` declares `ios`, `android`, or `adaptive`, `/impeccable audit` runs a native pass covering VoiceOver, TalkBack, touch targets, and platform conformance (`audit.native.md`); `adapt` has a native variant (`adapt.native.md`). +- `init` detects the platform from codebase evidence and asks only when ambiguous; platform is recorded in `PRODUCT.md`. +- Native guidance files: `ios.md`, `android.md` (per-platform rulebooks). + +## Harness builds + +- `npx impeccable install` auto-detects the harness and writes the right skill files (`.claude/skills/`, `.cursor/skills/`, `.codex/`, `.gemini/`, `.grok/`, etc.), plus provider-native hook manifests where supported. +- Per-model rule tuning: the Gemini build kills image-on-hover motion; the Codex build refuses ghost-cards and over-rounding (`README.md`; ``/`` sections in `craft-floor.md`). +- `npx skills add pbakaus/impeccable` installs one shared build for every harness (functionally complete, not tailored). +- Claude Code plugin: `/plugin marketplace add pbakaus/impeccable`. +- GitHub Copilot: Impeccable is built in (Settings → Experimental). + +## Evidence for the stinger + +- The Bee's default domain is web; native surfaces route to the native playbooks and the native audit pass. +- The stinger should note the per-model build behavior so the Bee knows the installed build may carry extra rules for its model. diff --git a/.agents/skills/impeccable-stinger/research/11-license-provenance.md b/.agents/skills/impeccable-stinger/research/11-license-provenance.md new file mode 100644 index 00000000..409c38f8 --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/11-license-provenance.md @@ -0,0 +1,27 @@ +# 11 — License, Provenance & Versioning + +**Source:** `LICENSE`, `NOTICE.md`, `package.json`, `README.md`, `impeccable.style/robots.txt` + +## License + +- **Apache-2.0** (`LICENSE`; `package.json` `"license": "Apache-2.0"`; `cli/engine/detect-antipatterns.mjs` header: "SPDX-License-Identifier: Apache-2.0"). +- Vendoring guidance content into the stinger is license-clean with attribution. Keep the NOTICE/attribution (`NOTICE.md` exists in the repo). +- Author: Paul Bakaus. Homepage: impeccable.style. npm: `impeccable`. + +## Site content signals (compliance) + +- `impeccable.style/robots.txt`: `Content-Signal: search=yes, ai-train=no, use=reference` (Cloudflare managed; also disallows GPTBot, ClaudeBot, CCBot, etc.). +- Implication: the stinger must be built from the **repo** (Apache-2.0), not scraped from the site. Site text is reference-only for understanding, not a training/vendoring source. + +## Versioning + +- Repo `package.json`: `3.5.0` (npm package version). Site markets **v4** ("A leaner core, tuned on frontier models like Fable and GPT-5.6-Sol. Four visitor modes."). +- Content is in sync: the repo's `SKILL.src.md` has all four modes (Persuade/Operate/Read/Experience); the site docs are generated from the repo's `skill/reference/` files. +- Upstream is actively maintained (repo HEAD `aee6ce9`, 2026-08-04; sitemap lastmods through 2026-07-22). +- Implication: the stinger's vendored reference docs need a refresh cadence; the installed side self-updates via `npx impeccable check`/`update`. + +## Research provenance + +- Clone: `/tmp/impeccable-RZVWdD` (shallow, depth 1, commit `aee6ce9`). +- Detector verified live: `node cli/bin/cli.js detect tests/fixtures` produced line-numbered findings (side-tab, design-system-color, etc.). +- Site pages fetched for reference: `/`, `/docs*`, `/slop`, `/research`, `/designing`, `/cases/neo-mirai`, `/tutorials/*`. diff --git a/.agents/skills/impeccable-stinger/research/index.md b/.agents/skills/impeccable-stinger/research/index.md new file mode 100644 index 00000000..40547606 --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/index.md @@ -0,0 +1,26 @@ +# Research Index — impeccable-stinger + +Manifest of primary-source research for `impeccable-worker-bee`. All files cite repo paths under `/tmp/impeccable-RZVWdD` (github.com/pbakaus/impeccable, commit aee6ce9, Apache-2.0). + +| File | Covers | Primary sources | +|---|---|---| +| `research-plan.md` | Scope, depth, method, provenance | Command Brief, repo | +| `01-system-overview.md` | Whole system: 7 layers, four-phase loop, per-model builds | `README.md`, `PRODUCT.md`, `skill/SKILL.src.md`, `package.json`, site `/designing` | +| `02-context-contract.md` | PRODUCT.md / DESIGN.md / surfaces / design.json, modes | `skill/scripts/context.mjs`, `skill/reference/init.md`, `document.md`, site `/docs/context` | +| `03-command-vocabulary.md` | 23 commands, routing rules, pinning | `skill/scripts/command-metadata.json`, `skill/SKILL.src.md`, site `/docs` | +| `04-new-work-direction.md` | Classification, five tests, direction contract, roll/dice, research lessons | `skill/reference/new-work.md`, `skill/scripts/concept-seed.mjs`, `lib/concept-catalog.mjs`, site `/research` | +| `05-craft-floor.md` | Quality floor, bans, reflexes, per-model sections | `skill/reference/craft-floor.md` | +| `06-detector-rules.md` | 59 rules (id/category/severity), CLI, exit codes, engines, ignores | `cli/engine/registry/antipatterns.mjs`, `cli/engine/*`, site `/slop` | +| `07-hooks-enforcement.md` | Per-edit + deep pass, harness manifests, approval, config | `skill/reference/hooks.md`, `skill/scripts/hook-admin.mjs`, `hook-lib.mjs`, site `/docs/hooks` | +| `08-live-mode.md` | Live browser iteration, alpha status, scripts | `skill/reference/live.md`, `skill/scripts/live/*`, site `/docs/live` | +| `09-maintenance-doctor.md` | Doctor (tool/schema/truth drift), config, ignores, update | `skill/reference/doctor.md`, `skill/scripts/doctor.mjs`, site `/docs/doctor`, `/docs/config` | +| `10-native-platforms-harnesses.md` | iOS/Android/adaptive, per-harness builds, per-model rules | `skill/reference/ios.md`, `android.md`, `audit.native.md`, `adapt.native.md`, `docs/HARNESSES.md` | +| `11-license-provenance.md` | Apache-2.0, site content signals, versioning, research provenance | `LICENSE`, `NOTICE.md`, `package.json`, site `robots.txt` | + +## Open questions for the user (not for stinger-forge to invent) + +1. **Scope of the Bee's routing:** should `impeccable-worker-bee` become the *default* router for all frontend UI/UX work (retiring `design-taste-frontend`, `frontend-design`, `high-end-visual-design`, `gpt-taste`, `web-design-guidelines` as fallbacks), or coexist? +2. **Upstream install vs stinger-only:** should the army run `npx impeccable install` per project (hooks + compiled skill) as the enforcement layer, with the stinger as guidance + gate procedure? (Recommended: yes.) +3. **CI gate:** add `npx impeccable detect src/` to army projects' PR checks? +4. **Live Mode:** adopt now (alpha) or defer until stable? +5. **Native:** does the army need the iOS/Android/adaptive playbooks in the first stinger release, or web-only? diff --git a/.agents/skills/impeccable-stinger/research/research-plan.md b/.agents/skills/impeccable-stinger/research/research-plan.md new file mode 100644 index 00000000..7e66e342 --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/research-plan.md @@ -0,0 +1,8 @@ +# Research Plan: impeccable-stinger + +- **Bee:** impeccable-worker-bee (Command Brief: `.cursor/commands/impeccable-worker-bee-command-brief.md`) +- **Depth tier:** deep (entire system: context contract, 23 commands, four-phase loop, 59-rule detector, hooks, live mode, worlds deck, maintenance) +- **Primary source:** `github.com/pbakaus/impeccable` (Apache-2.0), cloned at `/tmp/impeccable-RZVWdD` (commit `aee6ce9`, 2026-08-04, package v3.5.0) +- **Method:** repo-primary extraction (user-directed), not a web sweep. The repo is the canonical Apache-2.0 source; impeccable.style is generated from it and is reference-only (robots.txt: `ai-train=no, use=reference`). +- **Evidence files to extract:** `skill/SKILL.src.md`, `skill/reference/*.md` (33 files), `skill/scripts/*` (context, concept-seed, hook-admin, doctor, live), `cli/engine/registry/antipatterns.mjs` (59 rules), `cli/engine/*` (checks, constants, color, design-system, engines), `docs/*`, `DESIGN.md`, `PRODUCT.md`, `README.md`, `package.json`, `LICENSE`, `NOTICE.md`, `tests/`. +- **Output:** `research/` files below, `index.md` manifest, `research-summary.md` handoff. diff --git a/.agents/skills/impeccable-stinger/research/research-summary.md b/.agents/skills/impeccable-stinger/research/research-summary.md new file mode 100644 index 00000000..2d0e0597 --- /dev/null +++ b/.agents/skills/impeccable-stinger/research/research-summary.md @@ -0,0 +1,37 @@ +# Research Summary — impeccable-stinger + +- **Depth tier consumed:** deep (entire system) +- **Time window covered:** repo HEAD `aee6ce9` (2026-08-04); site sitemap lastmods 2026-04-10 → 2026-07-22. Repo-primary research, not a web sweep (user-directed; site robots.txt `ai-train=no`). +- **Files written:** 13 (research-plan + 11 topic files + index + this summary) under `.cursor/skills/impeccable-stinger/research/`. + +## The 5 most influential sources (for stinger-forge) + +1. **`skill/SKILL.src.md`** — the skill definition: setup, four modes, command routing, hooks, doctor, bounded-pass discipline. The stinger's SKILL.md should mirror its structure and voice. +2. **`skill/reference/craft-floor.md`** — the quality floor, absolute bans, and per-model (``, ``) sections. This is the anti-slop core the Bee enforces. +3. **`skill/reference/new-work.md` + `skill/scripts/concept-seed.mjs`** — job classification, five tests, direction contract, and the roll/dice variance machinery. This is what makes the system "whole" and is unique vs every existing army skill. +4. **`cli/engine/registry/antipatterns.mjs`** — the 59 deterministic rules (id/category/severity) that power the gate, hooks, CI, and slop catalog. The Bee's mandatory close-out gate. +5. **`skill/reference/hooks.md` + `skill/scripts/hook-admin.mjs`** — per-edit + deep-pass enforcement, harness manifests, Codex approval. The "every time" enforcement layer. + +## Open questions (for the user, not stinger-forge) + +1. Default router for all frontend UI/UX work, retiring overlapping prompt-only skills as fallbacks? +2. Upstream `npx impeccable install` per project as the enforcement layer (recommended), stinger as guidance + gate? +3. CI gate on army PR checks? +4. Live Mode now (alpha) or defer? +5. Native playbooks in first release, or web-only? + +## Sources stinger-forge should re-fetch with deeper context + +- `skill/reference/audit.md` + `audit.native.md` (5-dimension scoring rubric, P0-P3) — needed for the Polish-phase guide. +- `skill/reference/init.md` + `document.md` (interview flow, Stitch-format capture) — needed for the Start-phase guide. +- `skill/reference/live.md` + `live-setup.md` (alpha; decide inclusion). +- `docs/HARNESSES.md` (per-harness install/update details) — needed for the install/verify guide. +- `skill/scripts/context.mjs` (context loading + staleness directives) — needed for the context-contract guide. + +## Decisions (user-resolved 2026-08-06) + +1. Default router for all frontend UI/UX work — YES (retire overlapping prompt-only skills to fallbacks). +2. Install scope — HYBRID: global skill install + per-project context/hooks (hooks are project-local by harness design). +3. CI gate — YES (`npx impeccable detect src/` in PR checks). +4. Live Mode — include as opt-in, user-invoked, alpha; never auto-launched. +5. Native — include iOS/Android/adaptive playbooks. diff --git a/.agents/skills/impeccable-stinger/scripts/sync-check.mjs b/.agents/skills/impeccable-stinger/scripts/sync-check.mjs new file mode 100755 index 00000000..adfeabdf --- /dev/null +++ b/.agents/skills/impeccable-stinger/scripts/sync-check.mjs @@ -0,0 +1,157 @@ +#!/usr/bin/env node +/** + * impeccable-stinger pre-flight sync check. + * + * Verifies, before a design task starts, that the installed Impeccable skill + * is current with upstream and that the stinger's vendored coverage (guides + + * templates) still matches the installed skill's content. If everything is + * current it is skipped (exit 0); if behind or drifted it reports what changed + * (exit 2); if the skill is not installed it says so (exit 1). + * + * Usage: + * node sync-check.mjs # check only + * node sync-check.mjs --update # check, and run `npx impeccable update` when behind + * + * Exit codes: + * 0 = current and in sync (skip) + * 2 = behind upstream and/or content drift (needs update/refresh) + * 1 = not installed or check failed + */ +import { readFileSync, existsSync, readdirSync } from 'node:fs'; +import { join, dirname } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { spawnSync } from 'node:child_process'; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const STINGER = join(HERE, '..'); +const MANIFEST = JSON.parse(readFileSync(join(HERE, 'upstream-manifest.json'), 'utf8')); + +const CANDIDATE_DIRS = [ + join(process.env.HOME || '', '.agents', 'skills', 'impeccable'), + join(process.env.HOME || '', '.codex', 'skills', 'impeccable'), + join(process.env.HOME || '', '.claude', 'skills', 'impeccable'), + join(process.env.HOME || '', '.cursor', 'skills', 'impeccable'), + '.agents/skills/impeccable', + '.codex/skills/impeccable', + '.claude/skills/impeccable', + '.cursor/skills/impeccable', +]; + +const UPDATE_HOST = process.env.IMPECCABLE_UPDATE_HOST || 'https://impeccable.style'; +const FETCH_TIMEOUT_MS = 4000; + +function findInstalledSkill() { + for (const dir of CANDIDATE_DIRS) { + if (existsSync(join(dir, 'SKILL.md'))) return dir; + } + return null; +} + +function readInstalledVersion(dir) { + try { + const md = readFileSync(join(dir, 'SKILL.md'), 'utf8'); + const m = md.match(/^version:\s*(.+)$/m); + return m ? m[1].trim() : null; + } catch { + return null; + } +} + +function compareVersions(a, b) { + const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0); + const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0); + for (let i = 0; i < Math.max(pa.length, pb.length); i++) { + const da = pa[i] || 0; + const db = pb[i] || 0; + if (da !== db) return da - db; + } + return 0; +} + +async function fetchPublishedVersion() { + try { + const res = await fetch(`${UPDATE_HOST}/api/version`, { + signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), + }); + if (!res.ok) return null; + const body = await res.text(); + const m = body.match(/"version"\s*:\s*"([^"]+)"/) || body.match(/"skills"\s*:\s*"([^"]+)"/) || body.match(/^([0-9]+\.[0-9]+\.[0-9]+)/m); + return m ? m[1] : body.trim(); + } catch { + return null; + } +} + +function contentDrift(dir) { + const drift = { newReferenceFiles: [], newCommands: [], missingReferenceFiles: [] }; + const refDir = join(dir, 'reference'); + if (existsSync(refDir)) { + const installed = readdirSync(refDir).filter((f) => f.endsWith('.md')).sort(); + drift.newReferenceFiles = installed.filter((f) => !MANIFEST.referenceFiles.includes(f)); + drift.missingReferenceFiles = MANIFEST.referenceFiles.filter((f) => !installed.includes(f)); + } + const metaPath = join(dir, 'scripts', 'command-metadata.json'); + if (existsSync(metaPath)) { + try { + const meta = JSON.parse(readFileSync(metaPath, 'utf8')); + drift.newCommands = Object.keys(meta).filter((c) => !MANIFEST.commands.includes(c)); + } catch { + /* ignore unreadable metadata */ + } + } + return drift; +} + +function runUpdate() { + const r = spawnSync('npx', ['impeccable', 'update'], { stdio: 'inherit', shell: true }); + return r.status === 0; +} + +async function main() { + const args = process.argv.slice(2); + const doUpdate = args.includes('--update'); + + const installedDir = findInstalledSkill(); + if (!installedDir) { + console.log('[sync-check] NOT INSTALLED: no impeccable skill found in any harness skill dir.'); + console.log('[sync-check] Run: npx impeccable install --scope=global --providers=codex,claude,cursor'); + process.exit(1); + } + + const installedVersion = readInstalledVersion(installedDir); + const publishedVersion = await fetchPublishedVersion(); + const drift = contentDrift(installedDir); + + const behind = installedVersion && publishedVersion && compareVersions(publishedVersion, installedVersion) > 0; + const hasDrift = drift.newReferenceFiles.length > 0 || drift.newCommands.length > 0; + + console.log(`[sync-check] installed: ${installedVersion || 'unknown'} @ ${installedDir}`); + console.log(`[sync-check] published: ${publishedVersion || 'unreachable (offline?)'}`); + if (behind) console.log(`[sync-check] BEHIND: installed ${installedVersion} < published ${publishedVersion}`); + if (drift.newCommands.length) console.log(`[sync-check] NEW COMMANDS upstream: ${drift.newCommands.join(', ')}`); + if (drift.newReferenceFiles.length) console.log(`[sync-check] NEW REFERENCE FILES upstream: ${drift.newReferenceFiles.join(', ')}`); + if (drift.missingReferenceFiles.length) console.log(`[sync-check] MISSING REFERENCE FILES (installed skill lacks): ${drift.missingReferenceFiles.join(', ')}`); + + if (!behind && !hasDrift) { + console.log('[sync-check] CURRENT: upstream in sync, stinger coverage matches. Skipping update.'); + process.exit(0); + } + + if (doUpdate && behind) { + console.log('[sync-check] Running `npx impeccable update`...'); + if (runUpdate()) { + console.log('[sync-check] Updated. NOTE: Codex may require /hooks re-approval after an update.'); + process.exit(0); + } + console.log('[sync-check] Update failed.'); + process.exit(1); + } + + if (hasDrift) { + console.log('[sync-check] STINGER REFRESH NEEDED: upstream added content the stinger does not cover.'); + console.log('[sync-check] Add guides/templates for the new content, then update scripts/upstream-manifest.json.'); + } + process.exit(2); +} + +main(); diff --git a/.agents/skills/impeccable-stinger/scripts/upstream-manifest.json b/.agents/skills/impeccable-stinger/scripts/upstream-manifest.json new file mode 100644 index 00000000..b96d7c6c --- /dev/null +++ b/.agents/skills/impeccable-stinger/scripts/upstream-manifest.json @@ -0,0 +1,128 @@ +{ + "upstreamVersion": "4.0.4", + "upstreamCommit": "aee6ce9", + "upstreamDate": "2026-08-04", + "commands": [ + "craft", + "init", + "document", + "extract", + "live", + "adapt", + "animate", + "audit", + "bolder", + "clarify", + "colorize", + "critique", + "delight", + "distill", + "harden", + "onboard", + "layout", + "optimize", + "overdrive", + "polish", + "quieter", + "shape", + "typeset" + ], + "referenceFiles": [ + "adapt.md", + "adapt.native.md", + "android.md", + "animate.md", + "audit.md", + "audit.native.md", + "bolder.md", + "clarify.md", + "colorize.md", + "craft-floor.md", + "craft.md", + "critique.md", + "delight.md", + "distill.md", + "doctor.md", + "document.md", + "extract.md", + "harden.md", + "hooks.md", + "init.md", + "ios.md", + "layout.md", + "live-setup.md", + "live.md", + "new-work.md", + "onboard.md", + "operate.md", + "optimize.md", + "overdrive.md", + "polish.md", + "quieter.md", + "routing.md", + "shape.md", + "typeset.md", + "visualize.md" + ], + "rules": [ + "side-tab", + "border-accent-on-rounded", + "overused-font", + "flat-type-hierarchy", + "gradient-text", + "ai-color-palette", + "cream-palette", + "nested-cards", + "monotonous-spacing", + "bounce-easing", + "pulsing-dot", + "blinking-cursor", + "shape-assembled-illustration", + "dark-glow", + "radial-halo", + "radial-spotlight-glow", + "marquee", + "icon-tile-stack", + "italic-serif-display", + "hero-eyebrow-chip", + "kicker-above-heading", + "numbered-section-labels", + "em-dash-overuse", + "marketing-buzzword", + "aphoristic-cadence", + "oversized-h1", + "extreme-negative-tracking", + "broken-image", + "script-error", + "content-hidden-at-rest", + "edge-flush-cards", + "text-occlusion", + "first-viewport-column-overflow", + "gray-on-color", + "low-contrast", + "layout-transition", + "line-length", + "cramped-padding", + "body-text-viewport-edge", + "tight-leading", + "skipped-heading", + "heading-rhythm", + "justified-text", + "tiny-text", + "undersized-ui-text", + "all-caps-body", + "wide-tracking", + "text-overflow", + "repeated-container-text", + "clipped-overflow-container", + "design-system-font", + "design-system-color", + "design-system-radius", + "design-system-font-size", + "gpt-thin-border-wide-shadow", + "repeating-stripes-gradient", + "codex-grid-background", + "theater-slop-phrase", + "image-hover-transform" + ] +} diff --git a/.agents/skills/impeccable-stinger/templates/direction-contract.md b/.agents/skills/impeccable-stinger/templates/direction-contract.md new file mode 100644 index 00000000..96c3ffbf --- /dev/null +++ b/.agents/skills/impeccable-stinger/templates/direction-contract.md @@ -0,0 +1,16 @@ +# Direction Contract (write into the artifact as a comment block, <=150 words, five blocks) + +```ts +/* + * THESIS: + * OWN-WORLD: + * STORY: + * FIRST VIEWPORT: + * FORM: + */ +``` + +Rules: +- The contract is inspectable intent. A separate reviewer audits the built page against it promise-by-promise. +- Keep the seed key to reproduce the roll (including every re-roll round). +- A page that promised a radical composition and shipped the usual template does not pass quietly. diff --git a/.agents/skills/impeccable-stinger/templates/gate-report.md b/.agents/skills/impeccable-stinger/templates/gate-report.md new file mode 100644 index 00000000..d387c841 --- /dev/null +++ b/.agents/skills/impeccable-stinger/templates/gate-report.md @@ -0,0 +1,22 @@ +# Detector Gate Report + +| Field | Value | +|---|---| +| Target | `` | +| Command | `npx impeccable detect ` | +| Exit code | `0` (no findings) / `2` (findings) / `1` (failed) | +| Findings | `` | +| Resolved | `` | +| Waived | `` | + +## Findings + +| Rule id | Severity | File:line | Resolution (fix or waiver + reason) | +|---|---|---|---| +| `side-tab` | advisory | `src/components/Card.tsx:52` | Fixed — removed inset stripe | +| `overused-font` | advisory | `src/styles/global.css:14` | Waived — `ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md"` | + +## Verdict + +- [ ] Gate clean (0 findings) — close-out may proceed +- [ ] Gate failed (exit 2) — close-out blocked until resolved or waived diff --git a/.agents/skills/impeccable-stinger/templates/surface-brief.md b/.agents/skills/impeccable-stinger/templates/surface-brief.md new file mode 100644 index 00000000..497c4fff --- /dev/null +++ b/.agents/skills/impeccable-stinger/templates/surface-brief.md @@ -0,0 +1,10 @@ +# Surface Brief: `` + +- **Mode:** Persuade / Operate / Read / Experience +- **Job:** what the visitor came to do on this surface +- **Proof sequence:** what evidence the surface shows, in order +- **Chosen direction:** the committed world (or "inherits `` world") +- **Seed key:** `` (if rolled) +- **Anti-references:** what this surface must not do + +Written by the work itself; edited when the page's strategy changes. Lives at `.impeccable/surfaces/.md`. diff --git a/.agents/skills/impeccable-stinger/templates/sync-report.md b/.agents/skills/impeccable-stinger/templates/sync-report.md new file mode 100644 index 00000000..1040935a --- /dev/null +++ b/.agents/skills/impeccable-stinger/templates/sync-report.md @@ -0,0 +1,14 @@ +# Sync Check Report + +| Field | Value | +|---|---| +| Installed version | `<4.0.4>` | +| Published version | `<4.0.4>` | +| Status | `current` / `behind` / `not installed` | +| New commands upstream | `` | +| New reference files upstream | `` | +| Action taken | `skipped (current)` / `updated` / `stinger refresh` | + +- [ ] Current → skipped, task proceeded +- [ ] Updated → `/hooks` re-approval noted to user +- [ ] Stinger refresh needed → new guide/template added, manifest bumped diff --git a/.claude/agents/impeccable-worker-bee.md b/.claude/agents/impeccable-worker-bee.md new file mode 100644 index 00000000..0d3a84e0 --- /dev/null +++ b/.claude/agents/impeccable-worker-bee.md @@ -0,0 +1,114 @@ +--- +name: "impeccable-worker-bee" +description: "Operates the entire Impeccable design system (pbakaus/impeccable, Apache-2.0) as the Bee Army's frontend-design operating system: the four-phase loop (Start -> Iterate -> Polish -> 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 proactively for ANY frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture - \"polish the pricing page\", \"build a dashboard\", \"redo this hero\", \"make this not look like AI slop\". Do NOT invoke for backend-only or non-UI tasks, or for product-specific design-system token enforcement - that is design-system-worker-bee / ux-ui-worker-bee." +--- + +# Impeccable Worker Bee + +Before doing anything else, read `.claude/skills/impeccable-stinger/SKILL.md` in full and follow it as the operating manual. + +## Identity & responsibility + +`impeccable-worker-bee` is the roster's frontend-design operating system operator. It owns the entire Impeccable system as a closed loop: context contract, 23-command vocabulary, the four-phase design loop (Start -> Iterate -> Polish -> Maintain), the deterministic 59-rule anti-slop detector gate, hooks, live mode, and native playbooks. Every design element and every new page surface stays cohesive, from no design to a well-maintained design, or from a current design to a better design. It is the single router for all frontend UI/UX/design implementation work. It does not own product-specific design-system token enforcement (that is `design-system-worker-bee` / `ux-ui-worker-bee`), and it never vendors or re-implements the Impeccable engine: it operates the installed system. + +## Paired Stinger + +[`.claude/skills/impeccable-stinger/`](../skills/impeccable-stinger/) + +The Stinger's `SKILL.md` is the master index. Read it in full before any design work, then open the guides and reusable artifacts named by the selected phase. + +## Activation contract + +Activate proactively when the assigned work touches any of these surfaces: + +- Any frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture. +- Requests such as "polish the pricing page", "build a dashboard", "redo this hero", "make this not look like AI slop", "design a settings screen", "audit this UI", or any task that needs a cohesive visual system. +- Any task where the user wants to see the design live during development and point at issues before a PR. + +Do not activate as the final authority for product-specific design-system token enforcement (route to `design-system-worker-bee` / `ux-ui-worker-bee`), backend/non-UI work, Lighthouse/perf-only audits (route to `quality-worker-bee`), or Security acceptance (route to `security-worker-bee`). + +## Procedure + +1. **Phase 0 - Pre-flight sync check.** Run `node .claude/skills/impeccable-stinger/scripts/sync-check.mjs`. Exit `0` (current, in sync) -> skip and proceed. Exit `2` (behind upstream and/or content drift) -> `npx impeccable update` (note Codex `/hooks` re-approval to the user), refresh the stinger's guides/templates + `scripts/upstream-manifest.json` for new upstream content, re-run. Exit `1` (not installed) -> global install first (`npx impeccable install --scope=global --providers=codex,claude,cursor`), then per-project `install` + `init` + `document`. Record the result per `templates/sync-report.md`. See `guides/11-sync-check.md`. +2. **Phase 1 - Start (context + direction).** Ensure the context contract exists (`/impeccable init` -> `PRODUCT.md`; `/impeccable document` -> `DESIGN.md` + `.impeccable/design.json`); read it if present, never re-derive. Classify the job (greenfield / local extension / new surface / expression expansion / redesign / refinement). 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, apply the five tests (Truth, Translation, Consequence, Survival, Fit), and write the direction contract (`THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`) into the artifact per `templates/direction-contract.md`. Visualize when image tooling is available, then build toward the image. See `guides/01-context-contract.md` and `guides/02-start-phase.md`. +3. **Phase 2 - Iterate (bounded rounds).** Use named commands when the edit has a name (`polish`, `bolder`, `quieter`, `distill`, `typeset`, `layout`, `colorize`, `animate`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `harden`, `onboard`). `/impeccable live` is opt-in, user-invoked only (alpha): never auto-launch it. Bound the loop: build fully, inspect once batched (desktop + mobile), fix in one batch, confirm at most once, stop. The user is the "happy" gate. See `guides/03-iterate-phase.md` and `guides/08-live-mode.md`. +4. **Phase 3 - Polish (pre-ship gauntlet).** Run `/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). Run the deterministic gate: `npx impeccable detect ` (file, dir, or URL; `--json` for CI). Exit code 2 = findings = close-out fails until resolved or waived (narrowest ignore + reason). Hand off to the army close-out: `security-worker-bee` first, then `quality-worker-bee`. See `guides/04-polish-phase.md` and `guides/06-detector-gate.md`. +5. **Phase 4 - Maintain (cohesion).** `/impeccable extract` (fold repeated patterns into tokens/primitives), `/impeccable document` (re-capture the system when code drifts), `/impeccable doctor` (schema/truth/hook-path/config drift), `npx impeccable check` / `update` (keep the installed system current). Never repair drift as a side effect of a design task. See `guides/05-maintain-phase.md`. +6. **Install & verify (hybrid scope).** Global skill: `npx impeccable install --scope=global --providers=codex,claude,cursor`. Per project (one-time): `npx impeccable install` writes the hook manifests and `.impeccable/config.json`; `init`/`document` write the context files. Codex requires `/hooks` approval after install/update. Verify with `/impeccable doctor`. See `guides/10-install-and-verify.md`. +7. **Native surfaces.** 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`. + +## Critical directives + +- **Never self-grade.** Iterate in bounded rounds; the user is the "happy" gate. A separate reviewer (`quality-worker-bee` or a fresh reader) audits the build against its direction contract promise-by-promise. Self-accountability has ground truth, rubrics don't. +- **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. +- **The gate is mandatory.** `npx impeccable detect` exit code 2 fails the close-out. Waivers require the narrowest ignore plus a stated reason. +- **Upstream always in sync.** The pre-flight sync check runs before every task; if current it is skipped, if behind it is updated before any design work. A stale stinger manifest (new upstream commands/reference files) is a real finding: refresh the stinger, never proceed blind. +- **Never fork or modify the engine.** Call the installed system (`/impeccable`, `npx impeccable`); follow the bee-army-update contract (no upstream script execution during install, preserve the ownership manifest, no silent overwrites). +- **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. +- **Single vocabulary.** Never mix Impeccable with other design-taste skills in the same session: two design vocabularies collide and cancel each other out. +- **License discipline.** Apache-2.0 upstream; build from the repo, not the site (site robots.txt: `ai-train=no, use=reference`). Keep attribution. +- **Close-out order.** Security before quality, always. + +## Escalation + +Stop and ask one clarifying question when the surface, mode, or product context is genuinely ambiguous: never silently guess. Route unresolved work as follows: + +- Product-specific design-system token enforcement -> `design-system-worker-bee` / `ux-ui-worker-bee`. +- Backend/non-UI logic -> `react-worker-bee`, `preact-worker-bee`, or the relevant domain Bee. +- Lighthouse/perf-only audits -> `quality-worker-bee`. +- Security acceptance -> `security-worker-bee` (before quality). +- Live Mode (alpha) rough edges on uncommon setups -> flag to the user and fall back to named commands. +- Codex `/hooks` re-approval after an install/update -> surface to the user before proceeding. + +## References to skill files + +Utilize the Read tool to understand your skills listed at `.claude/skills/impeccable-stinger/` with all of its sub-folders and files. Read `SKILL.md` in full first. + +### Master indexes + +- `SKILL.md` - the four-phase loop, Phase 0 sync check, core principles, install/verify, native surfaces. +- `README.md` - folder layout, provenance, license. + +### Principles and procedures (guides/) + +- `guides/00-principles.md` - the system's non-negotiables (bounded passes, brief wins, no self-grading, single vocabulary, gate mandatory) +- `guides/01-context-contract.md` - PRODUCT.md / DESIGN.md / surfaces / design.json / four modes +- `guides/02-start-phase.md` - init, document, job classification, new-work flow, five tests, direction contract, roll, visualize +- `guides/03-iterate-phase.md` - named commands, bounded-round discipline, live mode opt-in +- `guides/04-polish-phase.md` - audit / clarify / harden, P0-P3, the deterministic gate, close-out +- `guides/05-maintain-phase.md` - extract / document / doctor / update, drift rules +- `guides/06-detector-gate.md` - CLI usage, exit codes, all 59 rules, DESIGN.md awareness, ignores, CI wiring +- `guides/07-hooks.md` - per-edit + deep pass, harness manifests, approval, the silent-hook failure mode +- `guides/08-live-mode.md` - opt-in browser iteration (alpha), session flow, Chrome extension +- `guides/09-native.md` - iOS / Android / adaptive playbooks, per-model harness builds +- `guides/10-install-and-verify.md` - global skill install + per-project hooks/context, doctor +- `guides/11-sync-check.md` - pre-flight upstream sync check (skip when current) + +### Worked examples (examples/) + +- `examples/01-happy-path-new-surface.md` - greenfield -> direction contract -> build -> gate -> maintain +- `examples/02-edge-case-refinement.md` - refinement with a narrow waiver +- `examples/03-live-mode-session.md` - opt-in live iteration +- `examples/04-sync-check.md` - pre-flight sync check (current / behind / drift / not installed) + +### Output templates (templates/) + +- `templates/direction-contract.md` - THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM +- `templates/gate-report.md` - detector gate result for the close-out +- `templates/surface-brief.md` - per-surface mode/job/proof/direction +- `templates/sync-report.md` - pre-flight sync check result + +### Scripts (scripts/) + +- `scripts/sync-check.mjs` - the pre-flight sync check runner (exit 0 skip / 2 update / 1 install) +- `scripts/upstream-manifest.json` - upstream content coverage manifest (commands, reference files, rules) + +### Research trail (research/) + +- `research/research-summary.md` - depth tier, sources, decisions, handoff +- `research/index.md` - manifest of all research files +- `research/01-system-overview.md` through `research/11-license-provenance.md` - primary-source evidence + +--- + +*Created by the Legendary Bee Factory.* diff --git a/.claude/skills/beekeeper-suit/PAIRING-AUDIT.md b/.claude/skills/beekeeper-suit/PAIRING-AUDIT.md index 0672198c..7f43f861 100644 --- a/.claude/skills/beekeeper-suit/PAIRING-AUDIT.md +++ b/.claude/skills/beekeeper-suit/PAIRING-AUDIT.md @@ -4,16 +4,22 @@ Ground truth pulled from the filesystem on 2026-08-14, after the repair pass. Th ## Totals -- Bees (`.claude/agents/*.md`): **75** -- Stinger folders (`.claude/skills/*`): **78** +- Bees (`.claude/agents/*.md`): **76** +- Stinger folders (`.claude/skills/*`): **79** - Orchestrator-level skills with no paired Bee by design: **3** (`beekeeper-suit`, `queen-bee-stinger`, `get-started-stinger`) -- Pairable Stingers: **75** +- Pairable Stingers: **76** ## Pairing integrity Clean. Every Bee has a matching Stinger and every pairable Stinger has a matching Bee, verified in both directions by naming convention. Zero orphans. -Every Bee also has a routing guide at `guides/.md`. 75 Bees, 75 guides, one-to-one. +Every Bee also has a routing guide at `guides/.md`. 76 Bees, 76 guides, one-to-one. + +## New additions + +`impeccable-worker-bee` / `impeccable-stinger` was ported in from a prior fork and registered here: it operates the Impeccable design system (pbakaus/impeccable, Apache-2.0) as the frontend-design operating system. The Impeccable engine is installed per machine via `npx impeccable install --scope=global --providers=codex,claude,cursor`; it is not vendored in this repo. The stinger's pre-flight sync check (`scripts/sync-check.mjs`) verifies the installed engine is current. + +`impeccable-worker-bee` is the single router for frontend UI/UX/design implementation. `design-system-worker-bee` and `ux-ui-svelte-worker-bee` retain product-specific token, component-library, and accessibility enforcement on established systems. ## Path integrity @@ -41,7 +47,7 @@ All routing references to the renamed `deeplake-dataset-worker-bee` were repaire ## Validation -All 78 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 75 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. +All 79 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 76 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. ## Dead reference repair diff --git a/.claude/skills/beekeeper-suit/SKILL.md b/.claude/skills/beekeeper-suit/SKILL.md index 1a137f45..14cb55e1 100644 --- a/.claude/skills/beekeeper-suit/SKILL.md +++ b/.claude/skills/beekeeper-suit/SKILL.md @@ -28,7 +28,7 @@ Three skills sit above the pairing law because they are orchestrator level, not ## Roster -75 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. +76 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. ### Stack and frameworks @@ -42,7 +42,7 @@ Three skills sit above the pairing law because they are orchestrator level, not | `react-worker-bee` | React 18/19 architecture: bulletproof-react patterns, Server Components, Suspense, Actions, Compiler, state layering | "review React architecture", "state management decision", "Server Components boundary", "React 19 patterns" | `react-stinger` | | `typescript-node-worker-bee` | TypeScript/Node code review and conventions: strict config, module resolution, test suites, boundary validation (body still cites a legacy package's specifics; see PAIRING-AUDIT.md) | "review this TypeScript code", "audit this Node code", "write a Vitest suite", "tighten the tsconfig" | `typescript-node-stinger` | | `python-worker-bee` | Python architecture: Django + Django Ninja + FastAPI + Celery + Channels + pytest + uv, ORM discipline, migrations, typed adoption | "review this Django code", "audit ORM patterns", "migrate DRF to Django Ninja", "set up Celery" | `python-stinger` | -| `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | +| `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract. Impeccable remains the primary router for UI/design implementation | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | | `dark-mode-theming-worker-bee` | Dark-mode theming: CSS variable token architecture, theme-provider wiring, FOWT prevention, SSR hydration safety, Tailwind v4 dark variant | "set up dark mode", "dark mode on SSR", "multi-brand theming", "FOWT fix" | `dark-mode-theming-stinger` | | `modal-toast-dialog-worker-bee` | Accessible overlay primitives: dialog, alert dialog, drawer, toast, command menu; focus trap, escape, scroll lock, aria contract | "choosing between overlay primitives", "debugging focus trap regressions", "building a command palette" | `modal-toast-dialog-stinger` | | `icon-system-worker-bee` | Icon library selection and delivery: tree-shake vs sprite, dynamic-import-by-name, custom SVG components, icon accessibility contract | "choosing an icon library", "bundle-size regressions from icon imports", "icon accessibility" | `icon-system-stinger` | @@ -50,7 +50,8 @@ Three skills sit above the pairing law because they are orchestrator level, not | `font-loading-worker-bee` | Font loading pipeline: font-display strategy, preload/crossorigin correctness, variable-font subsetting, CLS-from-font-swap elimination | "audit font loading", "fix FOIT", "CLS from font swap", "subset variable font" | `font-loading-stinger` | | `markdown-mdx-content-pipeline-worker-bee` | Markdown/MDX pipeline: compiler selection, remark/rehype chains, syntax highlighting, AST manipulation, XSS sanitization | "set up MDX", "configure Shiki", "write a remark plugin", "sanitize user markdown" | `markdown-mdx-content-pipeline-stinger` | | `csv-xlsx-import-export-worker-bee` | Spreadsheet upload and export feature: CSV/XLSX parsing, large-file streaming, column-mapping wizard, row validation, CSV injection prevention | "build a CSV import", "add XLSX upload", "column-mapping wizard", "CSV injection safe" | `csv-xlsx-import-export-stinger` | -| `design-system-worker-bee` | Bootstraps a complete design system from scratch: tokens, utility layer, per-component and per-screen specs, static HTML examples | "build a design system for X", "bootstrap UI for product Y", "create tokens and utilities for this product" | `design-system-stinger` | +| `design-system-worker-bee` | Bootstraps a complete design system from scratch: tokens, utility layer, per-component and per-screen specs, static HTML examples. Impeccable owns frontend UI/UX/design implementation and uses DESIGN.md drift rules plus its detector gate to make enforcement mechanical | "build a design system for X", "bootstrap UI for product Y", "create tokens and utilities for this product" | `design-system-stinger` | +| `impeccable-worker-bee` | Frontend-design operating system for all UI/UX/design implementation, redesign, refinement, new surfaces, components, and design-system capture. Runs Start -> Iterate -> Polish -> Maintain, the context contract, and the deterministic detector gate | "polish the pricing page", "build a dashboard", "redo this hero", "make this not look like AI slop", "design a settings screen", "audit this UI" | `impeccable-stinger` | | `http-rest-fundamentals-worker-bee` | HTTP/REST protocol correctness: method safety and idempotency, status-code honesty, headers, conditional and range requests | "is this status code correct", "why is CORS failing", "explain preflight", "PUT vs PATCH" | `http-rest-fundamentals-stinger` | | `image-optimization-worker-bee` | Image delivery: AVIF/WebP format selection, responsive srcset/sizes, blur placeholders, remote image config, CLI tooling | "optimize my images", "convert to AVIF", "fix layout shift from images", "audit our images" | `image-optimization-stinger` | @@ -208,6 +209,12 @@ Real sequences for this stack. Every sequence below closes with the Ship Gate; i 5. `seo-aeo-worker-bee` for metadata, JSON-LD, and Core Web Vitals. 6. Ship Gate. +### Frontend design / UI implementation + +1. **`impeccable-worker-bee`** is the single router for all frontend UI/UX/design implementation, redesign, refinement, new-surface, component, and design-system-capture work. It runs Start -> Iterate -> Polish -> Maintain, including the pre-flight sync check and deterministic `npx impeccable detect ` gate. +2. **`design-system-worker-bee`** and **`ux-ui-svelte-worker-bee`** own product-specific token, component-library, and accessibility enforcement on established systems. Impeccable makes that enforcement mechanical via DESIGN.md drift rules and the detector gate. +3. **`security-worker-bee`** then **`quality-worker-bee`** close out under the Plan execution loop. + ### Add auth 1. `workos-worker-bee` wires AuthKit, sessions, and SSO. @@ -251,7 +258,7 @@ Don't hand-roll a new Bee. Walk [`../queen-bee-stinger/guides/beekeeper-registra --- -**75 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `.claude/skills/`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. +**76 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `.claude/skills/`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. --- diff --git a/.claude/skills/beekeeper-suit/guides/impeccable-worker-bee.md b/.claude/skills/beekeeper-suit/guides/impeccable-worker-bee.md new file mode 100644 index 00000000..f73b2a6c --- /dev/null +++ b/.claude/skills/beekeeper-suit/guides/impeccable-worker-bee.md @@ -0,0 +1,55 @@ +# impeccable-worker-bee + +## Domain +This Bee is the frontend-design operating system operator. It owns the entire Impeccable system (pbakaus/impeccable, Apache-2.0) as a closed loop: the context contract (`PRODUCT.md` + `DESIGN.md` + per-surface briefs + `.impeccable/design.json`), the 23-command vocabulary, the four-phase design loop (Start -> Iterate -> Polish -> Maintain), the deterministic 59-rule anti-slop detector gate, hooks, live mode, and native playbooks. It is the single router for all frontend UI/UX/design implementation work: new surfaces, redesigns, refinements, component work, and design-system capture. It does not fork or modify the upstream Impeccable engine; it operates the pinned portable runtime bundle. + +**Explicit exclusions:** product-specific design-system token enforcement stays with `design-system-worker-bee` / `ux-ui-worker-bee` (this Bee makes that enforcement mechanical via DESIGN.md-drift rules); backend/non-UI work routes to the domain Bee; Lighthouse/perf-only audits stay with `quality-worker-bee`; Security acceptance stays with `security-worker-bee`. + +## Paired Stinger +[impeccable-stinger](../../impeccable-stinger) - the four-phase loop, Phase 0 pre-flight sync check, context contract, detector gate, hooks, live mode, native playbooks, install-and-verify, and the vendored Impeccable engine it operates. + +## Trigger phrases +- "polish the pricing page" +- "build a dashboard" +- "redo this hero" +- "make this not look like AI slop" +- "design a settings screen" +- "audit this UI" +- "keep the design cohesive across new pages" + +Or route proactively when the assigned work touches any frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture, or when the user wants to see the design live during development and point at issues before a PR. + +## Do NOT route when +- The request is product-specific design-system token enforcement, component-library wrapping, or accessibility compliance on an established system: that belongs to `design-system-worker-bee` / `ux-ui-worker-bee`. +- The request is backend-only or non-UI logic: that belongs to `react-worker-bee`, `preact-worker-bee`, or the relevant domain Bee. +- The request is a Lighthouse/perf-only audit: that belongs to `quality-worker-bee`. +- The request is Security acceptance: that belongs to `security-worker-bee` (always before quality). + +If a request straddles two Bees' domains, prefer the narrower-scoped Bee and let the broader one act as backup. + +## Inputs the Bee needs +- The design task: a surface or route to design/redesign/refine, a plain-English request, or a named command intent. +- Repo root and target surface(s); the surface's mode (Persuade / Operate / Read / Experience) or enough context to infer it from the surface, not the product. +- Existing context files if present: `PRODUCT.md`, `DESIGN.md`, `.impeccable/design.json`, `.impeccable/surfaces/*.md`, `.impeccable/config.json`. +- Environment: Node >= 22.18; Impeccable installed per project (`npx impeccable install`) or `npx` network access; hooks approved in Codex (`/hooks`) where applicable. +- Optional: brand kit, anti-references, screenshots, incumbent visual truth (tokens, theme, CSS, components, assets). + +## Outputs +- **Context contract files** - `PRODUCT.md`, `DESIGN.md` (Stitch format), `.impeccable/design.json`, `.impeccable/surfaces/*.md`, owned and kept current by this Bee. +- **Implemented UI** - source changes to the target surface(s), with the direction contract comment block (`THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`) at the top of new artifacts. +- **Detector evidence** - a gate result (0 findings, or resolved findings, or explicit waivers with reasons) attached to the close-out. +- **Design-system updates** - `extract` / `document` outputs that keep the system current. +- **Close-out handoff** - security -> quality verification result, then a summary to the user with what changed and what remains open. + +## Commonly sequenced with +- Plan execution loop: `impeccable-worker-bee` is the implementation Bee for frontend UI/UX/design work; it hands the final implemented state to `security-worker-bee`, reruns affected checks after security fixes, and only then hands it to `quality-worker-bee`. +- Design-system enforcement: `design-system-worker-bee` / `ux-ui-worker-bee` own product-specific token enforcement; `impeccable-worker-bee` makes it mechanical via the DESIGN.md-drift rules and the detector gate. + +## Critical directives the orchestrator should respect +- **Phase 0 pre-flight sync check first** - run `node .claude/skills/impeccable-stinger/scripts/sync-check.mjs` before any design work; skip when current (exit 0), update when behind (exit 2), global-install first when not installed (exit 1). +- **Never self-grade** - the Bee iterates in bounded rounds; 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. +- **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. +- **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 ` runs before any completion claim; exit code 2 fails the close-out until findings are resolved or explicitly waived (narrowest ignore + reason). +- **Never fork or modify the engine** - call the installed system (`/impeccable`, `npx impeccable`); follow the bee-army-update contract (no upstream script execution during install, preserve the ownership manifest, no silent overwrites). +- **Close-out order** - Security before quality, always. diff --git a/.claude/skills/impeccable-stinger/README.md b/.claude/skills/impeccable-stinger/README.md new file mode 100644 index 00000000..466a380d --- /dev/null +++ b/.claude/skills/impeccable-stinger/README.md @@ -0,0 +1,9 @@ +# impeccable-stinger + +The paired Stinger for `impeccable-worker-bee`: the Bee Army's frontend-design operating system operator. It encodes the entire Impeccable system (pbakaus/impeccable, Apache-2.0) as a four-phase loop — **Start → Iterate → Polish → Maintain** — with the deterministic 59-rule anti-slop detector gate as a mandatory close-out step. + +- Command Brief: `.claude/commands/impeccable-worker-bee-command-brief.md` +- Research: `research/research-summary.md` (repo-primary, commit `aee6ce9`, 2026-08-04) +- License: Apache-2.0 (upstream); this stinger is guidance + procedure, never vendored engine code. + +- Bee: `.claude/agents/impeccable-worker-bee.md` (agent file: `.claude/agents/impeccable-worker-bee.toml`) diff --git a/.claude/skills/impeccable-stinger/SKILL.md b/.claude/skills/impeccable-stinger/SKILL.md new file mode 100644 index 00000000..cc9ca3f9 --- /dev/null +++ b/.claude/skills/impeccable-stinger/SKILL.md @@ -0,0 +1,94 @@ +--- +name: "impeccable-stinger" +description: "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-stinger)." +license: Apache-2.0 (upstream impeccable) +--- + +# 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 ` 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 .claude/skills/impeccable-stinger/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 ` (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 `.claude/skills/impeccable-stinger/` 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) diff --git a/.claude/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md b/.claude/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md new file mode 100644 index 00000000..c8780789 --- /dev/null +++ b/.claude/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md @@ -0,0 +1,3 @@ +# Third-party notices + +The Impeccable Stinger documents and operates the Apache-2.0 Impeccable runtime from [pbakaus/impeccable](https://github.com/pbakaus/impeccable), version 4.0.4. It retains that attribution and is distributed as part of the Bee Army only as a reusable operating guide and portable runtime companion. diff --git a/.claude/skills/impeccable-stinger/examples/01-happy-path-new-surface.md b/.claude/skills/impeccable-stinger/examples/01-happy-path-new-surface.md new file mode 100644 index 00000000..9cf54de6 --- /dev/null +++ b/.claude/skills/impeccable-stinger/examples/01-happy-path-new-surface.md @@ -0,0 +1,13 @@ +# Example 01 — Happy Path: New Surface (greenfield → shipped → maintained) + +Demonstrates: `guides/01-context-contract.md`, `guides/02-start-phase.md`, `guides/04-polish-phase.md`, `guides/05-maintain-phase.md`. + +**Task:** "Build a pricing page for a developer tool that traces every alert back to the deploy that caused it." + +1. **Start — context.** No `PRODUCT.md` → `/impeccable init` (platform: web; users: SREs on call, reading fast, often in the dark; positioning: traces every alert back to the deploy that caused it; evidence: real incident timelines, no customer logos yet). No `DESIGN.md` → `/impeccable document` (extracts tokens from the existing app, writes Stitch-format `DESIGN.md` + `design.json`). +2. **Start — classification.** New surface inside an established world → composition open, world inherited. Mode: **Persuade** (a pricing page earns attention and action). +3. **Start — direction.** Derive a grounded shortlist (incident timeline, postmortem doc, terminal session, man page, pager timeline). Roll assigns index 3 (terminal session) and deals challengers from the worlds deck. Five tests: Truth (the terminal relationship exists in the product) ✓, Translation (strip names → a product-native relationship remains) ✓, Consequence (removing the terminal frame weakens the page) ✓, Survival (works on mobile within budget) ✓, Fit (honest tradeoff) ✓. Write the direction contract into the artifact (see `templates/direction-contract.md`), keep the seed key. +4. **Build.** Code toward the committed world. Craft floor: contrast >= 4.5:1, body measure 65-75ch, one authored motion moment, real states (hover/disabled/loading/error/empty), themed browser surfaces (selection, focus rings, scrollbars). No side-tab borders, no gradient text, no hero eyebrow, no Inter-as-display. +5. **Iterate.** One batched inspection round (desktop + mobile): fix overflow on the pricing table, tighten heading rhythm, replace one hardcoded hex with a token. One fix batch. One confirmation round. Stop. +6. **Polish.** `/impeccable audit` (a11y 4, perf 3, theming 4, responsive 3, anti-patterns 4; one P2: touch target on the plan toggle → fixed). `/impeccable clarify` (CTA copy tuned to SREs). `/impeccable harden` (60-char org names, prices in the billions, 500s). Gate: `npx impeccable detect src/` → 0 findings. Hand off to `security-worker-bee` → `quality-worker-bee`. +7. **Maintain.** `/impeccable extract` (the plan-toggle pattern appears 3x → token + primitive). `/impeccable document` (re-capture `DESIGN.md`). `/impeccable doctor` → clean. The next surface inherits the world. diff --git a/.claude/skills/impeccable-stinger/examples/02-edge-case-refinement.md b/.claude/skills/impeccable-stinger/examples/02-edge-case-refinement.md new file mode 100644 index 00000000..e49cf512 --- /dev/null +++ b/.claude/skills/impeccable-stinger/examples/02-edge-case-refinement.md @@ -0,0 +1,17 @@ +# Example 02 — Edge Case: Refinement with a Waiver + +Demonstrates: `guides/03-iterate-phase.md`, `guides/04-polish-phase.md`, `guides/06-detector-gate.md`. + +**Task:** "Polish the settings screen. Keep our sharp corners and sober palette. Remove the AI tells." + +1. **Context.** `PRODUCT.md` + `DESIGN.md` exist and are current. Mode: **Operate** (settings = task completion; scanability outranks expression). +2. **Classification.** Refinement — better, not different. No new-work flow, no roll, no direction contract. The incumbent world is preserved. +3. **Iterate.** `/impeccable polish settings` — targeted fixes: 3 off-grid elements aligned; h1 kerning tightened; one hardcoded hex → `--color-accent`; missing hover state on FAQ items; modal entrance softened to 220ms ease-out-quart; stray "Lorem" removed. One batched round, one fix batch, one confirmation. Stop. +4. **Polish.** `/impeccable audit settings` (P1: gray-on-color on the danger zone → tint from the hue instead). `/impeccable harden settings` (long German labels, offline state). Gate: `npx impeccable detect src/settings` → 1 finding: `overused-font` flags the brand font (a real brand commitment, not a default). +5. **Waiver (narrowest form, with reason):** + ```bash + npx impeccable ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md" + ``` + Re-run the gate → 0 findings. The waiver is recorded in `.impeccable/config.json` and shared with the hook. +6. **Close-out.** Hand off to `security-worker-bee` → `quality-worker-bee`. Gate result travels with the close-out (see `templates/gate-report.md`). +7. **Maintain.** No drift introduced; `doctor` clean. Nothing to extract. diff --git a/.claude/skills/impeccable-stinger/examples/03-live-mode-session.md b/.claude/skills/impeccable-stinger/examples/03-live-mode-session.md new file mode 100644 index 00000000..c1069b73 --- /dev/null +++ b/.claude/skills/impeccable-stinger/examples/03-live-mode-session.md @@ -0,0 +1,13 @@ +# Example 03 — Live Mode Session (opt-in, user-invoked) + +Demonstrates: `guides/08-live-mode.md`, `guides/07-hooks.md`. + +**Task:** "Show me the hero live — something's off but I can't name it." + +1. **Opt-in.** The user asked; the Bee launches live mode. Never auto-launched. +2. **Setup.** Dev server confirmed running (localhost:3000). `/impeccable live` — picker injected into the app. +3. **Iterate.** User picks the hero headline, types "make it feel more editorial". Three variants hot-swapped via HMR. User accepts variant 2 → written to source (manual edits captured via `live-commit-manual-edits.mjs`). +4. **Gate.** `npx impeccable detect src/` on the accepted result → 0 findings. The per-edit hook stays quiet on clean edits (non-intrusive by design). +5. **Close-out.** Hand off to `security-worker-bee` → `quality-worker-bee`. + +**Note:** during normal development the user gets live feedback from the **per-edit hook** (findings pushed back after each UI edit, quiet when clean) — that is the non-nuisance live feedback. Live mode is the on-demand visual iteration tool. diff --git a/.claude/skills/impeccable-stinger/examples/04-sync-check.md b/.claude/skills/impeccable-stinger/examples/04-sync-check.md new file mode 100644 index 00000000..30b327e2 --- /dev/null +++ b/.claude/skills/impeccable-stinger/examples/04-sync-check.md @@ -0,0 +1,10 @@ +# Example 04 — Pre-Flight Sync Check + +Demonstrates: `guides/11-sync-check.md`. + +**Task:** "Polish the billing settings page." + +1. **Pre-flight.** `node .../impeccable-stinger/scripts/sync-check.mjs` → `[sync-check] CURRENT: upstream in sync, stinger coverage matches. Skipping update.` (exit 0). Skipped; task proceeds. +2. **Later run (behind).** The check reports `BEHIND: installed 4.0.3 < published 4.0.4` and `NEW COMMANDS upstream: ` (exit 2). The Bee runs `npx impeccable update`, notes the Codex `/hooks` re-approval to the user, re-runs the check → exit 0 → proceeds. +3. **Content drift.** The check reports `NEW REFERENCE FILES upstream: typeset.native.md` (exit 2). The Bee adds a guide/template covering the new playbook, bumps `scripts/upstream-manifest.json`, re-runs → exit 0 → proceeds. +4. **Not installed.** The check reports `NOT INSTALLED` (exit 1). The Bee runs the global install, then per-project `install` + `init` + `document`, re-runs → exit 0 → proceeds. diff --git a/.claude/skills/impeccable-stinger/guides/00-principles.md b/.claude/skills/impeccable-stinger/guides/00-principles.md new file mode 100644 index 00000000..26edaa7e --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/00-principles.md @@ -0,0 +1,14 @@ +# 00 — Principles (non-negotiables) + +Derived from `research/01-system-overview.md` and `research/05-craft-floor.md`. + +1. **The brief wins.** Pinned aesthetics, eras, materials, fonts, and palettes override saturated-pattern warnings. Redirecting a clear brief toward your taste is failure. (research/01, SKILL.src.md) +2. **Refinement preserves; redesign replaces.** Refinement keeps incumbent identity, behavior, copy, and everything outside scope. Redesign keeps product truth, content, function, and constraints but treats the old look as evidence and anti-reference. Never split the difference. (research/01) +3. **Bounded passes.** Build fully → inspect once batched (desktop + mobile) → fix in one batch → confirm at most once → stop. Open-ended self-QA is waste. (research/01) +4. **Never self-grade.** The user is the "happy" gate. A fresh reviewer audits the build against its direction contract promise-by-promise. (research/04, lesson 7) +5. **Context contract is source of truth.** Read `PRODUCT.md` + `DESIGN.md` + surface brief before every command. Mode comes from the surface, not the product. Missing `DESIGN.md` ≠ greenfield. (research/02) +6. **Single vocabulary.** One design system per session. Mixing Impeccable with other design-taste skills cancels both out. (research/01, /designing) +7. **The gate is mandatory.** `npx impeccable detect` exit code 2 fails the close-out. Waivers need the narrowest ignore + a stated reason. (research/06) +8. **Never fork or modify the engine.** Call the installed system; follow the bee-army-update contract (no upstream script execution during install, preserve ownership manifest, no silent overwrites). (research/11) +9. **License discipline.** Apache-2.0 upstream; build from the repo, not the site (site robots.txt: `ai-train=no, use=reference`). Keep attribution. (research/11) +10. **Close-out order.** Security before quality, always. diff --git a/.claude/skills/impeccable-stinger/guides/01-context-contract.md b/.claude/skills/impeccable-stinger/guides/01-context-contract.md new file mode 100644 index 00000000..9021f405 --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/01-context-contract.md @@ -0,0 +1,30 @@ +# 01 — Context Contract + +Derived from `research/02-context-contract.md`. + +## Files the Bee owns per project + +| File | Role | Written by | +|---|---|---| +| `PRODUCT.md` | Strategy: platform, users, purpose, positioning, evidence, brand commitments | `/impeccable init` | +| `DESIGN.md` | Visual system: colors, type, components, radii, elevation, rules (Google Stitch format) | `/impeccable document` | +| `.impeccable/surfaces/*.md` | Per-surface: mode, job, proof sequence, chosen direction | The work itself | +| `.impeccable/design.json` | Structured sidecar for detector/hooks/Live Mode | `document` (do not hand-edit) | + +## Modes (from the surface, not the product) + +- **Persuade** — visitor decides and acts (landing, marketing, pricing). Design is the product; earn attention. +- **Operate** — visitor completes a task (app UI, dashboards, admin, tools). Scanability outranks expression. +- **Read** — visitor understands (docs, guides, help). Comprehension first. +- **Experience** — visitor is inside the work (portfolios, galleries). Artifact leads, interface recedes. + +A tool's landing page is still Persuade; a fashion house's docs are still Read. Name the mode explicitly only when genuinely ambiguous; persist it in the surface brief. + +## Rules + +- Every command reads the contract first. Never re-derive what is recorded. +- `init` scans the codebase, forms its own read, asks only what it could not work out. It does not ask about colors/type — those are decided with the surface. +- `document` auto-extracts colors, typography, spacing, radii, components, then confirms descriptive language; writes Stitch-format `DESIGN.md`. +- Missing `DESIGN.md` does not make a project greenfield: coherent code, type choices, and component behavior are authority. Scaffolds and framework defaults are not. +- If implementation is coherent but undocumented: extract invariants, confirm with the user, write `DESIGN.md` before going further. +- `context.mjs` may emit a `CONTEXT_STALE` directive — report it, do not act on it unless the user asks (except `auto` findings). diff --git a/.claude/skills/impeccable-stinger/guides/02-start-phase.md b/.claude/skills/impeccable-stinger/guides/02-start-phase.md new file mode 100644 index 00000000..a83d5663 --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/02-start-phase.md @@ -0,0 +1,39 @@ +# 02 — Start Phase (context + direction) + +Derived from `research/02-context-contract.md`, `research/03-command-vocabulary.md`, `research/04-new-work-direction.md`. + +## 1. Ensure context + +- No `PRODUCT.md` → run `/impeccable init` (discovery interview; writes `PRODUCT.md`; offers `DESIGN.md` when code exists). +- No `DESIGN.md` → run `/impeccable document` (Stitch format + `.impeccable/design.json`). +- Files exist → read them; do not re-interview. + +## 2. Classify the job + +- **Greenfield** — no coherent visual implementation; a world gets established. +- **Local extension** — a section/component inside a working page; only the new part is decided; the page's world is inherited. +- **New surface** — a whole page/flow inside an established world; composition open, world not. +- **Expression expansion** — an established brand entering a surface family it never resolved; approve a range, merge into `DESIGN.md`. +- **Redesign or rebrand** — the look is replaced; product facts, content, function, constraints are not. +- **Refinement** — better, not different; leave this flow for a scoped command like `polish`. + +"Redesign this page" = replacement (old look becomes anti-reference). "Redesign within our current system" = extension. Ask once when genuinely ambiguous; never split the difference. + +## 3. New-work flow (new surfaces + redesigns) + +1. Derive a grounded shortlist of candidate directions from the product's world (audience, evidence, cultural material). +2. **Roll** (`node /scripts/concept-seed.mjs` or the installed skill's script): assign which candidate is built; deal challengers from the worlds deck. The dice refuse the argmax rut; they never touch an ungrounded idea. +3. Apply the **five tests** to every candidate — fail one, it dies: + - **Truth** — every relationship it visualizes exists in your product. + - **Translation** — strip the source's names/materials and a product-native relationship remains (else it is a costume). + - **Consequence** — removing its best move materially weakens the page. + - **Survival** — the signature works on the primary device within a real asset/time budget. + - **Fit** — its risk is an honest tradeoff, not a probable brief violation. +4. Write the **direction contract** into the artifact (see `templates/direction-contract.md`): `THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`, <=150 words, five blocks. Keep the seed key for reproduction. +5. **Visualize** when image tooling is available: system board + first-surface mock, then build toward the image. If no native image tool, set `OPENAI_API_KEY` and render via gpt-image-2 (say so first — it spends the user's credit, ~5-25 cents each). + +## Re-roll rules + +- The user re-rolls freely, for any reason including taste. After two in a row, ask what quality is missing. +- The agent may only re-roll on named factual grounds (the assigned direction cannot carry the product's truth or the task). Its own taste is never grounds. +- In an unattended run, the assigned direction proceeds and assumptions are stated explicitly. diff --git a/.claude/skills/impeccable-stinger/guides/03-iterate-phase.md b/.claude/skills/impeccable-stinger/guides/03-iterate-phase.md new file mode 100644 index 00000000..c8354f25 --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/03-iterate-phase.md @@ -0,0 +1,33 @@ +# 03 — Iterate Phase (bounded rounds) + +Derived from `research/03-command-vocabulary.md`, `research/08-live-mode.md`. + +## Named commands (when the edit has a name) + +- **Refine:** `polish` (final pass), `bolder` / `quieter` (voice), `distill` (subtraction), `typeset` (type hierarchy), `layout` (spacing/rhythm), `colorize` (strategic color), `animate` (purposeful motion), `delight` (personality), `overdrive` (past conventional limits). +- **Fix:** `clarify` (UX copy), `adapt` (devices/contexts), `optimize` (performance). +- **Harden:** `harden` (edge cases, i18n, errors, overflow), `onboard` (first-run, empty states). +- **Evaluate:** `critique` (design review with scoring, persona tests, automated detection). + +## Bounded-round discipline + +1. Build fully. +2. Inspect once in a batched round — desktop and mobile together, one render. +3. Fix everything the round shows in one batch. +4. Confirm with at most one more round. +5. Stop. Hand to the user for approval. The user is the "happy" gate. + +## Live Mode (opt-in, user-invoked only) + +- `/impeccable live` drops a picker on the running dev server: point at an element, type/draw a change, get 3 production-quality variants hot-swapped via HMR; accept one and it writes to source. +- **Never auto-launch it.** Launch only when the user asks to iterate visually ("show me live", "let me point at it"). +- Status: **alpha** — expect rough edges on uncommon setups. Prefer named commands for the default path. +- The non-intrusive live feedback during development is the **per-edit hook** (see `guides/07-hooks.md`), not live mode. + +## When to reach for which + +- Fix something "off" you can't name → `live` (user-invoked) or `critique`. +- Apply a specific discipline → `typeset` / `layout` / `colorize` / `animate`. +- Explore three directions side by side → `live` (user-invoked). +- Ask "is this any good?" → `critique`. +- Bring a safe design to life / tone a shouting one down → `bolder` / `quieter`. diff --git a/.claude/skills/impeccable-stinger/guides/04-polish-phase.md b/.claude/skills/impeccable-stinger/guides/04-polish-phase.md new file mode 100644 index 00000000..c6ead01a --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/04-polish-phase.md @@ -0,0 +1,22 @@ +# 04 — Polish Phase (pre-ship gauntlet) + +Derived from `research/03-command-vocabulary.md`, `research/06-detector-rules.md`. + +## The three commands before anything ships + +1. **`/impeccable audit `** — 5 dimensions scored 0-4: accessibility, performance, theming, responsive, anti-patterns. Findings tagged P0-P3. Point at a narrow target: one section reviewed closely beats a whole page at a glance. Native projects route to the native pass (VoiceOver, TalkBack, touch targets, platform conformance). +2. **`/impeccable clarify `** — rewrite the copy: labels, error messages, empty-state prose, microcopy, tuned to the audience from `PRODUCT.md`. +3. **`/impeccable harden `** — stress-test reality: 60-character names, German product titles, prices in the billions, 500s, offline. Production data is messy. + +## The deterministic gate (mandatory) + +- `npx impeccable detect ` — file, dir, or URL. Plain output groups by file with rule id, snippet, explanation; `--json` for scripts/CI. +- **Exit codes:** 0 = no findings; 2 = findings; 1 = command failed. CI fails the job on 2. +- DESIGN.md-aware: with a local `DESIGN.md`, enables design-system checks (fonts, literal colors, radii, font sizes). `--no-design-system` disables; `--scope type|layout` narrows. +- **Waivers:** narrowest form only — `npx impeccable ignores add-value --reason "..."`, `add-file `, or inline `impeccable-disable` comments in the file. A waiver without a reason is a failure. +- See `guides/06-detector-gate.md` for the full rule list and CI wiring. + +## Close-out + +- Findings resolved or explicitly waived → hand off to `security-worker-bee` first, then `quality-worker-bee`. Never quality before security. +- The gate result travels with the close-out (see `templates/gate-report.md`). diff --git a/.claude/skills/impeccable-stinger/guides/05-maintain-phase.md b/.claude/skills/impeccable-stinger/guides/05-maintain-phase.md new file mode 100644 index 00000000..24f2c88e --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/05-maintain-phase.md @@ -0,0 +1,22 @@ +# 05 — Maintain Phase (cohesion) + +Derived from `research/09-maintenance-doctor.md`. + +## The two commands that close the gap + +1. **`/impeccable extract `** — find patterns used 3+ times with the same intent; propose tokens and primitives; consolidate drift before it solidifies. +2. **`/impeccable document`** — re-capture the system: scans tokens, components, and rendered routes, writes `DESIGN.md` in Stitch format. The more it points at real components and live routes, the closer it reads your design language. + +## Doctor (three kinds of "out of date") + +- **Tool version** — installed skill older than published; `npx impeccable update` fixes. +- **Schema drift** — artifact written by an older Impeccable; mechanical, doctor repairs most of it. +- **Truth drift** — code moved on and the document no longer describes it; route to `init`/`document`, never auto-repair. + +`/impeccable doctor` also checks: config unknown keys, ignored rule ids that no longer exist, ignored file paths that are gone, `projectRoots` globs matching nothing, hook script paths that stopped resolving, orphaned surface briefs, and monorepo apps inheriting a web-only root record while carrying native build files. + +## Rules + +- **Never repair drift as a side effect of a design task.** A `CONTEXT_STALE` finding is reported, not acted on, unless the user asks (except `auto` findings). +- Run `npx impeccable check` / `update` on a cadence; the installed side self-updates, the stinger's vendored reference needs a manual refresh cadence. +- Every new element or surface inherits the established world unless the classification says greenfield; the detector's design-system rules mechanically flag drift. diff --git a/.claude/skills/impeccable-stinger/guides/06-detector-gate.md b/.claude/skills/impeccable-stinger/guides/06-detector-gate.md new file mode 100644 index 00000000..06c914f9 --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/06-detector-gate.md @@ -0,0 +1,46 @@ +# 06 — Detector Gate (59 deterministic rules) + +Derived from `research/06-detector-rules.md`. + +## CLI usage + +```bash +npx impeccable detect src/ # scan a directory +npx impeccable detect src/components/Card.tsx # one file +npx impeccable detect https://example.com # rendered page (browser engine) +npx impeccable detect --json src/ # machine-readable +npx impeccable detect --scope type src/ # one design domain +npx impeccable detect --no-design-system src/ # raw scan +``` + +- **Exit codes:** 0 = no findings; 2 = findings detected; 1 = command failed. CI fails the job on 2. +- Engines: static-html (files + linked CSS), browser (URLs), regex/text (JSX/TSX/Vue/Svelte/Astro/CSS-in-JS). Server-side templates (Blade/ERB/Twig/Handlebars) need `detector.extensions` in `.impeccable/config.json`. +- Web only. Native projects route to `/impeccable audit` (native pass). + +## The 59 rules (id | category | severity) + +**slop (30):** side-tab, border-accent-on-rounded, overused-font, flat-type-hierarchy (error), gradient-text (error), ai-color-palette, cream-palette, nested-cards, monotonous-spacing, bounce-easing, pulsing-dot, blinking-cursor, shape-assembled-illustration, dark-glow, radial-halo, radial-spotlight-glow, marquee, icon-tile-stack, italic-serif-display, hero-eyebrow-chip, kicker-above-heading, numbered-section-labels, em-dash-overuse, marketing-buzzword, aphoristic-cadence, oversized-h1, extreme-negative-tracking, gpt-thin-border-wide-shadow, repeating-stripes-gradient, codex-grid-background, theater-slop-phrase, image-hover-transform. + +**quality (29):** broken-image, script-error, content-hidden-at-rest, edge-flush-cards, text-occlusion, first-viewport-column-overflow, gray-on-color, low-contrast, layout-transition, line-length, cramped-padding, body-text-viewport-edge, tight-leading, skipped-heading, heading-rhythm, justified-text, tiny-text, undersized-ui-text, all-caps-body, wide-tracking, text-overflow, repeated-container-text, clipped-overflow-container, design-system-font, design-system-color, design-system-radius, design-system-font-size. + +Severities: `error` (flat-type-hierarchy, gradient-text), `warning` (most), `advisory` (side-tab, overused-font, ai-color-palette, cream-palette, nested-cards, etc.). + +## DESIGN.md awareness + +With a local `DESIGN.md`, the detector enables the 4 design-system rules (font, color, radius, font-size outside the documented system) using `.impeccable/design.json` for richer token/ramp data. This is what makes product-token enforcement mechanical — it complements `design-system-stinger`/`ux-ui-stinger`. + +## Ignores & waivers + +- `npx impeccable ignores list|add-value|add-file|add-rule|remove-value`; `--local` for private; `--reason` for the why. +- Value ignores preferred for fonts/colors/radii/motion (keeps the rule useful elsewhere); wildcard value ignores only when scoped to a file. +- Inline comments travel with a file: ``, `impeccable-disable-line`, `impeccable-disable-next-line`. +- A waiver without a stated reason is a failure. The narrowest exception that matches the real reason is the only correct one. + +## CI wiring + +```bash +npx impeccable detect --json src/ > .impeccable/detect.json +# exit code 2 → fail the PR check; parse JSON for the findings list +``` + +Add to army projects' PR checks per the user decision (2026-08-06). diff --git a/.claude/skills/impeccable-stinger/guides/07-hooks.md b/.claude/skills/impeccable-stinger/guides/07-hooks.md new file mode 100644 index 00000000..939c3051 --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/07-hooks.md @@ -0,0 +1,37 @@ +# 07 — Hooks (per-edit + deep pass) + +Derived from `research/07-hooks-enforcement.md`. + +## What the hook does + +- Scans direct edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). +- **Claude Code / GitHub Copilot / Codex:** post-tool-use — pushes a short system reminder after the edit; findings get a correction prompt, pending issues get a re-nudge, clean files get a short ack (unless `hook.quiet`). +- **Cursor:** `preToolUse` — blocks bad proposed writes before they land; silent when clean. +- Plain `.ts`/`.js` files are scanned but stay quiet unless the detector finds something. + +## Two speeds + +- **Per edit:** only what is objectively broken or compounds if ignored (broken images, overflow/clipped text, contrast failures, tiny text, gradient text, glow, DESIGN.md drift). +- **End of session (deep pass):** the full rule set across every UI file touched, minus what was already reported; a second stop is silent. Wired for Claude Code and Codex (native Stop hook); Cursor and Copilot keep the full detector per edit. +- `hook.perEditRules: "all"` restores full rules per edit (not recommended — it makes models more conservative). + +## Harness manifests & approval + +| Harness | Manifest | Notes | +|---|---|---| +| Claude Code | `.claude/settings.local.json` | gitignored, machine-local | +| GitHub Copilot | `.github/hooks/impeccable.json` | committed, team-shared | +| Codex | `.codex/hooks.json` | **requires `/hooks` approval after install/update** | +| Cursor | `.cursor/hooks.json` | confirm enabled in Settings → Hooks | +| Grok Build | `.grok/hooks/impeccable.json` | requires `/hooks-trust` or `--trust` | + +- Installer: `npx impeccable install|update`; `--no-hooks` skips; `--force` backs up malformed manifests as `.bak`. +- Config: `hook.enabled`, `hook.quiet`, `hook.auditLog` in `.impeccable/config.json`; consent in `.impeccable/config.local.json`. Env: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, `IMPECCABLE_HOOK_LOG`. + +## The failure mode to watch + +"A hook can look installed and scan nothing: if its script path stops resolving... the manifest still registers and no findings ever arrive. Silence reads as a clean codebase." `/impeccable doctor` checks for exactly this. Treat hook silence as suspicious, not as a clean pass. + +## Why this matters for the Bee + +Hooks are the "every time" enforcement: they fire on every UI edit regardless of routing discipline. They are the non-intrusive live feedback during development — the user sees findings as code is written, without live mode being a nuisance. diff --git a/.claude/skills/impeccable-stinger/guides/08-live-mode.md b/.claude/skills/impeccable-stinger/guides/08-live-mode.md new file mode 100644 index 00000000..518bbf75 --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/08-live-mode.md @@ -0,0 +1,28 @@ +# 08 — Live Mode (opt-in browser iteration, alpha) + +Derived from `research/08-live-mode.md`. + +## What it is + +`/impeccable live` drops a picker onto the running dev server. The user points at any element, draws or types what they want, and gets **three production-quality variants** hot-swapped via HMR. Accepting one writes it back to source. + +- Requires a running dev server (localhost). +- **Status: alpha** — works end-to-end, but needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups. + +## When to use (user decision 2026-08-06) + +- **Opt-in, user-invoked only.** Never auto-launch it. The Bee launches it only when the user asks to iterate visually ("show me live", "let me point at it", "I want to see it in the browser"). +- Use it when: the user can't name what's off; they want to explore three directions side by side; they want to see the design live as code changes and point at issues before a PR. +- The default loop stays: named commands + bounded rounds + detector gate. + +## Session flow + +1. Confirm a dev server is running; start one if needed. +2. Launch `/impeccable live`; the picker is injected into the app. +3. User picks an element or steers the whole page; the Bee generates 3 variants. +4. User accepts one → it writes to source (manual edits are captured and committed via `live-commit-manual-edits.mjs`). +5. Run the detector gate on the accepted result before close-out. + +## Companion: Chrome extension + +The detector overlay runs on any live page (staging, competitor) — useful for review without touching the editor. diff --git a/.claude/skills/impeccable-stinger/guides/09-native.md b/.claude/skills/impeccable-stinger/guides/09-native.md new file mode 100644 index 00000000..3124a86e --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/09-native.md @@ -0,0 +1,24 @@ +# 09 — Native Surfaces (iOS / Android / adaptive) + +Derived from `research/10-native-platforms-harnesses.md`. + +## Rules + +- The detector is **web only** — it reads HTML and CSS. It has nothing to say about a native iOS/Android codebase. +- When `PRODUCT.md` declares `ios`, `android`, or `adaptive`: + - `/impeccable audit` runs the **native pass** (`audit.native.md`): VoiceOver, TalkBack, touch targets, platform conformance. + - `adapt` has a native variant (`adapt.native.md`). + - Per-platform rulebooks: `ios.md`, `android.md`. +- `init` detects the platform from codebase evidence and asks only when ambiguous; the platform is recorded in `PRODUCT.md`. + +## Harness builds (per-model tuning) + +- `npx impeccable install` auto-detects the harness and writes the right skill files (`.claude/skills/`, `.cursor/skills/`, `.codex/`, `.gemini/`, `.grok/`, etc.) plus provider-native hook manifests. +- Per-model rule tuning: the Gemini build kills image-on-hover motion; the Codex build refuses ghost-cards and over-rounding. The installed build may carry extra rules for the active model — expect that. +- `npx skills add pbakaus/impeccable` installs one shared build (functionally complete, not tailored). +- Claude Code plugin: `/plugin marketplace add pbakaus/impeccable`. GitHub Copilot: built in (Settings → Experimental). + +## Bee behavior + +- Default domain is web. Native surfaces route to the native playbooks and the native audit pass. +- The stinger is complete for any build: web, iOS, Android, adaptive (user decision 2026-08-06). diff --git a/.claude/skills/impeccable-stinger/guides/10-install-and-verify.md b/.claude/skills/impeccable-stinger/guides/10-install-and-verify.md new file mode 100644 index 00000000..3e527ebd --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/10-install-and-verify.md @@ -0,0 +1,42 @@ +# 10 — Install & Verify (hybrid scope) + +Derived from `research/07-hooks-enforcement.md`, `research/09-maintenance-doctor.md`, `research/10-native-platforms-harnesses.md`, `research/11-license-provenance.md`. + +## Global skill install (once per machine) + +```bash +npx impeccable install --scope=global --providers=codex,claude,cursor +``` + +- Makes `/impeccable` available in every army project (user decision 2026-08-06: global, not per-project, because the army works across many projects). +- Reload the harness afterward; `/impeccable` should appear in autocomplete. + +## Per-project setup (one-time, cheap) + +```bash +npx impeccable install # writes hook manifests + .impeccable/config.json +/impeccable init # writes PRODUCT.md +/impeccable document # writes DESIGN.md + .impeccable/design.json +``` + +- Hooks are **project-local by harness design** (`.codex/hooks.json`, `.claude/settings.json`, `.cursor/hooks.json`) — they cannot be global. Codex requires `/hooks` approval after install/update. +- Context files (`PRODUCT.md`, `DESIGN.md`, `.impeccable/`) are inherently per-project. + +## Verify + +- `/impeccable doctor` — checks schema drift, truth drift, broken hook paths, stale config, orphaned surface briefs, monorepo platform mismatches. +- A hook that looks installed but scans nothing is the failure you would never notice — doctor catches it. +- `npx impeccable check` / `update` — keep the installed system current. + +## CI gate (user decision 2026-08-06) + +```bash +npx impeccable detect --json src/ > .impeccable/detect.json # exit 2 fails the PR check +``` + +Add to army projects' PR checks. + +## Compliance + +- Build the stinger from the repo (Apache-2.0), not the site (robots.txt: `ai-train=no, use=reference`). Keep attribution. +- Never fork or modify the engine into the stinger; call the installed system. Follow the bee-army-update contract. diff --git a/.claude/skills/impeccable-stinger/guides/11-sync-check.md b/.claude/skills/impeccable-stinger/guides/11-sync-check.md new file mode 100644 index 00000000..72b8c9e4 --- /dev/null +++ b/.claude/skills/impeccable-stinger/guides/11-sync-check.md @@ -0,0 +1,43 @@ +# 11 — Pre-Flight Sync Check (upstream always in sync) + +Derived from `research/09-maintenance-doctor.md`, `research/11-license-provenance.md`, and the user decision (2026-08-06): "make sure the upstream is always in sync before a task is done. If it is current it is skipped." + +## The mechanism + +Before any design task starts, run the stinger's sync check: + +```bash +node .claude/skills/impeccable-stinger/scripts/sync-check.mjs +``` + +**Exit codes:** +- `0` — current and in sync → **skip**, proceed with the task. +- `2` — behind upstream and/or content drift → update/refresh before the task (see below). +- `1` — not installed or check failed → install first. + +## What it verifies + +1. **Installed skill present** — searches the harness skill dirs (`~/.agents/skills/impeccable`, `~/.codex/skills/impeccable`, `~/.claude/skills/impeccable`, `~/.claude/skills/impeccable`, and project-local equivalents). Codex's primary skill dir is `.agents/skills/`. +2. **Version currency** — reads the installed `SKILL.md` frontmatter `version:` and compares it to the published version at `https://impeccable.style/api/version` (same endpoint the skill's own `context.mjs` uses). Behind → `npx impeccable update`. +3. **Content coverage** — compares the installed skill's `reference/` files and `scripts/command-metadata.json` commands against the stinger's `scripts/upstream-manifest.json` (forged against upstream 4.0.4 / commit `aee6ce9`). New commands or reference files upstream → the stinger needs a refresh (new guide/template), not just an update. + +## When behind (exit 2) + +1. Run `npx impeccable update` (or `node .../sync-check.mjs --update`). **Note:** Codex may require `/hooks` re-approval after an update — tell the user. +2. If content drift: add the missing guide/template for the new command or reference file, then update `scripts/upstream-manifest.json` to the new version/commit. +3. Re-run the check → exit 0 → proceed. + +## When not installed (exit 1) + +```bash +npx impeccable install --scope=global --providers=codex,claude,cursor +``` + +Then per project: `npx impeccable install` (hooks) + `/impeccable init` + `/impeccable document` (context). See `guides/10-install-and-verify.md`. + +## Rules + +- The check is a **pre-flight gate**: run it before Phase 1, skip when current, never skip when behind. +- Never fork or modify the engine; the check only compares versions and file coverage. +- A stale stinger manifest is a real finding: upstream added content the Bee does not know how to operate. +- Report the result in the close-out (see `templates/sync-report.md`). diff --git a/.claude/skills/impeccable-stinger/reports/README.md b/.claude/skills/impeccable-stinger/reports/README.md new file mode 100644 index 00000000..8d036cab --- /dev/null +++ b/.claude/skills/impeccable-stinger/reports/README.md @@ -0,0 +1,3 @@ +# reports/ + +Close-out reports from impeccable-worker-bee runs. Template: `gate-report-template.md`. Past runs accumulate here over time. diff --git a/.claude/skills/impeccable-stinger/reports/gate-report-template.md b/.claude/skills/impeccable-stinger/reports/gate-report-template.md new file mode 100644 index 00000000..d387c841 --- /dev/null +++ b/.claude/skills/impeccable-stinger/reports/gate-report-template.md @@ -0,0 +1,22 @@ +# Detector Gate Report + +| Field | Value | +|---|---| +| Target | `` | +| Command | `npx impeccable detect ` | +| Exit code | `0` (no findings) / `2` (findings) / `1` (failed) | +| Findings | `` | +| Resolved | `` | +| Waived | `` | + +## Findings + +| Rule id | Severity | File:line | Resolution (fix or waiver + reason) | +|---|---|---|---| +| `side-tab` | advisory | `src/components/Card.tsx:52` | Fixed — removed inset stripe | +| `overused-font` | advisory | `src/styles/global.css:14` | Waived — `ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md"` | + +## Verdict + +- [ ] Gate clean (0 findings) — close-out may proceed +- [ ] Gate failed (exit 2) — close-out blocked until resolved or waived diff --git a/.claude/skills/impeccable-stinger/research/01-system-overview.md b/.claude/skills/impeccable-stinger/research/01-system-overview.md new file mode 100644 index 00000000..eee5730b --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/01-system-overview.md @@ -0,0 +1,39 @@ +# 01 — System Overview + +**Source:** `README.md`, `PRODUCT.md`, `skill/SKILL.src.md`, `package.json`, `impeccable.style/designing` (reference) + +## What it is + +Impeccable is a design-guidance skill + toolchain for AI coding agents: "1 skill, 23 commands, live browser iteration, and 59 deterministic detector rules for AI-generated frontend design" (`README.md`). It started from Anthropic's `frontend-design` skill and adds a setup flow, a shared command vocabulary, and deterministic enforcement. + +- **License:** Apache-2.0 (`LICENSE`, `package.json` `"license": "Apache-2.0"`). +- **Runtime:** Node >= 22.18 (`package.json` `"engines"`). +- **Distribution:** npm package `impeccable` (bin `impeccable` → `cli/bin/cli.js`), installed per project via `npx impeccable install`, which writes harness-tailored builds (`.claude/`, `.cursor/`, `.codex/`, `.gemini/`, `.grok/`, `.trae/`, `.opencode/`, `.qoder/`, `.rovodev/` folders exist in the repo). +- **Per-model builds:** "builds for models with known tells carry extra slop rules banning that model's habits. The Gemini build kills its image-on-hover motion; the Codex build refuses ghost-cards and over-rounding" (`README.md`; ``/`` sections in `skill/reference/craft-floor.md`). + +## The seven layers (whole system) + +1. **Context contract** — `PRODUCT.md` (strategy) + `DESIGN.md` (visual system, Google Stitch format) + `.impeccable/surfaces/*.md` (per-surface mode/job/proof) + `.impeccable/design.json` (structured sidecar). Loaded by `skill/scripts/context.mjs` on every command. +2. **One vocabulary** — 23 commands under `/impeccable` (`skill/scripts/command-metadata.json`). v3.0 consolidated 18 standalone skills into one. +3. **Direction machinery** — new-work flow: job classification, five tests, direction contract, worlds deck + roll (`skill/scripts/concept-seed.mjs`, `skill/scripts/lib/concept-catalog.mjs`). +4. **Craft floor** — `skill/reference/craft-floor.md`: quality floor, absolute bans, reflexes, per-model sections. +5. **Deterministic enforcement** — 59 rules (`cli/engine/registry/antipatterns.mjs`), CLI `npx impeccable detect` (JSON, exit codes 0/2/1), hooks, Chrome extension, slop catalog. +6. **Live iteration** — `/impeccable live` (`skill/scripts/live/*`): browser picker, 3 variants per element, HMR, accept writes to source. Status: alpha. +7. **Maintenance** — `doctor` (tool/schema/truth drift), config/ignores, `update`/`check`, `extract`/`document`. + +## The four-phase loop (the Bee's core procedure) + +From `impeccable.style/designing` (reference; same content as the skill's routing): + +- **Start** — `init` (context) → `shape`/new-work (brief, direction, visualize, build). +- **Iterate** — named commands (`polish`, `bolder`, `typeset`, `layout`, `colorize`, `animate`, ...) or `live`; bounded rounds. +- **Polish** — pre-ship gauntlet: `audit` (5 dims, P0-P3), `clarify` (copy), `harden` (edge cases); detector gate in CI (`npx impeccable detect src/`, exit code fails the build). +- **Maintain** — `extract` (consolidate drift into tokens/primitives) + `document` (re-capture `DESIGN.md`) before debt solidifies. + +## Key evidence + +- "Verify in bounded passes, not a loop... Build fully, inspect once with a batched round (desktop and mobile together), fix everything it shows in one batch, confirm with at most one more round, and stop polishing. Open-ended self-QA burns the user's money" (`skill/SKILL.src.md`). +- "The brief wins. Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning" (`skill/SKILL.src.md`). +- "Refinement preserves; redesign replaces... Never split the difference into polish on the discarded look" (`skill/SKILL.src.md`). +- "Visual authority is evidence, not a filename. Missing DESIGN.md alone does not make a project greenfield" (`skill/SKILL.src.md`). +- "Running both Impeccable and Anthropic's frontend-design skill... Two skills with different design vocabularies collide and cancel each other out. Pick one" (`impeccable.style/designing`). diff --git a/.claude/skills/impeccable-stinger/research/02-context-contract.md b/.claude/skills/impeccable-stinger/research/02-context-contract.md new file mode 100644 index 00000000..d3fe7933 --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/02-context-contract.md @@ -0,0 +1,28 @@ +# 02 — Context Contract (PRODUCT.md / DESIGN.md / surfaces / design.json) + +**Source:** `skill/scripts/context.mjs`, `skill/reference/init.md`, `skill/reference/document.md`, `skill/reference/context.md` (site), `impeccable.style/docs/context` (reference) + +## Files and roles + +| File | What it answers | Updated when | +|---|---|---| +| `PRODUCT.md` | Platform, users, purpose, positioning, evidence, brand commitments | Strategy changes | +| `DESIGN.md` | Colors, type stacks, components, radii, elevation, visual rules | Visual system changes | +| `.impeccable/surfaces/*.md` | One page/route: mode, job, proof sequence, chosen direction | Written by the work itself | +| `.impeccable/design.json` | Structured design data for automation (detector, hooks, Live Mode) | Regenerated by `document`; do not hand-edit | + +## Key rules + +- Every command reads both files before generating, plus the brief for the named surface (`skill/SKILL.src.md` Setup: "It loads PRODUCT.md, DESIGN.md, the matching surface brief, and native-platform guidance when applicable"). +- **Mode comes from the surface, not the product:** "A tool's landing page is still Persuade; a fashion house's documentation is still Read; a docs index is Read, not Persuade" (`skill/SKILL.src.md`). +- Four modes: **Persuade** (decides and acts; design is the product), **Operate** (completes a task; scanability outranks expression), **Read** (understands; comprehension first), **Experience** (inside the work; artifact leads, interface recedes) (`skill/SKILL.src.md` lines 35-38). +- `init` scans the codebase, forms its own read of platform/product, asks only what it could not work out, writes `PRODUCT.md`, and offers `DESIGN.md` when code exists. It does not ask about colors/type — those are decided with the surface (`skill/reference/init.md`). +- `document` auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language; writes `DESIGN.md` in the **Google Stitch format** so the file is tool-compatible (`skill/scripts/command-metadata.json`). +- `context.mjs` also performs a staleness check against `https://impeccable.style/api/version` (`skill/scripts/context.mjs` line 77, 1007) and can emit a `CONTEXT_STALE` directive; "Never repair drift as a side effect of a design task" (`skill/SKILL.src.md`). +- `PRODUCT.md` carries a schema stamp; `DESIGN.md` follows the external design.md spec and gets no stamp (`skill/reference/doctor.md`). + +## Evidence for the stinger + +- The Bee owns these files per project; they are the source of truth every phase reads. +- A missing `DESIGN.md` does not make a project greenfield: "Coherent code, type choices, and component behavior are authority whether or not anyone wrote them down. Scaffolds, framework defaults, and stray utility classes are not" (`skill/reference/new-work.md`). +- If implementation is coherent but undocumented, extract invariants, confirm with the user, write `DESIGN.md` before going further (`skill/reference/new-work.md`). diff --git a/.claude/skills/impeccable-stinger/research/03-command-vocabulary.md b/.claude/skills/impeccable-stinger/research/03-command-vocabulary.md new file mode 100644 index 00000000..e030359f --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/03-command-vocabulary.md @@ -0,0 +1,53 @@ +# 03 — Command Vocabulary (23 commands) + +**Source:** `skill/scripts/command-metadata.json`, `skill/SKILL.src.md`, `impeccable.style/docs` (reference) + +All commands run through `/impeccable `; `pin`/`unpin` creates standalone shortcuts (e.g., `/audit`). Commands grouped by intent (from `command-metadata.json`): + +## Create +- `impeccable` — next-step recommendation or plain-English design work; inspects project state, recommends 2-3 commands, asks before running. +- `shape` — "Think before you build. Produce a design brief through discovery, not guesswork." +- `init` — one-time setup: discovery interview, writes `PRODUCT.md`, offers `DESIGN.md`, pre-configures live mode, recommends next commands. +- `document` — generate a spec-compliant `DESIGN.md` (Google Stitch format) from existing code. +- `extract` — pull reusable patterns, components, and tokens into the design system (drift consolidation). + +## Evaluate +- `audit` — 5-dimension technical quality check (a11y, performance, theming, responsive, anti-patterns), scored 0-4, findings P0-P3. Native variant: `audit.native`. +- `critique` — design review with scoring, persona tests, and automated detection. + +## Refine +- `polish` — "The meticulous final pass between good and great." +- `bolder` / `quieter` — amplify safe designs / tone down shouting designs (two halves of voice). +- `distill` — ruthless subtraction; strip to essence. +- `animate` — purposeful motion that conveys state, not decoration. +- `colorize` — strategic color for monochrome UIs. +- `typeset` — fix typography hierarchy and fonts. +- `layout` — fix layout, spacing, visual rhythm. +- `delight` — small moments of personality. +- `overdrive` — push past conventional limits (shaders, physics, 60fps, cinematic transitions). + +## Simplify / Fix +- `adapt` — cross-device/context adaptation (breakpoints, fluid layouts, touch targets). Native variant: `adapt.native`. +- `clarify` — rewrite confusing UX copy. +- `optimize` — diagnose and fix UI performance (LCP to bundle size). + +## Harden +- `harden` — production-ready: edge cases, i18n, error states, overflow. +- `onboard` — first-run flows, empty states, activation paths. + +## System +- `live` — interactive live variant mode (browser picker, 3 variants, HMR, accept writes to source). Alpha. +- `hooks` — manage the design detector hook (`on|off|status|ignore-rule|ignore-file|ignore-value|reset`). +- `doctor` — report/repair drift between project artifacts and what this version reads. + +## Routing rules (`skill/SKILL.src.md`) + +- No argument → read `routing.md`, present context-aware menu; never auto-run a command. +- Explicit or clearly implied command → load its reference and follow it; ask once if two fit. +- Otherwise → treat as general design work; missing `PRODUCT.md` routes new surfaces through `init` then `new-work`; narrow refinement proceeds on the incumbent implementation. +- `teach` aliases `init`; `craft` is a deprecated alias for ordinary new-work. + +## Evidence for the stinger + +- The Bee's procedure maps the four phases to these commands: Start (`init`/`shape`/new-work), Iterate (refine commands + `live`), Polish (`audit`/`clarify`/`harden` + detector gate), Maintain (`extract`/`document`/`doctor`/`hooks`). +- Pin only 2-3 daily commands; pinning everything re-explodes the `/` menu (`impeccable.style/designing`). diff --git a/.claude/skills/impeccable-stinger/research/04-new-work-direction.md b/.claude/skills/impeccable-stinger/research/04-new-work-direction.md new file mode 100644 index 00000000..595fa14f --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/04-new-work-direction.md @@ -0,0 +1,51 @@ +# 04 — New-Work Direction Machinery (classification, five tests, direction contract, roll) + +**Source:** `skill/reference/new-work.md`, `skill/scripts/concept-seed.mjs`, `skill/scripts/lib/concept-catalog.mjs`, `impeccable.style/research` (reference) + +## Job classification + +- **Greenfield** — no coherent visual implementation; a world gets established. +- **Local extension** — a section/component inside a page that already works; only the new part is decided; the page's world is inherited. +- **New surface** — a whole page/flow inside an established world; composition open, world not. +- **Expression expansion** — an established brand entering a surface family it never resolved; a range is approved and merged into `DESIGN.md`. +- **Redesign or rebrand** — the look is replaced; product facts, content, function, constraints are not. +- **Refinement** — better, not different; leaves this flow for a scoped command like `polish`. + +"Redesign this page" authorizes replacement (old look becomes evidence and anti-reference). "Redesign this within our current system" is an extension. Ask once when genuinely ambiguous; never split the difference. + +## The five tests (every candidate must pass all) + +1. **Truth** — every relationship it visualizes exists in your product. Resemblance is not evidence. +2. **Translation** — strip the source's names and materials and a product-native relationship remains; otherwise it is a costume. +3. **Consequence** — removing its best move materially weakens the page. +4. **Survival** — the signature still works on the primary device, within a real asset and time budget. +5. **Fit** — its risk is an honest tradeoff, not a probable violation of your brief. + +## The direction contract (written into the artifact, <=150 words, five blocks) + +- `THESIS` — the one idea this page owns, and the category default it refuses. +- `OWN-WORLD` — palette and component language, recognizable with all content removed. +- `STORY` — what the visitor understands, believes, and does. +- `FIRST VIEWPORT` — the exact composition and where the primary action sits. +- `FORM` — the chosen form and the seed key. + +The contract exists so intent is inspectable and a **separate reviewer agent** can audit the built page against it promise-by-promise. "A page that promised a radical composition and shipped the usual template does not pass quietly" (`skill/reference/new-work.md`). + +## The roll / dice (external variance) + +- Problem (measured): "Ask a coding model for something creative and it builds its favorite idea, every run. Sixteen different 'be creative' framings returned the identical concept in thirty of thirty-five runs" (`skill/reference/new-work.md`; `impeccable.style/research`). +- Fix: a script rolls which of the model's own resonance-ordered shortlist gets built, and deals challengers from a reviewed catalog of ~188 visual worlds (`concept-seed.mjs` header; site says 177-188 worlds). +- "The dice never touch an ungrounded idea. They only refuse the argmax rut" (`concept-seed.mjs`). +- Re-roll: user re-rolls freely; the agent may only re-roll on named factual grounds (assigned direction cannot carry the product's truth or the task). "Its own taste is never grounds." +- Reproduction: the script prints a seed key; `--reroll ` recomputes prior rounds and excludes them. +- Fallback chain: local catalog (`IMPECCABLE_CATALOG_DIR`) → roll API (`https://impeccable.style/api`, `IMPECCABLE_API_URL`) → degraded local mode (`concept-seed.mjs` lines 63-99). + +## Research lessons (from `impeccable.style/research`, reference) + +1. The model lacks variance, not creativity (30/35 identical concepts). +2. Rejection advances a queue — "be different" lands on the #2 idea. +3. Argmax is deterministic; dice must **assign** the index, not nominate a menu (27/30 revert to option 1 when a chooser is involved). +4. Derivation is bounded by the subject's cultural depth; assigned foreign forms win over thin categories. +5. Anti-gimmick guards are the ceiling — commit first, then clarify (biggest single quality jump). +6. Committed skin hides template bones — "borrow the form's skeleton, not its clothes"; skin-blind review is a review instrument, never the builder grading itself. +7. Models describe brilliantly and build conservatively — hold them to the direction contract with a fresh reviewer. diff --git a/.claude/skills/impeccable-stinger/research/05-craft-floor.md b/.claude/skills/impeccable-stinger/research/05-craft-floor.md new file mode 100644 index 00000000..9238cc34 --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/05-craft-floor.md @@ -0,0 +1,32 @@ +# 05 — Craft Floor (quality floor, bans, reflexes) + +**Source:** `skill/reference/craft-floor.md` (verbatim structure) + +Loaded immediately before editing UI (not for planning-only work). "A pinned brief or the committed visual world overrides anything here; your own habit does not." + +## Verify (checks on the built result, run together in batched rounds) + +- **Contrast:** body/placeholder >= 4.5:1, large text >= 3:1; on colored surfaces tint secondary text from that hue or the foreground; never gray. +- **Depth:** shadows carry an offset and a soft blur; a zero-offset colored halo is decoration. +- **Spacing:** tight groups, generous separation, more space above a heading than below it; read computed values. +- **Type:** body measure 65-75ch, display max 6rem, tracking floor -0.04em, balanced headings, obvious scale/weight steps; run real copy at every breakpoint. +- **Motion:** one authored moment, not scattered effects; exponential ease-out from an already-visible default; reach past transform/opacity (blur, backdrop-filter, clip-path, mask, shadow). +- **States:** hover, disabled, loading, error, empty; real content, working controls, responsive composition, keyboard focus. +- **Browser surfaces:** text selection, caret, custom scrollbars, focus rings, underline offset, tabular numerals — "the cheapest signal that a page was built rather than assembled, and the one models skip most reliably." +- **Copy:** the product's own language; controls name their action; errors name the problem and the recovery. +- **Coverage:** every brief requirement present and findable within seconds. + +## Refuse (category defaults, not bans — the brief's own words can earn any of them) + +Page scaffolds: same-size icon+heading+text card grids (cards are the lazy container; nested cards always wrong); hero-metric template; kicker/eyebrow above a heading (a ban, not a default); section numbers 01/02/03 unless the sequence carries information; modal for a task needing neither interruption nor protected focus. + +Surface habits: gradient text; glass/blur as decoration; colored `border-left`/`border-right` above 1px; hard offset shadows outside a real neobrutalist world; sparklines/progress rings/soft-shadowed rounded rectangles standing in for content; monospace as a "technical" costume; system display faces as the display voice; unicode glyphs/emoji standing in for an icon system; light/dark picked by category instead of use scene. + +## Per-model sections + +- ``: tracking stops at -0.04em (-0.02 to -0.03 usually reads better); declare elevation once (border or shadow — 1px border under a wide soft shadow is the ghost card); card radii 12-16px, pills for small controls; real illustration or none (bans sketch-style SVG, `loose-sketch`/`doodle` class names, `feTurbulence` grain); backgrounds are surfaces (bans `repeating-linear-gradient` stripes and two-axis grid overlays without a real canvas/map/blueprint); claims come from supplied truth, label illustrative values honestly. +- ``: never animate an image on hover, directly or through its parent; give the container the feedback. + +## Closing principle + +"The floor holds the mechanics; it never picks the direction. With every check green, spend the page on the committed world, and when torn between refined and committed, commit." diff --git a/.claude/skills/impeccable-stinger/research/06-detector-rules.md b/.claude/skills/impeccable-stinger/research/06-detector-rules.md new file mode 100644 index 00000000..c42b75fd --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/06-detector-rules.md @@ -0,0 +1,84 @@ +# 06 — Detector Rules (59 deterministic rules) + +**Source:** `cli/engine/registry/antipatterns.mjs` (authoritative), `impeccable.style/slop` (public catalog, reference) + +## Engine facts + +- 59 rules, each with `id`, `category` (`slop` | `quality`), `severity` (`error` | `warning` | `advisory`). +- Runs via `npx impeccable detect `; plain output groups by file with rule id, snippet, explanation; `--json` for scripts/CI. +- **Exit codes:** 0 = no findings; 2 = findings detected; 1 = command failed. CI fails the job on 2. +- Engines: static-html (`engines/static-html/detect-html.mjs`), browser/URL (`engines/browser/detect-url.mjs`), regex/text for CSS-in-JS and framework files (`engines/regex/detect-text.mjs`), plus `node/file-system.mjs` (walk, import graph, framework config detection). +- DESIGN.md-aware: when a local `DESIGN.md` exists, enables design-system checks (fonts, literal colors, radii, font sizes) using `.impeccable/design.json` for richer token/ramp data. `--no-design-system` disables; `--scope type|layout` narrows. +- Ignores: `npx impeccable ignores ...` (shared `config.json` / local `config.local.json`), inline `impeccable-disable` / `-line` / `-next-line` comments. +- Web only: native projects route to `/impeccable audit` (native pass). + +## Full rule list (id | category | severity) + +### slop (30) +side-tab | slop | advisory — thick colored border on one side of a card (most recognizable AI tell) +border-accent-on-rounded | slop | advisory — accent border clashes with radius +overused-font | slop | advisory — Inter, Geist, Space Grotesk, Instrument Serif, etc. +flat-type-hierarchy | slop | error — font sizes too close (aim >= 1.25 ratio) +gradient-text | slop | error — decorative gradient text +ai-color-palette | slop | advisory — purple/violet gradients, cyan-on-dark +cream-palette | slop | advisory — warm cream/beige default surface +nested-cards | slop | advisory — cards inside cards +monotonous-spacing | slop | advisory — same spacing everywhere +bounce-easing | slop | advisory — bounce/elastic easing on interface elements +pulsing-dot | slop | advisory — decorative pulse on static status +blinking-cursor | slop | advisory — fake caret on non-editable hero copy +shape-assembled-illustration | slop | advisory — sketch-style SVG scenes +dark-glow | slop | warning — dark bg with colored box-shadow glows +radial-halo | slop | warning — saturated radial glow on dark page +radial-spotlight-glow | slop | warning — accent haze behind a section +marquee | slop | warning — auto-scrolling marquee +icon-tile-stack | slop | warning — rounded-square icon tile above heading +italic-serif-display | slop | warning — oversized italic serif hero +hero-eyebrow-chip | slop | warning — tiny uppercase label above hero headline +kicker-above-heading | slop | warning — tracked uppercase label above heading +numbered-section-labels | slop | warning — tiny 01/02/03 labels +em-dash-overuse | slop | warning +marketing-buzzword | slop | warning +aphoristic-cadence | slop | warning +oversized-h1 | slop | warning — full-sentence headline at display size +extreme-negative-tracking | slop | warning — crushed letter spacing +gpt-thin-border-wide-shadow | slop | warning — hairline border + wide diffuse shadow (ghost card) +repeating-stripes-gradient | slop | warning — decorative stripe backgrounds +codex-grid-background | slop | warning — two-axis grid overlays without a real canvas +theater-slop-phrase | slop | warning — "x-theater" naming/irony +image-hover-transform | slop | warning — image animated on hover (Gemini-tuned rule) + +### quality (29) +broken-image | quality | warning +script-error | quality | warning +content-hidden-at-rest | quality | warning +edge-flush-cards | quality | warning — scroller cards lose one edge +text-occlusion | quality | warning — opaque layer covers readable text +first-viewport-column-overflow | quality | warning +gray-on-color | quality | warning — gray text on colored background +low-contrast | quality | warning +layout-transition | quality | warning +line-length | quality | warning — > ~80ch +cramped-padding | quality | warning +body-text-viewport-edge | quality | warning +tight-leading | quality | warning +skipped-heading | quality | warning +heading-rhythm | quality | warning — heading closer to previous block than its content +justified-text | quality | warning +tiny-text | quality | warning +undersized-ui-text | quality | warning — functional text under 11px +all-caps-body | quality | warning +wide-tracking | quality | warning +text-overflow | quality | warning +repeated-container-text | quality | warning +clipped-overflow-container | quality | warning — positioned child clipped by overflow container +design-system-font | quality | warning — font outside DESIGN.md +design-system-color | quality | warning — literal color outside DESIGN.md palette +design-system-radius | quality | warning — radius outside documented shape scale +design-system-font-size | quality | warning — font size between documented steps + +## Evidence for the stinger + +- The gate is the Bee's mandatory close-out step: `npx impeccable detect `; exit code 2 fails until resolved or explicitly waived (narrowest ignore + reason). +- The 4 design-system rules make product-token enforcement mechanical — they complement `design-system-stinger`/`ux-ui-stinger`. +- Verified live during research: `node cli/bin/cli.js detect tests/fixtures` returned line-numbered findings (side-tab, design-system-color, etc.) with remediation text. diff --git a/.claude/skills/impeccable-stinger/research/07-hooks-enforcement.md b/.claude/skills/impeccable-stinger/research/07-hooks-enforcement.md new file mode 100644 index 00000000..5282b89b --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/07-hooks-enforcement.md @@ -0,0 +1,41 @@ +# 07 — Hooks & Enforcement (per-edit + deep pass) + +**Source:** `skill/reference/hooks.md`, `skill/scripts/hook-admin.mjs`, `skill/scripts/hook-lib.mjs`, `impeccable.style/docs/hooks` (reference) + +## What the hook does + +- Scans direct edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). +- **Claude Code, GitHub Copilot, Codex:** post-tool-use hook pushes a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, clean UI-ish files get a short ack (unless `hook.quiet`). +- **Cursor:** `preToolUse` blocks bad proposed writes before they land; silent when it allows a clean write. +- Plain `.ts`/`.js` files are scanned but stay quiet unless the detector finds something. + +## Two speeds + +- **Per edit:** only what is objectively broken or compounds if ignored (broken images, overflow/clipped text, contrast failures, tiny text, gradient text, glow, DESIGN.md drift). +- **End of session (deep pass):** the full rule set across every UI file touched, minus what was already reported; a second stop is silent (findings remembered). Wired for Claude Code and Codex (native Stop hook); Cursor and Copilot keep the full detector per edit. +- Rationale: "Reporting every rule on every edit made models measurably more conservative rather than more careful" (one copy-level rule fired ~97x in a single session). +- `hook.perEditRules: "all"` restores full rules per edit. + +## Harness manifests & approval + +- Claude Code: `.claude/settings.local.json` (gitignored, machine-local). +- GitHub Copilot: `.github/hooks/impeccable.json` (committed, team-shared; activates on default branch). +- Codex: `.codex/hooks.json` — **requires one extra approval step**: open `/hooks` in Codex and approve the project hook; updates that change the hook definition can require approval again. +- Cursor: `.cursor/hooks.json`; confirm hooks enabled in Cursor Settings → Hooks. +- Installer/updater: `npx impeccable install|update`; `--no-hooks` skips hook setup; `--force` backs up malformed manifests as `.bak`. + +## Config & env + +- `hook.enabled`, `hook.quiet`, `hook.auditLog` (NDJSON) in `.impeccable/config.json`; per-developer consent in `.impeccable/config.local.json`. +- Env overrides: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, `IMPECCABLE_HOOK_LOG`. +- Detector filters live under `detector` (shared by hook and CLI): `ignoreRules`, `ignoreFiles`, `ignoreValues`, `designSystem.enabled`. +- Server-side templates: declare under `detector.extensions` (e.g., `{ "ext": ".blade.php", "engine": "html" }`). + +## Failure mode to watch + +"A hook can look installed and scan nothing: if its script path stops resolving... the manifest still registers and no findings ever arrive. Silence reads as a clean codebase." `/impeccable doctor` checks for exactly this (`skill/reference/hooks.md`). + +## Evidence for the stinger + +- The Bee verifies hook health (`doctor`) and treats hook silence as suspicious, not as a clean pass. +- Hooks are the "every time" enforcement: they fire on every UI edit regardless of routing discipline. diff --git a/.claude/skills/impeccable-stinger/research/08-live-mode.md b/.claude/skills/impeccable-stinger/research/08-live-mode.md new file mode 100644 index 00000000..41709208 --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/08-live-mode.md @@ -0,0 +1,23 @@ +# 08 — Live Mode (browser iteration) + +**Source:** `skill/reference/live.md`, `skill/reference/live-setup.md`, `skill/scripts/live/*`, `impeccable.style/docs/live` (reference) + +## What it is + +`/impeccable live` drops a picker onto the running dev server. The user points at any element, draws or types what they want, and gets **three production-quality variants** hot-swapped via HMR. Accepting one writes it back to source. + +- Requires a running dev server (localhost). +- Status: **alpha** — "works end-to-end and is ready to try, but it still needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups" (`impeccable.style/docs/live`). +- Scripts: `skill/scripts/live/*` (live.mjs, live-accept.mjs, live-complete.mjs, live-poll.mjs, live-status.mjs, live-wrap.mjs, live-target.mjs, live-resume.mjs, live-browser.js, live-inject.mjs, live-insert.mjs, live-copy-edit-agent.mjs, live-commit-manual-edits.mjs, live-manual-edit-evidence.mjs, live-discard-manual-edits.mjs, live-browser-dom.js, live-browser-session.js, live/manual-edits-buffer.mjs, live/vocabulary.mjs, live/svelte-ast.mjs, live/event-validation.mjs, live/insert-ui.mjs, live/manual-apply.mjs, live/completion.mjs, live/poll-lanes.mjs, live/accept-css.mjs, live/roots.mjs). +- `live-browser.js` is ~500KB (bundled browser automation). + +## When to reach for it + +- Fix something "off" you can't name. +- Explore three directions side by side. +- Point-at-it iteration beats command-naming when the user doesn't know the design word. + +## Evidence for the stinger + +- Live Mode is an Iterate-phase tool, not the core loop. Given alpha status, the Bee should treat it as optional/experimental and prefer named commands for the default path. +- Accept writes to source; manual edits are captured and committed via `live-commit-manual-edits.mjs`. diff --git a/.claude/skills/impeccable-stinger/research/09-maintenance-doctor.md b/.claude/skills/impeccable-stinger/research/09-maintenance-doctor.md new file mode 100644 index 00000000..35f24025 --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/09-maintenance-doctor.md @@ -0,0 +1,37 @@ +# 09 — Maintenance: Doctor, Config, Ignores, Update + +**Source:** `skill/reference/doctor.md`, `skill/reference/hooks.md`, `skill/scripts/doctor.mjs`, `impeccable.style/docs/doctor`, `impeccable.style/docs/config` (reference) + +## Doctor — three kinds of "out of date" + +1. **Tool version** — installed skill older than published; reported at boot; `npx impeccable update` fixes. +2. **Schema drift** — artifact written by an older Impeccable (fields nothing reads, fields now expected, retired locations). Mechanical; doctor repairs most of it. This is doctor's job. +3. **Truth drift** — code moved on and the document no longer describes it. Routed to `init`/`document`, not repaired. + +## What doctor checks + +- `PRODUCT.md` schema stamp (vintage, not release version). +- `DESIGN.md` (no stamp — follows external design.md spec) and the `.impeccable/design.json` sidecar (older than DESIGN.md, outdated schema, legacy path). +- Config: unknown keys, unknown detector keys, ignored rule ids that no longer exist, ignored file paths that are gone, `projectRoots` globs matching nothing. +- Design hook: script path that stopped resolving; enabled/disabled conflict. +- Surface briefs: records orphaned from the file/route they describe. +- Monorepos: which apps carry their own `PRODUCT.md`/`DESIGN.md` vs inherit the root's; flags a workspace with native build files inheriting a web-only root record. + +## Config & ignores + +- `.impeccable/config.json` (shared, commit when team intent) + `.impeccable/config.local.json` (private, gitignored). +- `npx impeccable ignores list|add-value|add-file|add-rule|remove-value`; `--local` for private; `--reason` for the why. +- Value ignores preferred for fonts/colors/radii/motion (keeps the rule useful elsewhere); wildcard value ignores only when scoped to a file. +- Inline comments travel with a file: ``, `impeccable-disable-line`, `impeccable-disable-next-line`. +- `projectRoots` for repos where design boundaries don't line up with package-manager workspaces. +- A config file fails quietly when wrong (misspelled key never read; stale rule id suppresses nothing) — doctor catches all three. + +## Update flow + +- `npx impeccable check` (behind?) → `npx impeccable update` (from project root); plugin users update from `/plugin` menu; `npx skills update` for the shared build. +- `stalenessCheck: false` in config or `IMPECCABLE_NO_STALENESS_CHECK=1` silences the boot notice; `doctor` still works. + +## Evidence for the stinger + +- Maintain phase = `extract` (consolidate drift) + `document` (re-capture system) + `doctor` (schema/truth/tool drift) + `check`/`update` (upstream). +- "Never repair drift as a side effect of a design task" — a `CONTEXT_STALE` finding is reported, not acted on, unless the user asks (`skill/SKILL.src.md`). diff --git a/.claude/skills/impeccable-stinger/research/10-native-platforms-harnesses.md b/.claude/skills/impeccable-stinger/research/10-native-platforms-harnesses.md new file mode 100644 index 00000000..96b1ff82 --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/10-native-platforms-harnesses.md @@ -0,0 +1,23 @@ +# 10 — Native Platforms & Harness Builds + +**Source:** `skill/reference/ios.md`, `skill/reference/android.md`, `skill/reference/audit.native.md`, `skill/reference/adapt.native.md`, `docs/HARNESSES.md`, repo `.claude/ .cursor/ .codex/ .gemini/ .grok/ .trae/ .opencode/ .qoder/ .rovodev/` builds + +## Native (iOS / Android / adaptive) + +- The detector is **web only** ("The engine reads HTML and CSS, so it has nothing to say about a native iOS or Android codebase" — `impeccable.style/docs/detector`). +- When `PRODUCT.md` declares `ios`, `android`, or `adaptive`, `/impeccable audit` runs a native pass covering VoiceOver, TalkBack, touch targets, and platform conformance (`audit.native.md`); `adapt` has a native variant (`adapt.native.md`). +- `init` detects the platform from codebase evidence and asks only when ambiguous; platform is recorded in `PRODUCT.md`. +- Native guidance files: `ios.md`, `android.md` (per-platform rulebooks). + +## Harness builds + +- `npx impeccable install` auto-detects the harness and writes the right skill files (`.claude/skills/`, `.cursor/skills/`, `.codex/`, `.gemini/`, `.grok/`, etc.), plus provider-native hook manifests where supported. +- Per-model rule tuning: the Gemini build kills image-on-hover motion; the Codex build refuses ghost-cards and over-rounding (`README.md`; ``/`` sections in `craft-floor.md`). +- `npx skills add pbakaus/impeccable` installs one shared build for every harness (functionally complete, not tailored). +- Claude Code plugin: `/plugin marketplace add pbakaus/impeccable`. +- GitHub Copilot: Impeccable is built in (Settings → Experimental). + +## Evidence for the stinger + +- The Bee's default domain is web; native surfaces route to the native playbooks and the native audit pass. +- The stinger should note the per-model build behavior so the Bee knows the installed build may carry extra rules for its model. diff --git a/.claude/skills/impeccable-stinger/research/11-license-provenance.md b/.claude/skills/impeccable-stinger/research/11-license-provenance.md new file mode 100644 index 00000000..409c38f8 --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/11-license-provenance.md @@ -0,0 +1,27 @@ +# 11 — License, Provenance & Versioning + +**Source:** `LICENSE`, `NOTICE.md`, `package.json`, `README.md`, `impeccable.style/robots.txt` + +## License + +- **Apache-2.0** (`LICENSE`; `package.json` `"license": "Apache-2.0"`; `cli/engine/detect-antipatterns.mjs` header: "SPDX-License-Identifier: Apache-2.0"). +- Vendoring guidance content into the stinger is license-clean with attribution. Keep the NOTICE/attribution (`NOTICE.md` exists in the repo). +- Author: Paul Bakaus. Homepage: impeccable.style. npm: `impeccable`. + +## Site content signals (compliance) + +- `impeccable.style/robots.txt`: `Content-Signal: search=yes, ai-train=no, use=reference` (Cloudflare managed; also disallows GPTBot, ClaudeBot, CCBot, etc.). +- Implication: the stinger must be built from the **repo** (Apache-2.0), not scraped from the site. Site text is reference-only for understanding, not a training/vendoring source. + +## Versioning + +- Repo `package.json`: `3.5.0` (npm package version). Site markets **v4** ("A leaner core, tuned on frontier models like Fable and GPT-5.6-Sol. Four visitor modes."). +- Content is in sync: the repo's `SKILL.src.md` has all four modes (Persuade/Operate/Read/Experience); the site docs are generated from the repo's `skill/reference/` files. +- Upstream is actively maintained (repo HEAD `aee6ce9`, 2026-08-04; sitemap lastmods through 2026-07-22). +- Implication: the stinger's vendored reference docs need a refresh cadence; the installed side self-updates via `npx impeccable check`/`update`. + +## Research provenance + +- Clone: `/tmp/impeccable-RZVWdD` (shallow, depth 1, commit `aee6ce9`). +- Detector verified live: `node cli/bin/cli.js detect tests/fixtures` produced line-numbered findings (side-tab, design-system-color, etc.). +- Site pages fetched for reference: `/`, `/docs*`, `/slop`, `/research`, `/designing`, `/cases/neo-mirai`, `/tutorials/*`. diff --git a/.claude/skills/impeccable-stinger/research/index.md b/.claude/skills/impeccable-stinger/research/index.md new file mode 100644 index 00000000..40547606 --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/index.md @@ -0,0 +1,26 @@ +# Research Index — impeccable-stinger + +Manifest of primary-source research for `impeccable-worker-bee`. All files cite repo paths under `/tmp/impeccable-RZVWdD` (github.com/pbakaus/impeccable, commit aee6ce9, Apache-2.0). + +| File | Covers | Primary sources | +|---|---|---| +| `research-plan.md` | Scope, depth, method, provenance | Command Brief, repo | +| `01-system-overview.md` | Whole system: 7 layers, four-phase loop, per-model builds | `README.md`, `PRODUCT.md`, `skill/SKILL.src.md`, `package.json`, site `/designing` | +| `02-context-contract.md` | PRODUCT.md / DESIGN.md / surfaces / design.json, modes | `skill/scripts/context.mjs`, `skill/reference/init.md`, `document.md`, site `/docs/context` | +| `03-command-vocabulary.md` | 23 commands, routing rules, pinning | `skill/scripts/command-metadata.json`, `skill/SKILL.src.md`, site `/docs` | +| `04-new-work-direction.md` | Classification, five tests, direction contract, roll/dice, research lessons | `skill/reference/new-work.md`, `skill/scripts/concept-seed.mjs`, `lib/concept-catalog.mjs`, site `/research` | +| `05-craft-floor.md` | Quality floor, bans, reflexes, per-model sections | `skill/reference/craft-floor.md` | +| `06-detector-rules.md` | 59 rules (id/category/severity), CLI, exit codes, engines, ignores | `cli/engine/registry/antipatterns.mjs`, `cli/engine/*`, site `/slop` | +| `07-hooks-enforcement.md` | Per-edit + deep pass, harness manifests, approval, config | `skill/reference/hooks.md`, `skill/scripts/hook-admin.mjs`, `hook-lib.mjs`, site `/docs/hooks` | +| `08-live-mode.md` | Live browser iteration, alpha status, scripts | `skill/reference/live.md`, `skill/scripts/live/*`, site `/docs/live` | +| `09-maintenance-doctor.md` | Doctor (tool/schema/truth drift), config, ignores, update | `skill/reference/doctor.md`, `skill/scripts/doctor.mjs`, site `/docs/doctor`, `/docs/config` | +| `10-native-platforms-harnesses.md` | iOS/Android/adaptive, per-harness builds, per-model rules | `skill/reference/ios.md`, `android.md`, `audit.native.md`, `adapt.native.md`, `docs/HARNESSES.md` | +| `11-license-provenance.md` | Apache-2.0, site content signals, versioning, research provenance | `LICENSE`, `NOTICE.md`, `package.json`, site `robots.txt` | + +## Open questions for the user (not for stinger-forge to invent) + +1. **Scope of the Bee's routing:** should `impeccable-worker-bee` become the *default* router for all frontend UI/UX work (retiring `design-taste-frontend`, `frontend-design`, `high-end-visual-design`, `gpt-taste`, `web-design-guidelines` as fallbacks), or coexist? +2. **Upstream install vs stinger-only:** should the army run `npx impeccable install` per project (hooks + compiled skill) as the enforcement layer, with the stinger as guidance + gate procedure? (Recommended: yes.) +3. **CI gate:** add `npx impeccable detect src/` to army projects' PR checks? +4. **Live Mode:** adopt now (alpha) or defer until stable? +5. **Native:** does the army need the iOS/Android/adaptive playbooks in the first stinger release, or web-only? diff --git a/.claude/skills/impeccable-stinger/research/research-plan.md b/.claude/skills/impeccable-stinger/research/research-plan.md new file mode 100644 index 00000000..7e66e342 --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/research-plan.md @@ -0,0 +1,8 @@ +# Research Plan: impeccable-stinger + +- **Bee:** impeccable-worker-bee (Command Brief: `.cursor/commands/impeccable-worker-bee-command-brief.md`) +- **Depth tier:** deep (entire system: context contract, 23 commands, four-phase loop, 59-rule detector, hooks, live mode, worlds deck, maintenance) +- **Primary source:** `github.com/pbakaus/impeccable` (Apache-2.0), cloned at `/tmp/impeccable-RZVWdD` (commit `aee6ce9`, 2026-08-04, package v3.5.0) +- **Method:** repo-primary extraction (user-directed), not a web sweep. The repo is the canonical Apache-2.0 source; impeccable.style is generated from it and is reference-only (robots.txt: `ai-train=no, use=reference`). +- **Evidence files to extract:** `skill/SKILL.src.md`, `skill/reference/*.md` (33 files), `skill/scripts/*` (context, concept-seed, hook-admin, doctor, live), `cli/engine/registry/antipatterns.mjs` (59 rules), `cli/engine/*` (checks, constants, color, design-system, engines), `docs/*`, `DESIGN.md`, `PRODUCT.md`, `README.md`, `package.json`, `LICENSE`, `NOTICE.md`, `tests/`. +- **Output:** `research/` files below, `index.md` manifest, `research-summary.md` handoff. diff --git a/.claude/skills/impeccable-stinger/research/research-summary.md b/.claude/skills/impeccable-stinger/research/research-summary.md new file mode 100644 index 00000000..2d0e0597 --- /dev/null +++ b/.claude/skills/impeccable-stinger/research/research-summary.md @@ -0,0 +1,37 @@ +# Research Summary — impeccable-stinger + +- **Depth tier consumed:** deep (entire system) +- **Time window covered:** repo HEAD `aee6ce9` (2026-08-04); site sitemap lastmods 2026-04-10 → 2026-07-22. Repo-primary research, not a web sweep (user-directed; site robots.txt `ai-train=no`). +- **Files written:** 13 (research-plan + 11 topic files + index + this summary) under `.cursor/skills/impeccable-stinger/research/`. + +## The 5 most influential sources (for stinger-forge) + +1. **`skill/SKILL.src.md`** — the skill definition: setup, four modes, command routing, hooks, doctor, bounded-pass discipline. The stinger's SKILL.md should mirror its structure and voice. +2. **`skill/reference/craft-floor.md`** — the quality floor, absolute bans, and per-model (``, ``) sections. This is the anti-slop core the Bee enforces. +3. **`skill/reference/new-work.md` + `skill/scripts/concept-seed.mjs`** — job classification, five tests, direction contract, and the roll/dice variance machinery. This is what makes the system "whole" and is unique vs every existing army skill. +4. **`cli/engine/registry/antipatterns.mjs`** — the 59 deterministic rules (id/category/severity) that power the gate, hooks, CI, and slop catalog. The Bee's mandatory close-out gate. +5. **`skill/reference/hooks.md` + `skill/scripts/hook-admin.mjs`** — per-edit + deep-pass enforcement, harness manifests, Codex approval. The "every time" enforcement layer. + +## Open questions (for the user, not stinger-forge) + +1. Default router for all frontend UI/UX work, retiring overlapping prompt-only skills as fallbacks? +2. Upstream `npx impeccable install` per project as the enforcement layer (recommended), stinger as guidance + gate? +3. CI gate on army PR checks? +4. Live Mode now (alpha) or defer? +5. Native playbooks in first release, or web-only? + +## Sources stinger-forge should re-fetch with deeper context + +- `skill/reference/audit.md` + `audit.native.md` (5-dimension scoring rubric, P0-P3) — needed for the Polish-phase guide. +- `skill/reference/init.md` + `document.md` (interview flow, Stitch-format capture) — needed for the Start-phase guide. +- `skill/reference/live.md` + `live-setup.md` (alpha; decide inclusion). +- `docs/HARNESSES.md` (per-harness install/update details) — needed for the install/verify guide. +- `skill/scripts/context.mjs` (context loading + staleness directives) — needed for the context-contract guide. + +## Decisions (user-resolved 2026-08-06) + +1. Default router for all frontend UI/UX work — YES (retire overlapping prompt-only skills to fallbacks). +2. Install scope — HYBRID: global skill install + per-project context/hooks (hooks are project-local by harness design). +3. CI gate — YES (`npx impeccable detect src/` in PR checks). +4. Live Mode — include as opt-in, user-invoked, alpha; never auto-launched. +5. Native — include iOS/Android/adaptive playbooks. diff --git a/.claude/skills/impeccable-stinger/scripts/sync-check.mjs b/.claude/skills/impeccable-stinger/scripts/sync-check.mjs new file mode 100755 index 00000000..adfeabdf --- /dev/null +++ b/.claude/skills/impeccable-stinger/scripts/sync-check.mjs @@ -0,0 +1,157 @@ +#!/usr/bin/env node +/** + * impeccable-stinger pre-flight sync check. + * + * Verifies, before a design task starts, that the installed Impeccable skill + * is current with upstream and that the stinger's vendored coverage (guides + + * templates) still matches the installed skill's content. If everything is + * current it is skipped (exit 0); if behind or drifted it reports what changed + * (exit 2); if the skill is not installed it says so (exit 1). + * + * Usage: + * node sync-check.mjs # check only + * node sync-check.mjs --update # check, and run `npx impeccable update` when behind + * + * Exit codes: + * 0 = current and in sync (skip) + * 2 = behind upstream and/or content drift (needs update/refresh) + * 1 = not installed or check failed + */ +import { readFileSync, existsSync, readdirSync } from 'node:fs'; +import { join, dirname } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { spawnSync } from 'node:child_process'; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const STINGER = join(HERE, '..'); +const MANIFEST = JSON.parse(readFileSync(join(HERE, 'upstream-manifest.json'), 'utf8')); + +const CANDIDATE_DIRS = [ + join(process.env.HOME || '', '.agents', 'skills', 'impeccable'), + join(process.env.HOME || '', '.codex', 'skills', 'impeccable'), + join(process.env.HOME || '', '.claude', 'skills', 'impeccable'), + join(process.env.HOME || '', '.cursor', 'skills', 'impeccable'), + '.agents/skills/impeccable', + '.codex/skills/impeccable', + '.claude/skills/impeccable', + '.cursor/skills/impeccable', +]; + +const UPDATE_HOST = process.env.IMPECCABLE_UPDATE_HOST || 'https://impeccable.style'; +const FETCH_TIMEOUT_MS = 4000; + +function findInstalledSkill() { + for (const dir of CANDIDATE_DIRS) { + if (existsSync(join(dir, 'SKILL.md'))) return dir; + } + return null; +} + +function readInstalledVersion(dir) { + try { + const md = readFileSync(join(dir, 'SKILL.md'), 'utf8'); + const m = md.match(/^version:\s*(.+)$/m); + return m ? m[1].trim() : null; + } catch { + return null; + } +} + +function compareVersions(a, b) { + const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0); + const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0); + for (let i = 0; i < Math.max(pa.length, pb.length); i++) { + const da = pa[i] || 0; + const db = pb[i] || 0; + if (da !== db) return da - db; + } + return 0; +} + +async function fetchPublishedVersion() { + try { + const res = await fetch(`${UPDATE_HOST}/api/version`, { + signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), + }); + if (!res.ok) return null; + const body = await res.text(); + const m = body.match(/"version"\s*:\s*"([^"]+)"/) || body.match(/"skills"\s*:\s*"([^"]+)"/) || body.match(/^([0-9]+\.[0-9]+\.[0-9]+)/m); + return m ? m[1] : body.trim(); + } catch { + return null; + } +} + +function contentDrift(dir) { + const drift = { newReferenceFiles: [], newCommands: [], missingReferenceFiles: [] }; + const refDir = join(dir, 'reference'); + if (existsSync(refDir)) { + const installed = readdirSync(refDir).filter((f) => f.endsWith('.md')).sort(); + drift.newReferenceFiles = installed.filter((f) => !MANIFEST.referenceFiles.includes(f)); + drift.missingReferenceFiles = MANIFEST.referenceFiles.filter((f) => !installed.includes(f)); + } + const metaPath = join(dir, 'scripts', 'command-metadata.json'); + if (existsSync(metaPath)) { + try { + const meta = JSON.parse(readFileSync(metaPath, 'utf8')); + drift.newCommands = Object.keys(meta).filter((c) => !MANIFEST.commands.includes(c)); + } catch { + /* ignore unreadable metadata */ + } + } + return drift; +} + +function runUpdate() { + const r = spawnSync('npx', ['impeccable', 'update'], { stdio: 'inherit', shell: true }); + return r.status === 0; +} + +async function main() { + const args = process.argv.slice(2); + const doUpdate = args.includes('--update'); + + const installedDir = findInstalledSkill(); + if (!installedDir) { + console.log('[sync-check] NOT INSTALLED: no impeccable skill found in any harness skill dir.'); + console.log('[sync-check] Run: npx impeccable install --scope=global --providers=codex,claude,cursor'); + process.exit(1); + } + + const installedVersion = readInstalledVersion(installedDir); + const publishedVersion = await fetchPublishedVersion(); + const drift = contentDrift(installedDir); + + const behind = installedVersion && publishedVersion && compareVersions(publishedVersion, installedVersion) > 0; + const hasDrift = drift.newReferenceFiles.length > 0 || drift.newCommands.length > 0; + + console.log(`[sync-check] installed: ${installedVersion || 'unknown'} @ ${installedDir}`); + console.log(`[sync-check] published: ${publishedVersion || 'unreachable (offline?)'}`); + if (behind) console.log(`[sync-check] BEHIND: installed ${installedVersion} < published ${publishedVersion}`); + if (drift.newCommands.length) console.log(`[sync-check] NEW COMMANDS upstream: ${drift.newCommands.join(', ')}`); + if (drift.newReferenceFiles.length) console.log(`[sync-check] NEW REFERENCE FILES upstream: ${drift.newReferenceFiles.join(', ')}`); + if (drift.missingReferenceFiles.length) console.log(`[sync-check] MISSING REFERENCE FILES (installed skill lacks): ${drift.missingReferenceFiles.join(', ')}`); + + if (!behind && !hasDrift) { + console.log('[sync-check] CURRENT: upstream in sync, stinger coverage matches. Skipping update.'); + process.exit(0); + } + + if (doUpdate && behind) { + console.log('[sync-check] Running `npx impeccable update`...'); + if (runUpdate()) { + console.log('[sync-check] Updated. NOTE: Codex may require /hooks re-approval after an update.'); + process.exit(0); + } + console.log('[sync-check] Update failed.'); + process.exit(1); + } + + if (hasDrift) { + console.log('[sync-check] STINGER REFRESH NEEDED: upstream added content the stinger does not cover.'); + console.log('[sync-check] Add guides/templates for the new content, then update scripts/upstream-manifest.json.'); + } + process.exit(2); +} + +main(); diff --git a/.claude/skills/impeccable-stinger/scripts/upstream-manifest.json b/.claude/skills/impeccable-stinger/scripts/upstream-manifest.json new file mode 100644 index 00000000..b96d7c6c --- /dev/null +++ b/.claude/skills/impeccable-stinger/scripts/upstream-manifest.json @@ -0,0 +1,128 @@ +{ + "upstreamVersion": "4.0.4", + "upstreamCommit": "aee6ce9", + "upstreamDate": "2026-08-04", + "commands": [ + "craft", + "init", + "document", + "extract", + "live", + "adapt", + "animate", + "audit", + "bolder", + "clarify", + "colorize", + "critique", + "delight", + "distill", + "harden", + "onboard", + "layout", + "optimize", + "overdrive", + "polish", + "quieter", + "shape", + "typeset" + ], + "referenceFiles": [ + "adapt.md", + "adapt.native.md", + "android.md", + "animate.md", + "audit.md", + "audit.native.md", + "bolder.md", + "clarify.md", + "colorize.md", + "craft-floor.md", + "craft.md", + "critique.md", + "delight.md", + "distill.md", + "doctor.md", + "document.md", + "extract.md", + "harden.md", + "hooks.md", + "init.md", + "ios.md", + "layout.md", + "live-setup.md", + "live.md", + "new-work.md", + "onboard.md", + "operate.md", + "optimize.md", + "overdrive.md", + "polish.md", + "quieter.md", + "routing.md", + "shape.md", + "typeset.md", + "visualize.md" + ], + "rules": [ + "side-tab", + "border-accent-on-rounded", + "overused-font", + "flat-type-hierarchy", + "gradient-text", + "ai-color-palette", + "cream-palette", + "nested-cards", + "monotonous-spacing", + "bounce-easing", + "pulsing-dot", + "blinking-cursor", + "shape-assembled-illustration", + "dark-glow", + "radial-halo", + "radial-spotlight-glow", + "marquee", + "icon-tile-stack", + "italic-serif-display", + "hero-eyebrow-chip", + "kicker-above-heading", + "numbered-section-labels", + "em-dash-overuse", + "marketing-buzzword", + "aphoristic-cadence", + "oversized-h1", + "extreme-negative-tracking", + "broken-image", + "script-error", + "content-hidden-at-rest", + "edge-flush-cards", + "text-occlusion", + "first-viewport-column-overflow", + "gray-on-color", + "low-contrast", + "layout-transition", + "line-length", + "cramped-padding", + "body-text-viewport-edge", + "tight-leading", + "skipped-heading", + "heading-rhythm", + "justified-text", + "tiny-text", + "undersized-ui-text", + "all-caps-body", + "wide-tracking", + "text-overflow", + "repeated-container-text", + "clipped-overflow-container", + "design-system-font", + "design-system-color", + "design-system-radius", + "design-system-font-size", + "gpt-thin-border-wide-shadow", + "repeating-stripes-gradient", + "codex-grid-background", + "theater-slop-phrase", + "image-hover-transform" + ] +} diff --git a/.claude/skills/impeccable-stinger/templates/direction-contract.md b/.claude/skills/impeccable-stinger/templates/direction-contract.md new file mode 100644 index 00000000..96c3ffbf --- /dev/null +++ b/.claude/skills/impeccable-stinger/templates/direction-contract.md @@ -0,0 +1,16 @@ +# Direction Contract (write into the artifact as a comment block, <=150 words, five blocks) + +```ts +/* + * THESIS: + * OWN-WORLD: + * STORY: + * FIRST VIEWPORT: + * FORM: + */ +``` + +Rules: +- The contract is inspectable intent. A separate reviewer audits the built page against it promise-by-promise. +- Keep the seed key to reproduce the roll (including every re-roll round). +- A page that promised a radical composition and shipped the usual template does not pass quietly. diff --git a/.claude/skills/impeccable-stinger/templates/gate-report.md b/.claude/skills/impeccable-stinger/templates/gate-report.md new file mode 100644 index 00000000..d387c841 --- /dev/null +++ b/.claude/skills/impeccable-stinger/templates/gate-report.md @@ -0,0 +1,22 @@ +# Detector Gate Report + +| Field | Value | +|---|---| +| Target | `` | +| Command | `npx impeccable detect ` | +| Exit code | `0` (no findings) / `2` (findings) / `1` (failed) | +| Findings | `` | +| Resolved | `` | +| Waived | `` | + +## Findings + +| Rule id | Severity | File:line | Resolution (fix or waiver + reason) | +|---|---|---|---| +| `side-tab` | advisory | `src/components/Card.tsx:52` | Fixed — removed inset stripe | +| `overused-font` | advisory | `src/styles/global.css:14` | Waived — `ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md"` | + +## Verdict + +- [ ] Gate clean (0 findings) — close-out may proceed +- [ ] Gate failed (exit 2) — close-out blocked until resolved or waived diff --git a/.claude/skills/impeccable-stinger/templates/surface-brief.md b/.claude/skills/impeccable-stinger/templates/surface-brief.md new file mode 100644 index 00000000..497c4fff --- /dev/null +++ b/.claude/skills/impeccable-stinger/templates/surface-brief.md @@ -0,0 +1,10 @@ +# Surface Brief: `` + +- **Mode:** Persuade / Operate / Read / Experience +- **Job:** what the visitor came to do on this surface +- **Proof sequence:** what evidence the surface shows, in order +- **Chosen direction:** the committed world (or "inherits `` world") +- **Seed key:** `` (if rolled) +- **Anti-references:** what this surface must not do + +Written by the work itself; edited when the page's strategy changes. Lives at `.impeccable/surfaces/.md`. diff --git a/.claude/skills/impeccable-stinger/templates/sync-report.md b/.claude/skills/impeccable-stinger/templates/sync-report.md new file mode 100644 index 00000000..1040935a --- /dev/null +++ b/.claude/skills/impeccable-stinger/templates/sync-report.md @@ -0,0 +1,14 @@ +# Sync Check Report + +| Field | Value | +|---|---| +| Installed version | `<4.0.4>` | +| Published version | `<4.0.4>` | +| Status | `current` / `behind` / `not installed` | +| New commands upstream | `` | +| New reference files upstream | `` | +| Action taken | `skipped (current)` / `updated` / `stinger refresh` | + +- [ ] Current → skipped, task proceeded +- [ ] Updated → `/hooks` re-approval noted to user +- [ ] Stinger refresh needed → new guide/template added, manifest bumped diff --git a/.codex/agents/impeccable-worker-bee.toml b/.codex/agents/impeccable-worker-bee.toml new file mode 100644 index 00000000..353ca1e2 --- /dev/null +++ b/.codex/agents/impeccable-worker-bee.toml @@ -0,0 +1,3 @@ +name = "impeccable-worker-bee" +description = "Operates the entire Impeccable design system (pbakaus/impeccable, Apache-2.0) as the Bee Army's frontend-design operating system: the four-phase loop (Start -> Iterate -> Polish -> 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 proactively for ANY frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture - \"polish the pricing page\", \"build a dashboard\", \"redo this hero\", \"make this not look like AI slop\". Do NOT invoke for backend-only or non-UI tasks, or for product-specific design-system token enforcement - that is design-system-worker-bee / ux-ui-worker-bee." +developer_instructions = "# Impeccable Worker Bee\n\nBefore doing anything else, read `.agents/skills/impeccable-stinger/SKILL.md` in full and follow it as the operating manual.\n\n## Identity & responsibility\n\n`impeccable-worker-bee` is the roster's frontend-design operating system operator. It owns the entire Impeccable system as a closed loop: context contract, 23-command vocabulary, the four-phase design loop (Start -> Iterate -> Polish -> Maintain), the deterministic 59-rule anti-slop detector gate, hooks, live mode, and native playbooks. Every design element and every new page surface stays cohesive, from no design to a well-maintained design, or from a current design to a better design. It is the single router for all frontend UI/UX/design implementation work. It does not own product-specific design-system token enforcement (that is `design-system-worker-bee` / `ux-ui-worker-bee`), and it never vendors or re-implements the Impeccable engine: it operates the installed system.\n\n## Paired Stinger\n\n[`.agents/skills/impeccable-stinger/`](.agents/skills/impeccable-stinger/)\n\nThe Stinger's `SKILL.md` is the master index. Read it in full before any design work, then open the guides and reusable artifacts named by the selected phase.\n\n## Activation contract\n\nActivate proactively when the assigned work touches any of these surfaces:\n\n- Any frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture.\n- Requests such as \"polish the pricing page\", \"build a dashboard\", \"redo this hero\", \"make this not look like AI slop\", \"design a settings screen\", \"audit this UI\", or any task that needs a cohesive visual system.\n- Any task where the user wants to see the design live during development and point at issues before a PR.\n\nDo not activate as the final authority for product-specific design-system token enforcement (route to `design-system-worker-bee` / `ux-ui-worker-bee`), backend/non-UI work, Lighthouse/perf-only audits (route to `quality-worker-bee`), or Security acceptance (route to `security-worker-bee`).\n\n## Procedure\n\n1. **Phase 0 - Pre-flight sync check.** Run `node .agents/skills/impeccable-stinger/scripts/sync-check.mjs`. Exit `0` (current, in sync) -> skip and proceed. Exit `2` (behind upstream and/or content drift) -> `npx impeccable update` (note Codex `/hooks` re-approval to the user), refresh the stinger's guides/templates + `scripts/upstream-manifest.json` for new upstream content, re-run. Exit `1` (not installed) -> global install first (`npx impeccable install --scope=global --providers=codex,claude,cursor`), then per-project `install` + `init` + `document`. Record the result per `templates/sync-report.md`. See `guides/11-sync-check.md`.\n2. **Phase 1 - Start (context + direction).** Ensure the context contract exists (`/impeccable init` -> `PRODUCT.md`; `/impeccable document` -> `DESIGN.md` + `.impeccable/design.json`); read it if present, never re-derive. Classify the job (greenfield / local extension / new surface / expression expansion / redesign / refinement). 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, apply the five tests (Truth, Translation, Consequence, Survival, Fit), and write the direction contract (`THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`) into the artifact per `templates/direction-contract.md`. Visualize when image tooling is available, then build toward the image. See `guides/01-context-contract.md` and `guides/02-start-phase.md`.\n3. **Phase 2 - Iterate (bounded rounds).** Use named commands when the edit has a name (`polish`, `bolder`, `quieter`, `distill`, `typeset`, `layout`, `colorize`, `animate`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `harden`, `onboard`). `/impeccable live` is opt-in, user-invoked only (alpha): never auto-launch it. Bound the loop: build fully, inspect once batched (desktop + mobile), fix in one batch, confirm at most once, stop. The user is the \"happy\" gate. See `guides/03-iterate-phase.md` and `guides/08-live-mode.md`.\n4. **Phase 3 - Polish (pre-ship gauntlet).** Run `/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). Run the deterministic gate: `npx impeccable detect ` (file, dir, or URL; `--json` for CI). Exit code 2 = findings = close-out fails until resolved or waived (narrowest ignore + reason). Hand off to the army close-out: `security-worker-bee` first, then `quality-worker-bee`. See `guides/04-polish-phase.md` and `guides/06-detector-gate.md`.\n5. **Phase 4 - Maintain (cohesion).** `/impeccable extract` (fold repeated patterns into tokens/primitives), `/impeccable document` (re-capture the system when code drifts), `/impeccable doctor` (schema/truth/hook-path/config drift), `npx impeccable check` / `update` (keep the installed system current). Never repair drift as a side effect of a design task. See `guides/05-maintain-phase.md`.\n6. **Install & verify (hybrid scope).** Global skill: `npx impeccable install --scope=global --providers=codex,claude,cursor`. Per project (one-time): `npx impeccable install` writes the hook manifests and `.impeccable/config.json`; `init`/`document` write the context files. Codex requires `/hooks` approval after install/update. Verify with `/impeccable doctor`. See `guides/10-install-and-verify.md`.\n7. **Native surfaces.** 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`.\n\n## Critical directives\n\n- **Never self-grade.** Iterate in bounded rounds; the user is the \"happy\" gate. A separate reviewer (`quality-worker-bee` or a fresh reader) audits the build against its direction contract promise-by-promise. Self-accountability has ground truth, rubrics don't.\n- **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.\n- **The gate is mandatory.** `npx impeccable detect` exit code 2 fails the close-out. Waivers require the narrowest ignore plus a stated reason.\n- **Upstream always in sync.** The pre-flight sync check runs before every task; if current it is skipped, if behind it is updated before any design work. A stale stinger manifest (new upstream commands/reference files) is a real finding: refresh the stinger, never proceed blind.\n- **Never fork or modify the engine.** Call the installed system (`/impeccable`, `npx impeccable`); follow the bee-army-update contract (no upstream script execution during install, preserve the ownership manifest, no silent overwrites).\n- **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.\n- **Single vocabulary.** Never mix Impeccable with other design-taste skills in the same session: two design vocabularies collide and cancel each other out.\n- **License discipline.** Apache-2.0 upstream; build from the repo, not the site (site robots.txt: `ai-train=no, use=reference`). Keep attribution.\n- **Close-out order.** Security before quality, always.\n\n## Escalation\n\nStop and ask one clarifying question when the surface, mode, or product context is genuinely ambiguous: never silently guess. Route unresolved work as follows:\n\n- Product-specific design-system token enforcement -> `design-system-worker-bee` / `ux-ui-worker-bee`.\n- Backend/non-UI logic -> `react-worker-bee`, `preact-worker-bee`, or the relevant domain Bee.\n- Lighthouse/perf-only audits -> `quality-worker-bee`.\n- Security acceptance -> `security-worker-bee` (before quality).\n- Live Mode (alpha) rough edges on uncommon setups -> flag to the user and fall back to named commands.\n- Codex `/hooks` re-approval after an install/update -> surface to the user before proceeding.\n\n## References to skill files\n\nUtilize the Read tool to understand your skills listed at `.agents/skills/impeccable-stinger/` with all of its sub-folders and files. Read `SKILL.md` in full first.\n\n### Master indexes\n\n- `SKILL.md` - the four-phase loop, Phase 0 sync check, core principles, install/verify, native surfaces.\n- `README.md` - folder layout, provenance, license.\n\n### Principles and procedures (guides/)\n\n- `guides/00-principles.md` - the system's non-negotiables (bounded passes, brief wins, no self-grading, single vocabulary, gate mandatory)\n- `guides/01-context-contract.md` - PRODUCT.md / DESIGN.md / surfaces / design.json / four modes\n- `guides/02-start-phase.md` - init, document, job classification, new-work flow, five tests, direction contract, roll, visualize\n- `guides/03-iterate-phase.md` - named commands, bounded-round discipline, live mode opt-in\n- `guides/04-polish-phase.md` - audit / clarify / harden, P0-P3, the deterministic gate, close-out\n- `guides/05-maintain-phase.md` - extract / document / doctor / update, drift rules\n- `guides/06-detector-gate.md` - CLI usage, exit codes, all 59 rules, DESIGN.md awareness, ignores, CI wiring\n- `guides/07-hooks.md` - per-edit + deep pass, harness manifests, approval, the silent-hook failure mode\n- `guides/08-live-mode.md` - opt-in browser iteration (alpha), session flow, Chrome extension\n- `guides/09-native.md` - iOS / Android / adaptive playbooks, per-model harness builds\n- `guides/10-install-and-verify.md` - global skill install + per-project hooks/context, doctor\n- `guides/11-sync-check.md` - pre-flight upstream sync check (skip when current)\n\n### Worked examples (examples/)\n\n- `examples/01-happy-path-new-surface.md` - greenfield -> direction contract -> build -> gate -> maintain\n- `examples/02-edge-case-refinement.md` - refinement with a narrow waiver\n- `examples/03-live-mode-session.md` - opt-in live iteration\n- `examples/04-sync-check.md` - pre-flight sync check (current / behind / drift / not installed)\n\n### Output templates (templates/)\n\n- `templates/direction-contract.md` - THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM\n- `templates/gate-report.md` - detector gate result for the close-out\n- `templates/surface-brief.md` - per-surface mode/job/proof/direction\n- `templates/sync-report.md` - pre-flight sync check result\n\n### Scripts (scripts/)\n\n- `scripts/sync-check.mjs` - the pre-flight sync check runner (exit 0 skip / 2 update / 1 install)\n- `scripts/upstream-manifest.json` - upstream content coverage manifest (commands, reference files, rules)\n\n### Research trail (research/)\n\n- `research/research-summary.md` - depth tier, sources, decisions, handoff\n- `research/index.md` - manifest of all research files\n- `research/01-system-overview.md` through `research/11-license-provenance.md` - primary-source evidence\n\n---\n\n*Created by the Legendary Bee Factory.*\n" diff --git a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/PAIRING-AUDIT.md b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/PAIRING-AUDIT.md index 0672198c..7f43f861 100644 --- a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/PAIRING-AUDIT.md +++ b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/PAIRING-AUDIT.md @@ -4,16 +4,22 @@ Ground truth pulled from the filesystem on 2026-08-14, after the repair pass. Th ## Totals -- Bees (`.claude/agents/*.md`): **75** -- Stinger folders (`.claude/skills/*`): **78** +- Bees (`.claude/agents/*.md`): **76** +- Stinger folders (`.claude/skills/*`): **79** - Orchestrator-level skills with no paired Bee by design: **3** (`beekeeper-suit`, `queen-bee-stinger`, `get-started-stinger`) -- Pairable Stingers: **75** +- Pairable Stingers: **76** ## Pairing integrity Clean. Every Bee has a matching Stinger and every pairable Stinger has a matching Bee, verified in both directions by naming convention. Zero orphans. -Every Bee also has a routing guide at `guides/.md`. 75 Bees, 75 guides, one-to-one. +Every Bee also has a routing guide at `guides/.md`. 76 Bees, 76 guides, one-to-one. + +## New additions + +`impeccable-worker-bee` / `impeccable-stinger` was ported in from a prior fork and registered here: it operates the Impeccable design system (pbakaus/impeccable, Apache-2.0) as the frontend-design operating system. The Impeccable engine is installed per machine via `npx impeccable install --scope=global --providers=codex,claude,cursor`; it is not vendored in this repo. The stinger's pre-flight sync check (`scripts/sync-check.mjs`) verifies the installed engine is current. + +`impeccable-worker-bee` is the single router for frontend UI/UX/design implementation. `design-system-worker-bee` and `ux-ui-svelte-worker-bee` retain product-specific token, component-library, and accessibility enforcement on established systems. ## Path integrity @@ -41,7 +47,7 @@ All routing references to the renamed `deeplake-dataset-worker-bee` were repaire ## Validation -All 78 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 75 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. +All 79 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 76 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. ## Dead reference repair diff --git a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/SKILL.md b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/SKILL.md index c4fb309f..7cd38e4e 100644 --- a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/SKILL.md +++ b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/SKILL.md @@ -28,7 +28,7 @@ Three skills sit above the pairing law because they are orchestrator level, not ## Roster -75 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. +76 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. ### Stack and frameworks @@ -42,7 +42,7 @@ Three skills sit above the pairing law because they are orchestrator level, not | `react-worker-bee` | React 18/19 architecture: bulletproof-react patterns, Server Components, Suspense, Actions, Compiler, state layering | "review React architecture", "state management decision", "Server Components boundary", "React 19 patterns" | `react-stinger` | | `typescript-node-worker-bee` | TypeScript/Node code review and conventions: strict config, module resolution, test suites, boundary validation (body still cites a legacy package's specifics; see PAIRING-AUDIT.md) | "review this TypeScript code", "audit this Node code", "write a Vitest suite", "tighten the tsconfig" | `typescript-node-stinger` | | `python-worker-bee` | Python architecture: Django + Django Ninja + FastAPI + Celery + Channels + pytest + uv, ORM discipline, migrations, typed adoption | "review this Django code", "audit ORM patterns", "migrate DRF to Django Ninja", "set up Celery" | `python-stinger` | -| `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | +| `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract. Impeccable remains the primary router for UI/design implementation | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | | `dark-mode-theming-worker-bee` | Dark-mode theming: CSS variable token architecture, theme-provider wiring, FOWT prevention, SSR hydration safety, Tailwind v4 dark variant | "set up dark mode", "dark mode on SSR", "multi-brand theming", "FOWT fix" | `dark-mode-theming-stinger` | | `modal-toast-dialog-worker-bee` | Accessible overlay primitives: dialog, alert dialog, drawer, toast, command menu; focus trap, escape, scroll lock, aria contract | "choosing between overlay primitives", "debugging focus trap regressions", "building a command palette" | `modal-toast-dialog-stinger` | | `icon-system-worker-bee` | Icon library selection and delivery: tree-shake vs sprite, dynamic-import-by-name, custom SVG components, icon accessibility contract | "choosing an icon library", "bundle-size regressions from icon imports", "icon accessibility" | `icon-system-stinger` | @@ -50,7 +50,8 @@ Three skills sit above the pairing law because they are orchestrator level, not | `font-loading-worker-bee` | Font loading pipeline: font-display strategy, preload/crossorigin correctness, variable-font subsetting, CLS-from-font-swap elimination | "audit font loading", "fix FOIT", "CLS from font swap", "subset variable font" | `font-loading-stinger` | | `markdown-mdx-content-pipeline-worker-bee` | Markdown/MDX pipeline: compiler selection, remark/rehype chains, syntax highlighting, AST manipulation, XSS sanitization | "set up MDX", "configure Shiki", "write a remark plugin", "sanitize user markdown" | `markdown-mdx-content-pipeline-stinger` | | `csv-xlsx-import-export-worker-bee` | Spreadsheet upload and export feature: CSV/XLSX parsing, large-file streaming, column-mapping wizard, row validation, CSV injection prevention | "build a CSV import", "add XLSX upload", "column-mapping wizard", "CSV injection safe" | `csv-xlsx-import-export-stinger` | -| `design-system-worker-bee` | Bootstraps a complete design system from scratch: tokens, utility layer, per-component and per-screen specs, static HTML examples | "build a design system for X", "bootstrap UI for product Y", "create tokens and utilities for this product" | `design-system-stinger` | +| `design-system-worker-bee` | Bootstraps a complete design system from scratch: tokens, utility layer, per-component and per-screen specs, static HTML examples. Impeccable owns frontend UI/UX/design implementation and uses DESIGN.md drift rules plus its detector gate to make enforcement mechanical | "build a design system for X", "bootstrap UI for product Y", "create tokens and utilities for this product" | `design-system-stinger` | +| `impeccable-worker-bee` | Frontend-design operating system for all UI/UX/design implementation, redesign, refinement, new surfaces, components, and design-system capture. Runs Start -> Iterate -> Polish -> Maintain, the context contract, and the deterministic detector gate | "polish the pricing page", "build a dashboard", "redo this hero", "make this not look like AI slop", "design a settings screen", "audit this UI" | `impeccable-stinger` | | `http-rest-fundamentals-worker-bee` | HTTP/REST protocol correctness: method safety and idempotency, status-code honesty, headers, conditional and range requests | "is this status code correct", "why is CORS failing", "explain preflight", "PUT vs PATCH" | `http-rest-fundamentals-stinger` | | `image-optimization-worker-bee` | Image delivery: AVIF/WebP format selection, responsive srcset/sizes, blur placeholders, remote image config, CLI tooling | "optimize my images", "convert to AVIF", "fix layout shift from images", "audit our images" | `image-optimization-stinger` | @@ -208,6 +209,12 @@ Real sequences for this stack. Every sequence below closes with the Ship Gate; i 5. `seo-aeo-worker-bee` for metadata, JSON-LD, and Core Web Vitals. 6. Ship Gate. +### Frontend design / UI implementation + +1. **`impeccable-worker-bee`** is the single router for all frontend UI/UX/design implementation, redesign, refinement, new-surface, component, and design-system-capture work. It runs Start -> Iterate -> Polish -> Maintain, including the pre-flight sync check and deterministic `npx impeccable detect ` gate. +2. **`design-system-worker-bee`** and **`ux-ui-svelte-worker-bee`** own product-specific token, component-library, and accessibility enforcement on established systems. Impeccable makes that enforcement mechanical via DESIGN.md drift rules and the detector gate. +3. **`security-worker-bee`** then **`quality-worker-bee`** close out under the Plan execution loop. + ### Add auth 1. `workos-worker-bee` wires AuthKit, sessions, and SSO. @@ -251,7 +258,7 @@ Don't hand-roll a new Bee. Walk [`../queen-bee-stinger/guides/beekeeper-registra --- -**75 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `../`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. +**76 Bees registered.** Every Bee has a spawnable agent in `.claude/agents/` and a paired Stinger in `../`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. --- diff --git a/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/guides/impeccable-worker-bee.md b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/guides/impeccable-worker-bee.md new file mode 100644 index 00000000..f73b2a6c --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/beekeeper-suit/guides/impeccable-worker-bee.md @@ -0,0 +1,55 @@ +# impeccable-worker-bee + +## Domain +This Bee is the frontend-design operating system operator. It owns the entire Impeccable system (pbakaus/impeccable, Apache-2.0) as a closed loop: the context contract (`PRODUCT.md` + `DESIGN.md` + per-surface briefs + `.impeccable/design.json`), the 23-command vocabulary, the four-phase design loop (Start -> Iterate -> Polish -> Maintain), the deterministic 59-rule anti-slop detector gate, hooks, live mode, and native playbooks. It is the single router for all frontend UI/UX/design implementation work: new surfaces, redesigns, refinements, component work, and design-system capture. It does not fork or modify the upstream Impeccable engine; it operates the pinned portable runtime bundle. + +**Explicit exclusions:** product-specific design-system token enforcement stays with `design-system-worker-bee` / `ux-ui-worker-bee` (this Bee makes that enforcement mechanical via DESIGN.md-drift rules); backend/non-UI work routes to the domain Bee; Lighthouse/perf-only audits stay with `quality-worker-bee`; Security acceptance stays with `security-worker-bee`. + +## Paired Stinger +[impeccable-stinger](../../impeccable-stinger) - the four-phase loop, Phase 0 pre-flight sync check, context contract, detector gate, hooks, live mode, native playbooks, install-and-verify, and the vendored Impeccable engine it operates. + +## Trigger phrases +- "polish the pricing page" +- "build a dashboard" +- "redo this hero" +- "make this not look like AI slop" +- "design a settings screen" +- "audit this UI" +- "keep the design cohesive across new pages" + +Or route proactively when the assigned work touches any frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture, or when the user wants to see the design live during development and point at issues before a PR. + +## Do NOT route when +- The request is product-specific design-system token enforcement, component-library wrapping, or accessibility compliance on an established system: that belongs to `design-system-worker-bee` / `ux-ui-worker-bee`. +- The request is backend-only or non-UI logic: that belongs to `react-worker-bee`, `preact-worker-bee`, or the relevant domain Bee. +- The request is a Lighthouse/perf-only audit: that belongs to `quality-worker-bee`. +- The request is Security acceptance: that belongs to `security-worker-bee` (always before quality). + +If a request straddles two Bees' domains, prefer the narrower-scoped Bee and let the broader one act as backup. + +## Inputs the Bee needs +- The design task: a surface or route to design/redesign/refine, a plain-English request, or a named command intent. +- Repo root and target surface(s); the surface's mode (Persuade / Operate / Read / Experience) or enough context to infer it from the surface, not the product. +- Existing context files if present: `PRODUCT.md`, `DESIGN.md`, `.impeccable/design.json`, `.impeccable/surfaces/*.md`, `.impeccable/config.json`. +- Environment: Node >= 22.18; Impeccable installed per project (`npx impeccable install`) or `npx` network access; hooks approved in Codex (`/hooks`) where applicable. +- Optional: brand kit, anti-references, screenshots, incumbent visual truth (tokens, theme, CSS, components, assets). + +## Outputs +- **Context contract files** - `PRODUCT.md`, `DESIGN.md` (Stitch format), `.impeccable/design.json`, `.impeccable/surfaces/*.md`, owned and kept current by this Bee. +- **Implemented UI** - source changes to the target surface(s), with the direction contract comment block (`THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`) at the top of new artifacts. +- **Detector evidence** - a gate result (0 findings, or resolved findings, or explicit waivers with reasons) attached to the close-out. +- **Design-system updates** - `extract` / `document` outputs that keep the system current. +- **Close-out handoff** - security -> quality verification result, then a summary to the user with what changed and what remains open. + +## Commonly sequenced with +- Plan execution loop: `impeccable-worker-bee` is the implementation Bee for frontend UI/UX/design work; it hands the final implemented state to `security-worker-bee`, reruns affected checks after security fixes, and only then hands it to `quality-worker-bee`. +- Design-system enforcement: `design-system-worker-bee` / `ux-ui-worker-bee` own product-specific token enforcement; `impeccable-worker-bee` makes it mechanical via the DESIGN.md-drift rules and the detector gate. + +## Critical directives the orchestrator should respect +- **Phase 0 pre-flight sync check first** - run `node .claude/skills/impeccable-stinger/scripts/sync-check.mjs` before any design work; skip when current (exit 0), update when behind (exit 2), global-install first when not installed (exit 1). +- **Never self-grade** - the Bee iterates in bounded rounds; 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. +- **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. +- **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 ` runs before any completion claim; exit code 2 fails the close-out until findings are resolved or explicitly waived (narrowest ignore + reason). +- **Never fork or modify the engine** - call the installed system (`/impeccable`, `npx impeccable`); follow the bee-army-update contract (no upstream script execution during install, preserve the ownership manifest, no silent overwrites). +- **Close-out order** - Security before quality, always. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/README.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/README.md new file mode 100644 index 00000000..466a380d --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/README.md @@ -0,0 +1,9 @@ +# impeccable-stinger + +The paired Stinger for `impeccable-worker-bee`: the Bee Army's frontend-design operating system operator. It encodes the entire Impeccable system (pbakaus/impeccable, Apache-2.0) as a four-phase loop — **Start → Iterate → Polish → Maintain** — with the deterministic 59-rule anti-slop detector gate as a mandatory close-out step. + +- Command Brief: `.claude/commands/impeccable-worker-bee-command-brief.md` +- Research: `research/research-summary.md` (repo-primary, commit `aee6ce9`, 2026-08-04) +- License: Apache-2.0 (upstream); this stinger is guidance + procedure, never vendored engine code. + +- Bee: `.claude/agents/impeccable-worker-bee.md` (agent file: `.claude/agents/impeccable-worker-bee.toml`) diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/SKILL.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/SKILL.md new file mode 100644 index 00000000..5ac690fd --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/SKILL.md @@ -0,0 +1,94 @@ +--- +name: "impeccable-stinger" +description: "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-stinger)." +license: Apache-2.0 (upstream impeccable) +--- + +# 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 ` 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 ../impeccable-stinger/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 ` (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 `../impeccable-stinger/` 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) diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md new file mode 100644 index 00000000..c8780789 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md @@ -0,0 +1,3 @@ +# Third-party notices + +The Impeccable Stinger documents and operates the Apache-2.0 Impeccable runtime from [pbakaus/impeccable](https://github.com/pbakaus/impeccable), version 4.0.4. It retains that attribution and is distributed as part of the Bee Army only as a reusable operating guide and portable runtime companion. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/01-happy-path-new-surface.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/01-happy-path-new-surface.md new file mode 100644 index 00000000..9cf54de6 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/01-happy-path-new-surface.md @@ -0,0 +1,13 @@ +# Example 01 — Happy Path: New Surface (greenfield → shipped → maintained) + +Demonstrates: `guides/01-context-contract.md`, `guides/02-start-phase.md`, `guides/04-polish-phase.md`, `guides/05-maintain-phase.md`. + +**Task:** "Build a pricing page for a developer tool that traces every alert back to the deploy that caused it." + +1. **Start — context.** No `PRODUCT.md` → `/impeccable init` (platform: web; users: SREs on call, reading fast, often in the dark; positioning: traces every alert back to the deploy that caused it; evidence: real incident timelines, no customer logos yet). No `DESIGN.md` → `/impeccable document` (extracts tokens from the existing app, writes Stitch-format `DESIGN.md` + `design.json`). +2. **Start — classification.** New surface inside an established world → composition open, world inherited. Mode: **Persuade** (a pricing page earns attention and action). +3. **Start — direction.** Derive a grounded shortlist (incident timeline, postmortem doc, terminal session, man page, pager timeline). Roll assigns index 3 (terminal session) and deals challengers from the worlds deck. Five tests: Truth (the terminal relationship exists in the product) ✓, Translation (strip names → a product-native relationship remains) ✓, Consequence (removing the terminal frame weakens the page) ✓, Survival (works on mobile within budget) ✓, Fit (honest tradeoff) ✓. Write the direction contract into the artifact (see `templates/direction-contract.md`), keep the seed key. +4. **Build.** Code toward the committed world. Craft floor: contrast >= 4.5:1, body measure 65-75ch, one authored motion moment, real states (hover/disabled/loading/error/empty), themed browser surfaces (selection, focus rings, scrollbars). No side-tab borders, no gradient text, no hero eyebrow, no Inter-as-display. +5. **Iterate.** One batched inspection round (desktop + mobile): fix overflow on the pricing table, tighten heading rhythm, replace one hardcoded hex with a token. One fix batch. One confirmation round. Stop. +6. **Polish.** `/impeccable audit` (a11y 4, perf 3, theming 4, responsive 3, anti-patterns 4; one P2: touch target on the plan toggle → fixed). `/impeccable clarify` (CTA copy tuned to SREs). `/impeccable harden` (60-char org names, prices in the billions, 500s). Gate: `npx impeccable detect src/` → 0 findings. Hand off to `security-worker-bee` → `quality-worker-bee`. +7. **Maintain.** `/impeccable extract` (the plan-toggle pattern appears 3x → token + primitive). `/impeccable document` (re-capture `DESIGN.md`). `/impeccable doctor` → clean. The next surface inherits the world. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/02-edge-case-refinement.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/02-edge-case-refinement.md new file mode 100644 index 00000000..e49cf512 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/02-edge-case-refinement.md @@ -0,0 +1,17 @@ +# Example 02 — Edge Case: Refinement with a Waiver + +Demonstrates: `guides/03-iterate-phase.md`, `guides/04-polish-phase.md`, `guides/06-detector-gate.md`. + +**Task:** "Polish the settings screen. Keep our sharp corners and sober palette. Remove the AI tells." + +1. **Context.** `PRODUCT.md` + `DESIGN.md` exist and are current. Mode: **Operate** (settings = task completion; scanability outranks expression). +2. **Classification.** Refinement — better, not different. No new-work flow, no roll, no direction contract. The incumbent world is preserved. +3. **Iterate.** `/impeccable polish settings` — targeted fixes: 3 off-grid elements aligned; h1 kerning tightened; one hardcoded hex → `--color-accent`; missing hover state on FAQ items; modal entrance softened to 220ms ease-out-quart; stray "Lorem" removed. One batched round, one fix batch, one confirmation. Stop. +4. **Polish.** `/impeccable audit settings` (P1: gray-on-color on the danger zone → tint from the hue instead). `/impeccable harden settings` (long German labels, offline state). Gate: `npx impeccable detect src/settings` → 1 finding: `overused-font` flags the brand font (a real brand commitment, not a default). +5. **Waiver (narrowest form, with reason):** + ```bash + npx impeccable ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md" + ``` + Re-run the gate → 0 findings. The waiver is recorded in `.impeccable/config.json` and shared with the hook. +6. **Close-out.** Hand off to `security-worker-bee` → `quality-worker-bee`. Gate result travels with the close-out (see `templates/gate-report.md`). +7. **Maintain.** No drift introduced; `doctor` clean. Nothing to extract. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/03-live-mode-session.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/03-live-mode-session.md new file mode 100644 index 00000000..c1069b73 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/03-live-mode-session.md @@ -0,0 +1,13 @@ +# Example 03 — Live Mode Session (opt-in, user-invoked) + +Demonstrates: `guides/08-live-mode.md`, `guides/07-hooks.md`. + +**Task:** "Show me the hero live — something's off but I can't name it." + +1. **Opt-in.** The user asked; the Bee launches live mode. Never auto-launched. +2. **Setup.** Dev server confirmed running (localhost:3000). `/impeccable live` — picker injected into the app. +3. **Iterate.** User picks the hero headline, types "make it feel more editorial". Three variants hot-swapped via HMR. User accepts variant 2 → written to source (manual edits captured via `live-commit-manual-edits.mjs`). +4. **Gate.** `npx impeccable detect src/` on the accepted result → 0 findings. The per-edit hook stays quiet on clean edits (non-intrusive by design). +5. **Close-out.** Hand off to `security-worker-bee` → `quality-worker-bee`. + +**Note:** during normal development the user gets live feedback from the **per-edit hook** (findings pushed back after each UI edit, quiet when clean) — that is the non-nuisance live feedback. Live mode is the on-demand visual iteration tool. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/04-sync-check.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/04-sync-check.md new file mode 100644 index 00000000..30b327e2 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/examples/04-sync-check.md @@ -0,0 +1,10 @@ +# Example 04 — Pre-Flight Sync Check + +Demonstrates: `guides/11-sync-check.md`. + +**Task:** "Polish the billing settings page." + +1. **Pre-flight.** `node .../impeccable-stinger/scripts/sync-check.mjs` → `[sync-check] CURRENT: upstream in sync, stinger coverage matches. Skipping update.` (exit 0). Skipped; task proceeds. +2. **Later run (behind).** The check reports `BEHIND: installed 4.0.3 < published 4.0.4` and `NEW COMMANDS upstream: ` (exit 2). The Bee runs `npx impeccable update`, notes the Codex `/hooks` re-approval to the user, re-runs the check → exit 0 → proceeds. +3. **Content drift.** The check reports `NEW REFERENCE FILES upstream: typeset.native.md` (exit 2). The Bee adds a guide/template covering the new playbook, bumps `scripts/upstream-manifest.json`, re-runs → exit 0 → proceeds. +4. **Not installed.** The check reports `NOT INSTALLED` (exit 1). The Bee runs the global install, then per-project `install` + `init` + `document`, re-runs → exit 0 → proceeds. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/00-principles.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/00-principles.md new file mode 100644 index 00000000..26edaa7e --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/00-principles.md @@ -0,0 +1,14 @@ +# 00 — Principles (non-negotiables) + +Derived from `research/01-system-overview.md` and `research/05-craft-floor.md`. + +1. **The brief wins.** Pinned aesthetics, eras, materials, fonts, and palettes override saturated-pattern warnings. Redirecting a clear brief toward your taste is failure. (research/01, SKILL.src.md) +2. **Refinement preserves; redesign replaces.** Refinement keeps incumbent identity, behavior, copy, and everything outside scope. Redesign keeps product truth, content, function, and constraints but treats the old look as evidence and anti-reference. Never split the difference. (research/01) +3. **Bounded passes.** Build fully → inspect once batched (desktop + mobile) → fix in one batch → confirm at most once → stop. Open-ended self-QA is waste. (research/01) +4. **Never self-grade.** The user is the "happy" gate. A fresh reviewer audits the build against its direction contract promise-by-promise. (research/04, lesson 7) +5. **Context contract is source of truth.** Read `PRODUCT.md` + `DESIGN.md` + surface brief before every command. Mode comes from the surface, not the product. Missing `DESIGN.md` ≠ greenfield. (research/02) +6. **Single vocabulary.** One design system per session. Mixing Impeccable with other design-taste skills cancels both out. (research/01, /designing) +7. **The gate is mandatory.** `npx impeccable detect` exit code 2 fails the close-out. Waivers need the narrowest ignore + a stated reason. (research/06) +8. **Never fork or modify the engine.** Call the installed system; follow the bee-army-update contract (no upstream script execution during install, preserve ownership manifest, no silent overwrites). (research/11) +9. **License discipline.** Apache-2.0 upstream; build from the repo, not the site (site robots.txt: `ai-train=no, use=reference`). Keep attribution. (research/11) +10. **Close-out order.** Security before quality, always. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/01-context-contract.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/01-context-contract.md new file mode 100644 index 00000000..9021f405 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/01-context-contract.md @@ -0,0 +1,30 @@ +# 01 — Context Contract + +Derived from `research/02-context-contract.md`. + +## Files the Bee owns per project + +| File | Role | Written by | +|---|---|---| +| `PRODUCT.md` | Strategy: platform, users, purpose, positioning, evidence, brand commitments | `/impeccable init` | +| `DESIGN.md` | Visual system: colors, type, components, radii, elevation, rules (Google Stitch format) | `/impeccable document` | +| `.impeccable/surfaces/*.md` | Per-surface: mode, job, proof sequence, chosen direction | The work itself | +| `.impeccable/design.json` | Structured sidecar for detector/hooks/Live Mode | `document` (do not hand-edit) | + +## Modes (from the surface, not the product) + +- **Persuade** — visitor decides and acts (landing, marketing, pricing). Design is the product; earn attention. +- **Operate** — visitor completes a task (app UI, dashboards, admin, tools). Scanability outranks expression. +- **Read** — visitor understands (docs, guides, help). Comprehension first. +- **Experience** — visitor is inside the work (portfolios, galleries). Artifact leads, interface recedes. + +A tool's landing page is still Persuade; a fashion house's docs are still Read. Name the mode explicitly only when genuinely ambiguous; persist it in the surface brief. + +## Rules + +- Every command reads the contract first. Never re-derive what is recorded. +- `init` scans the codebase, forms its own read, asks only what it could not work out. It does not ask about colors/type — those are decided with the surface. +- `document` auto-extracts colors, typography, spacing, radii, components, then confirms descriptive language; writes Stitch-format `DESIGN.md`. +- Missing `DESIGN.md` does not make a project greenfield: coherent code, type choices, and component behavior are authority. Scaffolds and framework defaults are not. +- If implementation is coherent but undocumented: extract invariants, confirm with the user, write `DESIGN.md` before going further. +- `context.mjs` may emit a `CONTEXT_STALE` directive — report it, do not act on it unless the user asks (except `auto` findings). diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/02-start-phase.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/02-start-phase.md new file mode 100644 index 00000000..a83d5663 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/02-start-phase.md @@ -0,0 +1,39 @@ +# 02 — Start Phase (context + direction) + +Derived from `research/02-context-contract.md`, `research/03-command-vocabulary.md`, `research/04-new-work-direction.md`. + +## 1. Ensure context + +- No `PRODUCT.md` → run `/impeccable init` (discovery interview; writes `PRODUCT.md`; offers `DESIGN.md` when code exists). +- No `DESIGN.md` → run `/impeccable document` (Stitch format + `.impeccable/design.json`). +- Files exist → read them; do not re-interview. + +## 2. Classify the job + +- **Greenfield** — no coherent visual implementation; a world gets established. +- **Local extension** — a section/component inside a working page; only the new part is decided; the page's world is inherited. +- **New surface** — a whole page/flow inside an established world; composition open, world not. +- **Expression expansion** — an established brand entering a surface family it never resolved; approve a range, merge into `DESIGN.md`. +- **Redesign or rebrand** — the look is replaced; product facts, content, function, constraints are not. +- **Refinement** — better, not different; leave this flow for a scoped command like `polish`. + +"Redesign this page" = replacement (old look becomes anti-reference). "Redesign within our current system" = extension. Ask once when genuinely ambiguous; never split the difference. + +## 3. New-work flow (new surfaces + redesigns) + +1. Derive a grounded shortlist of candidate directions from the product's world (audience, evidence, cultural material). +2. **Roll** (`node /scripts/concept-seed.mjs` or the installed skill's script): assign which candidate is built; deal challengers from the worlds deck. The dice refuse the argmax rut; they never touch an ungrounded idea. +3. Apply the **five tests** to every candidate — fail one, it dies: + - **Truth** — every relationship it visualizes exists in your product. + - **Translation** — strip the source's names/materials and a product-native relationship remains (else it is a costume). + - **Consequence** — removing its best move materially weakens the page. + - **Survival** — the signature works on the primary device within a real asset/time budget. + - **Fit** — its risk is an honest tradeoff, not a probable brief violation. +4. Write the **direction contract** into the artifact (see `templates/direction-contract.md`): `THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`, <=150 words, five blocks. Keep the seed key for reproduction. +5. **Visualize** when image tooling is available: system board + first-surface mock, then build toward the image. If no native image tool, set `OPENAI_API_KEY` and render via gpt-image-2 (say so first — it spends the user's credit, ~5-25 cents each). + +## Re-roll rules + +- The user re-rolls freely, for any reason including taste. After two in a row, ask what quality is missing. +- The agent may only re-roll on named factual grounds (the assigned direction cannot carry the product's truth or the task). Its own taste is never grounds. +- In an unattended run, the assigned direction proceeds and assumptions are stated explicitly. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/03-iterate-phase.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/03-iterate-phase.md new file mode 100644 index 00000000..c8354f25 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/03-iterate-phase.md @@ -0,0 +1,33 @@ +# 03 — Iterate Phase (bounded rounds) + +Derived from `research/03-command-vocabulary.md`, `research/08-live-mode.md`. + +## Named commands (when the edit has a name) + +- **Refine:** `polish` (final pass), `bolder` / `quieter` (voice), `distill` (subtraction), `typeset` (type hierarchy), `layout` (spacing/rhythm), `colorize` (strategic color), `animate` (purposeful motion), `delight` (personality), `overdrive` (past conventional limits). +- **Fix:** `clarify` (UX copy), `adapt` (devices/contexts), `optimize` (performance). +- **Harden:** `harden` (edge cases, i18n, errors, overflow), `onboard` (first-run, empty states). +- **Evaluate:** `critique` (design review with scoring, persona tests, automated detection). + +## Bounded-round discipline + +1. Build fully. +2. Inspect once in a batched round — desktop and mobile together, one render. +3. Fix everything the round shows in one batch. +4. Confirm with at most one more round. +5. Stop. Hand to the user for approval. The user is the "happy" gate. + +## Live Mode (opt-in, user-invoked only) + +- `/impeccable live` drops a picker on the running dev server: point at an element, type/draw a change, get 3 production-quality variants hot-swapped via HMR; accept one and it writes to source. +- **Never auto-launch it.** Launch only when the user asks to iterate visually ("show me live", "let me point at it"). +- Status: **alpha** — expect rough edges on uncommon setups. Prefer named commands for the default path. +- The non-intrusive live feedback during development is the **per-edit hook** (see `guides/07-hooks.md`), not live mode. + +## When to reach for which + +- Fix something "off" you can't name → `live` (user-invoked) or `critique`. +- Apply a specific discipline → `typeset` / `layout` / `colorize` / `animate`. +- Explore three directions side by side → `live` (user-invoked). +- Ask "is this any good?" → `critique`. +- Bring a safe design to life / tone a shouting one down → `bolder` / `quieter`. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/04-polish-phase.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/04-polish-phase.md new file mode 100644 index 00000000..c6ead01a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/04-polish-phase.md @@ -0,0 +1,22 @@ +# 04 — Polish Phase (pre-ship gauntlet) + +Derived from `research/03-command-vocabulary.md`, `research/06-detector-rules.md`. + +## The three commands before anything ships + +1. **`/impeccable audit `** — 5 dimensions scored 0-4: accessibility, performance, theming, responsive, anti-patterns. Findings tagged P0-P3. Point at a narrow target: one section reviewed closely beats a whole page at a glance. Native projects route to the native pass (VoiceOver, TalkBack, touch targets, platform conformance). +2. **`/impeccable clarify `** — rewrite the copy: labels, error messages, empty-state prose, microcopy, tuned to the audience from `PRODUCT.md`. +3. **`/impeccable harden `** — stress-test reality: 60-character names, German product titles, prices in the billions, 500s, offline. Production data is messy. + +## The deterministic gate (mandatory) + +- `npx impeccable detect ` — file, dir, or URL. Plain output groups by file with rule id, snippet, explanation; `--json` for scripts/CI. +- **Exit codes:** 0 = no findings; 2 = findings; 1 = command failed. CI fails the job on 2. +- DESIGN.md-aware: with a local `DESIGN.md`, enables design-system checks (fonts, literal colors, radii, font sizes). `--no-design-system` disables; `--scope type|layout` narrows. +- **Waivers:** narrowest form only — `npx impeccable ignores add-value --reason "..."`, `add-file `, or inline `impeccable-disable` comments in the file. A waiver without a reason is a failure. +- See `guides/06-detector-gate.md` for the full rule list and CI wiring. + +## Close-out + +- Findings resolved or explicitly waived → hand off to `security-worker-bee` first, then `quality-worker-bee`. Never quality before security. +- The gate result travels with the close-out (see `templates/gate-report.md`). diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/05-maintain-phase.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/05-maintain-phase.md new file mode 100644 index 00000000..24f2c88e --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/05-maintain-phase.md @@ -0,0 +1,22 @@ +# 05 — Maintain Phase (cohesion) + +Derived from `research/09-maintenance-doctor.md`. + +## The two commands that close the gap + +1. **`/impeccable extract `** — find patterns used 3+ times with the same intent; propose tokens and primitives; consolidate drift before it solidifies. +2. **`/impeccable document`** — re-capture the system: scans tokens, components, and rendered routes, writes `DESIGN.md` in Stitch format. The more it points at real components and live routes, the closer it reads your design language. + +## Doctor (three kinds of "out of date") + +- **Tool version** — installed skill older than published; `npx impeccable update` fixes. +- **Schema drift** — artifact written by an older Impeccable; mechanical, doctor repairs most of it. +- **Truth drift** — code moved on and the document no longer describes it; route to `init`/`document`, never auto-repair. + +`/impeccable doctor` also checks: config unknown keys, ignored rule ids that no longer exist, ignored file paths that are gone, `projectRoots` globs matching nothing, hook script paths that stopped resolving, orphaned surface briefs, and monorepo apps inheriting a web-only root record while carrying native build files. + +## Rules + +- **Never repair drift as a side effect of a design task.** A `CONTEXT_STALE` finding is reported, not acted on, unless the user asks (except `auto` findings). +- Run `npx impeccable check` / `update` on a cadence; the installed side self-updates, the stinger's vendored reference needs a manual refresh cadence. +- Every new element or surface inherits the established world unless the classification says greenfield; the detector's design-system rules mechanically flag drift. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/06-detector-gate.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/06-detector-gate.md new file mode 100644 index 00000000..06c914f9 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/06-detector-gate.md @@ -0,0 +1,46 @@ +# 06 — Detector Gate (59 deterministic rules) + +Derived from `research/06-detector-rules.md`. + +## CLI usage + +```bash +npx impeccable detect src/ # scan a directory +npx impeccable detect src/components/Card.tsx # one file +npx impeccable detect https://example.com # rendered page (browser engine) +npx impeccable detect --json src/ # machine-readable +npx impeccable detect --scope type src/ # one design domain +npx impeccable detect --no-design-system src/ # raw scan +``` + +- **Exit codes:** 0 = no findings; 2 = findings detected; 1 = command failed. CI fails the job on 2. +- Engines: static-html (files + linked CSS), browser (URLs), regex/text (JSX/TSX/Vue/Svelte/Astro/CSS-in-JS). Server-side templates (Blade/ERB/Twig/Handlebars) need `detector.extensions` in `.impeccable/config.json`. +- Web only. Native projects route to `/impeccable audit` (native pass). + +## The 59 rules (id | category | severity) + +**slop (30):** side-tab, border-accent-on-rounded, overused-font, flat-type-hierarchy (error), gradient-text (error), ai-color-palette, cream-palette, nested-cards, monotonous-spacing, bounce-easing, pulsing-dot, blinking-cursor, shape-assembled-illustration, dark-glow, radial-halo, radial-spotlight-glow, marquee, icon-tile-stack, italic-serif-display, hero-eyebrow-chip, kicker-above-heading, numbered-section-labels, em-dash-overuse, marketing-buzzword, aphoristic-cadence, oversized-h1, extreme-negative-tracking, gpt-thin-border-wide-shadow, repeating-stripes-gradient, codex-grid-background, theater-slop-phrase, image-hover-transform. + +**quality (29):** broken-image, script-error, content-hidden-at-rest, edge-flush-cards, text-occlusion, first-viewport-column-overflow, gray-on-color, low-contrast, layout-transition, line-length, cramped-padding, body-text-viewport-edge, tight-leading, skipped-heading, heading-rhythm, justified-text, tiny-text, undersized-ui-text, all-caps-body, wide-tracking, text-overflow, repeated-container-text, clipped-overflow-container, design-system-font, design-system-color, design-system-radius, design-system-font-size. + +Severities: `error` (flat-type-hierarchy, gradient-text), `warning` (most), `advisory` (side-tab, overused-font, ai-color-palette, cream-palette, nested-cards, etc.). + +## DESIGN.md awareness + +With a local `DESIGN.md`, the detector enables the 4 design-system rules (font, color, radius, font-size outside the documented system) using `.impeccable/design.json` for richer token/ramp data. This is what makes product-token enforcement mechanical — it complements `design-system-stinger`/`ux-ui-stinger`. + +## Ignores & waivers + +- `npx impeccable ignores list|add-value|add-file|add-rule|remove-value`; `--local` for private; `--reason` for the why. +- Value ignores preferred for fonts/colors/radii/motion (keeps the rule useful elsewhere); wildcard value ignores only when scoped to a file. +- Inline comments travel with a file: ``, `impeccable-disable-line`, `impeccable-disable-next-line`. +- A waiver without a stated reason is a failure. The narrowest exception that matches the real reason is the only correct one. + +## CI wiring + +```bash +npx impeccable detect --json src/ > .impeccable/detect.json +# exit code 2 → fail the PR check; parse JSON for the findings list +``` + +Add to army projects' PR checks per the user decision (2026-08-06). diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/07-hooks.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/07-hooks.md new file mode 100644 index 00000000..939c3051 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/07-hooks.md @@ -0,0 +1,37 @@ +# 07 — Hooks (per-edit + deep pass) + +Derived from `research/07-hooks-enforcement.md`. + +## What the hook does + +- Scans direct edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). +- **Claude Code / GitHub Copilot / Codex:** post-tool-use — pushes a short system reminder after the edit; findings get a correction prompt, pending issues get a re-nudge, clean files get a short ack (unless `hook.quiet`). +- **Cursor:** `preToolUse` — blocks bad proposed writes before they land; silent when clean. +- Plain `.ts`/`.js` files are scanned but stay quiet unless the detector finds something. + +## Two speeds + +- **Per edit:** only what is objectively broken or compounds if ignored (broken images, overflow/clipped text, contrast failures, tiny text, gradient text, glow, DESIGN.md drift). +- **End of session (deep pass):** the full rule set across every UI file touched, minus what was already reported; a second stop is silent. Wired for Claude Code and Codex (native Stop hook); Cursor and Copilot keep the full detector per edit. +- `hook.perEditRules: "all"` restores full rules per edit (not recommended — it makes models more conservative). + +## Harness manifests & approval + +| Harness | Manifest | Notes | +|---|---|---| +| Claude Code | `.claude/settings.local.json` | gitignored, machine-local | +| GitHub Copilot | `.github/hooks/impeccable.json` | committed, team-shared | +| Codex | `.codex/hooks.json` | **requires `/hooks` approval after install/update** | +| Cursor | `.cursor/hooks.json` | confirm enabled in Settings → Hooks | +| Grok Build | `.grok/hooks/impeccable.json` | requires `/hooks-trust` or `--trust` | + +- Installer: `npx impeccable install|update`; `--no-hooks` skips; `--force` backs up malformed manifests as `.bak`. +- Config: `hook.enabled`, `hook.quiet`, `hook.auditLog` in `.impeccable/config.json`; consent in `.impeccable/config.local.json`. Env: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, `IMPECCABLE_HOOK_LOG`. + +## The failure mode to watch + +"A hook can look installed and scan nothing: if its script path stops resolving... the manifest still registers and no findings ever arrive. Silence reads as a clean codebase." `/impeccable doctor` checks for exactly this. Treat hook silence as suspicious, not as a clean pass. + +## Why this matters for the Bee + +Hooks are the "every time" enforcement: they fire on every UI edit regardless of routing discipline. They are the non-intrusive live feedback during development — the user sees findings as code is written, without live mode being a nuisance. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/08-live-mode.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/08-live-mode.md new file mode 100644 index 00000000..518bbf75 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/08-live-mode.md @@ -0,0 +1,28 @@ +# 08 — Live Mode (opt-in browser iteration, alpha) + +Derived from `research/08-live-mode.md`. + +## What it is + +`/impeccable live` drops a picker onto the running dev server. The user points at any element, draws or types what they want, and gets **three production-quality variants** hot-swapped via HMR. Accepting one writes it back to source. + +- Requires a running dev server (localhost). +- **Status: alpha** — works end-to-end, but needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups. + +## When to use (user decision 2026-08-06) + +- **Opt-in, user-invoked only.** Never auto-launch it. The Bee launches it only when the user asks to iterate visually ("show me live", "let me point at it", "I want to see it in the browser"). +- Use it when: the user can't name what's off; they want to explore three directions side by side; they want to see the design live as code changes and point at issues before a PR. +- The default loop stays: named commands + bounded rounds + detector gate. + +## Session flow + +1. Confirm a dev server is running; start one if needed. +2. Launch `/impeccable live`; the picker is injected into the app. +3. User picks an element or steers the whole page; the Bee generates 3 variants. +4. User accepts one → it writes to source (manual edits are captured and committed via `live-commit-manual-edits.mjs`). +5. Run the detector gate on the accepted result before close-out. + +## Companion: Chrome extension + +The detector overlay runs on any live page (staging, competitor) — useful for review without touching the editor. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/09-native.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/09-native.md new file mode 100644 index 00000000..3124a86e --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/09-native.md @@ -0,0 +1,24 @@ +# 09 — Native Surfaces (iOS / Android / adaptive) + +Derived from `research/10-native-platforms-harnesses.md`. + +## Rules + +- The detector is **web only** — it reads HTML and CSS. It has nothing to say about a native iOS/Android codebase. +- When `PRODUCT.md` declares `ios`, `android`, or `adaptive`: + - `/impeccable audit` runs the **native pass** (`audit.native.md`): VoiceOver, TalkBack, touch targets, platform conformance. + - `adapt` has a native variant (`adapt.native.md`). + - Per-platform rulebooks: `ios.md`, `android.md`. +- `init` detects the platform from codebase evidence and asks only when ambiguous; the platform is recorded in `PRODUCT.md`. + +## Harness builds (per-model tuning) + +- `npx impeccable install` auto-detects the harness and writes the right skill files (`.claude/skills/`, `.cursor/skills/`, `.codex/`, `.gemini/`, `.grok/`, etc.) plus provider-native hook manifests. +- Per-model rule tuning: the Gemini build kills image-on-hover motion; the Codex build refuses ghost-cards and over-rounding. The installed build may carry extra rules for the active model — expect that. +- `npx skills add pbakaus/impeccable` installs one shared build (functionally complete, not tailored). +- Claude Code plugin: `/plugin marketplace add pbakaus/impeccable`. GitHub Copilot: built in (Settings → Experimental). + +## Bee behavior + +- Default domain is web. Native surfaces route to the native playbooks and the native audit pass. +- The stinger is complete for any build: web, iOS, Android, adaptive (user decision 2026-08-06). diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/10-install-and-verify.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/10-install-and-verify.md new file mode 100644 index 00000000..3e527ebd --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/10-install-and-verify.md @@ -0,0 +1,42 @@ +# 10 — Install & Verify (hybrid scope) + +Derived from `research/07-hooks-enforcement.md`, `research/09-maintenance-doctor.md`, `research/10-native-platforms-harnesses.md`, `research/11-license-provenance.md`. + +## Global skill install (once per machine) + +```bash +npx impeccable install --scope=global --providers=codex,claude,cursor +``` + +- Makes `/impeccable` available in every army project (user decision 2026-08-06: global, not per-project, because the army works across many projects). +- Reload the harness afterward; `/impeccable` should appear in autocomplete. + +## Per-project setup (one-time, cheap) + +```bash +npx impeccable install # writes hook manifests + .impeccable/config.json +/impeccable init # writes PRODUCT.md +/impeccable document # writes DESIGN.md + .impeccable/design.json +``` + +- Hooks are **project-local by harness design** (`.codex/hooks.json`, `.claude/settings.json`, `.cursor/hooks.json`) — they cannot be global. Codex requires `/hooks` approval after install/update. +- Context files (`PRODUCT.md`, `DESIGN.md`, `.impeccable/`) are inherently per-project. + +## Verify + +- `/impeccable doctor` — checks schema drift, truth drift, broken hook paths, stale config, orphaned surface briefs, monorepo platform mismatches. +- A hook that looks installed but scans nothing is the failure you would never notice — doctor catches it. +- `npx impeccable check` / `update` — keep the installed system current. + +## CI gate (user decision 2026-08-06) + +```bash +npx impeccable detect --json src/ > .impeccable/detect.json # exit 2 fails the PR check +``` + +Add to army projects' PR checks. + +## Compliance + +- Build the stinger from the repo (Apache-2.0), not the site (robots.txt: `ai-train=no, use=reference`). Keep attribution. +- Never fork or modify the engine into the stinger; call the installed system. Follow the bee-army-update contract. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/11-sync-check.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/11-sync-check.md new file mode 100644 index 00000000..72b8c9e4 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/guides/11-sync-check.md @@ -0,0 +1,43 @@ +# 11 — Pre-Flight Sync Check (upstream always in sync) + +Derived from `research/09-maintenance-doctor.md`, `research/11-license-provenance.md`, and the user decision (2026-08-06): "make sure the upstream is always in sync before a task is done. If it is current it is skipped." + +## The mechanism + +Before any design task starts, run the stinger's sync check: + +```bash +node .claude/skills/impeccable-stinger/scripts/sync-check.mjs +``` + +**Exit codes:** +- `0` — current and in sync → **skip**, proceed with the task. +- `2` — behind upstream and/or content drift → update/refresh before the task (see below). +- `1` — not installed or check failed → install first. + +## What it verifies + +1. **Installed skill present** — searches the harness skill dirs (`~/.agents/skills/impeccable`, `~/.codex/skills/impeccable`, `~/.claude/skills/impeccable`, `~/.claude/skills/impeccable`, and project-local equivalents). Codex's primary skill dir is `.agents/skills/`. +2. **Version currency** — reads the installed `SKILL.md` frontmatter `version:` and compares it to the published version at `https://impeccable.style/api/version` (same endpoint the skill's own `context.mjs` uses). Behind → `npx impeccable update`. +3. **Content coverage** — compares the installed skill's `reference/` files and `scripts/command-metadata.json` commands against the stinger's `scripts/upstream-manifest.json` (forged against upstream 4.0.4 / commit `aee6ce9`). New commands or reference files upstream → the stinger needs a refresh (new guide/template), not just an update. + +## When behind (exit 2) + +1. Run `npx impeccable update` (or `node .../sync-check.mjs --update`). **Note:** Codex may require `/hooks` re-approval after an update — tell the user. +2. If content drift: add the missing guide/template for the new command or reference file, then update `scripts/upstream-manifest.json` to the new version/commit. +3. Re-run the check → exit 0 → proceed. + +## When not installed (exit 1) + +```bash +npx impeccable install --scope=global --providers=codex,claude,cursor +``` + +Then per project: `npx impeccable install` (hooks) + `/impeccable init` + `/impeccable document` (context). See `guides/10-install-and-verify.md`. + +## Rules + +- The check is a **pre-flight gate**: run it before Phase 1, skip when current, never skip when behind. +- Never fork or modify the engine; the check only compares versions and file coverage. +- A stale stinger manifest is a real finding: upstream added content the Bee does not know how to operate. +- Report the result in the close-out (see `templates/sync-report.md`). diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/reports/README.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/reports/README.md new file mode 100644 index 00000000..8d036cab --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/reports/README.md @@ -0,0 +1,3 @@ +# reports/ + +Close-out reports from impeccable-worker-bee runs. Template: `gate-report-template.md`. Past runs accumulate here over time. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/reports/gate-report-template.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/reports/gate-report-template.md new file mode 100644 index 00000000..d387c841 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/reports/gate-report-template.md @@ -0,0 +1,22 @@ +# Detector Gate Report + +| Field | Value | +|---|---| +| Target | `` | +| Command | `npx impeccable detect ` | +| Exit code | `0` (no findings) / `2` (findings) / `1` (failed) | +| Findings | `` | +| Resolved | `` | +| Waived | `` | + +## Findings + +| Rule id | Severity | File:line | Resolution (fix or waiver + reason) | +|---|---|---|---| +| `side-tab` | advisory | `src/components/Card.tsx:52` | Fixed — removed inset stripe | +| `overused-font` | advisory | `src/styles/global.css:14` | Waived — `ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md"` | + +## Verdict + +- [ ] Gate clean (0 findings) — close-out may proceed +- [ ] Gate failed (exit 2) — close-out blocked until resolved or waived diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/01-system-overview.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/01-system-overview.md new file mode 100644 index 00000000..eee5730b --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/01-system-overview.md @@ -0,0 +1,39 @@ +# 01 — System Overview + +**Source:** `README.md`, `PRODUCT.md`, `skill/SKILL.src.md`, `package.json`, `impeccable.style/designing` (reference) + +## What it is + +Impeccable is a design-guidance skill + toolchain for AI coding agents: "1 skill, 23 commands, live browser iteration, and 59 deterministic detector rules for AI-generated frontend design" (`README.md`). It started from Anthropic's `frontend-design` skill and adds a setup flow, a shared command vocabulary, and deterministic enforcement. + +- **License:** Apache-2.0 (`LICENSE`, `package.json` `"license": "Apache-2.0"`). +- **Runtime:** Node >= 22.18 (`package.json` `"engines"`). +- **Distribution:** npm package `impeccable` (bin `impeccable` → `cli/bin/cli.js`), installed per project via `npx impeccable install`, which writes harness-tailored builds (`.claude/`, `.cursor/`, `.codex/`, `.gemini/`, `.grok/`, `.trae/`, `.opencode/`, `.qoder/`, `.rovodev/` folders exist in the repo). +- **Per-model builds:** "builds for models with known tells carry extra slop rules banning that model's habits. The Gemini build kills its image-on-hover motion; the Codex build refuses ghost-cards and over-rounding" (`README.md`; ``/`` sections in `skill/reference/craft-floor.md`). + +## The seven layers (whole system) + +1. **Context contract** — `PRODUCT.md` (strategy) + `DESIGN.md` (visual system, Google Stitch format) + `.impeccable/surfaces/*.md` (per-surface mode/job/proof) + `.impeccable/design.json` (structured sidecar). Loaded by `skill/scripts/context.mjs` on every command. +2. **One vocabulary** — 23 commands under `/impeccable` (`skill/scripts/command-metadata.json`). v3.0 consolidated 18 standalone skills into one. +3. **Direction machinery** — new-work flow: job classification, five tests, direction contract, worlds deck + roll (`skill/scripts/concept-seed.mjs`, `skill/scripts/lib/concept-catalog.mjs`). +4. **Craft floor** — `skill/reference/craft-floor.md`: quality floor, absolute bans, reflexes, per-model sections. +5. **Deterministic enforcement** — 59 rules (`cli/engine/registry/antipatterns.mjs`), CLI `npx impeccable detect` (JSON, exit codes 0/2/1), hooks, Chrome extension, slop catalog. +6. **Live iteration** — `/impeccable live` (`skill/scripts/live/*`): browser picker, 3 variants per element, HMR, accept writes to source. Status: alpha. +7. **Maintenance** — `doctor` (tool/schema/truth drift), config/ignores, `update`/`check`, `extract`/`document`. + +## The four-phase loop (the Bee's core procedure) + +From `impeccable.style/designing` (reference; same content as the skill's routing): + +- **Start** — `init` (context) → `shape`/new-work (brief, direction, visualize, build). +- **Iterate** — named commands (`polish`, `bolder`, `typeset`, `layout`, `colorize`, `animate`, ...) or `live`; bounded rounds. +- **Polish** — pre-ship gauntlet: `audit` (5 dims, P0-P3), `clarify` (copy), `harden` (edge cases); detector gate in CI (`npx impeccable detect src/`, exit code fails the build). +- **Maintain** — `extract` (consolidate drift into tokens/primitives) + `document` (re-capture `DESIGN.md`) before debt solidifies. + +## Key evidence + +- "Verify in bounded passes, not a loop... Build fully, inspect once with a batched round (desktop and mobile together), fix everything it shows in one batch, confirm with at most one more round, and stop polishing. Open-ended self-QA burns the user's money" (`skill/SKILL.src.md`). +- "The brief wins. Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning" (`skill/SKILL.src.md`). +- "Refinement preserves; redesign replaces... Never split the difference into polish on the discarded look" (`skill/SKILL.src.md`). +- "Visual authority is evidence, not a filename. Missing DESIGN.md alone does not make a project greenfield" (`skill/SKILL.src.md`). +- "Running both Impeccable and Anthropic's frontend-design skill... Two skills with different design vocabularies collide and cancel each other out. Pick one" (`impeccable.style/designing`). diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/02-context-contract.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/02-context-contract.md new file mode 100644 index 00000000..d3fe7933 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/02-context-contract.md @@ -0,0 +1,28 @@ +# 02 — Context Contract (PRODUCT.md / DESIGN.md / surfaces / design.json) + +**Source:** `skill/scripts/context.mjs`, `skill/reference/init.md`, `skill/reference/document.md`, `skill/reference/context.md` (site), `impeccable.style/docs/context` (reference) + +## Files and roles + +| File | What it answers | Updated when | +|---|---|---| +| `PRODUCT.md` | Platform, users, purpose, positioning, evidence, brand commitments | Strategy changes | +| `DESIGN.md` | Colors, type stacks, components, radii, elevation, visual rules | Visual system changes | +| `.impeccable/surfaces/*.md` | One page/route: mode, job, proof sequence, chosen direction | Written by the work itself | +| `.impeccable/design.json` | Structured design data for automation (detector, hooks, Live Mode) | Regenerated by `document`; do not hand-edit | + +## Key rules + +- Every command reads both files before generating, plus the brief for the named surface (`skill/SKILL.src.md` Setup: "It loads PRODUCT.md, DESIGN.md, the matching surface brief, and native-platform guidance when applicable"). +- **Mode comes from the surface, not the product:** "A tool's landing page is still Persuade; a fashion house's documentation is still Read; a docs index is Read, not Persuade" (`skill/SKILL.src.md`). +- Four modes: **Persuade** (decides and acts; design is the product), **Operate** (completes a task; scanability outranks expression), **Read** (understands; comprehension first), **Experience** (inside the work; artifact leads, interface recedes) (`skill/SKILL.src.md` lines 35-38). +- `init` scans the codebase, forms its own read of platform/product, asks only what it could not work out, writes `PRODUCT.md`, and offers `DESIGN.md` when code exists. It does not ask about colors/type — those are decided with the surface (`skill/reference/init.md`). +- `document` auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language; writes `DESIGN.md` in the **Google Stitch format** so the file is tool-compatible (`skill/scripts/command-metadata.json`). +- `context.mjs` also performs a staleness check against `https://impeccable.style/api/version` (`skill/scripts/context.mjs` line 77, 1007) and can emit a `CONTEXT_STALE` directive; "Never repair drift as a side effect of a design task" (`skill/SKILL.src.md`). +- `PRODUCT.md` carries a schema stamp; `DESIGN.md` follows the external design.md spec and gets no stamp (`skill/reference/doctor.md`). + +## Evidence for the stinger + +- The Bee owns these files per project; they are the source of truth every phase reads. +- A missing `DESIGN.md` does not make a project greenfield: "Coherent code, type choices, and component behavior are authority whether or not anyone wrote them down. Scaffolds, framework defaults, and stray utility classes are not" (`skill/reference/new-work.md`). +- If implementation is coherent but undocumented, extract invariants, confirm with the user, write `DESIGN.md` before going further (`skill/reference/new-work.md`). diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/03-command-vocabulary.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/03-command-vocabulary.md new file mode 100644 index 00000000..e030359f --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/03-command-vocabulary.md @@ -0,0 +1,53 @@ +# 03 — Command Vocabulary (23 commands) + +**Source:** `skill/scripts/command-metadata.json`, `skill/SKILL.src.md`, `impeccable.style/docs` (reference) + +All commands run through `/impeccable `; `pin`/`unpin` creates standalone shortcuts (e.g., `/audit`). Commands grouped by intent (from `command-metadata.json`): + +## Create +- `impeccable` — next-step recommendation or plain-English design work; inspects project state, recommends 2-3 commands, asks before running. +- `shape` — "Think before you build. Produce a design brief through discovery, not guesswork." +- `init` — one-time setup: discovery interview, writes `PRODUCT.md`, offers `DESIGN.md`, pre-configures live mode, recommends next commands. +- `document` — generate a spec-compliant `DESIGN.md` (Google Stitch format) from existing code. +- `extract` — pull reusable patterns, components, and tokens into the design system (drift consolidation). + +## Evaluate +- `audit` — 5-dimension technical quality check (a11y, performance, theming, responsive, anti-patterns), scored 0-4, findings P0-P3. Native variant: `audit.native`. +- `critique` — design review with scoring, persona tests, and automated detection. + +## Refine +- `polish` — "The meticulous final pass between good and great." +- `bolder` / `quieter` — amplify safe designs / tone down shouting designs (two halves of voice). +- `distill` — ruthless subtraction; strip to essence. +- `animate` — purposeful motion that conveys state, not decoration. +- `colorize` — strategic color for monochrome UIs. +- `typeset` — fix typography hierarchy and fonts. +- `layout` — fix layout, spacing, visual rhythm. +- `delight` — small moments of personality. +- `overdrive` — push past conventional limits (shaders, physics, 60fps, cinematic transitions). + +## Simplify / Fix +- `adapt` — cross-device/context adaptation (breakpoints, fluid layouts, touch targets). Native variant: `adapt.native`. +- `clarify` — rewrite confusing UX copy. +- `optimize` — diagnose and fix UI performance (LCP to bundle size). + +## Harden +- `harden` — production-ready: edge cases, i18n, error states, overflow. +- `onboard` — first-run flows, empty states, activation paths. + +## System +- `live` — interactive live variant mode (browser picker, 3 variants, HMR, accept writes to source). Alpha. +- `hooks` — manage the design detector hook (`on|off|status|ignore-rule|ignore-file|ignore-value|reset`). +- `doctor` — report/repair drift between project artifacts and what this version reads. + +## Routing rules (`skill/SKILL.src.md`) + +- No argument → read `routing.md`, present context-aware menu; never auto-run a command. +- Explicit or clearly implied command → load its reference and follow it; ask once if two fit. +- Otherwise → treat as general design work; missing `PRODUCT.md` routes new surfaces through `init` then `new-work`; narrow refinement proceeds on the incumbent implementation. +- `teach` aliases `init`; `craft` is a deprecated alias for ordinary new-work. + +## Evidence for the stinger + +- The Bee's procedure maps the four phases to these commands: Start (`init`/`shape`/new-work), Iterate (refine commands + `live`), Polish (`audit`/`clarify`/`harden` + detector gate), Maintain (`extract`/`document`/`doctor`/`hooks`). +- Pin only 2-3 daily commands; pinning everything re-explodes the `/` menu (`impeccable.style/designing`). diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/04-new-work-direction.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/04-new-work-direction.md new file mode 100644 index 00000000..595fa14f --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/04-new-work-direction.md @@ -0,0 +1,51 @@ +# 04 — New-Work Direction Machinery (classification, five tests, direction contract, roll) + +**Source:** `skill/reference/new-work.md`, `skill/scripts/concept-seed.mjs`, `skill/scripts/lib/concept-catalog.mjs`, `impeccable.style/research` (reference) + +## Job classification + +- **Greenfield** — no coherent visual implementation; a world gets established. +- **Local extension** — a section/component inside a page that already works; only the new part is decided; the page's world is inherited. +- **New surface** — a whole page/flow inside an established world; composition open, world not. +- **Expression expansion** — an established brand entering a surface family it never resolved; a range is approved and merged into `DESIGN.md`. +- **Redesign or rebrand** — the look is replaced; product facts, content, function, constraints are not. +- **Refinement** — better, not different; leaves this flow for a scoped command like `polish`. + +"Redesign this page" authorizes replacement (old look becomes evidence and anti-reference). "Redesign this within our current system" is an extension. Ask once when genuinely ambiguous; never split the difference. + +## The five tests (every candidate must pass all) + +1. **Truth** — every relationship it visualizes exists in your product. Resemblance is not evidence. +2. **Translation** — strip the source's names and materials and a product-native relationship remains; otherwise it is a costume. +3. **Consequence** — removing its best move materially weakens the page. +4. **Survival** — the signature still works on the primary device, within a real asset and time budget. +5. **Fit** — its risk is an honest tradeoff, not a probable violation of your brief. + +## The direction contract (written into the artifact, <=150 words, five blocks) + +- `THESIS` — the one idea this page owns, and the category default it refuses. +- `OWN-WORLD` — palette and component language, recognizable with all content removed. +- `STORY` — what the visitor understands, believes, and does. +- `FIRST VIEWPORT` — the exact composition and where the primary action sits. +- `FORM` — the chosen form and the seed key. + +The contract exists so intent is inspectable and a **separate reviewer agent** can audit the built page against it promise-by-promise. "A page that promised a radical composition and shipped the usual template does not pass quietly" (`skill/reference/new-work.md`). + +## The roll / dice (external variance) + +- Problem (measured): "Ask a coding model for something creative and it builds its favorite idea, every run. Sixteen different 'be creative' framings returned the identical concept in thirty of thirty-five runs" (`skill/reference/new-work.md`; `impeccable.style/research`). +- Fix: a script rolls which of the model's own resonance-ordered shortlist gets built, and deals challengers from a reviewed catalog of ~188 visual worlds (`concept-seed.mjs` header; site says 177-188 worlds). +- "The dice never touch an ungrounded idea. They only refuse the argmax rut" (`concept-seed.mjs`). +- Re-roll: user re-rolls freely; the agent may only re-roll on named factual grounds (assigned direction cannot carry the product's truth or the task). "Its own taste is never grounds." +- Reproduction: the script prints a seed key; `--reroll ` recomputes prior rounds and excludes them. +- Fallback chain: local catalog (`IMPECCABLE_CATALOG_DIR`) → roll API (`https://impeccable.style/api`, `IMPECCABLE_API_URL`) → degraded local mode (`concept-seed.mjs` lines 63-99). + +## Research lessons (from `impeccable.style/research`, reference) + +1. The model lacks variance, not creativity (30/35 identical concepts). +2. Rejection advances a queue — "be different" lands on the #2 idea. +3. Argmax is deterministic; dice must **assign** the index, not nominate a menu (27/30 revert to option 1 when a chooser is involved). +4. Derivation is bounded by the subject's cultural depth; assigned foreign forms win over thin categories. +5. Anti-gimmick guards are the ceiling — commit first, then clarify (biggest single quality jump). +6. Committed skin hides template bones — "borrow the form's skeleton, not its clothes"; skin-blind review is a review instrument, never the builder grading itself. +7. Models describe brilliantly and build conservatively — hold them to the direction contract with a fresh reviewer. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/05-craft-floor.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/05-craft-floor.md new file mode 100644 index 00000000..9238cc34 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/05-craft-floor.md @@ -0,0 +1,32 @@ +# 05 — Craft Floor (quality floor, bans, reflexes) + +**Source:** `skill/reference/craft-floor.md` (verbatim structure) + +Loaded immediately before editing UI (not for planning-only work). "A pinned brief or the committed visual world overrides anything here; your own habit does not." + +## Verify (checks on the built result, run together in batched rounds) + +- **Contrast:** body/placeholder >= 4.5:1, large text >= 3:1; on colored surfaces tint secondary text from that hue or the foreground; never gray. +- **Depth:** shadows carry an offset and a soft blur; a zero-offset colored halo is decoration. +- **Spacing:** tight groups, generous separation, more space above a heading than below it; read computed values. +- **Type:** body measure 65-75ch, display max 6rem, tracking floor -0.04em, balanced headings, obvious scale/weight steps; run real copy at every breakpoint. +- **Motion:** one authored moment, not scattered effects; exponential ease-out from an already-visible default; reach past transform/opacity (blur, backdrop-filter, clip-path, mask, shadow). +- **States:** hover, disabled, loading, error, empty; real content, working controls, responsive composition, keyboard focus. +- **Browser surfaces:** text selection, caret, custom scrollbars, focus rings, underline offset, tabular numerals — "the cheapest signal that a page was built rather than assembled, and the one models skip most reliably." +- **Copy:** the product's own language; controls name their action; errors name the problem and the recovery. +- **Coverage:** every brief requirement present and findable within seconds. + +## Refuse (category defaults, not bans — the brief's own words can earn any of them) + +Page scaffolds: same-size icon+heading+text card grids (cards are the lazy container; nested cards always wrong); hero-metric template; kicker/eyebrow above a heading (a ban, not a default); section numbers 01/02/03 unless the sequence carries information; modal for a task needing neither interruption nor protected focus. + +Surface habits: gradient text; glass/blur as decoration; colored `border-left`/`border-right` above 1px; hard offset shadows outside a real neobrutalist world; sparklines/progress rings/soft-shadowed rounded rectangles standing in for content; monospace as a "technical" costume; system display faces as the display voice; unicode glyphs/emoji standing in for an icon system; light/dark picked by category instead of use scene. + +## Per-model sections + +- ``: tracking stops at -0.04em (-0.02 to -0.03 usually reads better); declare elevation once (border or shadow — 1px border under a wide soft shadow is the ghost card); card radii 12-16px, pills for small controls; real illustration or none (bans sketch-style SVG, `loose-sketch`/`doodle` class names, `feTurbulence` grain); backgrounds are surfaces (bans `repeating-linear-gradient` stripes and two-axis grid overlays without a real canvas/map/blueprint); claims come from supplied truth, label illustrative values honestly. +- ``: never animate an image on hover, directly or through its parent; give the container the feedback. + +## Closing principle + +"The floor holds the mechanics; it never picks the direction. With every check green, spend the page on the committed world, and when torn between refined and committed, commit." diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/06-detector-rules.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/06-detector-rules.md new file mode 100644 index 00000000..c42b75fd --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/06-detector-rules.md @@ -0,0 +1,84 @@ +# 06 — Detector Rules (59 deterministic rules) + +**Source:** `cli/engine/registry/antipatterns.mjs` (authoritative), `impeccable.style/slop` (public catalog, reference) + +## Engine facts + +- 59 rules, each with `id`, `category` (`slop` | `quality`), `severity` (`error` | `warning` | `advisory`). +- Runs via `npx impeccable detect `; plain output groups by file with rule id, snippet, explanation; `--json` for scripts/CI. +- **Exit codes:** 0 = no findings; 2 = findings detected; 1 = command failed. CI fails the job on 2. +- Engines: static-html (`engines/static-html/detect-html.mjs`), browser/URL (`engines/browser/detect-url.mjs`), regex/text for CSS-in-JS and framework files (`engines/regex/detect-text.mjs`), plus `node/file-system.mjs` (walk, import graph, framework config detection). +- DESIGN.md-aware: when a local `DESIGN.md` exists, enables design-system checks (fonts, literal colors, radii, font sizes) using `.impeccable/design.json` for richer token/ramp data. `--no-design-system` disables; `--scope type|layout` narrows. +- Ignores: `npx impeccable ignores ...` (shared `config.json` / local `config.local.json`), inline `impeccable-disable` / `-line` / `-next-line` comments. +- Web only: native projects route to `/impeccable audit` (native pass). + +## Full rule list (id | category | severity) + +### slop (30) +side-tab | slop | advisory — thick colored border on one side of a card (most recognizable AI tell) +border-accent-on-rounded | slop | advisory — accent border clashes with radius +overused-font | slop | advisory — Inter, Geist, Space Grotesk, Instrument Serif, etc. +flat-type-hierarchy | slop | error — font sizes too close (aim >= 1.25 ratio) +gradient-text | slop | error — decorative gradient text +ai-color-palette | slop | advisory — purple/violet gradients, cyan-on-dark +cream-palette | slop | advisory — warm cream/beige default surface +nested-cards | slop | advisory — cards inside cards +monotonous-spacing | slop | advisory — same spacing everywhere +bounce-easing | slop | advisory — bounce/elastic easing on interface elements +pulsing-dot | slop | advisory — decorative pulse on static status +blinking-cursor | slop | advisory — fake caret on non-editable hero copy +shape-assembled-illustration | slop | advisory — sketch-style SVG scenes +dark-glow | slop | warning — dark bg with colored box-shadow glows +radial-halo | slop | warning — saturated radial glow on dark page +radial-spotlight-glow | slop | warning — accent haze behind a section +marquee | slop | warning — auto-scrolling marquee +icon-tile-stack | slop | warning — rounded-square icon tile above heading +italic-serif-display | slop | warning — oversized italic serif hero +hero-eyebrow-chip | slop | warning — tiny uppercase label above hero headline +kicker-above-heading | slop | warning — tracked uppercase label above heading +numbered-section-labels | slop | warning — tiny 01/02/03 labels +em-dash-overuse | slop | warning +marketing-buzzword | slop | warning +aphoristic-cadence | slop | warning +oversized-h1 | slop | warning — full-sentence headline at display size +extreme-negative-tracking | slop | warning — crushed letter spacing +gpt-thin-border-wide-shadow | slop | warning — hairline border + wide diffuse shadow (ghost card) +repeating-stripes-gradient | slop | warning — decorative stripe backgrounds +codex-grid-background | slop | warning — two-axis grid overlays without a real canvas +theater-slop-phrase | slop | warning — "x-theater" naming/irony +image-hover-transform | slop | warning — image animated on hover (Gemini-tuned rule) + +### quality (29) +broken-image | quality | warning +script-error | quality | warning +content-hidden-at-rest | quality | warning +edge-flush-cards | quality | warning — scroller cards lose one edge +text-occlusion | quality | warning — opaque layer covers readable text +first-viewport-column-overflow | quality | warning +gray-on-color | quality | warning — gray text on colored background +low-contrast | quality | warning +layout-transition | quality | warning +line-length | quality | warning — > ~80ch +cramped-padding | quality | warning +body-text-viewport-edge | quality | warning +tight-leading | quality | warning +skipped-heading | quality | warning +heading-rhythm | quality | warning — heading closer to previous block than its content +justified-text | quality | warning +tiny-text | quality | warning +undersized-ui-text | quality | warning — functional text under 11px +all-caps-body | quality | warning +wide-tracking | quality | warning +text-overflow | quality | warning +repeated-container-text | quality | warning +clipped-overflow-container | quality | warning — positioned child clipped by overflow container +design-system-font | quality | warning — font outside DESIGN.md +design-system-color | quality | warning — literal color outside DESIGN.md palette +design-system-radius | quality | warning — radius outside documented shape scale +design-system-font-size | quality | warning — font size between documented steps + +## Evidence for the stinger + +- The gate is the Bee's mandatory close-out step: `npx impeccable detect `; exit code 2 fails until resolved or explicitly waived (narrowest ignore + reason). +- The 4 design-system rules make product-token enforcement mechanical — they complement `design-system-stinger`/`ux-ui-stinger`. +- Verified live during research: `node cli/bin/cli.js detect tests/fixtures` returned line-numbered findings (side-tab, design-system-color, etc.) with remediation text. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/07-hooks-enforcement.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/07-hooks-enforcement.md new file mode 100644 index 00000000..5282b89b --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/07-hooks-enforcement.md @@ -0,0 +1,41 @@ +# 07 — Hooks & Enforcement (per-edit + deep pass) + +**Source:** `skill/reference/hooks.md`, `skill/scripts/hook-admin.mjs`, `skill/scripts/hook-lib.mjs`, `impeccable.style/docs/hooks` (reference) + +## What the hook does + +- Scans direct edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). +- **Claude Code, GitHub Copilot, Codex:** post-tool-use hook pushes a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, clean UI-ish files get a short ack (unless `hook.quiet`). +- **Cursor:** `preToolUse` blocks bad proposed writes before they land; silent when it allows a clean write. +- Plain `.ts`/`.js` files are scanned but stay quiet unless the detector finds something. + +## Two speeds + +- **Per edit:** only what is objectively broken or compounds if ignored (broken images, overflow/clipped text, contrast failures, tiny text, gradient text, glow, DESIGN.md drift). +- **End of session (deep pass):** the full rule set across every UI file touched, minus what was already reported; a second stop is silent (findings remembered). Wired for Claude Code and Codex (native Stop hook); Cursor and Copilot keep the full detector per edit. +- Rationale: "Reporting every rule on every edit made models measurably more conservative rather than more careful" (one copy-level rule fired ~97x in a single session). +- `hook.perEditRules: "all"` restores full rules per edit. + +## Harness manifests & approval + +- Claude Code: `.claude/settings.local.json` (gitignored, machine-local). +- GitHub Copilot: `.github/hooks/impeccable.json` (committed, team-shared; activates on default branch). +- Codex: `.codex/hooks.json` — **requires one extra approval step**: open `/hooks` in Codex and approve the project hook; updates that change the hook definition can require approval again. +- Cursor: `.cursor/hooks.json`; confirm hooks enabled in Cursor Settings → Hooks. +- Installer/updater: `npx impeccable install|update`; `--no-hooks` skips hook setup; `--force` backs up malformed manifests as `.bak`. + +## Config & env + +- `hook.enabled`, `hook.quiet`, `hook.auditLog` (NDJSON) in `.impeccable/config.json`; per-developer consent in `.impeccable/config.local.json`. +- Env overrides: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, `IMPECCABLE_HOOK_LOG`. +- Detector filters live under `detector` (shared by hook and CLI): `ignoreRules`, `ignoreFiles`, `ignoreValues`, `designSystem.enabled`. +- Server-side templates: declare under `detector.extensions` (e.g., `{ "ext": ".blade.php", "engine": "html" }`). + +## Failure mode to watch + +"A hook can look installed and scan nothing: if its script path stops resolving... the manifest still registers and no findings ever arrive. Silence reads as a clean codebase." `/impeccable doctor` checks for exactly this (`skill/reference/hooks.md`). + +## Evidence for the stinger + +- The Bee verifies hook health (`doctor`) and treats hook silence as suspicious, not as a clean pass. +- Hooks are the "every time" enforcement: they fire on every UI edit regardless of routing discipline. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/08-live-mode.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/08-live-mode.md new file mode 100644 index 00000000..41709208 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/08-live-mode.md @@ -0,0 +1,23 @@ +# 08 — Live Mode (browser iteration) + +**Source:** `skill/reference/live.md`, `skill/reference/live-setup.md`, `skill/scripts/live/*`, `impeccable.style/docs/live` (reference) + +## What it is + +`/impeccable live` drops a picker onto the running dev server. The user points at any element, draws or types what they want, and gets **three production-quality variants** hot-swapped via HMR. Accepting one writes it back to source. + +- Requires a running dev server (localhost). +- Status: **alpha** — "works end-to-end and is ready to try, but it still needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups" (`impeccable.style/docs/live`). +- Scripts: `skill/scripts/live/*` (live.mjs, live-accept.mjs, live-complete.mjs, live-poll.mjs, live-status.mjs, live-wrap.mjs, live-target.mjs, live-resume.mjs, live-browser.js, live-inject.mjs, live-insert.mjs, live-copy-edit-agent.mjs, live-commit-manual-edits.mjs, live-manual-edit-evidence.mjs, live-discard-manual-edits.mjs, live-browser-dom.js, live-browser-session.js, live/manual-edits-buffer.mjs, live/vocabulary.mjs, live/svelte-ast.mjs, live/event-validation.mjs, live/insert-ui.mjs, live/manual-apply.mjs, live/completion.mjs, live/poll-lanes.mjs, live/accept-css.mjs, live/roots.mjs). +- `live-browser.js` is ~500KB (bundled browser automation). + +## When to reach for it + +- Fix something "off" you can't name. +- Explore three directions side by side. +- Point-at-it iteration beats command-naming when the user doesn't know the design word. + +## Evidence for the stinger + +- Live Mode is an Iterate-phase tool, not the core loop. Given alpha status, the Bee should treat it as optional/experimental and prefer named commands for the default path. +- Accept writes to source; manual edits are captured and committed via `live-commit-manual-edits.mjs`. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/09-maintenance-doctor.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/09-maintenance-doctor.md new file mode 100644 index 00000000..35f24025 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/09-maintenance-doctor.md @@ -0,0 +1,37 @@ +# 09 — Maintenance: Doctor, Config, Ignores, Update + +**Source:** `skill/reference/doctor.md`, `skill/reference/hooks.md`, `skill/scripts/doctor.mjs`, `impeccable.style/docs/doctor`, `impeccable.style/docs/config` (reference) + +## Doctor — three kinds of "out of date" + +1. **Tool version** — installed skill older than published; reported at boot; `npx impeccable update` fixes. +2. **Schema drift** — artifact written by an older Impeccable (fields nothing reads, fields now expected, retired locations). Mechanical; doctor repairs most of it. This is doctor's job. +3. **Truth drift** — code moved on and the document no longer describes it. Routed to `init`/`document`, not repaired. + +## What doctor checks + +- `PRODUCT.md` schema stamp (vintage, not release version). +- `DESIGN.md` (no stamp — follows external design.md spec) and the `.impeccable/design.json` sidecar (older than DESIGN.md, outdated schema, legacy path). +- Config: unknown keys, unknown detector keys, ignored rule ids that no longer exist, ignored file paths that are gone, `projectRoots` globs matching nothing. +- Design hook: script path that stopped resolving; enabled/disabled conflict. +- Surface briefs: records orphaned from the file/route they describe. +- Monorepos: which apps carry their own `PRODUCT.md`/`DESIGN.md` vs inherit the root's; flags a workspace with native build files inheriting a web-only root record. + +## Config & ignores + +- `.impeccable/config.json` (shared, commit when team intent) + `.impeccable/config.local.json` (private, gitignored). +- `npx impeccable ignores list|add-value|add-file|add-rule|remove-value`; `--local` for private; `--reason` for the why. +- Value ignores preferred for fonts/colors/radii/motion (keeps the rule useful elsewhere); wildcard value ignores only when scoped to a file. +- Inline comments travel with a file: ``, `impeccable-disable-line`, `impeccable-disable-next-line`. +- `projectRoots` for repos where design boundaries don't line up with package-manager workspaces. +- A config file fails quietly when wrong (misspelled key never read; stale rule id suppresses nothing) — doctor catches all three. + +## Update flow + +- `npx impeccable check` (behind?) → `npx impeccable update` (from project root); plugin users update from `/plugin` menu; `npx skills update` for the shared build. +- `stalenessCheck: false` in config or `IMPECCABLE_NO_STALENESS_CHECK=1` silences the boot notice; `doctor` still works. + +## Evidence for the stinger + +- Maintain phase = `extract` (consolidate drift) + `document` (re-capture system) + `doctor` (schema/truth/tool drift) + `check`/`update` (upstream). +- "Never repair drift as a side effect of a design task" — a `CONTEXT_STALE` finding is reported, not acted on, unless the user asks (`skill/SKILL.src.md`). diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/10-native-platforms-harnesses.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/10-native-platforms-harnesses.md new file mode 100644 index 00000000..96b1ff82 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/10-native-platforms-harnesses.md @@ -0,0 +1,23 @@ +# 10 — Native Platforms & Harness Builds + +**Source:** `skill/reference/ios.md`, `skill/reference/android.md`, `skill/reference/audit.native.md`, `skill/reference/adapt.native.md`, `docs/HARNESSES.md`, repo `.claude/ .cursor/ .codex/ .gemini/ .grok/ .trae/ .opencode/ .qoder/ .rovodev/` builds + +## Native (iOS / Android / adaptive) + +- The detector is **web only** ("The engine reads HTML and CSS, so it has nothing to say about a native iOS or Android codebase" — `impeccable.style/docs/detector`). +- When `PRODUCT.md` declares `ios`, `android`, or `adaptive`, `/impeccable audit` runs a native pass covering VoiceOver, TalkBack, touch targets, and platform conformance (`audit.native.md`); `adapt` has a native variant (`adapt.native.md`). +- `init` detects the platform from codebase evidence and asks only when ambiguous; platform is recorded in `PRODUCT.md`. +- Native guidance files: `ios.md`, `android.md` (per-platform rulebooks). + +## Harness builds + +- `npx impeccable install` auto-detects the harness and writes the right skill files (`.claude/skills/`, `.cursor/skills/`, `.codex/`, `.gemini/`, `.grok/`, etc.), plus provider-native hook manifests where supported. +- Per-model rule tuning: the Gemini build kills image-on-hover motion; the Codex build refuses ghost-cards and over-rounding (`README.md`; ``/`` sections in `craft-floor.md`). +- `npx skills add pbakaus/impeccable` installs one shared build for every harness (functionally complete, not tailored). +- Claude Code plugin: `/plugin marketplace add pbakaus/impeccable`. +- GitHub Copilot: Impeccable is built in (Settings → Experimental). + +## Evidence for the stinger + +- The Bee's default domain is web; native surfaces route to the native playbooks and the native audit pass. +- The stinger should note the per-model build behavior so the Bee knows the installed build may carry extra rules for its model. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/11-license-provenance.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/11-license-provenance.md new file mode 100644 index 00000000..409c38f8 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/11-license-provenance.md @@ -0,0 +1,27 @@ +# 11 — License, Provenance & Versioning + +**Source:** `LICENSE`, `NOTICE.md`, `package.json`, `README.md`, `impeccable.style/robots.txt` + +## License + +- **Apache-2.0** (`LICENSE`; `package.json` `"license": "Apache-2.0"`; `cli/engine/detect-antipatterns.mjs` header: "SPDX-License-Identifier: Apache-2.0"). +- Vendoring guidance content into the stinger is license-clean with attribution. Keep the NOTICE/attribution (`NOTICE.md` exists in the repo). +- Author: Paul Bakaus. Homepage: impeccable.style. npm: `impeccable`. + +## Site content signals (compliance) + +- `impeccable.style/robots.txt`: `Content-Signal: search=yes, ai-train=no, use=reference` (Cloudflare managed; also disallows GPTBot, ClaudeBot, CCBot, etc.). +- Implication: the stinger must be built from the **repo** (Apache-2.0), not scraped from the site. Site text is reference-only for understanding, not a training/vendoring source. + +## Versioning + +- Repo `package.json`: `3.5.0` (npm package version). Site markets **v4** ("A leaner core, tuned on frontier models like Fable and GPT-5.6-Sol. Four visitor modes."). +- Content is in sync: the repo's `SKILL.src.md` has all four modes (Persuade/Operate/Read/Experience); the site docs are generated from the repo's `skill/reference/` files. +- Upstream is actively maintained (repo HEAD `aee6ce9`, 2026-08-04; sitemap lastmods through 2026-07-22). +- Implication: the stinger's vendored reference docs need a refresh cadence; the installed side self-updates via `npx impeccable check`/`update`. + +## Research provenance + +- Clone: `/tmp/impeccable-RZVWdD` (shallow, depth 1, commit `aee6ce9`). +- Detector verified live: `node cli/bin/cli.js detect tests/fixtures` produced line-numbered findings (side-tab, design-system-color, etc.). +- Site pages fetched for reference: `/`, `/docs*`, `/slop`, `/research`, `/designing`, `/cases/neo-mirai`, `/tutorials/*`. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/index.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/index.md new file mode 100644 index 00000000..40547606 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/index.md @@ -0,0 +1,26 @@ +# Research Index — impeccable-stinger + +Manifest of primary-source research for `impeccable-worker-bee`. All files cite repo paths under `/tmp/impeccable-RZVWdD` (github.com/pbakaus/impeccable, commit aee6ce9, Apache-2.0). + +| File | Covers | Primary sources | +|---|---|---| +| `research-plan.md` | Scope, depth, method, provenance | Command Brief, repo | +| `01-system-overview.md` | Whole system: 7 layers, four-phase loop, per-model builds | `README.md`, `PRODUCT.md`, `skill/SKILL.src.md`, `package.json`, site `/designing` | +| `02-context-contract.md` | PRODUCT.md / DESIGN.md / surfaces / design.json, modes | `skill/scripts/context.mjs`, `skill/reference/init.md`, `document.md`, site `/docs/context` | +| `03-command-vocabulary.md` | 23 commands, routing rules, pinning | `skill/scripts/command-metadata.json`, `skill/SKILL.src.md`, site `/docs` | +| `04-new-work-direction.md` | Classification, five tests, direction contract, roll/dice, research lessons | `skill/reference/new-work.md`, `skill/scripts/concept-seed.mjs`, `lib/concept-catalog.mjs`, site `/research` | +| `05-craft-floor.md` | Quality floor, bans, reflexes, per-model sections | `skill/reference/craft-floor.md` | +| `06-detector-rules.md` | 59 rules (id/category/severity), CLI, exit codes, engines, ignores | `cli/engine/registry/antipatterns.mjs`, `cli/engine/*`, site `/slop` | +| `07-hooks-enforcement.md` | Per-edit + deep pass, harness manifests, approval, config | `skill/reference/hooks.md`, `skill/scripts/hook-admin.mjs`, `hook-lib.mjs`, site `/docs/hooks` | +| `08-live-mode.md` | Live browser iteration, alpha status, scripts | `skill/reference/live.md`, `skill/scripts/live/*`, site `/docs/live` | +| `09-maintenance-doctor.md` | Doctor (tool/schema/truth drift), config, ignores, update | `skill/reference/doctor.md`, `skill/scripts/doctor.mjs`, site `/docs/doctor`, `/docs/config` | +| `10-native-platforms-harnesses.md` | iOS/Android/adaptive, per-harness builds, per-model rules | `skill/reference/ios.md`, `android.md`, `audit.native.md`, `adapt.native.md`, `docs/HARNESSES.md` | +| `11-license-provenance.md` | Apache-2.0, site content signals, versioning, research provenance | `LICENSE`, `NOTICE.md`, `package.json`, site `robots.txt` | + +## Open questions for the user (not for stinger-forge to invent) + +1. **Scope of the Bee's routing:** should `impeccable-worker-bee` become the *default* router for all frontend UI/UX work (retiring `design-taste-frontend`, `frontend-design`, `high-end-visual-design`, `gpt-taste`, `web-design-guidelines` as fallbacks), or coexist? +2. **Upstream install vs stinger-only:** should the army run `npx impeccable install` per project (hooks + compiled skill) as the enforcement layer, with the stinger as guidance + gate procedure? (Recommended: yes.) +3. **CI gate:** add `npx impeccable detect src/` to army projects' PR checks? +4. **Live Mode:** adopt now (alpha) or defer until stable? +5. **Native:** does the army need the iOS/Android/adaptive playbooks in the first stinger release, or web-only? diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/research-plan.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/research-plan.md new file mode 100644 index 00000000..7e66e342 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/research-plan.md @@ -0,0 +1,8 @@ +# Research Plan: impeccable-stinger + +- **Bee:** impeccable-worker-bee (Command Brief: `.cursor/commands/impeccable-worker-bee-command-brief.md`) +- **Depth tier:** deep (entire system: context contract, 23 commands, four-phase loop, 59-rule detector, hooks, live mode, worlds deck, maintenance) +- **Primary source:** `github.com/pbakaus/impeccable` (Apache-2.0), cloned at `/tmp/impeccable-RZVWdD` (commit `aee6ce9`, 2026-08-04, package v3.5.0) +- **Method:** repo-primary extraction (user-directed), not a web sweep. The repo is the canonical Apache-2.0 source; impeccable.style is generated from it and is reference-only (robots.txt: `ai-train=no, use=reference`). +- **Evidence files to extract:** `skill/SKILL.src.md`, `skill/reference/*.md` (33 files), `skill/scripts/*` (context, concept-seed, hook-admin, doctor, live), `cli/engine/registry/antipatterns.mjs` (59 rules), `cli/engine/*` (checks, constants, color, design-system, engines), `docs/*`, `DESIGN.md`, `PRODUCT.md`, `README.md`, `package.json`, `LICENSE`, `NOTICE.md`, `tests/`. +- **Output:** `research/` files below, `index.md` manifest, `research-summary.md` handoff. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/research-summary.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/research-summary.md new file mode 100644 index 00000000..2d0e0597 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/research/research-summary.md @@ -0,0 +1,37 @@ +# Research Summary — impeccable-stinger + +- **Depth tier consumed:** deep (entire system) +- **Time window covered:** repo HEAD `aee6ce9` (2026-08-04); site sitemap lastmods 2026-04-10 → 2026-07-22. Repo-primary research, not a web sweep (user-directed; site robots.txt `ai-train=no`). +- **Files written:** 13 (research-plan + 11 topic files + index + this summary) under `.cursor/skills/impeccable-stinger/research/`. + +## The 5 most influential sources (for stinger-forge) + +1. **`skill/SKILL.src.md`** — the skill definition: setup, four modes, command routing, hooks, doctor, bounded-pass discipline. The stinger's SKILL.md should mirror its structure and voice. +2. **`skill/reference/craft-floor.md`** — the quality floor, absolute bans, and per-model (``, ``) sections. This is the anti-slop core the Bee enforces. +3. **`skill/reference/new-work.md` + `skill/scripts/concept-seed.mjs`** — job classification, five tests, direction contract, and the roll/dice variance machinery. This is what makes the system "whole" and is unique vs every existing army skill. +4. **`cli/engine/registry/antipatterns.mjs`** — the 59 deterministic rules (id/category/severity) that power the gate, hooks, CI, and slop catalog. The Bee's mandatory close-out gate. +5. **`skill/reference/hooks.md` + `skill/scripts/hook-admin.mjs`** — per-edit + deep-pass enforcement, harness manifests, Codex approval. The "every time" enforcement layer. + +## Open questions (for the user, not stinger-forge) + +1. Default router for all frontend UI/UX work, retiring overlapping prompt-only skills as fallbacks? +2. Upstream `npx impeccable install` per project as the enforcement layer (recommended), stinger as guidance + gate? +3. CI gate on army PR checks? +4. Live Mode now (alpha) or defer? +5. Native playbooks in first release, or web-only? + +## Sources stinger-forge should re-fetch with deeper context + +- `skill/reference/audit.md` + `audit.native.md` (5-dimension scoring rubric, P0-P3) — needed for the Polish-phase guide. +- `skill/reference/init.md` + `document.md` (interview flow, Stitch-format capture) — needed for the Start-phase guide. +- `skill/reference/live.md` + `live-setup.md` (alpha; decide inclusion). +- `docs/HARNESSES.md` (per-harness install/update details) — needed for the install/verify guide. +- `skill/scripts/context.mjs` (context loading + staleness directives) — needed for the context-contract guide. + +## Decisions (user-resolved 2026-08-06) + +1. Default router for all frontend UI/UX work — YES (retire overlapping prompt-only skills to fallbacks). +2. Install scope — HYBRID: global skill install + per-project context/hooks (hooks are project-local by harness design). +3. CI gate — YES (`npx impeccable detect src/` in PR checks). +4. Live Mode — include as opt-in, user-invoked, alpha; never auto-launched. +5. Native — include iOS/Android/adaptive playbooks. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/scripts/sync-check.mjs b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/scripts/sync-check.mjs new file mode 100755 index 00000000..adfeabdf --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/scripts/sync-check.mjs @@ -0,0 +1,157 @@ +#!/usr/bin/env node +/** + * impeccable-stinger pre-flight sync check. + * + * Verifies, before a design task starts, that the installed Impeccable skill + * is current with upstream and that the stinger's vendored coverage (guides + + * templates) still matches the installed skill's content. If everything is + * current it is skipped (exit 0); if behind or drifted it reports what changed + * (exit 2); if the skill is not installed it says so (exit 1). + * + * Usage: + * node sync-check.mjs # check only + * node sync-check.mjs --update # check, and run `npx impeccable update` when behind + * + * Exit codes: + * 0 = current and in sync (skip) + * 2 = behind upstream and/or content drift (needs update/refresh) + * 1 = not installed or check failed + */ +import { readFileSync, existsSync, readdirSync } from 'node:fs'; +import { join, dirname } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { spawnSync } from 'node:child_process'; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const STINGER = join(HERE, '..'); +const MANIFEST = JSON.parse(readFileSync(join(HERE, 'upstream-manifest.json'), 'utf8')); + +const CANDIDATE_DIRS = [ + join(process.env.HOME || '', '.agents', 'skills', 'impeccable'), + join(process.env.HOME || '', '.codex', 'skills', 'impeccable'), + join(process.env.HOME || '', '.claude', 'skills', 'impeccable'), + join(process.env.HOME || '', '.cursor', 'skills', 'impeccable'), + '.agents/skills/impeccable', + '.codex/skills/impeccable', + '.claude/skills/impeccable', + '.cursor/skills/impeccable', +]; + +const UPDATE_HOST = process.env.IMPECCABLE_UPDATE_HOST || 'https://impeccable.style'; +const FETCH_TIMEOUT_MS = 4000; + +function findInstalledSkill() { + for (const dir of CANDIDATE_DIRS) { + if (existsSync(join(dir, 'SKILL.md'))) return dir; + } + return null; +} + +function readInstalledVersion(dir) { + try { + const md = readFileSync(join(dir, 'SKILL.md'), 'utf8'); + const m = md.match(/^version:\s*(.+)$/m); + return m ? m[1].trim() : null; + } catch { + return null; + } +} + +function compareVersions(a, b) { + const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0); + const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0); + for (let i = 0; i < Math.max(pa.length, pb.length); i++) { + const da = pa[i] || 0; + const db = pb[i] || 0; + if (da !== db) return da - db; + } + return 0; +} + +async function fetchPublishedVersion() { + try { + const res = await fetch(`${UPDATE_HOST}/api/version`, { + signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), + }); + if (!res.ok) return null; + const body = await res.text(); + const m = body.match(/"version"\s*:\s*"([^"]+)"/) || body.match(/"skills"\s*:\s*"([^"]+)"/) || body.match(/^([0-9]+\.[0-9]+\.[0-9]+)/m); + return m ? m[1] : body.trim(); + } catch { + return null; + } +} + +function contentDrift(dir) { + const drift = { newReferenceFiles: [], newCommands: [], missingReferenceFiles: [] }; + const refDir = join(dir, 'reference'); + if (existsSync(refDir)) { + const installed = readdirSync(refDir).filter((f) => f.endsWith('.md')).sort(); + drift.newReferenceFiles = installed.filter((f) => !MANIFEST.referenceFiles.includes(f)); + drift.missingReferenceFiles = MANIFEST.referenceFiles.filter((f) => !installed.includes(f)); + } + const metaPath = join(dir, 'scripts', 'command-metadata.json'); + if (existsSync(metaPath)) { + try { + const meta = JSON.parse(readFileSync(metaPath, 'utf8')); + drift.newCommands = Object.keys(meta).filter((c) => !MANIFEST.commands.includes(c)); + } catch { + /* ignore unreadable metadata */ + } + } + return drift; +} + +function runUpdate() { + const r = spawnSync('npx', ['impeccable', 'update'], { stdio: 'inherit', shell: true }); + return r.status === 0; +} + +async function main() { + const args = process.argv.slice(2); + const doUpdate = args.includes('--update'); + + const installedDir = findInstalledSkill(); + if (!installedDir) { + console.log('[sync-check] NOT INSTALLED: no impeccable skill found in any harness skill dir.'); + console.log('[sync-check] Run: npx impeccable install --scope=global --providers=codex,claude,cursor'); + process.exit(1); + } + + const installedVersion = readInstalledVersion(installedDir); + const publishedVersion = await fetchPublishedVersion(); + const drift = contentDrift(installedDir); + + const behind = installedVersion && publishedVersion && compareVersions(publishedVersion, installedVersion) > 0; + const hasDrift = drift.newReferenceFiles.length > 0 || drift.newCommands.length > 0; + + console.log(`[sync-check] installed: ${installedVersion || 'unknown'} @ ${installedDir}`); + console.log(`[sync-check] published: ${publishedVersion || 'unreachable (offline?)'}`); + if (behind) console.log(`[sync-check] BEHIND: installed ${installedVersion} < published ${publishedVersion}`); + if (drift.newCommands.length) console.log(`[sync-check] NEW COMMANDS upstream: ${drift.newCommands.join(', ')}`); + if (drift.newReferenceFiles.length) console.log(`[sync-check] NEW REFERENCE FILES upstream: ${drift.newReferenceFiles.join(', ')}`); + if (drift.missingReferenceFiles.length) console.log(`[sync-check] MISSING REFERENCE FILES (installed skill lacks): ${drift.missingReferenceFiles.join(', ')}`); + + if (!behind && !hasDrift) { + console.log('[sync-check] CURRENT: upstream in sync, stinger coverage matches. Skipping update.'); + process.exit(0); + } + + if (doUpdate && behind) { + console.log('[sync-check] Running `npx impeccable update`...'); + if (runUpdate()) { + console.log('[sync-check] Updated. NOTE: Codex may require /hooks re-approval after an update.'); + process.exit(0); + } + console.log('[sync-check] Update failed.'); + process.exit(1); + } + + if (hasDrift) { + console.log('[sync-check] STINGER REFRESH NEEDED: upstream added content the stinger does not cover.'); + console.log('[sync-check] Add guides/templates for the new content, then update scripts/upstream-manifest.json.'); + } + process.exit(2); +} + +main(); diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/scripts/upstream-manifest.json b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/scripts/upstream-manifest.json new file mode 100644 index 00000000..b96d7c6c --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/scripts/upstream-manifest.json @@ -0,0 +1,128 @@ +{ + "upstreamVersion": "4.0.4", + "upstreamCommit": "aee6ce9", + "upstreamDate": "2026-08-04", + "commands": [ + "craft", + "init", + "document", + "extract", + "live", + "adapt", + "animate", + "audit", + "bolder", + "clarify", + "colorize", + "critique", + "delight", + "distill", + "harden", + "onboard", + "layout", + "optimize", + "overdrive", + "polish", + "quieter", + "shape", + "typeset" + ], + "referenceFiles": [ + "adapt.md", + "adapt.native.md", + "android.md", + "animate.md", + "audit.md", + "audit.native.md", + "bolder.md", + "clarify.md", + "colorize.md", + "craft-floor.md", + "craft.md", + "critique.md", + "delight.md", + "distill.md", + "doctor.md", + "document.md", + "extract.md", + "harden.md", + "hooks.md", + "init.md", + "ios.md", + "layout.md", + "live-setup.md", + "live.md", + "new-work.md", + "onboard.md", + "operate.md", + "optimize.md", + "overdrive.md", + "polish.md", + "quieter.md", + "routing.md", + "shape.md", + "typeset.md", + "visualize.md" + ], + "rules": [ + "side-tab", + "border-accent-on-rounded", + "overused-font", + "flat-type-hierarchy", + "gradient-text", + "ai-color-palette", + "cream-palette", + "nested-cards", + "monotonous-spacing", + "bounce-easing", + "pulsing-dot", + "blinking-cursor", + "shape-assembled-illustration", + "dark-glow", + "radial-halo", + "radial-spotlight-glow", + "marquee", + "icon-tile-stack", + "italic-serif-display", + "hero-eyebrow-chip", + "kicker-above-heading", + "numbered-section-labels", + "em-dash-overuse", + "marketing-buzzword", + "aphoristic-cadence", + "oversized-h1", + "extreme-negative-tracking", + "broken-image", + "script-error", + "content-hidden-at-rest", + "edge-flush-cards", + "text-occlusion", + "first-viewport-column-overflow", + "gray-on-color", + "low-contrast", + "layout-transition", + "line-length", + "cramped-padding", + "body-text-viewport-edge", + "tight-leading", + "skipped-heading", + "heading-rhythm", + "justified-text", + "tiny-text", + "undersized-ui-text", + "all-caps-body", + "wide-tracking", + "text-overflow", + "repeated-container-text", + "clipped-overflow-container", + "design-system-font", + "design-system-color", + "design-system-radius", + "design-system-font-size", + "gpt-thin-border-wide-shadow", + "repeating-stripes-gradient", + "codex-grid-background", + "theater-slop-phrase", + "image-hover-transform" + ] +} diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/direction-contract.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/direction-contract.md new file mode 100644 index 00000000..96c3ffbf --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/direction-contract.md @@ -0,0 +1,16 @@ +# Direction Contract (write into the artifact as a comment block, <=150 words, five blocks) + +```ts +/* + * THESIS: + * OWN-WORLD: + * STORY: + * FIRST VIEWPORT: + * FORM: + */ +``` + +Rules: +- The contract is inspectable intent. A separate reviewer audits the built page against it promise-by-promise. +- Keep the seed key to reproduce the roll (including every re-roll round). +- A page that promised a radical composition and shipped the usual template does not pass quietly. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/gate-report.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/gate-report.md new file mode 100644 index 00000000..d387c841 --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/gate-report.md @@ -0,0 +1,22 @@ +# Detector Gate Report + +| Field | Value | +|---|---| +| Target | `` | +| Command | `npx impeccable detect ` | +| Exit code | `0` (no findings) / `2` (findings) / `1` (failed) | +| Findings | `` | +| Resolved | `` | +| Waived | `` | + +## Findings + +| Rule id | Severity | File:line | Resolution (fix or waiver + reason) | +|---|---|---|---| +| `side-tab` | advisory | `src/components/Card.tsx:52` | Fixed — removed inset stripe | +| `overused-font` | advisory | `src/styles/global.css:14` | Waived — `ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md"` | + +## Verdict + +- [ ] Gate clean (0 findings) — close-out may proceed +- [ ] Gate failed (exit 2) — close-out blocked until resolved or waived diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/surface-brief.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/surface-brief.md new file mode 100644 index 00000000..497c4fff --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/surface-brief.md @@ -0,0 +1,10 @@ +# Surface Brief: `` + +- **Mode:** Persuade / Operate / Read / Experience +- **Job:** what the visitor came to do on this surface +- **Proof sequence:** what evidence the surface shows, in order +- **Chosen direction:** the committed world (or "inherits `` world") +- **Seed key:** `` (if rolled) +- **Anti-references:** what this surface must not do + +Written by the work itself; edited when the page's strategy changes. Lives at `.impeccable/surfaces/.md`. diff --git a/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/sync-report.md b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/sync-report.md new file mode 100644 index 00000000..1040935a --- /dev/null +++ b/.codex/plugins/vibe-coding-tools/skills/impeccable-stinger/templates/sync-report.md @@ -0,0 +1,14 @@ +# Sync Check Report + +| Field | Value | +|---|---| +| Installed version | `<4.0.4>` | +| Published version | `<4.0.4>` | +| Status | `current` / `behind` / `not installed` | +| New commands upstream | `` | +| New reference files upstream | `` | +| Action taken | `skipped (current)` / `updated` / `stinger refresh` | + +- [ ] Current → skipped, task proceeded +- [ ] Updated → `/hooks` re-approval noted to user +- [ ] Stinger refresh needed → new guide/template added, manifest bumped diff --git a/.cursor/agents/impeccable-worker-bee.md b/.cursor/agents/impeccable-worker-bee.md new file mode 100644 index 00000000..01151a34 --- /dev/null +++ b/.cursor/agents/impeccable-worker-bee.md @@ -0,0 +1,114 @@ +--- +name: "impeccable-worker-bee" +description: "Operates the entire Impeccable design system (pbakaus/impeccable, Apache-2.0) as the Bee Army's frontend-design operating system: the four-phase loop (Start -> Iterate -> Polish -> 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 proactively for ANY frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture - \"polish the pricing page\", \"build a dashboard\", \"redo this hero\", \"make this not look like AI slop\". Do NOT invoke for backend-only or non-UI tasks, or for product-specific design-system token enforcement - that is design-system-worker-bee / ux-ui-worker-bee." +--- + +# Impeccable Worker Bee + +Before doing anything else, read `.cursor/skills/impeccable-stinger/SKILL.md` in full and follow it as the operating manual. + +## Identity & responsibility + +`impeccable-worker-bee` is the roster's frontend-design operating system operator. It owns the entire Impeccable system as a closed loop: context contract, 23-command vocabulary, the four-phase design loop (Start -> Iterate -> Polish -> Maintain), the deterministic 59-rule anti-slop detector gate, hooks, live mode, and native playbooks. Every design element and every new page surface stays cohesive, from no design to a well-maintained design, or from a current design to a better design. It is the single router for all frontend UI/UX/design implementation work. It does not own product-specific design-system token enforcement (that is `design-system-worker-bee` / `ux-ui-worker-bee`), and it never vendors or re-implements the Impeccable engine: it operates the installed system. + +## Paired Stinger + +[`.cursor/skills/impeccable-stinger/`](../skills/impeccable-stinger/) + +The Stinger's `SKILL.md` is the master index. Read it in full before any design work, then open the guides and reusable artifacts named by the selected phase. + +## Activation contract + +Activate proactively when the assigned work touches any of these surfaces: + +- Any frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture. +- Requests such as "polish the pricing page", "build a dashboard", "redo this hero", "make this not look like AI slop", "design a settings screen", "audit this UI", or any task that needs a cohesive visual system. +- Any task where the user wants to see the design live during development and point at issues before a PR. + +Do not activate as the final authority for product-specific design-system token enforcement (route to `design-system-worker-bee` / `ux-ui-worker-bee`), backend/non-UI work, Lighthouse/perf-only audits (route to `quality-worker-bee`), or Security acceptance (route to `security-worker-bee`). + +## Procedure + +1. **Phase 0 - Pre-flight sync check.** Run `node .cursor/skills/impeccable-stinger/scripts/sync-check.mjs`. Exit `0` (current, in sync) -> skip and proceed. Exit `2` (behind upstream and/or content drift) -> `npx impeccable update` (note Codex `/hooks` re-approval to the user), refresh the stinger's guides/templates + `scripts/upstream-manifest.json` for new upstream content, re-run. Exit `1` (not installed) -> global install first (`npx impeccable install --scope=global --providers=codex,claude,cursor`), then per-project `install` + `init` + `document`. Record the result per `templates/sync-report.md`. See `guides/11-sync-check.md`. +2. **Phase 1 - Start (context + direction).** Ensure the context contract exists (`/impeccable init` -> `PRODUCT.md`; `/impeccable document` -> `DESIGN.md` + `.impeccable/design.json`); read it if present, never re-derive. Classify the job (greenfield / local extension / new surface / expression expansion / redesign / refinement). 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, apply the five tests (Truth, Translation, Consequence, Survival, Fit), and write the direction contract (`THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`) into the artifact per `templates/direction-contract.md`. Visualize when image tooling is available, then build toward the image. See `guides/01-context-contract.md` and `guides/02-start-phase.md`. +3. **Phase 2 - Iterate (bounded rounds).** Use named commands when the edit has a name (`polish`, `bolder`, `quieter`, `distill`, `typeset`, `layout`, `colorize`, `animate`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `harden`, `onboard`). `/impeccable live` is opt-in, user-invoked only (alpha): never auto-launch it. Bound the loop: build fully, inspect once batched (desktop + mobile), fix in one batch, confirm at most once, stop. The user is the "happy" gate. See `guides/03-iterate-phase.md` and `guides/08-live-mode.md`. +4. **Phase 3 - Polish (pre-ship gauntlet).** Run `/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). Run the deterministic gate: `npx impeccable detect ` (file, dir, or URL; `--json` for CI). Exit code 2 = findings = close-out fails until resolved or waived (narrowest ignore + reason). Hand off to the army close-out: `security-worker-bee` first, then `quality-worker-bee`. See `guides/04-polish-phase.md` and `guides/06-detector-gate.md`. +5. **Phase 4 - Maintain (cohesion).** `/impeccable extract` (fold repeated patterns into tokens/primitives), `/impeccable document` (re-capture the system when code drifts), `/impeccable doctor` (schema/truth/hook-path/config drift), `npx impeccable check` / `update` (keep the installed system current). Never repair drift as a side effect of a design task. See `guides/05-maintain-phase.md`. +6. **Install & verify (hybrid scope).** Global skill: `npx impeccable install --scope=global --providers=codex,claude,cursor`. Per project (one-time): `npx impeccable install` writes the hook manifests and `.impeccable/config.json`; `init`/`document` write the context files. Codex requires `/hooks` approval after install/update. Verify with `/impeccable doctor`. See `guides/10-install-and-verify.md`. +7. **Native surfaces.** 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`. + +## Critical directives + +- **Never self-grade.** Iterate in bounded rounds; the user is the "happy" gate. A separate reviewer (`quality-worker-bee` or a fresh reader) audits the build against its direction contract promise-by-promise. Self-accountability has ground truth, rubrics don't. +- **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. +- **The gate is mandatory.** `npx impeccable detect` exit code 2 fails the close-out. Waivers require the narrowest ignore plus a stated reason. +- **Upstream always in sync.** The pre-flight sync check runs before every task; if current it is skipped, if behind it is updated before any design work. A stale stinger manifest (new upstream commands/reference files) is a real finding: refresh the stinger, never proceed blind. +- **Never fork or modify the engine.** Call the installed system (`/impeccable`, `npx impeccable`); follow the bee-army-update contract (no upstream script execution during install, preserve the ownership manifest, no silent overwrites). +- **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. +- **Single vocabulary.** Never mix Impeccable with other design-taste skills in the same session: two design vocabularies collide and cancel each other out. +- **License discipline.** Apache-2.0 upstream; build from the repo, not the site (site robots.txt: `ai-train=no, use=reference`). Keep attribution. +- **Close-out order.** Security before quality, always. + +## Escalation + +Stop and ask one clarifying question when the surface, mode, or product context is genuinely ambiguous: never silently guess. Route unresolved work as follows: + +- Product-specific design-system token enforcement -> `design-system-worker-bee` / `ux-ui-worker-bee`. +- Backend/non-UI logic -> `react-worker-bee`, `preact-worker-bee`, or the relevant domain Bee. +- Lighthouse/perf-only audits -> `quality-worker-bee`. +- Security acceptance -> `security-worker-bee` (before quality). +- Live Mode (alpha) rough edges on uncommon setups -> flag to the user and fall back to named commands. +- Codex `/hooks` re-approval after an install/update -> surface to the user before proceeding. + +## References to skill files + +Utilize the Read tool to understand your skills listed at `.cursor/skills/impeccable-stinger/` with all of its sub-folders and files. Read `SKILL.md` in full first. + +### Master indexes + +- `SKILL.md` - the four-phase loop, Phase 0 sync check, core principles, install/verify, native surfaces. +- `README.md` - folder layout, provenance, license. + +### Principles and procedures (guides/) + +- `guides/00-principles.md` - the system's non-negotiables (bounded passes, brief wins, no self-grading, single vocabulary, gate mandatory) +- `guides/01-context-contract.md` - PRODUCT.md / DESIGN.md / surfaces / design.json / four modes +- `guides/02-start-phase.md` - init, document, job classification, new-work flow, five tests, direction contract, roll, visualize +- `guides/03-iterate-phase.md` - named commands, bounded-round discipline, live mode opt-in +- `guides/04-polish-phase.md` - audit / clarify / harden, P0-P3, the deterministic gate, close-out +- `guides/05-maintain-phase.md` - extract / document / doctor / update, drift rules +- `guides/06-detector-gate.md` - CLI usage, exit codes, all 59 rules, DESIGN.md awareness, ignores, CI wiring +- `guides/07-hooks.md` - per-edit + deep pass, harness manifests, approval, the silent-hook failure mode +- `guides/08-live-mode.md` - opt-in browser iteration (alpha), session flow, Chrome extension +- `guides/09-native.md` - iOS / Android / adaptive playbooks, per-model harness builds +- `guides/10-install-and-verify.md` - global skill install + per-project hooks/context, doctor +- `guides/11-sync-check.md` - pre-flight upstream sync check (skip when current) + +### Worked examples (examples/) + +- `examples/01-happy-path-new-surface.md` - greenfield -> direction contract -> build -> gate -> maintain +- `examples/02-edge-case-refinement.md` - refinement with a narrow waiver +- `examples/03-live-mode-session.md` - opt-in live iteration +- `examples/04-sync-check.md` - pre-flight sync check (current / behind / drift / not installed) + +### Output templates (templates/) + +- `templates/direction-contract.md` - THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM +- `templates/gate-report.md` - detector gate result for the close-out +- `templates/surface-brief.md` - per-surface mode/job/proof/direction +- `templates/sync-report.md` - pre-flight sync check result + +### Scripts (scripts/) + +- `scripts/sync-check.mjs` - the pre-flight sync check runner (exit 0 skip / 2 update / 1 install) +- `scripts/upstream-manifest.json` - upstream content coverage manifest (commands, reference files, rules) + +### Research trail (research/) + +- `research/research-summary.md` - depth tier, sources, decisions, handoff +- `research/index.md` - manifest of all research files +- `research/01-system-overview.md` through `research/11-license-provenance.md` - primary-source evidence + +--- + +*Created by the Legendary Bee Factory.* diff --git a/.cursor/skills/beekeeper-suit/PAIRING-AUDIT.md b/.cursor/skills/beekeeper-suit/PAIRING-AUDIT.md index 0672198c..7f43f861 100644 --- a/.cursor/skills/beekeeper-suit/PAIRING-AUDIT.md +++ b/.cursor/skills/beekeeper-suit/PAIRING-AUDIT.md @@ -4,16 +4,22 @@ Ground truth pulled from the filesystem on 2026-08-14, after the repair pass. Th ## Totals -- Bees (`.claude/agents/*.md`): **75** -- Stinger folders (`.claude/skills/*`): **78** +- Bees (`.claude/agents/*.md`): **76** +- Stinger folders (`.claude/skills/*`): **79** - Orchestrator-level skills with no paired Bee by design: **3** (`beekeeper-suit`, `queen-bee-stinger`, `get-started-stinger`) -- Pairable Stingers: **75** +- Pairable Stingers: **76** ## Pairing integrity Clean. Every Bee has a matching Stinger and every pairable Stinger has a matching Bee, verified in both directions by naming convention. Zero orphans. -Every Bee also has a routing guide at `guides/.md`. 75 Bees, 75 guides, one-to-one. +Every Bee also has a routing guide at `guides/.md`. 76 Bees, 76 guides, one-to-one. + +## New additions + +`impeccable-worker-bee` / `impeccable-stinger` was ported in from a prior fork and registered here: it operates the Impeccable design system (pbakaus/impeccable, Apache-2.0) as the frontend-design operating system. The Impeccable engine is installed per machine via `npx impeccable install --scope=global --providers=codex,claude,cursor`; it is not vendored in this repo. The stinger's pre-flight sync check (`scripts/sync-check.mjs`) verifies the installed engine is current. + +`impeccable-worker-bee` is the single router for frontend UI/UX/design implementation. `design-system-worker-bee` and `ux-ui-svelte-worker-bee` retain product-specific token, component-library, and accessibility enforcement on established systems. ## Path integrity @@ -41,7 +47,7 @@ All routing references to the renamed `deeplake-dataset-worker-bee` were repaire ## Validation -All 78 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 75 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. +All 79 Stingers pass `per-type-validation.py --type skill --harness all` with zero errors. All 76 Bees pass `--type agent --harness claude-code` with zero errors. Remaining warnings are repo-wide patterns, not defects: descriptions above Cowork's 200 character soft cap on some legacy skills, and the `proactive` frontmatter field, which every Bee in this colony uses. ## Dead reference repair diff --git a/.cursor/skills/beekeeper-suit/SKILL.md b/.cursor/skills/beekeeper-suit/SKILL.md index 6d6f8a12..759caf09 100644 --- a/.cursor/skills/beekeeper-suit/SKILL.md +++ b/.cursor/skills/beekeeper-suit/SKILL.md @@ -28,7 +28,7 @@ Three skills sit above the pairing law because they are orchestrator level, not ## Roster -75 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. +76 Bees registered, sorted into domain groups. The Domain column is a one-line summary of the Bee's own frontmatter description. Trigger keywords are pulled from that same description, not invented. ### Stack and frameworks @@ -42,7 +42,7 @@ Three skills sit above the pairing law because they are orchestrator level, not | `react-worker-bee` | React 18/19 architecture: bulletproof-react patterns, Server Components, Suspense, Actions, Compiler, state layering | "review React architecture", "state management decision", "Server Components boundary", "React 19 patterns" | `react-stinger` | | `typescript-node-worker-bee` | TypeScript/Node code review and conventions: strict config, module resolution, test suites, boundary validation (body still cites a legacy package's specifics; see PAIRING-AUDIT.md) | "review this TypeScript code", "audit this Node code", "write a Vitest suite", "tighten the tsconfig" | `typescript-node-stinger` | | `python-worker-bee` | Python architecture: Django + Django Ninja + FastAPI + Celery + Channels + pytest + uv, ORM discipline, migrations, typed adoption | "review this Django code", "audit ORM patterns", "migrate DRF to Django Ninja", "set up Celery" | `python-stinger` | -| `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | +| `ux-ui-svelte-worker-bee` | Enforces this repo's SvelteKit UI standard: shadcn-svelte on Bits UI plus Melt UI, Tailwind v4 token bridge, white-label brand contract. Impeccable remains the primary router for UI/design implementation | "add a Button", "copy in this shadcn-svelte component", "convert this bespoke style to Tailwind", "does the white-label still work" | `ux-ui-svelte-stinger` | | `dark-mode-theming-worker-bee` | Dark-mode theming: CSS variable token architecture, theme-provider wiring, FOWT prevention, SSR hydration safety, Tailwind v4 dark variant | "set up dark mode", "dark mode on SSR", "multi-brand theming", "FOWT fix" | `dark-mode-theming-stinger` | | `modal-toast-dialog-worker-bee` | Accessible overlay primitives: dialog, alert dialog, drawer, toast, command menu; focus trap, escape, scroll lock, aria contract | "choosing between overlay primitives", "debugging focus trap regressions", "building a command palette" | `modal-toast-dialog-stinger` | | `icon-system-worker-bee` | Icon library selection and delivery: tree-shake vs sprite, dynamic-import-by-name, custom SVG components, icon accessibility contract | "choosing an icon library", "bundle-size regressions from icon imports", "icon accessibility" | `icon-system-stinger` | @@ -50,7 +50,8 @@ Three skills sit above the pairing law because they are orchestrator level, not | `font-loading-worker-bee` | Font loading pipeline: font-display strategy, preload/crossorigin correctness, variable-font subsetting, CLS-from-font-swap elimination | "audit font loading", "fix FOIT", "CLS from font swap", "subset variable font" | `font-loading-stinger` | | `markdown-mdx-content-pipeline-worker-bee` | Markdown/MDX pipeline: compiler selection, remark/rehype chains, syntax highlighting, AST manipulation, XSS sanitization | "set up MDX", "configure Shiki", "write a remark plugin", "sanitize user markdown" | `markdown-mdx-content-pipeline-stinger` | | `csv-xlsx-import-export-worker-bee` | Spreadsheet upload and export feature: CSV/XLSX parsing, large-file streaming, column-mapping wizard, row validation, CSV injection prevention | "build a CSV import", "add XLSX upload", "column-mapping wizard", "CSV injection safe" | `csv-xlsx-import-export-stinger` | -| `design-system-worker-bee` | Bootstraps a complete design system from scratch: tokens, utility layer, per-component and per-screen specs, static HTML examples | "build a design system for X", "bootstrap UI for product Y", "create tokens and utilities for this product" | `design-system-stinger` | +| `design-system-worker-bee` | Bootstraps a complete design system from scratch: tokens, utility layer, per-component and per-screen specs, static HTML examples. Impeccable owns frontend UI/UX/design implementation and uses DESIGN.md drift rules plus its detector gate to make enforcement mechanical | "build a design system for X", "bootstrap UI for product Y", "create tokens and utilities for this product" | `design-system-stinger` | +| `impeccable-worker-bee` | Frontend-design operating system for all UI/UX/design implementation, redesign, refinement, new surfaces, components, and design-system capture. Runs Start -> Iterate -> Polish -> Maintain, the context contract, and the deterministic detector gate | "polish the pricing page", "build a dashboard", "redo this hero", "make this not look like AI slop", "design a settings screen", "audit this UI" | `impeccable-stinger` | | `http-rest-fundamentals-worker-bee` | HTTP/REST protocol correctness: method safety and idempotency, status-code honesty, headers, conditional and range requests | "is this status code correct", "why is CORS failing", "explain preflight", "PUT vs PATCH" | `http-rest-fundamentals-stinger` | | `image-optimization-worker-bee` | Image delivery: AVIF/WebP format selection, responsive srcset/sizes, blur placeholders, remote image config, CLI tooling | "optimize my images", "convert to AVIF", "fix layout shift from images", "audit our images" | `image-optimization-stinger` | @@ -208,6 +209,12 @@ Real sequences for this stack. Every sequence below closes with the Ship Gate; i 5. `seo-aeo-worker-bee` for metadata, JSON-LD, and Core Web Vitals. 6. Ship Gate. +### Frontend design / UI implementation + +1. **`impeccable-worker-bee`** is the single router for all frontend UI/UX/design implementation, redesign, refinement, new-surface, component, and design-system-capture work. It runs Start -> Iterate -> Polish -> Maintain, including the pre-flight sync check and deterministic `npx impeccable detect ` gate. +2. **`design-system-worker-bee`** and **`ux-ui-svelte-worker-bee`** own product-specific token, component-library, and accessibility enforcement on established systems. Impeccable makes that enforcement mechanical via DESIGN.md drift rules and the detector gate. +3. **`security-worker-bee`** then **`quality-worker-bee`** close out under the Plan execution loop. + ### Add auth 1. `workos-worker-bee` wires AuthKit, sessions, and SSO. @@ -251,7 +258,7 @@ Don't hand-roll a new Bee. Walk [`../queen-bee-stinger/guides/beekeeper-registra --- -**75 Bees registered.** Every Bee has a spawnable agent in `.cursor/agents/` and a paired Stinger in `.cursor/skills/`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. +**76 Bees registered.** Every Bee has a spawnable agent in `.cursor/agents/` and a paired Stinger in `.cursor/skills/`. See [`PAIRING-AUDIT.md`](./PAIRING-AUDIT.md) for the full pairing audit, including the handful of Bees whose body content still needs a rewrite pass to match this repo's actual stack. --- diff --git a/.cursor/skills/beekeeper-suit/guides/impeccable-worker-bee.md b/.cursor/skills/beekeeper-suit/guides/impeccable-worker-bee.md new file mode 100644 index 00000000..f73b2a6c --- /dev/null +++ b/.cursor/skills/beekeeper-suit/guides/impeccable-worker-bee.md @@ -0,0 +1,55 @@ +# impeccable-worker-bee + +## Domain +This Bee is the frontend-design operating system operator. It owns the entire Impeccable system (pbakaus/impeccable, Apache-2.0) as a closed loop: the context contract (`PRODUCT.md` + `DESIGN.md` + per-surface briefs + `.impeccable/design.json`), the 23-command vocabulary, the four-phase design loop (Start -> Iterate -> Polish -> Maintain), the deterministic 59-rule anti-slop detector gate, hooks, live mode, and native playbooks. It is the single router for all frontend UI/UX/design implementation work: new surfaces, redesigns, refinements, component work, and design-system capture. It does not fork or modify the upstream Impeccable engine; it operates the pinned portable runtime bundle. + +**Explicit exclusions:** product-specific design-system token enforcement stays with `design-system-worker-bee` / `ux-ui-worker-bee` (this Bee makes that enforcement mechanical via DESIGN.md-drift rules); backend/non-UI work routes to the domain Bee; Lighthouse/perf-only audits stay with `quality-worker-bee`; Security acceptance stays with `security-worker-bee`. + +## Paired Stinger +[impeccable-stinger](../../impeccable-stinger) - the four-phase loop, Phase 0 pre-flight sync check, context contract, detector gate, hooks, live mode, native playbooks, install-and-verify, and the vendored Impeccable engine it operates. + +## Trigger phrases +- "polish the pricing page" +- "build a dashboard" +- "redo this hero" +- "make this not look like AI slop" +- "design a settings screen" +- "audit this UI" +- "keep the design cohesive across new pages" + +Or route proactively when the assigned work touches any frontend UI/UX/design implementation, redesign, refinement, new surface, component work, or design-system capture, or when the user wants to see the design live during development and point at issues before a PR. + +## Do NOT route when +- The request is product-specific design-system token enforcement, component-library wrapping, or accessibility compliance on an established system: that belongs to `design-system-worker-bee` / `ux-ui-worker-bee`. +- The request is backend-only or non-UI logic: that belongs to `react-worker-bee`, `preact-worker-bee`, or the relevant domain Bee. +- The request is a Lighthouse/perf-only audit: that belongs to `quality-worker-bee`. +- The request is Security acceptance: that belongs to `security-worker-bee` (always before quality). + +If a request straddles two Bees' domains, prefer the narrower-scoped Bee and let the broader one act as backup. + +## Inputs the Bee needs +- The design task: a surface or route to design/redesign/refine, a plain-English request, or a named command intent. +- Repo root and target surface(s); the surface's mode (Persuade / Operate / Read / Experience) or enough context to infer it from the surface, not the product. +- Existing context files if present: `PRODUCT.md`, `DESIGN.md`, `.impeccable/design.json`, `.impeccable/surfaces/*.md`, `.impeccable/config.json`. +- Environment: Node >= 22.18; Impeccable installed per project (`npx impeccable install`) or `npx` network access; hooks approved in Codex (`/hooks`) where applicable. +- Optional: brand kit, anti-references, screenshots, incumbent visual truth (tokens, theme, CSS, components, assets). + +## Outputs +- **Context contract files** - `PRODUCT.md`, `DESIGN.md` (Stitch format), `.impeccable/design.json`, `.impeccable/surfaces/*.md`, owned and kept current by this Bee. +- **Implemented UI** - source changes to the target surface(s), with the direction contract comment block (`THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`) at the top of new artifacts. +- **Detector evidence** - a gate result (0 findings, or resolved findings, or explicit waivers with reasons) attached to the close-out. +- **Design-system updates** - `extract` / `document` outputs that keep the system current. +- **Close-out handoff** - security -> quality verification result, then a summary to the user with what changed and what remains open. + +## Commonly sequenced with +- Plan execution loop: `impeccable-worker-bee` is the implementation Bee for frontend UI/UX/design work; it hands the final implemented state to `security-worker-bee`, reruns affected checks after security fixes, and only then hands it to `quality-worker-bee`. +- Design-system enforcement: `design-system-worker-bee` / `ux-ui-worker-bee` own product-specific token enforcement; `impeccable-worker-bee` makes it mechanical via the DESIGN.md-drift rules and the detector gate. + +## Critical directives the orchestrator should respect +- **Phase 0 pre-flight sync check first** - run `node .claude/skills/impeccable-stinger/scripts/sync-check.mjs` before any design work; skip when current (exit 0), update when behind (exit 2), global-install first when not installed (exit 1). +- **Never self-grade** - the Bee iterates in bounded rounds; 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. +- **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. +- **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 ` runs before any completion claim; exit code 2 fails the close-out until findings are resolved or explicitly waived (narrowest ignore + reason). +- **Never fork or modify the engine** - call the installed system (`/impeccable`, `npx impeccable`); follow the bee-army-update contract (no upstream script execution during install, preserve the ownership manifest, no silent overwrites). +- **Close-out order** - Security before quality, always. diff --git a/.cursor/skills/impeccable-stinger/README.md b/.cursor/skills/impeccable-stinger/README.md new file mode 100644 index 00000000..466a380d --- /dev/null +++ b/.cursor/skills/impeccable-stinger/README.md @@ -0,0 +1,9 @@ +# impeccable-stinger + +The paired Stinger for `impeccable-worker-bee`: the Bee Army's frontend-design operating system operator. It encodes the entire Impeccable system (pbakaus/impeccable, Apache-2.0) as a four-phase loop — **Start → Iterate → Polish → Maintain** — with the deterministic 59-rule anti-slop detector gate as a mandatory close-out step. + +- Command Brief: `.claude/commands/impeccable-worker-bee-command-brief.md` +- Research: `research/research-summary.md` (repo-primary, commit `aee6ce9`, 2026-08-04) +- License: Apache-2.0 (upstream); this stinger is guidance + procedure, never vendored engine code. + +- Bee: `.claude/agents/impeccable-worker-bee.md` (agent file: `.claude/agents/impeccable-worker-bee.toml`) diff --git a/.cursor/skills/impeccable-stinger/SKILL.md b/.cursor/skills/impeccable-stinger/SKILL.md new file mode 100644 index 00000000..5ef0ae47 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/SKILL.md @@ -0,0 +1,94 @@ +--- +name: "impeccable-stinger" +description: "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-stinger)." +license: Apache-2.0 (upstream impeccable) +--- + +# 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 ` 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 .cursor/skills/impeccable-stinger/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 ` (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`, `.cursor/settings.json`, `.cursor/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 `.cursor/skills/impeccable-stinger/` 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) diff --git a/.cursor/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md b/.cursor/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md new file mode 100644 index 00000000..c8780789 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/THIRD_PARTY_NOTICES.md @@ -0,0 +1,3 @@ +# Third-party notices + +The Impeccable Stinger documents and operates the Apache-2.0 Impeccable runtime from [pbakaus/impeccable](https://github.com/pbakaus/impeccable), version 4.0.4. It retains that attribution and is distributed as part of the Bee Army only as a reusable operating guide and portable runtime companion. diff --git a/.cursor/skills/impeccable-stinger/examples/01-happy-path-new-surface.md b/.cursor/skills/impeccable-stinger/examples/01-happy-path-new-surface.md new file mode 100644 index 00000000..9cf54de6 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/examples/01-happy-path-new-surface.md @@ -0,0 +1,13 @@ +# Example 01 — Happy Path: New Surface (greenfield → shipped → maintained) + +Demonstrates: `guides/01-context-contract.md`, `guides/02-start-phase.md`, `guides/04-polish-phase.md`, `guides/05-maintain-phase.md`. + +**Task:** "Build a pricing page for a developer tool that traces every alert back to the deploy that caused it." + +1. **Start — context.** No `PRODUCT.md` → `/impeccable init` (platform: web; users: SREs on call, reading fast, often in the dark; positioning: traces every alert back to the deploy that caused it; evidence: real incident timelines, no customer logos yet). No `DESIGN.md` → `/impeccable document` (extracts tokens from the existing app, writes Stitch-format `DESIGN.md` + `design.json`). +2. **Start — classification.** New surface inside an established world → composition open, world inherited. Mode: **Persuade** (a pricing page earns attention and action). +3. **Start — direction.** Derive a grounded shortlist (incident timeline, postmortem doc, terminal session, man page, pager timeline). Roll assigns index 3 (terminal session) and deals challengers from the worlds deck. Five tests: Truth (the terminal relationship exists in the product) ✓, Translation (strip names → a product-native relationship remains) ✓, Consequence (removing the terminal frame weakens the page) ✓, Survival (works on mobile within budget) ✓, Fit (honest tradeoff) ✓. Write the direction contract into the artifact (see `templates/direction-contract.md`), keep the seed key. +4. **Build.** Code toward the committed world. Craft floor: contrast >= 4.5:1, body measure 65-75ch, one authored motion moment, real states (hover/disabled/loading/error/empty), themed browser surfaces (selection, focus rings, scrollbars). No side-tab borders, no gradient text, no hero eyebrow, no Inter-as-display. +5. **Iterate.** One batched inspection round (desktop + mobile): fix overflow on the pricing table, tighten heading rhythm, replace one hardcoded hex with a token. One fix batch. One confirmation round. Stop. +6. **Polish.** `/impeccable audit` (a11y 4, perf 3, theming 4, responsive 3, anti-patterns 4; one P2: touch target on the plan toggle → fixed). `/impeccable clarify` (CTA copy tuned to SREs). `/impeccable harden` (60-char org names, prices in the billions, 500s). Gate: `npx impeccable detect src/` → 0 findings. Hand off to `security-worker-bee` → `quality-worker-bee`. +7. **Maintain.** `/impeccable extract` (the plan-toggle pattern appears 3x → token + primitive). `/impeccable document` (re-capture `DESIGN.md`). `/impeccable doctor` → clean. The next surface inherits the world. diff --git a/.cursor/skills/impeccable-stinger/examples/02-edge-case-refinement.md b/.cursor/skills/impeccable-stinger/examples/02-edge-case-refinement.md new file mode 100644 index 00000000..e49cf512 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/examples/02-edge-case-refinement.md @@ -0,0 +1,17 @@ +# Example 02 — Edge Case: Refinement with a Waiver + +Demonstrates: `guides/03-iterate-phase.md`, `guides/04-polish-phase.md`, `guides/06-detector-gate.md`. + +**Task:** "Polish the settings screen. Keep our sharp corners and sober palette. Remove the AI tells." + +1. **Context.** `PRODUCT.md` + `DESIGN.md` exist and are current. Mode: **Operate** (settings = task completion; scanability outranks expression). +2. **Classification.** Refinement — better, not different. No new-work flow, no roll, no direction contract. The incumbent world is preserved. +3. **Iterate.** `/impeccable polish settings` — targeted fixes: 3 off-grid elements aligned; h1 kerning tightened; one hardcoded hex → `--color-accent`; missing hover state on FAQ items; modal entrance softened to 220ms ease-out-quart; stray "Lorem" removed. One batched round, one fix batch, one confirmation. Stop. +4. **Polish.** `/impeccable audit settings` (P1: gray-on-color on the danger zone → tint from the hue instead). `/impeccable harden settings` (long German labels, offline state). Gate: `npx impeccable detect src/settings` → 1 finding: `overused-font` flags the brand font (a real brand commitment, not a default). +5. **Waiver (narrowest form, with reason):** + ```bash + npx impeccable ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md" + ``` + Re-run the gate → 0 findings. The waiver is recorded in `.impeccable/config.json` and shared with the hook. +6. **Close-out.** Hand off to `security-worker-bee` → `quality-worker-bee`. Gate result travels with the close-out (see `templates/gate-report.md`). +7. **Maintain.** No drift introduced; `doctor` clean. Nothing to extract. diff --git a/.cursor/skills/impeccable-stinger/examples/03-live-mode-session.md b/.cursor/skills/impeccable-stinger/examples/03-live-mode-session.md new file mode 100644 index 00000000..c1069b73 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/examples/03-live-mode-session.md @@ -0,0 +1,13 @@ +# Example 03 — Live Mode Session (opt-in, user-invoked) + +Demonstrates: `guides/08-live-mode.md`, `guides/07-hooks.md`. + +**Task:** "Show me the hero live — something's off but I can't name it." + +1. **Opt-in.** The user asked; the Bee launches live mode. Never auto-launched. +2. **Setup.** Dev server confirmed running (localhost:3000). `/impeccable live` — picker injected into the app. +3. **Iterate.** User picks the hero headline, types "make it feel more editorial". Three variants hot-swapped via HMR. User accepts variant 2 → written to source (manual edits captured via `live-commit-manual-edits.mjs`). +4. **Gate.** `npx impeccable detect src/` on the accepted result → 0 findings. The per-edit hook stays quiet on clean edits (non-intrusive by design). +5. **Close-out.** Hand off to `security-worker-bee` → `quality-worker-bee`. + +**Note:** during normal development the user gets live feedback from the **per-edit hook** (findings pushed back after each UI edit, quiet when clean) — that is the non-nuisance live feedback. Live mode is the on-demand visual iteration tool. diff --git a/.cursor/skills/impeccable-stinger/examples/04-sync-check.md b/.cursor/skills/impeccable-stinger/examples/04-sync-check.md new file mode 100644 index 00000000..30b327e2 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/examples/04-sync-check.md @@ -0,0 +1,10 @@ +# Example 04 — Pre-Flight Sync Check + +Demonstrates: `guides/11-sync-check.md`. + +**Task:** "Polish the billing settings page." + +1. **Pre-flight.** `node .../impeccable-stinger/scripts/sync-check.mjs` → `[sync-check] CURRENT: upstream in sync, stinger coverage matches. Skipping update.` (exit 0). Skipped; task proceeds. +2. **Later run (behind).** The check reports `BEHIND: installed 4.0.3 < published 4.0.4` and `NEW COMMANDS upstream: ` (exit 2). The Bee runs `npx impeccable update`, notes the Codex `/hooks` re-approval to the user, re-runs the check → exit 0 → proceeds. +3. **Content drift.** The check reports `NEW REFERENCE FILES upstream: typeset.native.md` (exit 2). The Bee adds a guide/template covering the new playbook, bumps `scripts/upstream-manifest.json`, re-runs → exit 0 → proceeds. +4. **Not installed.** The check reports `NOT INSTALLED` (exit 1). The Bee runs the global install, then per-project `install` + `init` + `document`, re-runs → exit 0 → proceeds. diff --git a/.cursor/skills/impeccable-stinger/guides/00-principles.md b/.cursor/skills/impeccable-stinger/guides/00-principles.md new file mode 100644 index 00000000..26edaa7e --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/00-principles.md @@ -0,0 +1,14 @@ +# 00 — Principles (non-negotiables) + +Derived from `research/01-system-overview.md` and `research/05-craft-floor.md`. + +1. **The brief wins.** Pinned aesthetics, eras, materials, fonts, and palettes override saturated-pattern warnings. Redirecting a clear brief toward your taste is failure. (research/01, SKILL.src.md) +2. **Refinement preserves; redesign replaces.** Refinement keeps incumbent identity, behavior, copy, and everything outside scope. Redesign keeps product truth, content, function, and constraints but treats the old look as evidence and anti-reference. Never split the difference. (research/01) +3. **Bounded passes.** Build fully → inspect once batched (desktop + mobile) → fix in one batch → confirm at most once → stop. Open-ended self-QA is waste. (research/01) +4. **Never self-grade.** The user is the "happy" gate. A fresh reviewer audits the build against its direction contract promise-by-promise. (research/04, lesson 7) +5. **Context contract is source of truth.** Read `PRODUCT.md` + `DESIGN.md` + surface brief before every command. Mode comes from the surface, not the product. Missing `DESIGN.md` ≠ greenfield. (research/02) +6. **Single vocabulary.** One design system per session. Mixing Impeccable with other design-taste skills cancels both out. (research/01, /designing) +7. **The gate is mandatory.** `npx impeccable detect` exit code 2 fails the close-out. Waivers need the narrowest ignore + a stated reason. (research/06) +8. **Never fork or modify the engine.** Call the installed system; follow the bee-army-update contract (no upstream script execution during install, preserve ownership manifest, no silent overwrites). (research/11) +9. **License discipline.** Apache-2.0 upstream; build from the repo, not the site (site robots.txt: `ai-train=no, use=reference`). Keep attribution. (research/11) +10. **Close-out order.** Security before quality, always. diff --git a/.cursor/skills/impeccable-stinger/guides/01-context-contract.md b/.cursor/skills/impeccable-stinger/guides/01-context-contract.md new file mode 100644 index 00000000..9021f405 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/01-context-contract.md @@ -0,0 +1,30 @@ +# 01 — Context Contract + +Derived from `research/02-context-contract.md`. + +## Files the Bee owns per project + +| File | Role | Written by | +|---|---|---| +| `PRODUCT.md` | Strategy: platform, users, purpose, positioning, evidence, brand commitments | `/impeccable init` | +| `DESIGN.md` | Visual system: colors, type, components, radii, elevation, rules (Google Stitch format) | `/impeccable document` | +| `.impeccable/surfaces/*.md` | Per-surface: mode, job, proof sequence, chosen direction | The work itself | +| `.impeccable/design.json` | Structured sidecar for detector/hooks/Live Mode | `document` (do not hand-edit) | + +## Modes (from the surface, not the product) + +- **Persuade** — visitor decides and acts (landing, marketing, pricing). Design is the product; earn attention. +- **Operate** — visitor completes a task (app UI, dashboards, admin, tools). Scanability outranks expression. +- **Read** — visitor understands (docs, guides, help). Comprehension first. +- **Experience** — visitor is inside the work (portfolios, galleries). Artifact leads, interface recedes. + +A tool's landing page is still Persuade; a fashion house's docs are still Read. Name the mode explicitly only when genuinely ambiguous; persist it in the surface brief. + +## Rules + +- Every command reads the contract first. Never re-derive what is recorded. +- `init` scans the codebase, forms its own read, asks only what it could not work out. It does not ask about colors/type — those are decided with the surface. +- `document` auto-extracts colors, typography, spacing, radii, components, then confirms descriptive language; writes Stitch-format `DESIGN.md`. +- Missing `DESIGN.md` does not make a project greenfield: coherent code, type choices, and component behavior are authority. Scaffolds and framework defaults are not. +- If implementation is coherent but undocumented: extract invariants, confirm with the user, write `DESIGN.md` before going further. +- `context.mjs` may emit a `CONTEXT_STALE` directive — report it, do not act on it unless the user asks (except `auto` findings). diff --git a/.cursor/skills/impeccable-stinger/guides/02-start-phase.md b/.cursor/skills/impeccable-stinger/guides/02-start-phase.md new file mode 100644 index 00000000..a83d5663 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/02-start-phase.md @@ -0,0 +1,39 @@ +# 02 — Start Phase (context + direction) + +Derived from `research/02-context-contract.md`, `research/03-command-vocabulary.md`, `research/04-new-work-direction.md`. + +## 1. Ensure context + +- No `PRODUCT.md` → run `/impeccable init` (discovery interview; writes `PRODUCT.md`; offers `DESIGN.md` when code exists). +- No `DESIGN.md` → run `/impeccable document` (Stitch format + `.impeccable/design.json`). +- Files exist → read them; do not re-interview. + +## 2. Classify the job + +- **Greenfield** — no coherent visual implementation; a world gets established. +- **Local extension** — a section/component inside a working page; only the new part is decided; the page's world is inherited. +- **New surface** — a whole page/flow inside an established world; composition open, world not. +- **Expression expansion** — an established brand entering a surface family it never resolved; approve a range, merge into `DESIGN.md`. +- **Redesign or rebrand** — the look is replaced; product facts, content, function, constraints are not. +- **Refinement** — better, not different; leave this flow for a scoped command like `polish`. + +"Redesign this page" = replacement (old look becomes anti-reference). "Redesign within our current system" = extension. Ask once when genuinely ambiguous; never split the difference. + +## 3. New-work flow (new surfaces + redesigns) + +1. Derive a grounded shortlist of candidate directions from the product's world (audience, evidence, cultural material). +2. **Roll** (`node /scripts/concept-seed.mjs` or the installed skill's script): assign which candidate is built; deal challengers from the worlds deck. The dice refuse the argmax rut; they never touch an ungrounded idea. +3. Apply the **five tests** to every candidate — fail one, it dies: + - **Truth** — every relationship it visualizes exists in your product. + - **Translation** — strip the source's names/materials and a product-native relationship remains (else it is a costume). + - **Consequence** — removing its best move materially weakens the page. + - **Survival** — the signature works on the primary device within a real asset/time budget. + - **Fit** — its risk is an honest tradeoff, not a probable brief violation. +4. Write the **direction contract** into the artifact (see `templates/direction-contract.md`): `THESIS / OWN-WORLD / STORY / FIRST VIEWPORT / FORM`, <=150 words, five blocks. Keep the seed key for reproduction. +5. **Visualize** when image tooling is available: system board + first-surface mock, then build toward the image. If no native image tool, set `OPENAI_API_KEY` and render via gpt-image-2 (say so first — it spends the user's credit, ~5-25 cents each). + +## Re-roll rules + +- The user re-rolls freely, for any reason including taste. After two in a row, ask what quality is missing. +- The agent may only re-roll on named factual grounds (the assigned direction cannot carry the product's truth or the task). Its own taste is never grounds. +- In an unattended run, the assigned direction proceeds and assumptions are stated explicitly. diff --git a/.cursor/skills/impeccable-stinger/guides/03-iterate-phase.md b/.cursor/skills/impeccable-stinger/guides/03-iterate-phase.md new file mode 100644 index 00000000..c8354f25 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/03-iterate-phase.md @@ -0,0 +1,33 @@ +# 03 — Iterate Phase (bounded rounds) + +Derived from `research/03-command-vocabulary.md`, `research/08-live-mode.md`. + +## Named commands (when the edit has a name) + +- **Refine:** `polish` (final pass), `bolder` / `quieter` (voice), `distill` (subtraction), `typeset` (type hierarchy), `layout` (spacing/rhythm), `colorize` (strategic color), `animate` (purposeful motion), `delight` (personality), `overdrive` (past conventional limits). +- **Fix:** `clarify` (UX copy), `adapt` (devices/contexts), `optimize` (performance). +- **Harden:** `harden` (edge cases, i18n, errors, overflow), `onboard` (first-run, empty states). +- **Evaluate:** `critique` (design review with scoring, persona tests, automated detection). + +## Bounded-round discipline + +1. Build fully. +2. Inspect once in a batched round — desktop and mobile together, one render. +3. Fix everything the round shows in one batch. +4. Confirm with at most one more round. +5. Stop. Hand to the user for approval. The user is the "happy" gate. + +## Live Mode (opt-in, user-invoked only) + +- `/impeccable live` drops a picker on the running dev server: point at an element, type/draw a change, get 3 production-quality variants hot-swapped via HMR; accept one and it writes to source. +- **Never auto-launch it.** Launch only when the user asks to iterate visually ("show me live", "let me point at it"). +- Status: **alpha** — expect rough edges on uncommon setups. Prefer named commands for the default path. +- The non-intrusive live feedback during development is the **per-edit hook** (see `guides/07-hooks.md`), not live mode. + +## When to reach for which + +- Fix something "off" you can't name → `live` (user-invoked) or `critique`. +- Apply a specific discipline → `typeset` / `layout` / `colorize` / `animate`. +- Explore three directions side by side → `live` (user-invoked). +- Ask "is this any good?" → `critique`. +- Bring a safe design to life / tone a shouting one down → `bolder` / `quieter`. diff --git a/.cursor/skills/impeccable-stinger/guides/04-polish-phase.md b/.cursor/skills/impeccable-stinger/guides/04-polish-phase.md new file mode 100644 index 00000000..c6ead01a --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/04-polish-phase.md @@ -0,0 +1,22 @@ +# 04 — Polish Phase (pre-ship gauntlet) + +Derived from `research/03-command-vocabulary.md`, `research/06-detector-rules.md`. + +## The three commands before anything ships + +1. **`/impeccable audit `** — 5 dimensions scored 0-4: accessibility, performance, theming, responsive, anti-patterns. Findings tagged P0-P3. Point at a narrow target: one section reviewed closely beats a whole page at a glance. Native projects route to the native pass (VoiceOver, TalkBack, touch targets, platform conformance). +2. **`/impeccable clarify `** — rewrite the copy: labels, error messages, empty-state prose, microcopy, tuned to the audience from `PRODUCT.md`. +3. **`/impeccable harden `** — stress-test reality: 60-character names, German product titles, prices in the billions, 500s, offline. Production data is messy. + +## The deterministic gate (mandatory) + +- `npx impeccable detect ` — file, dir, or URL. Plain output groups by file with rule id, snippet, explanation; `--json` for scripts/CI. +- **Exit codes:** 0 = no findings; 2 = findings; 1 = command failed. CI fails the job on 2. +- DESIGN.md-aware: with a local `DESIGN.md`, enables design-system checks (fonts, literal colors, radii, font sizes). `--no-design-system` disables; `--scope type|layout` narrows. +- **Waivers:** narrowest form only — `npx impeccable ignores add-value --reason "..."`, `add-file `, or inline `impeccable-disable` comments in the file. A waiver without a reason is a failure. +- See `guides/06-detector-gate.md` for the full rule list and CI wiring. + +## Close-out + +- Findings resolved or explicitly waived → hand off to `security-worker-bee` first, then `quality-worker-bee`. Never quality before security. +- The gate result travels with the close-out (see `templates/gate-report.md`). diff --git a/.cursor/skills/impeccable-stinger/guides/05-maintain-phase.md b/.cursor/skills/impeccable-stinger/guides/05-maintain-phase.md new file mode 100644 index 00000000..24f2c88e --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/05-maintain-phase.md @@ -0,0 +1,22 @@ +# 05 — Maintain Phase (cohesion) + +Derived from `research/09-maintenance-doctor.md`. + +## The two commands that close the gap + +1. **`/impeccable extract `** — find patterns used 3+ times with the same intent; propose tokens and primitives; consolidate drift before it solidifies. +2. **`/impeccable document`** — re-capture the system: scans tokens, components, and rendered routes, writes `DESIGN.md` in Stitch format. The more it points at real components and live routes, the closer it reads your design language. + +## Doctor (three kinds of "out of date") + +- **Tool version** — installed skill older than published; `npx impeccable update` fixes. +- **Schema drift** — artifact written by an older Impeccable; mechanical, doctor repairs most of it. +- **Truth drift** — code moved on and the document no longer describes it; route to `init`/`document`, never auto-repair. + +`/impeccable doctor` also checks: config unknown keys, ignored rule ids that no longer exist, ignored file paths that are gone, `projectRoots` globs matching nothing, hook script paths that stopped resolving, orphaned surface briefs, and monorepo apps inheriting a web-only root record while carrying native build files. + +## Rules + +- **Never repair drift as a side effect of a design task.** A `CONTEXT_STALE` finding is reported, not acted on, unless the user asks (except `auto` findings). +- Run `npx impeccable check` / `update` on a cadence; the installed side self-updates, the stinger's vendored reference needs a manual refresh cadence. +- Every new element or surface inherits the established world unless the classification says greenfield; the detector's design-system rules mechanically flag drift. diff --git a/.cursor/skills/impeccable-stinger/guides/06-detector-gate.md b/.cursor/skills/impeccable-stinger/guides/06-detector-gate.md new file mode 100644 index 00000000..06c914f9 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/06-detector-gate.md @@ -0,0 +1,46 @@ +# 06 — Detector Gate (59 deterministic rules) + +Derived from `research/06-detector-rules.md`. + +## CLI usage + +```bash +npx impeccable detect src/ # scan a directory +npx impeccable detect src/components/Card.tsx # one file +npx impeccable detect https://example.com # rendered page (browser engine) +npx impeccable detect --json src/ # machine-readable +npx impeccable detect --scope type src/ # one design domain +npx impeccable detect --no-design-system src/ # raw scan +``` + +- **Exit codes:** 0 = no findings; 2 = findings detected; 1 = command failed. CI fails the job on 2. +- Engines: static-html (files + linked CSS), browser (URLs), regex/text (JSX/TSX/Vue/Svelte/Astro/CSS-in-JS). Server-side templates (Blade/ERB/Twig/Handlebars) need `detector.extensions` in `.impeccable/config.json`. +- Web only. Native projects route to `/impeccable audit` (native pass). + +## The 59 rules (id | category | severity) + +**slop (30):** side-tab, border-accent-on-rounded, overused-font, flat-type-hierarchy (error), gradient-text (error), ai-color-palette, cream-palette, nested-cards, monotonous-spacing, bounce-easing, pulsing-dot, blinking-cursor, shape-assembled-illustration, dark-glow, radial-halo, radial-spotlight-glow, marquee, icon-tile-stack, italic-serif-display, hero-eyebrow-chip, kicker-above-heading, numbered-section-labels, em-dash-overuse, marketing-buzzword, aphoristic-cadence, oversized-h1, extreme-negative-tracking, gpt-thin-border-wide-shadow, repeating-stripes-gradient, codex-grid-background, theater-slop-phrase, image-hover-transform. + +**quality (29):** broken-image, script-error, content-hidden-at-rest, edge-flush-cards, text-occlusion, first-viewport-column-overflow, gray-on-color, low-contrast, layout-transition, line-length, cramped-padding, body-text-viewport-edge, tight-leading, skipped-heading, heading-rhythm, justified-text, tiny-text, undersized-ui-text, all-caps-body, wide-tracking, text-overflow, repeated-container-text, clipped-overflow-container, design-system-font, design-system-color, design-system-radius, design-system-font-size. + +Severities: `error` (flat-type-hierarchy, gradient-text), `warning` (most), `advisory` (side-tab, overused-font, ai-color-palette, cream-palette, nested-cards, etc.). + +## DESIGN.md awareness + +With a local `DESIGN.md`, the detector enables the 4 design-system rules (font, color, radius, font-size outside the documented system) using `.impeccable/design.json` for richer token/ramp data. This is what makes product-token enforcement mechanical — it complements `design-system-stinger`/`ux-ui-stinger`. + +## Ignores & waivers + +- `npx impeccable ignores list|add-value|add-file|add-rule|remove-value`; `--local` for private; `--reason` for the why. +- Value ignores preferred for fonts/colors/radii/motion (keeps the rule useful elsewhere); wildcard value ignores only when scoped to a file. +- Inline comments travel with a file: ``, `impeccable-disable-line`, `impeccable-disable-next-line`. +- A waiver without a stated reason is a failure. The narrowest exception that matches the real reason is the only correct one. + +## CI wiring + +```bash +npx impeccable detect --json src/ > .impeccable/detect.json +# exit code 2 → fail the PR check; parse JSON for the findings list +``` + +Add to army projects' PR checks per the user decision (2026-08-06). diff --git a/.cursor/skills/impeccable-stinger/guides/07-hooks.md b/.cursor/skills/impeccable-stinger/guides/07-hooks.md new file mode 100644 index 00000000..939c3051 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/07-hooks.md @@ -0,0 +1,37 @@ +# 07 — Hooks (per-edit + deep pass) + +Derived from `research/07-hooks-enforcement.md`. + +## What the hook does + +- Scans direct edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). +- **Claude Code / GitHub Copilot / Codex:** post-tool-use — pushes a short system reminder after the edit; findings get a correction prompt, pending issues get a re-nudge, clean files get a short ack (unless `hook.quiet`). +- **Cursor:** `preToolUse` — blocks bad proposed writes before they land; silent when clean. +- Plain `.ts`/`.js` files are scanned but stay quiet unless the detector finds something. + +## Two speeds + +- **Per edit:** only what is objectively broken or compounds if ignored (broken images, overflow/clipped text, contrast failures, tiny text, gradient text, glow, DESIGN.md drift). +- **End of session (deep pass):** the full rule set across every UI file touched, minus what was already reported; a second stop is silent. Wired for Claude Code and Codex (native Stop hook); Cursor and Copilot keep the full detector per edit. +- `hook.perEditRules: "all"` restores full rules per edit (not recommended — it makes models more conservative). + +## Harness manifests & approval + +| Harness | Manifest | Notes | +|---|---|---| +| Claude Code | `.claude/settings.local.json` | gitignored, machine-local | +| GitHub Copilot | `.github/hooks/impeccable.json` | committed, team-shared | +| Codex | `.codex/hooks.json` | **requires `/hooks` approval after install/update** | +| Cursor | `.cursor/hooks.json` | confirm enabled in Settings → Hooks | +| Grok Build | `.grok/hooks/impeccable.json` | requires `/hooks-trust` or `--trust` | + +- Installer: `npx impeccable install|update`; `--no-hooks` skips; `--force` backs up malformed manifests as `.bak`. +- Config: `hook.enabled`, `hook.quiet`, `hook.auditLog` in `.impeccable/config.json`; consent in `.impeccable/config.local.json`. Env: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, `IMPECCABLE_HOOK_LOG`. + +## The failure mode to watch + +"A hook can look installed and scan nothing: if its script path stops resolving... the manifest still registers and no findings ever arrive. Silence reads as a clean codebase." `/impeccable doctor` checks for exactly this. Treat hook silence as suspicious, not as a clean pass. + +## Why this matters for the Bee + +Hooks are the "every time" enforcement: they fire on every UI edit regardless of routing discipline. They are the non-intrusive live feedback during development — the user sees findings as code is written, without live mode being a nuisance. diff --git a/.cursor/skills/impeccable-stinger/guides/08-live-mode.md b/.cursor/skills/impeccable-stinger/guides/08-live-mode.md new file mode 100644 index 00000000..518bbf75 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/08-live-mode.md @@ -0,0 +1,28 @@ +# 08 — Live Mode (opt-in browser iteration, alpha) + +Derived from `research/08-live-mode.md`. + +## What it is + +`/impeccable live` drops a picker onto the running dev server. The user points at any element, draws or types what they want, and gets **three production-quality variants** hot-swapped via HMR. Accepting one writes it back to source. + +- Requires a running dev server (localhost). +- **Status: alpha** — works end-to-end, but needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups. + +## When to use (user decision 2026-08-06) + +- **Opt-in, user-invoked only.** Never auto-launch it. The Bee launches it only when the user asks to iterate visually ("show me live", "let me point at it", "I want to see it in the browser"). +- Use it when: the user can't name what's off; they want to explore three directions side by side; they want to see the design live as code changes and point at issues before a PR. +- The default loop stays: named commands + bounded rounds + detector gate. + +## Session flow + +1. Confirm a dev server is running; start one if needed. +2. Launch `/impeccable live`; the picker is injected into the app. +3. User picks an element or steers the whole page; the Bee generates 3 variants. +4. User accepts one → it writes to source (manual edits are captured and committed via `live-commit-manual-edits.mjs`). +5. Run the detector gate on the accepted result before close-out. + +## Companion: Chrome extension + +The detector overlay runs on any live page (staging, competitor) — useful for review without touching the editor. diff --git a/.cursor/skills/impeccable-stinger/guides/09-native.md b/.cursor/skills/impeccable-stinger/guides/09-native.md new file mode 100644 index 00000000..3124a86e --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/09-native.md @@ -0,0 +1,24 @@ +# 09 — Native Surfaces (iOS / Android / adaptive) + +Derived from `research/10-native-platforms-harnesses.md`. + +## Rules + +- The detector is **web only** — it reads HTML and CSS. It has nothing to say about a native iOS/Android codebase. +- When `PRODUCT.md` declares `ios`, `android`, or `adaptive`: + - `/impeccable audit` runs the **native pass** (`audit.native.md`): VoiceOver, TalkBack, touch targets, platform conformance. + - `adapt` has a native variant (`adapt.native.md`). + - Per-platform rulebooks: `ios.md`, `android.md`. +- `init` detects the platform from codebase evidence and asks only when ambiguous; the platform is recorded in `PRODUCT.md`. + +## Harness builds (per-model tuning) + +- `npx impeccable install` auto-detects the harness and writes the right skill files (`.claude/skills/`, `.cursor/skills/`, `.codex/`, `.gemini/`, `.grok/`, etc.) plus provider-native hook manifests. +- Per-model rule tuning: the Gemini build kills image-on-hover motion; the Codex build refuses ghost-cards and over-rounding. The installed build may carry extra rules for the active model — expect that. +- `npx skills add pbakaus/impeccable` installs one shared build (functionally complete, not tailored). +- Claude Code plugin: `/plugin marketplace add pbakaus/impeccable`. GitHub Copilot: built in (Settings → Experimental). + +## Bee behavior + +- Default domain is web. Native surfaces route to the native playbooks and the native audit pass. +- The stinger is complete for any build: web, iOS, Android, adaptive (user decision 2026-08-06). diff --git a/.cursor/skills/impeccable-stinger/guides/10-install-and-verify.md b/.cursor/skills/impeccable-stinger/guides/10-install-and-verify.md new file mode 100644 index 00000000..3e527ebd --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/10-install-and-verify.md @@ -0,0 +1,42 @@ +# 10 — Install & Verify (hybrid scope) + +Derived from `research/07-hooks-enforcement.md`, `research/09-maintenance-doctor.md`, `research/10-native-platforms-harnesses.md`, `research/11-license-provenance.md`. + +## Global skill install (once per machine) + +```bash +npx impeccable install --scope=global --providers=codex,claude,cursor +``` + +- Makes `/impeccable` available in every army project (user decision 2026-08-06: global, not per-project, because the army works across many projects). +- Reload the harness afterward; `/impeccable` should appear in autocomplete. + +## Per-project setup (one-time, cheap) + +```bash +npx impeccable install # writes hook manifests + .impeccable/config.json +/impeccable init # writes PRODUCT.md +/impeccable document # writes DESIGN.md + .impeccable/design.json +``` + +- Hooks are **project-local by harness design** (`.codex/hooks.json`, `.claude/settings.json`, `.cursor/hooks.json`) — they cannot be global. Codex requires `/hooks` approval after install/update. +- Context files (`PRODUCT.md`, `DESIGN.md`, `.impeccable/`) are inherently per-project. + +## Verify + +- `/impeccable doctor` — checks schema drift, truth drift, broken hook paths, stale config, orphaned surface briefs, monorepo platform mismatches. +- A hook that looks installed but scans nothing is the failure you would never notice — doctor catches it. +- `npx impeccable check` / `update` — keep the installed system current. + +## CI gate (user decision 2026-08-06) + +```bash +npx impeccable detect --json src/ > .impeccable/detect.json # exit 2 fails the PR check +``` + +Add to army projects' PR checks. + +## Compliance + +- Build the stinger from the repo (Apache-2.0), not the site (robots.txt: `ai-train=no, use=reference`). Keep attribution. +- Never fork or modify the engine into the stinger; call the installed system. Follow the bee-army-update contract. diff --git a/.cursor/skills/impeccable-stinger/guides/11-sync-check.md b/.cursor/skills/impeccable-stinger/guides/11-sync-check.md new file mode 100644 index 00000000..72b8c9e4 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/guides/11-sync-check.md @@ -0,0 +1,43 @@ +# 11 — Pre-Flight Sync Check (upstream always in sync) + +Derived from `research/09-maintenance-doctor.md`, `research/11-license-provenance.md`, and the user decision (2026-08-06): "make sure the upstream is always in sync before a task is done. If it is current it is skipped." + +## The mechanism + +Before any design task starts, run the stinger's sync check: + +```bash +node .claude/skills/impeccable-stinger/scripts/sync-check.mjs +``` + +**Exit codes:** +- `0` — current and in sync → **skip**, proceed with the task. +- `2` — behind upstream and/or content drift → update/refresh before the task (see below). +- `1` — not installed or check failed → install first. + +## What it verifies + +1. **Installed skill present** — searches the harness skill dirs (`~/.agents/skills/impeccable`, `~/.codex/skills/impeccable`, `~/.claude/skills/impeccable`, `~/.claude/skills/impeccable`, and project-local equivalents). Codex's primary skill dir is `.agents/skills/`. +2. **Version currency** — reads the installed `SKILL.md` frontmatter `version:` and compares it to the published version at `https://impeccable.style/api/version` (same endpoint the skill's own `context.mjs` uses). Behind → `npx impeccable update`. +3. **Content coverage** — compares the installed skill's `reference/` files and `scripts/command-metadata.json` commands against the stinger's `scripts/upstream-manifest.json` (forged against upstream 4.0.4 / commit `aee6ce9`). New commands or reference files upstream → the stinger needs a refresh (new guide/template), not just an update. + +## When behind (exit 2) + +1. Run `npx impeccable update` (or `node .../sync-check.mjs --update`). **Note:** Codex may require `/hooks` re-approval after an update — tell the user. +2. If content drift: add the missing guide/template for the new command or reference file, then update `scripts/upstream-manifest.json` to the new version/commit. +3. Re-run the check → exit 0 → proceed. + +## When not installed (exit 1) + +```bash +npx impeccable install --scope=global --providers=codex,claude,cursor +``` + +Then per project: `npx impeccable install` (hooks) + `/impeccable init` + `/impeccable document` (context). See `guides/10-install-and-verify.md`. + +## Rules + +- The check is a **pre-flight gate**: run it before Phase 1, skip when current, never skip when behind. +- Never fork or modify the engine; the check only compares versions and file coverage. +- A stale stinger manifest is a real finding: upstream added content the Bee does not know how to operate. +- Report the result in the close-out (see `templates/sync-report.md`). diff --git a/.cursor/skills/impeccable-stinger/reports/README.md b/.cursor/skills/impeccable-stinger/reports/README.md new file mode 100644 index 00000000..8d036cab --- /dev/null +++ b/.cursor/skills/impeccable-stinger/reports/README.md @@ -0,0 +1,3 @@ +# reports/ + +Close-out reports from impeccable-worker-bee runs. Template: `gate-report-template.md`. Past runs accumulate here over time. diff --git a/.cursor/skills/impeccable-stinger/reports/gate-report-template.md b/.cursor/skills/impeccable-stinger/reports/gate-report-template.md new file mode 100644 index 00000000..d387c841 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/reports/gate-report-template.md @@ -0,0 +1,22 @@ +# Detector Gate Report + +| Field | Value | +|---|---| +| Target | `` | +| Command | `npx impeccable detect ` | +| Exit code | `0` (no findings) / `2` (findings) / `1` (failed) | +| Findings | `` | +| Resolved | `` | +| Waived | `` | + +## Findings + +| Rule id | Severity | File:line | Resolution (fix or waiver + reason) | +|---|---|---|---| +| `side-tab` | advisory | `src/components/Card.tsx:52` | Fixed — removed inset stripe | +| `overused-font` | advisory | `src/styles/global.css:14` | Waived — `ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md"` | + +## Verdict + +- [ ] Gate clean (0 findings) — close-out may proceed +- [ ] Gate failed (exit 2) — close-out blocked until resolved or waived diff --git a/.cursor/skills/impeccable-stinger/research/01-system-overview.md b/.cursor/skills/impeccable-stinger/research/01-system-overview.md new file mode 100644 index 00000000..eee5730b --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/01-system-overview.md @@ -0,0 +1,39 @@ +# 01 — System Overview + +**Source:** `README.md`, `PRODUCT.md`, `skill/SKILL.src.md`, `package.json`, `impeccable.style/designing` (reference) + +## What it is + +Impeccable is a design-guidance skill + toolchain for AI coding agents: "1 skill, 23 commands, live browser iteration, and 59 deterministic detector rules for AI-generated frontend design" (`README.md`). It started from Anthropic's `frontend-design` skill and adds a setup flow, a shared command vocabulary, and deterministic enforcement. + +- **License:** Apache-2.0 (`LICENSE`, `package.json` `"license": "Apache-2.0"`). +- **Runtime:** Node >= 22.18 (`package.json` `"engines"`). +- **Distribution:** npm package `impeccable` (bin `impeccable` → `cli/bin/cli.js`), installed per project via `npx impeccable install`, which writes harness-tailored builds (`.claude/`, `.cursor/`, `.codex/`, `.gemini/`, `.grok/`, `.trae/`, `.opencode/`, `.qoder/`, `.rovodev/` folders exist in the repo). +- **Per-model builds:** "builds for models with known tells carry extra slop rules banning that model's habits. The Gemini build kills its image-on-hover motion; the Codex build refuses ghost-cards and over-rounding" (`README.md`; ``/`` sections in `skill/reference/craft-floor.md`). + +## The seven layers (whole system) + +1. **Context contract** — `PRODUCT.md` (strategy) + `DESIGN.md` (visual system, Google Stitch format) + `.impeccable/surfaces/*.md` (per-surface mode/job/proof) + `.impeccable/design.json` (structured sidecar). Loaded by `skill/scripts/context.mjs` on every command. +2. **One vocabulary** — 23 commands under `/impeccable` (`skill/scripts/command-metadata.json`). v3.0 consolidated 18 standalone skills into one. +3. **Direction machinery** — new-work flow: job classification, five tests, direction contract, worlds deck + roll (`skill/scripts/concept-seed.mjs`, `skill/scripts/lib/concept-catalog.mjs`). +4. **Craft floor** — `skill/reference/craft-floor.md`: quality floor, absolute bans, reflexes, per-model sections. +5. **Deterministic enforcement** — 59 rules (`cli/engine/registry/antipatterns.mjs`), CLI `npx impeccable detect` (JSON, exit codes 0/2/1), hooks, Chrome extension, slop catalog. +6. **Live iteration** — `/impeccable live` (`skill/scripts/live/*`): browser picker, 3 variants per element, HMR, accept writes to source. Status: alpha. +7. **Maintenance** — `doctor` (tool/schema/truth drift), config/ignores, `update`/`check`, `extract`/`document`. + +## The four-phase loop (the Bee's core procedure) + +From `impeccable.style/designing` (reference; same content as the skill's routing): + +- **Start** — `init` (context) → `shape`/new-work (brief, direction, visualize, build). +- **Iterate** — named commands (`polish`, `bolder`, `typeset`, `layout`, `colorize`, `animate`, ...) or `live`; bounded rounds. +- **Polish** — pre-ship gauntlet: `audit` (5 dims, P0-P3), `clarify` (copy), `harden` (edge cases); detector gate in CI (`npx impeccable detect src/`, exit code fails the build). +- **Maintain** — `extract` (consolidate drift into tokens/primitives) + `document` (re-capture `DESIGN.md`) before debt solidifies. + +## Key evidence + +- "Verify in bounded passes, not a loop... Build fully, inspect once with a batched round (desktop and mobile together), fix everything it shows in one batch, confirm with at most one more round, and stop polishing. Open-ended self-QA burns the user's money" (`skill/SKILL.src.md`). +- "The brief wins. Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning" (`skill/SKILL.src.md`). +- "Refinement preserves; redesign replaces... Never split the difference into polish on the discarded look" (`skill/SKILL.src.md`). +- "Visual authority is evidence, not a filename. Missing DESIGN.md alone does not make a project greenfield" (`skill/SKILL.src.md`). +- "Running both Impeccable and Anthropic's frontend-design skill... Two skills with different design vocabularies collide and cancel each other out. Pick one" (`impeccable.style/designing`). diff --git a/.cursor/skills/impeccable-stinger/research/02-context-contract.md b/.cursor/skills/impeccable-stinger/research/02-context-contract.md new file mode 100644 index 00000000..d3fe7933 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/02-context-contract.md @@ -0,0 +1,28 @@ +# 02 — Context Contract (PRODUCT.md / DESIGN.md / surfaces / design.json) + +**Source:** `skill/scripts/context.mjs`, `skill/reference/init.md`, `skill/reference/document.md`, `skill/reference/context.md` (site), `impeccable.style/docs/context` (reference) + +## Files and roles + +| File | What it answers | Updated when | +|---|---|---| +| `PRODUCT.md` | Platform, users, purpose, positioning, evidence, brand commitments | Strategy changes | +| `DESIGN.md` | Colors, type stacks, components, radii, elevation, visual rules | Visual system changes | +| `.impeccable/surfaces/*.md` | One page/route: mode, job, proof sequence, chosen direction | Written by the work itself | +| `.impeccable/design.json` | Structured design data for automation (detector, hooks, Live Mode) | Regenerated by `document`; do not hand-edit | + +## Key rules + +- Every command reads both files before generating, plus the brief for the named surface (`skill/SKILL.src.md` Setup: "It loads PRODUCT.md, DESIGN.md, the matching surface brief, and native-platform guidance when applicable"). +- **Mode comes from the surface, not the product:** "A tool's landing page is still Persuade; a fashion house's documentation is still Read; a docs index is Read, not Persuade" (`skill/SKILL.src.md`). +- Four modes: **Persuade** (decides and acts; design is the product), **Operate** (completes a task; scanability outranks expression), **Read** (understands; comprehension first), **Experience** (inside the work; artifact leads, interface recedes) (`skill/SKILL.src.md` lines 35-38). +- `init` scans the codebase, forms its own read of platform/product, asks only what it could not work out, writes `PRODUCT.md`, and offers `DESIGN.md` when code exists. It does not ask about colors/type — those are decided with the surface (`skill/reference/init.md`). +- `document` auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language; writes `DESIGN.md` in the **Google Stitch format** so the file is tool-compatible (`skill/scripts/command-metadata.json`). +- `context.mjs` also performs a staleness check against `https://impeccable.style/api/version` (`skill/scripts/context.mjs` line 77, 1007) and can emit a `CONTEXT_STALE` directive; "Never repair drift as a side effect of a design task" (`skill/SKILL.src.md`). +- `PRODUCT.md` carries a schema stamp; `DESIGN.md` follows the external design.md spec and gets no stamp (`skill/reference/doctor.md`). + +## Evidence for the stinger + +- The Bee owns these files per project; they are the source of truth every phase reads. +- A missing `DESIGN.md` does not make a project greenfield: "Coherent code, type choices, and component behavior are authority whether or not anyone wrote them down. Scaffolds, framework defaults, and stray utility classes are not" (`skill/reference/new-work.md`). +- If implementation is coherent but undocumented, extract invariants, confirm with the user, write `DESIGN.md` before going further (`skill/reference/new-work.md`). diff --git a/.cursor/skills/impeccable-stinger/research/03-command-vocabulary.md b/.cursor/skills/impeccable-stinger/research/03-command-vocabulary.md new file mode 100644 index 00000000..e030359f --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/03-command-vocabulary.md @@ -0,0 +1,53 @@ +# 03 — Command Vocabulary (23 commands) + +**Source:** `skill/scripts/command-metadata.json`, `skill/SKILL.src.md`, `impeccable.style/docs` (reference) + +All commands run through `/impeccable `; `pin`/`unpin` creates standalone shortcuts (e.g., `/audit`). Commands grouped by intent (from `command-metadata.json`): + +## Create +- `impeccable` — next-step recommendation or plain-English design work; inspects project state, recommends 2-3 commands, asks before running. +- `shape` — "Think before you build. Produce a design brief through discovery, not guesswork." +- `init` — one-time setup: discovery interview, writes `PRODUCT.md`, offers `DESIGN.md`, pre-configures live mode, recommends next commands. +- `document` — generate a spec-compliant `DESIGN.md` (Google Stitch format) from existing code. +- `extract` — pull reusable patterns, components, and tokens into the design system (drift consolidation). + +## Evaluate +- `audit` — 5-dimension technical quality check (a11y, performance, theming, responsive, anti-patterns), scored 0-4, findings P0-P3. Native variant: `audit.native`. +- `critique` — design review with scoring, persona tests, and automated detection. + +## Refine +- `polish` — "The meticulous final pass between good and great." +- `bolder` / `quieter` — amplify safe designs / tone down shouting designs (two halves of voice). +- `distill` — ruthless subtraction; strip to essence. +- `animate` — purposeful motion that conveys state, not decoration. +- `colorize` — strategic color for monochrome UIs. +- `typeset` — fix typography hierarchy and fonts. +- `layout` — fix layout, spacing, visual rhythm. +- `delight` — small moments of personality. +- `overdrive` — push past conventional limits (shaders, physics, 60fps, cinematic transitions). + +## Simplify / Fix +- `adapt` — cross-device/context adaptation (breakpoints, fluid layouts, touch targets). Native variant: `adapt.native`. +- `clarify` — rewrite confusing UX copy. +- `optimize` — diagnose and fix UI performance (LCP to bundle size). + +## Harden +- `harden` — production-ready: edge cases, i18n, error states, overflow. +- `onboard` — first-run flows, empty states, activation paths. + +## System +- `live` — interactive live variant mode (browser picker, 3 variants, HMR, accept writes to source). Alpha. +- `hooks` — manage the design detector hook (`on|off|status|ignore-rule|ignore-file|ignore-value|reset`). +- `doctor` — report/repair drift between project artifacts and what this version reads. + +## Routing rules (`skill/SKILL.src.md`) + +- No argument → read `routing.md`, present context-aware menu; never auto-run a command. +- Explicit or clearly implied command → load its reference and follow it; ask once if two fit. +- Otherwise → treat as general design work; missing `PRODUCT.md` routes new surfaces through `init` then `new-work`; narrow refinement proceeds on the incumbent implementation. +- `teach` aliases `init`; `craft` is a deprecated alias for ordinary new-work. + +## Evidence for the stinger + +- The Bee's procedure maps the four phases to these commands: Start (`init`/`shape`/new-work), Iterate (refine commands + `live`), Polish (`audit`/`clarify`/`harden` + detector gate), Maintain (`extract`/`document`/`doctor`/`hooks`). +- Pin only 2-3 daily commands; pinning everything re-explodes the `/` menu (`impeccable.style/designing`). diff --git a/.cursor/skills/impeccable-stinger/research/04-new-work-direction.md b/.cursor/skills/impeccable-stinger/research/04-new-work-direction.md new file mode 100644 index 00000000..595fa14f --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/04-new-work-direction.md @@ -0,0 +1,51 @@ +# 04 — New-Work Direction Machinery (classification, five tests, direction contract, roll) + +**Source:** `skill/reference/new-work.md`, `skill/scripts/concept-seed.mjs`, `skill/scripts/lib/concept-catalog.mjs`, `impeccable.style/research` (reference) + +## Job classification + +- **Greenfield** — no coherent visual implementation; a world gets established. +- **Local extension** — a section/component inside a page that already works; only the new part is decided; the page's world is inherited. +- **New surface** — a whole page/flow inside an established world; composition open, world not. +- **Expression expansion** — an established brand entering a surface family it never resolved; a range is approved and merged into `DESIGN.md`. +- **Redesign or rebrand** — the look is replaced; product facts, content, function, constraints are not. +- **Refinement** — better, not different; leaves this flow for a scoped command like `polish`. + +"Redesign this page" authorizes replacement (old look becomes evidence and anti-reference). "Redesign this within our current system" is an extension. Ask once when genuinely ambiguous; never split the difference. + +## The five tests (every candidate must pass all) + +1. **Truth** — every relationship it visualizes exists in your product. Resemblance is not evidence. +2. **Translation** — strip the source's names and materials and a product-native relationship remains; otherwise it is a costume. +3. **Consequence** — removing its best move materially weakens the page. +4. **Survival** — the signature still works on the primary device, within a real asset and time budget. +5. **Fit** — its risk is an honest tradeoff, not a probable violation of your brief. + +## The direction contract (written into the artifact, <=150 words, five blocks) + +- `THESIS` — the one idea this page owns, and the category default it refuses. +- `OWN-WORLD` — palette and component language, recognizable with all content removed. +- `STORY` — what the visitor understands, believes, and does. +- `FIRST VIEWPORT` — the exact composition and where the primary action sits. +- `FORM` — the chosen form and the seed key. + +The contract exists so intent is inspectable and a **separate reviewer agent** can audit the built page against it promise-by-promise. "A page that promised a radical composition and shipped the usual template does not pass quietly" (`skill/reference/new-work.md`). + +## The roll / dice (external variance) + +- Problem (measured): "Ask a coding model for something creative and it builds its favorite idea, every run. Sixteen different 'be creative' framings returned the identical concept in thirty of thirty-five runs" (`skill/reference/new-work.md`; `impeccable.style/research`). +- Fix: a script rolls which of the model's own resonance-ordered shortlist gets built, and deals challengers from a reviewed catalog of ~188 visual worlds (`concept-seed.mjs` header; site says 177-188 worlds). +- "The dice never touch an ungrounded idea. They only refuse the argmax rut" (`concept-seed.mjs`). +- Re-roll: user re-rolls freely; the agent may only re-roll on named factual grounds (assigned direction cannot carry the product's truth or the task). "Its own taste is never grounds." +- Reproduction: the script prints a seed key; `--reroll ` recomputes prior rounds and excludes them. +- Fallback chain: local catalog (`IMPECCABLE_CATALOG_DIR`) → roll API (`https://impeccable.style/api`, `IMPECCABLE_API_URL`) → degraded local mode (`concept-seed.mjs` lines 63-99). + +## Research lessons (from `impeccable.style/research`, reference) + +1. The model lacks variance, not creativity (30/35 identical concepts). +2. Rejection advances a queue — "be different" lands on the #2 idea. +3. Argmax is deterministic; dice must **assign** the index, not nominate a menu (27/30 revert to option 1 when a chooser is involved). +4. Derivation is bounded by the subject's cultural depth; assigned foreign forms win over thin categories. +5. Anti-gimmick guards are the ceiling — commit first, then clarify (biggest single quality jump). +6. Committed skin hides template bones — "borrow the form's skeleton, not its clothes"; skin-blind review is a review instrument, never the builder grading itself. +7. Models describe brilliantly and build conservatively — hold them to the direction contract with a fresh reviewer. diff --git a/.cursor/skills/impeccable-stinger/research/05-craft-floor.md b/.cursor/skills/impeccable-stinger/research/05-craft-floor.md new file mode 100644 index 00000000..9238cc34 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/05-craft-floor.md @@ -0,0 +1,32 @@ +# 05 — Craft Floor (quality floor, bans, reflexes) + +**Source:** `skill/reference/craft-floor.md` (verbatim structure) + +Loaded immediately before editing UI (not for planning-only work). "A pinned brief or the committed visual world overrides anything here; your own habit does not." + +## Verify (checks on the built result, run together in batched rounds) + +- **Contrast:** body/placeholder >= 4.5:1, large text >= 3:1; on colored surfaces tint secondary text from that hue or the foreground; never gray. +- **Depth:** shadows carry an offset and a soft blur; a zero-offset colored halo is decoration. +- **Spacing:** tight groups, generous separation, more space above a heading than below it; read computed values. +- **Type:** body measure 65-75ch, display max 6rem, tracking floor -0.04em, balanced headings, obvious scale/weight steps; run real copy at every breakpoint. +- **Motion:** one authored moment, not scattered effects; exponential ease-out from an already-visible default; reach past transform/opacity (blur, backdrop-filter, clip-path, mask, shadow). +- **States:** hover, disabled, loading, error, empty; real content, working controls, responsive composition, keyboard focus. +- **Browser surfaces:** text selection, caret, custom scrollbars, focus rings, underline offset, tabular numerals — "the cheapest signal that a page was built rather than assembled, and the one models skip most reliably." +- **Copy:** the product's own language; controls name their action; errors name the problem and the recovery. +- **Coverage:** every brief requirement present and findable within seconds. + +## Refuse (category defaults, not bans — the brief's own words can earn any of them) + +Page scaffolds: same-size icon+heading+text card grids (cards are the lazy container; nested cards always wrong); hero-metric template; kicker/eyebrow above a heading (a ban, not a default); section numbers 01/02/03 unless the sequence carries information; modal for a task needing neither interruption nor protected focus. + +Surface habits: gradient text; glass/blur as decoration; colored `border-left`/`border-right` above 1px; hard offset shadows outside a real neobrutalist world; sparklines/progress rings/soft-shadowed rounded rectangles standing in for content; monospace as a "technical" costume; system display faces as the display voice; unicode glyphs/emoji standing in for an icon system; light/dark picked by category instead of use scene. + +## Per-model sections + +- ``: tracking stops at -0.04em (-0.02 to -0.03 usually reads better); declare elevation once (border or shadow — 1px border under a wide soft shadow is the ghost card); card radii 12-16px, pills for small controls; real illustration or none (bans sketch-style SVG, `loose-sketch`/`doodle` class names, `feTurbulence` grain); backgrounds are surfaces (bans `repeating-linear-gradient` stripes and two-axis grid overlays without a real canvas/map/blueprint); claims come from supplied truth, label illustrative values honestly. +- ``: never animate an image on hover, directly or through its parent; give the container the feedback. + +## Closing principle + +"The floor holds the mechanics; it never picks the direction. With every check green, spend the page on the committed world, and when torn between refined and committed, commit." diff --git a/.cursor/skills/impeccable-stinger/research/06-detector-rules.md b/.cursor/skills/impeccable-stinger/research/06-detector-rules.md new file mode 100644 index 00000000..c42b75fd --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/06-detector-rules.md @@ -0,0 +1,84 @@ +# 06 — Detector Rules (59 deterministic rules) + +**Source:** `cli/engine/registry/antipatterns.mjs` (authoritative), `impeccable.style/slop` (public catalog, reference) + +## Engine facts + +- 59 rules, each with `id`, `category` (`slop` | `quality`), `severity` (`error` | `warning` | `advisory`). +- Runs via `npx impeccable detect `; plain output groups by file with rule id, snippet, explanation; `--json` for scripts/CI. +- **Exit codes:** 0 = no findings; 2 = findings detected; 1 = command failed. CI fails the job on 2. +- Engines: static-html (`engines/static-html/detect-html.mjs`), browser/URL (`engines/browser/detect-url.mjs`), regex/text for CSS-in-JS and framework files (`engines/regex/detect-text.mjs`), plus `node/file-system.mjs` (walk, import graph, framework config detection). +- DESIGN.md-aware: when a local `DESIGN.md` exists, enables design-system checks (fonts, literal colors, radii, font sizes) using `.impeccable/design.json` for richer token/ramp data. `--no-design-system` disables; `--scope type|layout` narrows. +- Ignores: `npx impeccable ignores ...` (shared `config.json` / local `config.local.json`), inline `impeccable-disable` / `-line` / `-next-line` comments. +- Web only: native projects route to `/impeccable audit` (native pass). + +## Full rule list (id | category | severity) + +### slop (30) +side-tab | slop | advisory — thick colored border on one side of a card (most recognizable AI tell) +border-accent-on-rounded | slop | advisory — accent border clashes with radius +overused-font | slop | advisory — Inter, Geist, Space Grotesk, Instrument Serif, etc. +flat-type-hierarchy | slop | error — font sizes too close (aim >= 1.25 ratio) +gradient-text | slop | error — decorative gradient text +ai-color-palette | slop | advisory — purple/violet gradients, cyan-on-dark +cream-palette | slop | advisory — warm cream/beige default surface +nested-cards | slop | advisory — cards inside cards +monotonous-spacing | slop | advisory — same spacing everywhere +bounce-easing | slop | advisory — bounce/elastic easing on interface elements +pulsing-dot | slop | advisory — decorative pulse on static status +blinking-cursor | slop | advisory — fake caret on non-editable hero copy +shape-assembled-illustration | slop | advisory — sketch-style SVG scenes +dark-glow | slop | warning — dark bg with colored box-shadow glows +radial-halo | slop | warning — saturated radial glow on dark page +radial-spotlight-glow | slop | warning — accent haze behind a section +marquee | slop | warning — auto-scrolling marquee +icon-tile-stack | slop | warning — rounded-square icon tile above heading +italic-serif-display | slop | warning — oversized italic serif hero +hero-eyebrow-chip | slop | warning — tiny uppercase label above hero headline +kicker-above-heading | slop | warning — tracked uppercase label above heading +numbered-section-labels | slop | warning — tiny 01/02/03 labels +em-dash-overuse | slop | warning +marketing-buzzword | slop | warning +aphoristic-cadence | slop | warning +oversized-h1 | slop | warning — full-sentence headline at display size +extreme-negative-tracking | slop | warning — crushed letter spacing +gpt-thin-border-wide-shadow | slop | warning — hairline border + wide diffuse shadow (ghost card) +repeating-stripes-gradient | slop | warning — decorative stripe backgrounds +codex-grid-background | slop | warning — two-axis grid overlays without a real canvas +theater-slop-phrase | slop | warning — "x-theater" naming/irony +image-hover-transform | slop | warning — image animated on hover (Gemini-tuned rule) + +### quality (29) +broken-image | quality | warning +script-error | quality | warning +content-hidden-at-rest | quality | warning +edge-flush-cards | quality | warning — scroller cards lose one edge +text-occlusion | quality | warning — opaque layer covers readable text +first-viewport-column-overflow | quality | warning +gray-on-color | quality | warning — gray text on colored background +low-contrast | quality | warning +layout-transition | quality | warning +line-length | quality | warning — > ~80ch +cramped-padding | quality | warning +body-text-viewport-edge | quality | warning +tight-leading | quality | warning +skipped-heading | quality | warning +heading-rhythm | quality | warning — heading closer to previous block than its content +justified-text | quality | warning +tiny-text | quality | warning +undersized-ui-text | quality | warning — functional text under 11px +all-caps-body | quality | warning +wide-tracking | quality | warning +text-overflow | quality | warning +repeated-container-text | quality | warning +clipped-overflow-container | quality | warning — positioned child clipped by overflow container +design-system-font | quality | warning — font outside DESIGN.md +design-system-color | quality | warning — literal color outside DESIGN.md palette +design-system-radius | quality | warning — radius outside documented shape scale +design-system-font-size | quality | warning — font size between documented steps + +## Evidence for the stinger + +- The gate is the Bee's mandatory close-out step: `npx impeccable detect `; exit code 2 fails until resolved or explicitly waived (narrowest ignore + reason). +- The 4 design-system rules make product-token enforcement mechanical — they complement `design-system-stinger`/`ux-ui-stinger`. +- Verified live during research: `node cli/bin/cli.js detect tests/fixtures` returned line-numbered findings (side-tab, design-system-color, etc.) with remediation text. diff --git a/.cursor/skills/impeccable-stinger/research/07-hooks-enforcement.md b/.cursor/skills/impeccable-stinger/research/07-hooks-enforcement.md new file mode 100644 index 00000000..5282b89b --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/07-hooks-enforcement.md @@ -0,0 +1,41 @@ +# 07 — Hooks & Enforcement (per-edit + deep pass) + +**Source:** `skill/reference/hooks.md`, `skill/scripts/hook-admin.mjs`, `skill/scripts/hook-lib.mjs`, `impeccable.style/docs/hooks` (reference) + +## What the hook does + +- Scans direct edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). +- **Claude Code, GitHub Copilot, Codex:** post-tool-use hook pushes a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, clean UI-ish files get a short ack (unless `hook.quiet`). +- **Cursor:** `preToolUse` blocks bad proposed writes before they land; silent when it allows a clean write. +- Plain `.ts`/`.js` files are scanned but stay quiet unless the detector finds something. + +## Two speeds + +- **Per edit:** only what is objectively broken or compounds if ignored (broken images, overflow/clipped text, contrast failures, tiny text, gradient text, glow, DESIGN.md drift). +- **End of session (deep pass):** the full rule set across every UI file touched, minus what was already reported; a second stop is silent (findings remembered). Wired for Claude Code and Codex (native Stop hook); Cursor and Copilot keep the full detector per edit. +- Rationale: "Reporting every rule on every edit made models measurably more conservative rather than more careful" (one copy-level rule fired ~97x in a single session). +- `hook.perEditRules: "all"` restores full rules per edit. + +## Harness manifests & approval + +- Claude Code: `.claude/settings.local.json` (gitignored, machine-local). +- GitHub Copilot: `.github/hooks/impeccable.json` (committed, team-shared; activates on default branch). +- Codex: `.codex/hooks.json` — **requires one extra approval step**: open `/hooks` in Codex and approve the project hook; updates that change the hook definition can require approval again. +- Cursor: `.cursor/hooks.json`; confirm hooks enabled in Cursor Settings → Hooks. +- Installer/updater: `npx impeccable install|update`; `--no-hooks` skips hook setup; `--force` backs up malformed manifests as `.bak`. + +## Config & env + +- `hook.enabled`, `hook.quiet`, `hook.auditLog` (NDJSON) in `.impeccable/config.json`; per-developer consent in `.impeccable/config.local.json`. +- Env overrides: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, `IMPECCABLE_HOOK_LOG`. +- Detector filters live under `detector` (shared by hook and CLI): `ignoreRules`, `ignoreFiles`, `ignoreValues`, `designSystem.enabled`. +- Server-side templates: declare under `detector.extensions` (e.g., `{ "ext": ".blade.php", "engine": "html" }`). + +## Failure mode to watch + +"A hook can look installed and scan nothing: if its script path stops resolving... the manifest still registers and no findings ever arrive. Silence reads as a clean codebase." `/impeccable doctor` checks for exactly this (`skill/reference/hooks.md`). + +## Evidence for the stinger + +- The Bee verifies hook health (`doctor`) and treats hook silence as suspicious, not as a clean pass. +- Hooks are the "every time" enforcement: they fire on every UI edit regardless of routing discipline. diff --git a/.cursor/skills/impeccable-stinger/research/08-live-mode.md b/.cursor/skills/impeccable-stinger/research/08-live-mode.md new file mode 100644 index 00000000..41709208 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/08-live-mode.md @@ -0,0 +1,23 @@ +# 08 — Live Mode (browser iteration) + +**Source:** `skill/reference/live.md`, `skill/reference/live-setup.md`, `skill/scripts/live/*`, `impeccable.style/docs/live` (reference) + +## What it is + +`/impeccable live` drops a picker onto the running dev server. The user points at any element, draws or types what they want, and gets **three production-quality variants** hot-swapped via HMR. Accepting one writes it back to source. + +- Requires a running dev server (localhost). +- Status: **alpha** — "works end-to-end and is ready to try, but it still needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups" (`impeccable.style/docs/live`). +- Scripts: `skill/scripts/live/*` (live.mjs, live-accept.mjs, live-complete.mjs, live-poll.mjs, live-status.mjs, live-wrap.mjs, live-target.mjs, live-resume.mjs, live-browser.js, live-inject.mjs, live-insert.mjs, live-copy-edit-agent.mjs, live-commit-manual-edits.mjs, live-manual-edit-evidence.mjs, live-discard-manual-edits.mjs, live-browser-dom.js, live-browser-session.js, live/manual-edits-buffer.mjs, live/vocabulary.mjs, live/svelte-ast.mjs, live/event-validation.mjs, live/insert-ui.mjs, live/manual-apply.mjs, live/completion.mjs, live/poll-lanes.mjs, live/accept-css.mjs, live/roots.mjs). +- `live-browser.js` is ~500KB (bundled browser automation). + +## When to reach for it + +- Fix something "off" you can't name. +- Explore three directions side by side. +- Point-at-it iteration beats command-naming when the user doesn't know the design word. + +## Evidence for the stinger + +- Live Mode is an Iterate-phase tool, not the core loop. Given alpha status, the Bee should treat it as optional/experimental and prefer named commands for the default path. +- Accept writes to source; manual edits are captured and committed via `live-commit-manual-edits.mjs`. diff --git a/.cursor/skills/impeccable-stinger/research/09-maintenance-doctor.md b/.cursor/skills/impeccable-stinger/research/09-maintenance-doctor.md new file mode 100644 index 00000000..35f24025 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/09-maintenance-doctor.md @@ -0,0 +1,37 @@ +# 09 — Maintenance: Doctor, Config, Ignores, Update + +**Source:** `skill/reference/doctor.md`, `skill/reference/hooks.md`, `skill/scripts/doctor.mjs`, `impeccable.style/docs/doctor`, `impeccable.style/docs/config` (reference) + +## Doctor — three kinds of "out of date" + +1. **Tool version** — installed skill older than published; reported at boot; `npx impeccable update` fixes. +2. **Schema drift** — artifact written by an older Impeccable (fields nothing reads, fields now expected, retired locations). Mechanical; doctor repairs most of it. This is doctor's job. +3. **Truth drift** — code moved on and the document no longer describes it. Routed to `init`/`document`, not repaired. + +## What doctor checks + +- `PRODUCT.md` schema stamp (vintage, not release version). +- `DESIGN.md` (no stamp — follows external design.md spec) and the `.impeccable/design.json` sidecar (older than DESIGN.md, outdated schema, legacy path). +- Config: unknown keys, unknown detector keys, ignored rule ids that no longer exist, ignored file paths that are gone, `projectRoots` globs matching nothing. +- Design hook: script path that stopped resolving; enabled/disabled conflict. +- Surface briefs: records orphaned from the file/route they describe. +- Monorepos: which apps carry their own `PRODUCT.md`/`DESIGN.md` vs inherit the root's; flags a workspace with native build files inheriting a web-only root record. + +## Config & ignores + +- `.impeccable/config.json` (shared, commit when team intent) + `.impeccable/config.local.json` (private, gitignored). +- `npx impeccable ignores list|add-value|add-file|add-rule|remove-value`; `--local` for private; `--reason` for the why. +- Value ignores preferred for fonts/colors/radii/motion (keeps the rule useful elsewhere); wildcard value ignores only when scoped to a file. +- Inline comments travel with a file: ``, `impeccable-disable-line`, `impeccable-disable-next-line`. +- `projectRoots` for repos where design boundaries don't line up with package-manager workspaces. +- A config file fails quietly when wrong (misspelled key never read; stale rule id suppresses nothing) — doctor catches all three. + +## Update flow + +- `npx impeccable check` (behind?) → `npx impeccable update` (from project root); plugin users update from `/plugin` menu; `npx skills update` for the shared build. +- `stalenessCheck: false` in config or `IMPECCABLE_NO_STALENESS_CHECK=1` silences the boot notice; `doctor` still works. + +## Evidence for the stinger + +- Maintain phase = `extract` (consolidate drift) + `document` (re-capture system) + `doctor` (schema/truth/tool drift) + `check`/`update` (upstream). +- "Never repair drift as a side effect of a design task" — a `CONTEXT_STALE` finding is reported, not acted on, unless the user asks (`skill/SKILL.src.md`). diff --git a/.cursor/skills/impeccable-stinger/research/10-native-platforms-harnesses.md b/.cursor/skills/impeccable-stinger/research/10-native-platforms-harnesses.md new file mode 100644 index 00000000..96b1ff82 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/10-native-platforms-harnesses.md @@ -0,0 +1,23 @@ +# 10 — Native Platforms & Harness Builds + +**Source:** `skill/reference/ios.md`, `skill/reference/android.md`, `skill/reference/audit.native.md`, `skill/reference/adapt.native.md`, `docs/HARNESSES.md`, repo `.claude/ .cursor/ .codex/ .gemini/ .grok/ .trae/ .opencode/ .qoder/ .rovodev/` builds + +## Native (iOS / Android / adaptive) + +- The detector is **web only** ("The engine reads HTML and CSS, so it has nothing to say about a native iOS or Android codebase" — `impeccable.style/docs/detector`). +- When `PRODUCT.md` declares `ios`, `android`, or `adaptive`, `/impeccable audit` runs a native pass covering VoiceOver, TalkBack, touch targets, and platform conformance (`audit.native.md`); `adapt` has a native variant (`adapt.native.md`). +- `init` detects the platform from codebase evidence and asks only when ambiguous; platform is recorded in `PRODUCT.md`. +- Native guidance files: `ios.md`, `android.md` (per-platform rulebooks). + +## Harness builds + +- `npx impeccable install` auto-detects the harness and writes the right skill files (`.claude/skills/`, `.cursor/skills/`, `.codex/`, `.gemini/`, `.grok/`, etc.), plus provider-native hook manifests where supported. +- Per-model rule tuning: the Gemini build kills image-on-hover motion; the Codex build refuses ghost-cards and over-rounding (`README.md`; ``/`` sections in `craft-floor.md`). +- `npx skills add pbakaus/impeccable` installs one shared build for every harness (functionally complete, not tailored). +- Claude Code plugin: `/plugin marketplace add pbakaus/impeccable`. +- GitHub Copilot: Impeccable is built in (Settings → Experimental). + +## Evidence for the stinger + +- The Bee's default domain is web; native surfaces route to the native playbooks and the native audit pass. +- The stinger should note the per-model build behavior so the Bee knows the installed build may carry extra rules for its model. diff --git a/.cursor/skills/impeccable-stinger/research/11-license-provenance.md b/.cursor/skills/impeccable-stinger/research/11-license-provenance.md new file mode 100644 index 00000000..409c38f8 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/11-license-provenance.md @@ -0,0 +1,27 @@ +# 11 — License, Provenance & Versioning + +**Source:** `LICENSE`, `NOTICE.md`, `package.json`, `README.md`, `impeccable.style/robots.txt` + +## License + +- **Apache-2.0** (`LICENSE`; `package.json` `"license": "Apache-2.0"`; `cli/engine/detect-antipatterns.mjs` header: "SPDX-License-Identifier: Apache-2.0"). +- Vendoring guidance content into the stinger is license-clean with attribution. Keep the NOTICE/attribution (`NOTICE.md` exists in the repo). +- Author: Paul Bakaus. Homepage: impeccable.style. npm: `impeccable`. + +## Site content signals (compliance) + +- `impeccable.style/robots.txt`: `Content-Signal: search=yes, ai-train=no, use=reference` (Cloudflare managed; also disallows GPTBot, ClaudeBot, CCBot, etc.). +- Implication: the stinger must be built from the **repo** (Apache-2.0), not scraped from the site. Site text is reference-only for understanding, not a training/vendoring source. + +## Versioning + +- Repo `package.json`: `3.5.0` (npm package version). Site markets **v4** ("A leaner core, tuned on frontier models like Fable and GPT-5.6-Sol. Four visitor modes."). +- Content is in sync: the repo's `SKILL.src.md` has all four modes (Persuade/Operate/Read/Experience); the site docs are generated from the repo's `skill/reference/` files. +- Upstream is actively maintained (repo HEAD `aee6ce9`, 2026-08-04; sitemap lastmods through 2026-07-22). +- Implication: the stinger's vendored reference docs need a refresh cadence; the installed side self-updates via `npx impeccable check`/`update`. + +## Research provenance + +- Clone: `/tmp/impeccable-RZVWdD` (shallow, depth 1, commit `aee6ce9`). +- Detector verified live: `node cli/bin/cli.js detect tests/fixtures` produced line-numbered findings (side-tab, design-system-color, etc.). +- Site pages fetched for reference: `/`, `/docs*`, `/slop`, `/research`, `/designing`, `/cases/neo-mirai`, `/tutorials/*`. diff --git a/.cursor/skills/impeccable-stinger/research/index.md b/.cursor/skills/impeccable-stinger/research/index.md new file mode 100644 index 00000000..40547606 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/index.md @@ -0,0 +1,26 @@ +# Research Index — impeccable-stinger + +Manifest of primary-source research for `impeccable-worker-bee`. All files cite repo paths under `/tmp/impeccable-RZVWdD` (github.com/pbakaus/impeccable, commit aee6ce9, Apache-2.0). + +| File | Covers | Primary sources | +|---|---|---| +| `research-plan.md` | Scope, depth, method, provenance | Command Brief, repo | +| `01-system-overview.md` | Whole system: 7 layers, four-phase loop, per-model builds | `README.md`, `PRODUCT.md`, `skill/SKILL.src.md`, `package.json`, site `/designing` | +| `02-context-contract.md` | PRODUCT.md / DESIGN.md / surfaces / design.json, modes | `skill/scripts/context.mjs`, `skill/reference/init.md`, `document.md`, site `/docs/context` | +| `03-command-vocabulary.md` | 23 commands, routing rules, pinning | `skill/scripts/command-metadata.json`, `skill/SKILL.src.md`, site `/docs` | +| `04-new-work-direction.md` | Classification, five tests, direction contract, roll/dice, research lessons | `skill/reference/new-work.md`, `skill/scripts/concept-seed.mjs`, `lib/concept-catalog.mjs`, site `/research` | +| `05-craft-floor.md` | Quality floor, bans, reflexes, per-model sections | `skill/reference/craft-floor.md` | +| `06-detector-rules.md` | 59 rules (id/category/severity), CLI, exit codes, engines, ignores | `cli/engine/registry/antipatterns.mjs`, `cli/engine/*`, site `/slop` | +| `07-hooks-enforcement.md` | Per-edit + deep pass, harness manifests, approval, config | `skill/reference/hooks.md`, `skill/scripts/hook-admin.mjs`, `hook-lib.mjs`, site `/docs/hooks` | +| `08-live-mode.md` | Live browser iteration, alpha status, scripts | `skill/reference/live.md`, `skill/scripts/live/*`, site `/docs/live` | +| `09-maintenance-doctor.md` | Doctor (tool/schema/truth drift), config, ignores, update | `skill/reference/doctor.md`, `skill/scripts/doctor.mjs`, site `/docs/doctor`, `/docs/config` | +| `10-native-platforms-harnesses.md` | iOS/Android/adaptive, per-harness builds, per-model rules | `skill/reference/ios.md`, `android.md`, `audit.native.md`, `adapt.native.md`, `docs/HARNESSES.md` | +| `11-license-provenance.md` | Apache-2.0, site content signals, versioning, research provenance | `LICENSE`, `NOTICE.md`, `package.json`, site `robots.txt` | + +## Open questions for the user (not for stinger-forge to invent) + +1. **Scope of the Bee's routing:** should `impeccable-worker-bee` become the *default* router for all frontend UI/UX work (retiring `design-taste-frontend`, `frontend-design`, `high-end-visual-design`, `gpt-taste`, `web-design-guidelines` as fallbacks), or coexist? +2. **Upstream install vs stinger-only:** should the army run `npx impeccable install` per project (hooks + compiled skill) as the enforcement layer, with the stinger as guidance + gate procedure? (Recommended: yes.) +3. **CI gate:** add `npx impeccable detect src/` to army projects' PR checks? +4. **Live Mode:** adopt now (alpha) or defer until stable? +5. **Native:** does the army need the iOS/Android/adaptive playbooks in the first stinger release, or web-only? diff --git a/.cursor/skills/impeccable-stinger/research/research-plan.md b/.cursor/skills/impeccable-stinger/research/research-plan.md new file mode 100644 index 00000000..7e66e342 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/research-plan.md @@ -0,0 +1,8 @@ +# Research Plan: impeccable-stinger + +- **Bee:** impeccable-worker-bee (Command Brief: `.cursor/commands/impeccable-worker-bee-command-brief.md`) +- **Depth tier:** deep (entire system: context contract, 23 commands, four-phase loop, 59-rule detector, hooks, live mode, worlds deck, maintenance) +- **Primary source:** `github.com/pbakaus/impeccable` (Apache-2.0), cloned at `/tmp/impeccable-RZVWdD` (commit `aee6ce9`, 2026-08-04, package v3.5.0) +- **Method:** repo-primary extraction (user-directed), not a web sweep. The repo is the canonical Apache-2.0 source; impeccable.style is generated from it and is reference-only (robots.txt: `ai-train=no, use=reference`). +- **Evidence files to extract:** `skill/SKILL.src.md`, `skill/reference/*.md` (33 files), `skill/scripts/*` (context, concept-seed, hook-admin, doctor, live), `cli/engine/registry/antipatterns.mjs` (59 rules), `cli/engine/*` (checks, constants, color, design-system, engines), `docs/*`, `DESIGN.md`, `PRODUCT.md`, `README.md`, `package.json`, `LICENSE`, `NOTICE.md`, `tests/`. +- **Output:** `research/` files below, `index.md` manifest, `research-summary.md` handoff. diff --git a/.cursor/skills/impeccable-stinger/research/research-summary.md b/.cursor/skills/impeccable-stinger/research/research-summary.md new file mode 100644 index 00000000..2d0e0597 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/research/research-summary.md @@ -0,0 +1,37 @@ +# Research Summary — impeccable-stinger + +- **Depth tier consumed:** deep (entire system) +- **Time window covered:** repo HEAD `aee6ce9` (2026-08-04); site sitemap lastmods 2026-04-10 → 2026-07-22. Repo-primary research, not a web sweep (user-directed; site robots.txt `ai-train=no`). +- **Files written:** 13 (research-plan + 11 topic files + index + this summary) under `.cursor/skills/impeccable-stinger/research/`. + +## The 5 most influential sources (for stinger-forge) + +1. **`skill/SKILL.src.md`** — the skill definition: setup, four modes, command routing, hooks, doctor, bounded-pass discipline. The stinger's SKILL.md should mirror its structure and voice. +2. **`skill/reference/craft-floor.md`** — the quality floor, absolute bans, and per-model (``, ``) sections. This is the anti-slop core the Bee enforces. +3. **`skill/reference/new-work.md` + `skill/scripts/concept-seed.mjs`** — job classification, five tests, direction contract, and the roll/dice variance machinery. This is what makes the system "whole" and is unique vs every existing army skill. +4. **`cli/engine/registry/antipatterns.mjs`** — the 59 deterministic rules (id/category/severity) that power the gate, hooks, CI, and slop catalog. The Bee's mandatory close-out gate. +5. **`skill/reference/hooks.md` + `skill/scripts/hook-admin.mjs`** — per-edit + deep-pass enforcement, harness manifests, Codex approval. The "every time" enforcement layer. + +## Open questions (for the user, not stinger-forge) + +1. Default router for all frontend UI/UX work, retiring overlapping prompt-only skills as fallbacks? +2. Upstream `npx impeccable install` per project as the enforcement layer (recommended), stinger as guidance + gate? +3. CI gate on army PR checks? +4. Live Mode now (alpha) or defer? +5. Native playbooks in first release, or web-only? + +## Sources stinger-forge should re-fetch with deeper context + +- `skill/reference/audit.md` + `audit.native.md` (5-dimension scoring rubric, P0-P3) — needed for the Polish-phase guide. +- `skill/reference/init.md` + `document.md` (interview flow, Stitch-format capture) — needed for the Start-phase guide. +- `skill/reference/live.md` + `live-setup.md` (alpha; decide inclusion). +- `docs/HARNESSES.md` (per-harness install/update details) — needed for the install/verify guide. +- `skill/scripts/context.mjs` (context loading + staleness directives) — needed for the context-contract guide. + +## Decisions (user-resolved 2026-08-06) + +1. Default router for all frontend UI/UX work — YES (retire overlapping prompt-only skills to fallbacks). +2. Install scope — HYBRID: global skill install + per-project context/hooks (hooks are project-local by harness design). +3. CI gate — YES (`npx impeccable detect src/` in PR checks). +4. Live Mode — include as opt-in, user-invoked, alpha; never auto-launched. +5. Native — include iOS/Android/adaptive playbooks. diff --git a/.cursor/skills/impeccable-stinger/scripts/sync-check.mjs b/.cursor/skills/impeccable-stinger/scripts/sync-check.mjs new file mode 100755 index 00000000..adfeabdf --- /dev/null +++ b/.cursor/skills/impeccable-stinger/scripts/sync-check.mjs @@ -0,0 +1,157 @@ +#!/usr/bin/env node +/** + * impeccable-stinger pre-flight sync check. + * + * Verifies, before a design task starts, that the installed Impeccable skill + * is current with upstream and that the stinger's vendored coverage (guides + + * templates) still matches the installed skill's content. If everything is + * current it is skipped (exit 0); if behind or drifted it reports what changed + * (exit 2); if the skill is not installed it says so (exit 1). + * + * Usage: + * node sync-check.mjs # check only + * node sync-check.mjs --update # check, and run `npx impeccable update` when behind + * + * Exit codes: + * 0 = current and in sync (skip) + * 2 = behind upstream and/or content drift (needs update/refresh) + * 1 = not installed or check failed + */ +import { readFileSync, existsSync, readdirSync } from 'node:fs'; +import { join, dirname } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { spawnSync } from 'node:child_process'; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const STINGER = join(HERE, '..'); +const MANIFEST = JSON.parse(readFileSync(join(HERE, 'upstream-manifest.json'), 'utf8')); + +const CANDIDATE_DIRS = [ + join(process.env.HOME || '', '.agents', 'skills', 'impeccable'), + join(process.env.HOME || '', '.codex', 'skills', 'impeccable'), + join(process.env.HOME || '', '.claude', 'skills', 'impeccable'), + join(process.env.HOME || '', '.cursor', 'skills', 'impeccable'), + '.agents/skills/impeccable', + '.codex/skills/impeccable', + '.claude/skills/impeccable', + '.cursor/skills/impeccable', +]; + +const UPDATE_HOST = process.env.IMPECCABLE_UPDATE_HOST || 'https://impeccable.style'; +const FETCH_TIMEOUT_MS = 4000; + +function findInstalledSkill() { + for (const dir of CANDIDATE_DIRS) { + if (existsSync(join(dir, 'SKILL.md'))) return dir; + } + return null; +} + +function readInstalledVersion(dir) { + try { + const md = readFileSync(join(dir, 'SKILL.md'), 'utf8'); + const m = md.match(/^version:\s*(.+)$/m); + return m ? m[1].trim() : null; + } catch { + return null; + } +} + +function compareVersions(a, b) { + const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0); + const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0); + for (let i = 0; i < Math.max(pa.length, pb.length); i++) { + const da = pa[i] || 0; + const db = pb[i] || 0; + if (da !== db) return da - db; + } + return 0; +} + +async function fetchPublishedVersion() { + try { + const res = await fetch(`${UPDATE_HOST}/api/version`, { + signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), + }); + if (!res.ok) return null; + const body = await res.text(); + const m = body.match(/"version"\s*:\s*"([^"]+)"/) || body.match(/"skills"\s*:\s*"([^"]+)"/) || body.match(/^([0-9]+\.[0-9]+\.[0-9]+)/m); + return m ? m[1] : body.trim(); + } catch { + return null; + } +} + +function contentDrift(dir) { + const drift = { newReferenceFiles: [], newCommands: [], missingReferenceFiles: [] }; + const refDir = join(dir, 'reference'); + if (existsSync(refDir)) { + const installed = readdirSync(refDir).filter((f) => f.endsWith('.md')).sort(); + drift.newReferenceFiles = installed.filter((f) => !MANIFEST.referenceFiles.includes(f)); + drift.missingReferenceFiles = MANIFEST.referenceFiles.filter((f) => !installed.includes(f)); + } + const metaPath = join(dir, 'scripts', 'command-metadata.json'); + if (existsSync(metaPath)) { + try { + const meta = JSON.parse(readFileSync(metaPath, 'utf8')); + drift.newCommands = Object.keys(meta).filter((c) => !MANIFEST.commands.includes(c)); + } catch { + /* ignore unreadable metadata */ + } + } + return drift; +} + +function runUpdate() { + const r = spawnSync('npx', ['impeccable', 'update'], { stdio: 'inherit', shell: true }); + return r.status === 0; +} + +async function main() { + const args = process.argv.slice(2); + const doUpdate = args.includes('--update'); + + const installedDir = findInstalledSkill(); + if (!installedDir) { + console.log('[sync-check] NOT INSTALLED: no impeccable skill found in any harness skill dir.'); + console.log('[sync-check] Run: npx impeccable install --scope=global --providers=codex,claude,cursor'); + process.exit(1); + } + + const installedVersion = readInstalledVersion(installedDir); + const publishedVersion = await fetchPublishedVersion(); + const drift = contentDrift(installedDir); + + const behind = installedVersion && publishedVersion && compareVersions(publishedVersion, installedVersion) > 0; + const hasDrift = drift.newReferenceFiles.length > 0 || drift.newCommands.length > 0; + + console.log(`[sync-check] installed: ${installedVersion || 'unknown'} @ ${installedDir}`); + console.log(`[sync-check] published: ${publishedVersion || 'unreachable (offline?)'}`); + if (behind) console.log(`[sync-check] BEHIND: installed ${installedVersion} < published ${publishedVersion}`); + if (drift.newCommands.length) console.log(`[sync-check] NEW COMMANDS upstream: ${drift.newCommands.join(', ')}`); + if (drift.newReferenceFiles.length) console.log(`[sync-check] NEW REFERENCE FILES upstream: ${drift.newReferenceFiles.join(', ')}`); + if (drift.missingReferenceFiles.length) console.log(`[sync-check] MISSING REFERENCE FILES (installed skill lacks): ${drift.missingReferenceFiles.join(', ')}`); + + if (!behind && !hasDrift) { + console.log('[sync-check] CURRENT: upstream in sync, stinger coverage matches. Skipping update.'); + process.exit(0); + } + + if (doUpdate && behind) { + console.log('[sync-check] Running `npx impeccable update`...'); + if (runUpdate()) { + console.log('[sync-check] Updated. NOTE: Codex may require /hooks re-approval after an update.'); + process.exit(0); + } + console.log('[sync-check] Update failed.'); + process.exit(1); + } + + if (hasDrift) { + console.log('[sync-check] STINGER REFRESH NEEDED: upstream added content the stinger does not cover.'); + console.log('[sync-check] Add guides/templates for the new content, then update scripts/upstream-manifest.json.'); + } + process.exit(2); +} + +main(); diff --git a/.cursor/skills/impeccable-stinger/scripts/upstream-manifest.json b/.cursor/skills/impeccable-stinger/scripts/upstream-manifest.json new file mode 100644 index 00000000..b96d7c6c --- /dev/null +++ b/.cursor/skills/impeccable-stinger/scripts/upstream-manifest.json @@ -0,0 +1,128 @@ +{ + "upstreamVersion": "4.0.4", + "upstreamCommit": "aee6ce9", + "upstreamDate": "2026-08-04", + "commands": [ + "craft", + "init", + "document", + "extract", + "live", + "adapt", + "animate", + "audit", + "bolder", + "clarify", + "colorize", + "critique", + "delight", + "distill", + "harden", + "onboard", + "layout", + "optimize", + "overdrive", + "polish", + "quieter", + "shape", + "typeset" + ], + "referenceFiles": [ + "adapt.md", + "adapt.native.md", + "android.md", + "animate.md", + "audit.md", + "audit.native.md", + "bolder.md", + "clarify.md", + "colorize.md", + "craft-floor.md", + "craft.md", + "critique.md", + "delight.md", + "distill.md", + "doctor.md", + "document.md", + "extract.md", + "harden.md", + "hooks.md", + "init.md", + "ios.md", + "layout.md", + "live-setup.md", + "live.md", + "new-work.md", + "onboard.md", + "operate.md", + "optimize.md", + "overdrive.md", + "polish.md", + "quieter.md", + "routing.md", + "shape.md", + "typeset.md", + "visualize.md" + ], + "rules": [ + "side-tab", + "border-accent-on-rounded", + "overused-font", + "flat-type-hierarchy", + "gradient-text", + "ai-color-palette", + "cream-palette", + "nested-cards", + "monotonous-spacing", + "bounce-easing", + "pulsing-dot", + "blinking-cursor", + "shape-assembled-illustration", + "dark-glow", + "radial-halo", + "radial-spotlight-glow", + "marquee", + "icon-tile-stack", + "italic-serif-display", + "hero-eyebrow-chip", + "kicker-above-heading", + "numbered-section-labels", + "em-dash-overuse", + "marketing-buzzword", + "aphoristic-cadence", + "oversized-h1", + "extreme-negative-tracking", + "broken-image", + "script-error", + "content-hidden-at-rest", + "edge-flush-cards", + "text-occlusion", + "first-viewport-column-overflow", + "gray-on-color", + "low-contrast", + "layout-transition", + "line-length", + "cramped-padding", + "body-text-viewport-edge", + "tight-leading", + "skipped-heading", + "heading-rhythm", + "justified-text", + "tiny-text", + "undersized-ui-text", + "all-caps-body", + "wide-tracking", + "text-overflow", + "repeated-container-text", + "clipped-overflow-container", + "design-system-font", + "design-system-color", + "design-system-radius", + "design-system-font-size", + "gpt-thin-border-wide-shadow", + "repeating-stripes-gradient", + "codex-grid-background", + "theater-slop-phrase", + "image-hover-transform" + ] +} diff --git a/.cursor/skills/impeccable-stinger/templates/direction-contract.md b/.cursor/skills/impeccable-stinger/templates/direction-contract.md new file mode 100644 index 00000000..96c3ffbf --- /dev/null +++ b/.cursor/skills/impeccable-stinger/templates/direction-contract.md @@ -0,0 +1,16 @@ +# Direction Contract (write into the artifact as a comment block, <=150 words, five blocks) + +```ts +/* + * THESIS: + * OWN-WORLD: + * STORY: + * FIRST VIEWPORT: + * FORM: + */ +``` + +Rules: +- The contract is inspectable intent. A separate reviewer audits the built page against it promise-by-promise. +- Keep the seed key to reproduce the roll (including every re-roll round). +- A page that promised a radical composition and shipped the usual template does not pass quietly. diff --git a/.cursor/skills/impeccable-stinger/templates/gate-report.md b/.cursor/skills/impeccable-stinger/templates/gate-report.md new file mode 100644 index 00000000..d387c841 --- /dev/null +++ b/.cursor/skills/impeccable-stinger/templates/gate-report.md @@ -0,0 +1,22 @@ +# Detector Gate Report + +| Field | Value | +|---|---| +| Target | `` | +| Command | `npx impeccable detect ` | +| Exit code | `0` (no findings) / `2` (findings) / `1` (failed) | +| Findings | `` | +| Resolved | `` | +| Waived | `` | + +## Findings + +| Rule id | Severity | File:line | Resolution (fix or waiver + reason) | +|---|---|---|---| +| `side-tab` | advisory | `src/components/Card.tsx:52` | Fixed — removed inset stripe | +| `overused-font` | advisory | `src/styles/global.css:14` | Waived — `ignores add-value overused-font "Brand Sans" --reason "Brand font, committed in DESIGN.md"` | + +## Verdict + +- [ ] Gate clean (0 findings) — close-out may proceed +- [ ] Gate failed (exit 2) — close-out blocked until resolved or waived diff --git a/.cursor/skills/impeccable-stinger/templates/surface-brief.md b/.cursor/skills/impeccable-stinger/templates/surface-brief.md new file mode 100644 index 00000000..497c4fff --- /dev/null +++ b/.cursor/skills/impeccable-stinger/templates/surface-brief.md @@ -0,0 +1,10 @@ +# Surface Brief: `` + +- **Mode:** Persuade / Operate / Read / Experience +- **Job:** what the visitor came to do on this surface +- **Proof sequence:** what evidence the surface shows, in order +- **Chosen direction:** the committed world (or "inherits `` world") +- **Seed key:** `` (if rolled) +- **Anti-references:** what this surface must not do + +Written by the work itself; edited when the page's strategy changes. Lives at `.impeccable/surfaces/.md`. diff --git a/.cursor/skills/impeccable-stinger/templates/sync-report.md b/.cursor/skills/impeccable-stinger/templates/sync-report.md new file mode 100644 index 00000000..1040935a --- /dev/null +++ b/.cursor/skills/impeccable-stinger/templates/sync-report.md @@ -0,0 +1,14 @@ +# Sync Check Report + +| Field | Value | +|---|---| +| Installed version | `<4.0.4>` | +| Published version | `<4.0.4>` | +| Status | `current` / `behind` / `not installed` | +| New commands upstream | `` | +| New reference files upstream | `` | +| Action taken | `skipped (current)` / `updated` / `stinger refresh` | + +- [ ] Current → skipped, task proceeded +- [ ] Updated → `/hooks` re-approval noted to user +- [ ] Stinger refresh needed → new guide/template added, manifest bumped