Replace the bulky modal action panel and separate cycler with a single
compact floating bar (~343px x 46px) that shapeshifts between three
modes: configure, generating, and cycling.
Configure mode: action pill (clickable, opens a 4-column chip grid
popover), inline text input with contextual placeholder, variant count
toggle (click to cycle 2/3/4), and Go button. One line, no labels,
no redundant "impeccable" branding.
Generating mode: action label + progressive dot indicators + status
text. Same bar, same position, content crossfades.
Cycling mode: prev/next nav buttons, clickable dot indicators,
counter, accept/discard. Same bar, same position.
Design details:
- Translucent warm paper background with 16px backdrop blur
- ease-out-quint spring entrance (translateY + opacity)
- Action picker scales from pill origin with 0.18s transition
- Dots animate in with scale(0.6)->scale(1) as variants arrive
- Bar tracks selected element on scroll via requestAnimationFrame
- All interactive elements have hover/active micro-interactions
- Input captures keyboard events (stopPropagation) to prevent
picker nav from firing while typing
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New feature: /impeccable live starts an interactive visual iteration server.
Users select elements in the browser, pick a design action (bolder, quieter,
etc.), and the agent generates HTML+CSS variants written directly to source.
The dev server's HMR hot-swaps them in, and MutationObserver progressively
reveals each variant in a cycler UI as it arrives.
Architecture:
- src/live/server.mjs: HTTP + WebSocket server with session token auth,
long-poll /poll endpoint for the agent, WebSocket for the browser
- src/live/poll.mjs: CLI client (npx impeccable poll / poll --reply)
- src/live/browser.js: element picker with keyboard nav (arrows=siblings,
shift+arrows=parent/child), action panel (12 commands, freeform input,
variant count), variant cycler with progressive reveal via MutationObserver
- src/live/protocol.mjs: shared message types and event validation
- source/skills/impeccable/reference/live.md: agent loop instructions
(inject script, poll loop, generate variants, accept/discard, cleanup)
CLI changes:
- bin/cli.js: added "poll" top-level command
- src/detect-antipatterns.mjs: liveCli() now delegates to src/live/server.mjs
- package.json: added ws dependency
Registered /impeccable live as command #22 across all standard locations.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pre-3.0, onboard was folded into /harden when we were trying to reduce
namespace pollution. In the single-skill model that tradeoff is gone,
so the weakest of the old merges is the first to undo.
Harden and onboard live in different mental modes. Harden is defensive
(edge cases, i18n, overflow, errors). Onboard is activation (first-run
flows, empty states as CTAs, progressive disclosure). A user thinking
"design the onboarding flow" was never going to type /impeccable harden.
Changes:
- New reference file at source/skills/impeccable/reference/onboard.md,
restored from the pre-merge version in git history rather than the
condensed 33-line summary that was in harden.md.
- Removed the "Onboarding & First-Run Experience" section from
source/skills/impeccable/reference/harden.md.
- Updated harden description/editorial/process-steps to drop onboarding
keywords; split commandProcessSteps so harden stays focused on
production resilience and onboard gets its own phases.
- Registered onboard in: SKILL.md description + command menu + router
table, command-metadata.json, IMPECCABLE_SUB_COMMANDS, pin.mjs
VALID_COMMANDS, SKILL_CATEGORIES, COMMAND_RELATIONSHIPS, data.js
commandCategories + commandProcessSteps + commandRelationships,
framework-viz commandSymbols + commandNumbers.
- Reused the existing content/site/skills/onboard.md editorial wrapper
(it was orphaned by the merge but never deleted), updating it to use
/impeccable onboard.
- Bumped all user-facing count references 20 -> 21: public/index.html,
CLAUDE.md, README.md, NOTICE.md, plugin.json, marketplace.json,
sitemap.xml, build-sub-pages.js.
- Harness dir audit.md and critique.md changes are the
{{available_commands}} placeholder expanding to include onboard.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove "Rewritten docs site" (internal site polish, not a shipped
feature) and "Teach runs automatically on first use" (not new; that
behavior already existed pre-3.0). What's left is the consolidation
and the pin mechanism, which are the two user-facing changes in 3.0.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
npm subprocesses can regenerate a stray package-lock.json (last time
this happened, it was reverted in 3ca60a8). Add it to .gitignore so it
stops showing up as untracked.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Bump skills plugin version 2.1.1 -> 3.0.0 (plugin.json, marketplace.json,
harness SKILL.md files). CLI and Chrome extension unchanged.
- Remove prefixed universal zip bundle and all related code:
factory.js prefix/outputSuffix options, zip.js variant pass, utils.js
prefixSkillReferences, the "universal-prefixed" entry in
download-providers.js, and the matching test suite in utils.test.js.
- Redesign Get Started step 1 "Install the skill and CLI": two terminal
rows (npx skills + npm i -g impeccable) with paired notes, drop the
Recommended badge.
- Collapse "Other install methods" back into a <details> element so the
primary install path is the first thing users see.
- Simplify step 3 to "Add the Chrome extension": remove the CLI tool
block (now in step 1), use standard .btn .btn-primary for the CTA so
it matches other primary buttons (square corners, accent slide-up
hover), and lay out the preview screenshot next to the button instead
of stacked so the screenshot no longer dominates vertical space.
- CLAUDE.md: rewrite with v3.0 architecture, the "no em dash also means
no --" rule, the harness-dirs-are-tracked gotcha, the named-export
test-spy warning, and the evals inline-skill.ts sync note.
- AGENTS.md, DEVELOP.md: drop prefixed variant references.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Biggest change in a while. Users previously had 18 standalone skill
entries cluttering their /menu; now they have one entry (/impeccable)
that routes to 20 specialized commands via argument dispatch. The pin
mechanism (/impeccable pin audit) restores standalone shortcuts on
demand for commands users hit all the time.
## Architecture
- Single /impeccable skill with command router section in SKILL.md
- 20 commands served via reference files under source/skills/impeccable/reference/
- /impeccable pin <command> creates a lightweight redirect shim so users
who prefer /audit, /polish, etc. can still have them
- Context gathering (teach) auto-runs on first use
- command-metadata.json is the single source of truth for command
descriptions, argument hints, and relationships
## Site rewrite
- Docs URL: /skills renamed to /docs (with /skills permanent redirects)
- Homepage hero frames Impeccable as "one skill with 20 commands"
- "Get Started" split into 50/50 install + how-to-use with editorial
numbered steps, /impeccable shown as the home command with three modes
- New /docs overview: home command hero card + dense category rows
matching the old cheatsheet density, with leads-to/pairs-with/
combines-with relationship metadata served from a shared source
- Cheatsheet merged into /docs, /cheatsheet redirects
- Magazine spread and mobile cards show /impeccable as a stacked
namespace label above the command name at full display size
- Periodic table updated with craft/teach/extract as first-class cells
- Skill detail pages generate from reference files, with an editorial
wrapper per command for tagline + body
- Tutorials and anti-patterns pages updated to use /impeccable <cmd>
## Build system
- Dead code removed (scripts/lib/transformers/shared.js)
- Build log wording fixed ("1 skill" not "1 skills (1 user-invocable)")
- generateApiData fallback branch removed (throws loudly if metadata
missing instead of silently degrading)
- Commands API includes editorial tagline alongside the long description;
UI surfaces prefer tagline for human display, description for auto-
trigger keyword matching
## Gitignore
- Added .claude/scheduled_tasks.lock, .claude/settings.local.json to
ignore list (local Claude Code state that should not be tracked).
- Harness skill directories (.claude/skills/, .agents/skills/, etc.)
remain tracked by design: npx skills reads them from this repo at
install time and they enable clean submodule use.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
generateYamlFrontmatter only re-quoted values starting with `[` or `{`,
but parseFrontmatter strips surrounding quotes on input. Descriptions
containing `: ` (e.g. "Also handles: critique...") round-tripped into
unquoted plain scalars that YAML parsers reject. Added a yamlNeedsQuoting
check covering colon-space, space-hash, YAML indicator chars, reserved
keywords, and number-like strings, plus regression tests.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two detector bugs that produced false positives on sites like uselinkshot.com:
1. The bg-black regex matched Tailwind opacity modifiers (bg-black/3,
hover:bg-black/5) because / is a word boundary. Added negative lookahead.
2. resolveBackground ignored url() background-images, walking past them to
the body's white bg. White text on a dark hero image was flagged as
1.0:1 white-on-white. Now bails on url() images like it does for gradients.
Also: extension build auto-generates dist/extension.zip, version bumps for
CLI (2.1.7) and extension (1.0.1).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The gallery page had broken styling and missing images. The visual
mode page already has the same specimen gallery in a better layout.
- Removed public/gallery.html and its build entry point
- Updated homepage links to point to /visual-mode#try-it-live
- Added 301 redirect from /gallery to /visual-mode#try-it-live
- Added id="try-it-live" anchor to the visual-mode gallery section
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When .claude/skills is a symlink to .agents/skills, updating both
providers wrote to the same directory twice -- the last write
(.agents) always won, making .claude content identical to .agents.
The up-to-date check also always failed because it compared
provider-specific bundle content against the wrong provider's files.
Fix: use realpathSync to detect shared directories and process each
unique real path only once with its matching bundle provider. Respects
the user's symlink setup for non-impeccable skills.
Tested: first run updates 18 skills, second run reports "up to date".
CLI bumped to v2.1.6.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Build system now injects skills version (from plugin.json) into
every SKILL.md frontmatter as a version field
- CLI reads the version from the local impeccable SKILL.md and
displays it in check/update output
- Hash comparison normalizes the version field (so a version bump
alone doesn't trigger a full re-download)
- Removed misleading CLI version display from skills commands
CLI bumped to v2.1.5.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Skills installed via npx skills add resolve {{scripts_path}} to
.agents/skills/... while our bundle resolves it per-provider
(.claude/skills/..., .cursor/skills/..., etc). Without normalizing,
identical content always shows as different.
Also compare only one provider instead of all (they have the same
content, just different path prefixes).
CLI bumped to v2.1.4.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The hash comparison was comparing the entire local skills directory
(which includes user's custom skills) against the bundle (which only
has impeccable skills). Now only compares skills that exist in the
bundle, so custom skills don't cause a false mismatch.
CLI bumped to v2.1.3.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
CLI changes (bumped to v2.1.2, skills stay at v2.1.1):
- `npx impeccable skills check` compares local skill files against
the latest bundle and reports whether updates are available
- `npx impeccable skills update` now downloads the bundle first,
compares hashes, and skips with "up to date" if nothing changed
- Removed the local-modifications warning (was confusing for users
who installed via npx skills add)
Versioning:
- CLI (package.json), skills (plugin.json/marketplace.json), and
Chrome extension (manifest.json) are now versioned independently
- CLAUDE.md updated to document when to bump each
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
npx skills update has a known upstream bug (vercel-labs/skills#775)
where it can't find the lock file. Instead of trying it first and
falling back, always use our direct download which is reliable.
Also:
- Site now recommends `npx impeccable skills update` everywhere
instead of `npx skills update`
- Direct download path now re-applies prefix after updating
- Runs cleanup after download to strip deprecated stubs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
npx skills update has a known bug where it can't find the lock file
(vercel-labs/skills#775). Our direct download fallback is the primary
working path, so the message should not sound like an error.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The post-update-cleanup section now instructs the AI to tell the user
what's happening and why before running the script, so file deletions
don't feel unexpected.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The refactored factory.js transformer dropped script file support that
existed in the old shared.js version. Scripts were read from source
but never written to dist/, so npx skills installed skills without the
cleanup-deprecated.mjs script, causing errors on first load.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add max-width: 56ch to install-step-body so long descriptions
don't run edge to edge
- Rewrite FAQ update answer as a scannable list instead of dense
paragraphs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Delete source/skills/ directories for deprecated skills (arrange,
normalize, onboard, extract, frontend-design, teach-impeccable).
The cleanup script handles migration; stubs are no longer needed.
- Add "npx skills update" command to the Stay Updated install section
- Rewrite FAQ update answer: lead with npx skills update, add
troubleshooting for failed updates (re-install + run /impeccable)
- Run cleanup script in `npx impeccable skills update` before
delegating to npx skills update, preventing failures from
deprecated entries in skills-lock.json
- Run cleanup script after `npx impeccable skills install` to remove
leftover files from previous versions
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The build still generates deprecated stubs in dist/ (so the cleanup
script can redirect users), but now removes them from the repo's own
harness directories so they don't clutter the local skill list.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Bundled as source/skills/impeccable/scripts/cleanup-deprecated.mjs,
runs via the self-deleting <post-update-cleanup> section in the skill.
The script:
- Finds all harness skill dirs (.claude, .cursor, .agents, etc.)
- Deletes deprecated skill directories (arrange, normalize, onboard,
extract, frontend-design, teach-impeccable) and i-prefixed variants
- Verifies each file contains "impeccable" before deleting to avoid
touching unrelated user skills with the same name
- Handles both symlinks and regular directories
- Removes matching entries from skills-lock.json (only if source is
pbakaus/impeccable)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The build counts active commands by checking for DEPRECATED in the
skill description. Without this, the old source files were still
counted as active (22) while the site says 18, failing CI.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Version bump across package.json, plugin.json, marketplace.json
- Changelog entry for v2.1 in index.html
- Hero version link updated
- Added <post-update-cleanup> section to impeccable SKILL.md that
detects and removes leftover files from renamed/merged skills
(arrange, normalize, onboard, extract, frontend-design,
teach-impeccable). Verifies files contain "impeccable" before
deleting to avoid touching unrelated user skills. Self-deletes
after first run so it only executes once per update.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Use h3 headings with custom IDs instead of inline spans so the browser
scrolls to the right position. Added {#id} syntax support to the
markdown heading renderer.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Syne stays in reflex_fonts_to_reject but no longer gets a standalone
DON'T rule in the skill or a separate LLM-only entry in the catalog.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Clarify that /impeccable craft runs /shape internally (not the other way around)
- Add three-mode documentation (freeform/craft/teach) to /impeccable page with anchor links
- Add sidebar sub-links for /impeccable craft and /impeccable teach
- Fix hallucinated npx impeccable live description in tutorial and visual-mode page
- Remove nonsensical "Do not skip the independent part" from critique tutorial
- Make Step 4 less prescriptive (users can fix all at once or one-by-one)
- Improve CLI and browser extension install copy with specific features and use cases
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Extension is now live on the Chrome Web Store. Replace all
coming-soon placeholders with install links on the homepage,
visual-mode page, and overlay tutorial.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
These self-contained HTML files and the detector script were served
by the dev server from public/ but never made it into the Cloudflare
Pages build directory, causing 404s on the deployed site.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Cloudflare Pages merges headers from all matching rules rather than
overriding, so the path-specific SAMEORIGIN conflicted with the global
DENY. Switch the global rule to SAMEORIGIN since the site only frames
its own antipattern example pages.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The global _headers rule set DENY for all paths, preventing the
/visual-mode/ page from embedding /antipattern-examples/ in an iframe.
Add a path-specific SAMEORIGIN override for /antipattern-examples/*.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The Bun shipped with Cloudflare Pages doesn't dedupe shared CSS chunks
across HTML entrypoints — each entry tries to emit its own copy. With
chunk: '[name]-[hash].[ext]', three sub-pages all named index.html
(skills/, tutorials/, anti-patterns/) plus shared CSS content end up
producing chunks with identical name+hash and the build aborts on
'Multiple files share the same output path'.
Including [dir] in the chunk and asset templates scopes each chunk to
its entry's source directory, so the per-entry copies land in unique
paths even when dedupe is off. Local Bun (1.3.x) still emits a single
shared chunk because [dir] is only used when there are multiple chunk
candidates.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Bundles recent CLI/detector work that landed on v2.0 since 2.0.6:
side-tab border detection on oklch/oklab/lch/lab and CSS variables,
emoji-only handling in contrast/icon-tile rules, asymmetric
font-size-aware cramped-padding rule, full anti-pattern names in
overlay labels, and the CI sandbox flags for Puppeteer fixture tests.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Cloudflare Pages ships an older Bun than the one used locally. That
version emits shared CSS chunks via the default 'chunk-[hash]' naming
template, but the [hash] token isn't always populated when the chunk
is shared across multiple HTML entrypoints — every sub-page that
imports sub-pages.css ends up wanting the same './chunk-' filename
and the build aborts with 'Multiple files share the same output path'.
Pin the chunk and asset naming explicitly so [hash] is always present
regardless of Bun version.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When Bun.build aggregates resolution failures, the thrown error keeps the
real causes on error.errors (an array). The previous handler only printed
error.message and error.stack, both of which are generic / undefined for
this kind of failure, so CI logs read as 'Bundle failed / undefined' with
no clue what was unresolved. Walk error.errors first so the actual file +
import that failed shows up in CI output.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The /visual-mode sub-page rules added in 27d1b13 duplicated
.visual-mode-preview (and its header/dot/title children) in
sub-pages.css with a max-width + margin: 0 auto. Because sub-pages.css
loads after main.css on index.html, those styles won on the homepage
too. Auto margins on a grid item disable justify-self: stretch, so the
preview collapsed to the iframe's 300px intrinsic width instead of
filling its 3fr cell in .visual-mode-demo.
Scope the rules to .visual-mode-page so they only apply on the sub-page
and the homepage falls back to main.css's .visual-mode-preview rule.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two unrelated breakages were stacking on the v2.0 PR:
1. The static site build crashed because the generated /visual-mode page
referenced images via root-absolute paths (/antipattern-images/*.png).
Bun's HTML loader resolves <img src> at build time relative to the
source HTML file and treats a leading slash as filesystem-absolute, so
it could not find the images. Use a relative path so Bun bundles and
hashes them the same way the homepage already does.
2. The Puppeteer-backed fixture tests crashed in GitHub Actions because
the Ubuntu runners block unprivileged user namespaces, so Chrome's
sandbox cannot initialize. Pass --no-sandbox / --disable-setuid-sandbox
only when process.env.CI is set, so local users keep the hardened
default launch.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Call out the frontend-design to impeccable rename on its own (and the
/teach-impeccable to /impeccable teach move), and reframe the /shape
bullet to cover both /shape and /impeccable craft as the new ways to
create with Impeccable.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Drop the metric-heavy framing and lead with the user-facing wins
(font/color diversity, design quality, Codex support) plus a brief
nod to the eval framework and anti-attractor technique.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tightened the v2.0 changelog on the homepage. Same information density,
fewer words, no em dashes, and dropped what does not concern users.
- Skill rewrite bullet: same numbers, shorter framing.
- Detection engine bullet: dropped the 'hard-to-hit cases that slip
past regex-only scanners' flourish at the end.
- CLI bullet: collapsed parenthetical clauses into short phrases.
- Chrome extension bullet: replaced the em dash with a colon.
- /critique bullet: tightened.
- /shape bullet: replaced the em dash with a period break.
- "Rebuilt site and docs" renamed to "New docs site" and trimmed to
just what users experience (top-level sections, skill pages,
tutorials, rule cards). Dropped the 'mobile experience overhauled'
line — implementation detail, not a user-facing feature.
- Licensing bullet: renamed to 'Apache 2.0 throughout'.
The min-height: calc(100vh - var(--site-header-height)) added earlier
so the sticky sidebar's border-right divider reaches the bottom of
the viewport on desktop was applying on mobile too. On mobile the
sidebar is static (not sticky) and collapses behind a toggle, so the
min-height reserved a full viewport of empty space above the main
content whenever the menu was collapsed. The result: opening
/anti-patterns on mobile showed just the 'Sections' dropdown in the
first screen, then a blank viewport, then the rules below the fold.
Wrap the min-height rule in a min-width: 921px media query so it only
applies on desktop, matching the breakpoint that switches the layout
to the two-column grid.
