Why use it: you clone pbakaus/impeccable to change detector rules or skills, or add a provider — and need a correct build/test loop from the first run.
What it produces: dist/ (per-provider bundles), regenerated provider directories in the repository (must be committed), and test results.
Requirements
| Item | Version | Notes |
|---|---|---|
| Bun | 1.3.x (run with 1.3.5) | Primary package manager and test runner |
| Node | ≥ 22.18.0 | CI runs a matrix of 22.18.0 and 24 |
| Chrome | — | Needed only for the detector: bunx puppeteer browsers install chrome |
| Playwright chromium | — | Needed only for the live-e2e* opt-in suites: npx playwright install chromium |
The basic loop
git clone https://github.com/pbakaus/impeccable
cd impeccable
bun install # ~24s, 227 package
bun run build # ~7s
env -u OPENCODE_CONFIG_DIR bun run test:core # ~72s — xem cảnh báo bên dưới
bun run build ends with self-checks; use these to determine whether the build is healthy:
✓ Generated counts: 23 commands, 61 detection rules
✓ Plugin/skill versions agree: 4.1.3
✓ Plugin manifest shape matches the verified loader contract
✓ Prose validator: no AI tells in user-facing copy
✓ Skill prose validator: skill/ is clean
✓ ask_instruction call sites: 8 sentence-initial
✨ Build complete!
Other build scripts in package.json:
| Command | What it does |
|---|---|
bun run build:skills |
Build skills only, skipping synchronization to the root |
bun run build |
build:skills + copy dist to build/_data/dist |
bun run build:release |
As above, but with synchronization to the root (for releases) |
bun run build:browser |
Regenerate cli/engine/detect-antipatterns-browser.js |
bun run build:extension |
Package the extension — see 07 |
bun run clean / rebuild |
rm -rf dist build / clean, then build |
⚠️ The easiest gate to miss: generated output must be committed
CI checks that generated provider directories are already in the commit (.github/workflows/ci.yml:113-114):
- name: Verify generated tracked outputs
run: git diff --exit-code -- .agents .claude .cursor .gemini .github/skills plugin cli/engine/detect-antipatterns-browser.js extension/detector
Changing skill/SKILL.src.md and committing only the source makes CI fail. The correct process:
# sửa skill/SKILL.src.md hoặc cli/engine/...
bun run build
git add -A .agents .claude .cursor .gemini .github/skills plugin \
cli/engine/detect-antipatterns-browser.js extension/detector
git commit -m "..."
Check before pushing, using the exact command CI runs:
bun run build && \
git diff --exit-code -- .agents .claude .cursor .gemini .github/skills plugin \
cli/engine/detect-antipatterns-browser.js extension/detector \
&& echo "GATE CLEAN" || echo "GATE DIRTY — commit generated output"
Actually run on a clean checkout at fcc271c: bun run build ; afterward, the gate was clean — the build is deterministic and does not create incidental changes.
The repository's latest commit is literally named Sync generated provider output — this is the normal workflow, not an incident.
⚠️ Environment trap: OPENCODE_CONFIG_DIR causes 8 tests to fail
Running without cleanup on a machine with this variable set (Orca sets it):
518 pass · 8 skip · 8 fail
All 8 failures are in tests/skills-cli.test.js, and the assertion states the reason:
Expected to contain: "Install target: [1] Detected only (claude, codex, cursor, gemini) [2] Customize [1]:"
Received: "... [1] Detected only (claude, codex, cursor, gemini, opencode) [2] Customize [1]: ..."
Cause, from cli/bin/commands/skills.mjs:80-84:
function opencodeGlobalConfigDir(home) {
if (process.env.OPENCODE_CONFIG_DIR) return process.env.OPENCODE_CONFIG_DIR;
if (process.env.XDG_CONFIG_HOME) return join(process.env.XDG_CONFIG_HOME, 'opencode');
return join(home, '.config', 'opencode');
}
The harness detector reads the actual environment variables on your machine, so OpenCode is detected and leaks into the assertion. This suite is not hermetic. Overriding HOME does not help (tested — still 8 failures), because the path comes from environment variables, not home.
The correct way to run:
env -u OPENCODE_CONFIG_DIR bun run test:core
# 874 pass · 0 fail · ~72s
If your machine has XDG_CONFIG_HOME or HERMES_HOMEset, unset those as well when running tests.
Test suites
Run through node scripts/run-tests.mjs <suite...>; package.json , wrapped as npm scripts.
| Suite | Command | File count | Contents |
|---|---|---|---|
core |
bun run test:core |
45 | Build, provider transform, CLI helper, context, storage |
detector |
bun run test:detector |
11 | Detector via text, fixtures, and Puppeteer |
live |
bun run test:live |
44 | Live-mode unit and local-server tests |
framework |
bun run test:framework |
1 | Fixture framework: inject, CSP, generated-file, wrap |
plugin-e2e |
bun run test:plugin-e2e |
1 | Install the ./plugin subtree into an actual Claude Code sandbox |
cli-e2e |
bun run test:cli-e2e |
1 | Deterministic install/update with a local universal bundle |
Alias:
default / all-local = core, detector, live, framework, plugin-e2e
all = default + cli-remote-e2e, live-e2e, live-e2e-accept-cleanup,
new-work-e2e, skill-behavior, live-svelte-adapter-deepseek
node scripts/run-tests.mjs --list # xem từng suite gồm file nào
node scripts/run-tests.mjs --help
bun run test # = suite default
Opt-in suites (not run by default; cost money or time):
| Suite | Requirements |
|---|---|
live-e2e |
npx playwright install chromium, ~2 minutes |
live-e2e-accept-cleanup |
Provider API key |
new-work-e2e |
Playwright |
skill-behavior |
API keys for 3 providers in .env at the root (gitignored); ~5 minutes, costing a few cents. Current baseline: 21–22/24 |
cli-remote-e2e |
Network access to impeccable.style |
live-svelte-adapter-deepseek |
DeepSeek key |
Without a key, the suite skips cleanly, rather than failing.
Suite skill-behavior runs the 3 cheapest models from 3 vendors, inlines skill/SKILL.src.md as the system prompt, then asserts against tool-call traces rather than free-form text. Run it whenever you change the Setup section of skill/SKILL.src.md, skill/scripts/context.mjs, or references affecting Setup.
What CI checks
| Job | Contents |
|---|---|
changes |
node scripts/ci-test-plan.mjs decides which parts need to run |
test-matrix |
Node 22.18.0 + 24: bun install → core → install Chrome → detector → live → framework → build:browser → build → build:extension → lint the Firefox extension with web-ext@10 → generated-output gate → upload dist/ |
test |
Aggregate gate, checking only the results of test-matrix |
cli-remote-e2e, live-e2e-smoke, live-e2e-full, live-e2e-accept-cleanup, live-svelte-adapter-deepseek, skill-behavior |
Opt-in paths, gated by changes and secrets |
Architecture: where to edit
| To change | Edit this file |
|---|---|
| Skill content and chat commands | skill/SKILL.src.md (the sole source) → bun run build |
| Command metadata (description, argument hint) | plugin/skills/impeccable/scripts/command-metadata.json (generated — edit the source, then build) |
| Detector rules | cli/engine/registry/antipatterns.mjs, cli/engine/rules/checks.mjs |
| Static HTML/CSS engine | cli/engine/engines/static-html/ |
| Regex engine | cli/engine/engines/regex/detect-text.mjs |
| Browser engine | cli/engine/engines/browser/detect-url.mjs |
| CLI argument parsing and exit codes | cli/engine/cli/main.mjs |
| Install/update/link | cli/bin/commands/skills.mjs |
| Add a new provider | See docs/DEVELOP.md , section "Adding a New Provider" |
Full contributor documentation: docs/DEVELOP.md, docs/STYLE.md, docs/HARNESSES.md.
Release
node scripts/release.mjs skill # bun run release:skill
node scripts/release.mjs cli # bun run release:cli
node scripts/release.mjs extension # bun run release:ext
Three separate version lines: CLI (npm, currently 3.6.1), skill bundle (currently 4.1.3), and extension (currently 1.3.3).
Verified note: npm version 3.6.1 lags behind git
mainwith the same version number —SUBCOMMAND_HELP(per-subcommand help) exists inmainbut not in the published tarball. When debugging user reports, ask whether they usenpx(the npm version) or run from a checkout; do not assume they are identical.
Other checks
bun run audit # bun audit --audit-level=moderate
bun run smoke:hooks # smoke provider hook
bun run bench:detector # benchmark detector
bun run bench:detector:browser