Paul BakausandClaude Opus 4.7
d26ccac1be
tests/live-e2e/agents/llm-agent.mjs: a Claude-backed VariantAgent that
implements the same one-method interface as the fake agent
(generateVariants(event, context) → { scopedCss, variants[] }). Default
model claude-haiku-4-5; override via IMPECCABLE_E2E_LLM_MODEL.
Prompt caching is on — the system prompt (instructions + the live-mode
spec from reference/live.md) is the cacheable prefix. First call writes
~10K tokens to cache; subsequent fixtures pay only the cache-read rate.
JSON output is validated for shape (scopedCss, variants[N].innerHtml),
with light error messages on parse failure.
tests/live-e2e.test.mjs: read IMPECCABLE_E2E_AGENT (fake|llm). When 'llm',
construct the LLM agent and skip the case cleanly if ANTHROPIC_API_KEY is
unset. Param-manifest assertions are gated to fake mode (LLM may emit
zero-param "fixed point" variants per the live.md spec). The accepted-h1
class assertion now allows hero-title as one of multiple classes so an
LLM agent that adds classes alongside the original still passes.
Test timeouts widen for LLM mode: 25s first-pass on conditional-render
fixtures (vs 5s for fake), 60s on direct waits (vs 30s). Without these,
the LLM's 3-8s generate latency races the orchestration's state-loss
recovery window.
tests/live-e2e/ui.mjs: clickGo retries up to 3× on stability failures.
Required because conditional-render fixtures (modal/tabs) animate the bar
mid-transition when preActions trigger framework HMR; a single click can
land during a re-render and Playwright's stability gate times out.
Pass rate on a typical sweep: 18/19 in LLM mode, 19/19 in fake mode.
The modal fixture's intrinsic state-loss flake (Fast Refresh resetting
useState(open) when source changes) is amplified by LLM latency and may
need a re-run; documented in CLAUDE.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
4.1 KiB
Repository Guidelines
Skill bootstrap: skip the post-update-cleanup step
If you load the Impeccable skill from .agents/skills/impeccable/SKILL.md (or any sibling harness directory under this repo), it begins with a <post-update-cleanup> block that runs scripts/cleanup-deprecated.mjs and then self-deletes. Do not run it here, and do not delete the block. This repo is the source of truth for the skill; cleanup-deprecated assumes a consumer project and would touch legitimate source files. The block is regenerated from source/skills/impeccable/SKILL.md on every bun run build, so any deletion churns back. Skip it silently and proceed with the task.
Project Structure & Module Organization
source/ is the source of truth. Author skills in source/skills/impeccable/ and keep provider output in dist/ generated, not hand-edited. Build logic lives in scripts/, with provider configs in scripts/lib/transformers/. Runtime detection code ships from src/. The website lives in public/, local API/dev serving lives in server/, and regression coverage lives in tests/ with fixtures under tests/fixtures/.
Build, Test, and Development Commands
bun run dev- start the local Bun server.bun run build- regeneratedist/, derived site assets, and validation output.bun run rebuild- clean and rebuild everything from scratch.bun test tests/build.test.js- run a focused Bun test.bun run test- run the full Bun + Node test suite.bun run test:live-e2e- opt-in live-mode E2E against framework fixtures (~2 min; needsnpx playwright install chromiumonce).bun run build:browser/bun run build:extension- rebuild browser-specific bundles.
Run bun run build after changing anything in source/, transformer code, or user-facing counts.
Coding Style & Naming Conventions
Use ESM, semicolons, and the existing two-space indentation style in JS, HTML, and CSS. Prefer small, single-purpose modules over large abstractions. Keep filenames descriptive and lowercase with hyphens where needed; skill entrypoints stay as SKILL.md, helper scripts use .js or .mjs. In source frontmatter, use clear kebab-case names and concise descriptions. There is no dedicated formatter or linter configured here, so match surrounding code closely.
Testing Guidelines
Tests use Bun’s test runner plus Node’s built-in --test. Name tests *.test.js or *.test.mjs and place new fixtures near the behavior they cover, usually under tests/fixtures/. Prefer targeted test runs while iterating, then finish with bun run test. If you change generated outputs or provider transforms, verify both source parsing and at least one affected provider path in dist/.
For changes to source/skills/impeccable/scripts/live-*.{mjs,js}, also run bun run test:live-e2e (kept out of the default suite because it does real npm install per fixture and boots framework dev servers). Scope to one fixture with IMPECCABLE_E2E_ONLY=<fixture-name> while iterating; pass IMPECCABLE_E2E_DEBUG=1 for page-DOM and dev-server-log dumps on failure. Schema and authoring guide for new fixtures live in tests/framework-fixtures/README.md.
Set IMPECCABLE_E2E_AGENT=llm to swap the deterministic fake agent for a Claude-backed one (tests/live-e2e/agents/llm-agent.mjs, default Haiku 4.5, override via IMPECCABLE_E2E_LLM_MODEL). Requires ANTHROPIC_API_KEY; tests skip cleanly when it's unset. This path hits the API — use it for verification, not CI.
Commit & Pull Request Guidelines
Recent history favors short, imperative subjects such as Fix: ..., Add ..., Improve ..., or Bump .... Keep commits focused and explain the user-facing impact when it is not obvious. PRs should summarize what changed, list validation performed, and call out regenerated artifacts like dist/ or build/. Include screenshots for visible public/ changes and mention affected providers when transform behavior changes.
Contributor Notes
Do not edit generated provider files directly unless you are intentionally patching generated output as part of a build-system change. Prefer fixing the root source in source/, scripts/, or src/, then regenerate artifacts.