Before: 422 lines. After: 386 lines. The cut is conservative because
evals/AGENT.md revealed that most of what looked like bloat is actually
load-bearing: the font_selection_procedure with its 23-font ban list
(lesson 6), the theme_selection with audience examples (lesson 9), and
the absolute_bans with literal CSS patterns (lesson 7) all drive
measurable eval improvements and must stay inline.
What moved out of SKILL.md:
- Context Gathering Protocol (52 → ~18 lines). The full protocol — cache
semantics, dispatch tree, teach/document/live exceptions, why-it-matters
— moved to reference/context.md. SKILL.md keeps only the compact hook:
load command, "never infer from codebase" warning, and pointer.
- Pin/Unpin (14 → 6 lines). Details moved to reference/pin.md.
- Spatial principles: dropped 4pt-vs-8pt rationale, gap-vs-margins CSS
technicality, and container-queries-vs-viewport explanation (not
load-bearing in the main skill). Kept all load-bearing rules
including the 80-char body-text line (detector-backed).
What did NOT move (load-bearing per evals):
- <font_selection_procedure> with the 23-font ban list
- <theme_selection> with the 8 audience examples
- <absolute_bans> with literal CSS patterns
- All XML tag structure (lesson 8: XML works better than markdown
for reasoning models, especially OpenAI)
Also added:
- reference/context.md (new) — full context protocol
- reference/pin.md (new) — full pin/unpin docs
- "Never infer brand, audience, or tone from the codebase" warning
restored to SKILL.md (was dropped in an earlier refactor)
Fixed:
- reference/colorize.md had "Accent borders: Add colored left/top
borders to cards or sections" which directly contradicted
SKILL.md's absolute_ban on border-left/right > 1px. Rewrote the
accent-border advice to use hairline borders, surface tints, or
leading glyphs instead, with an explicit reference to the ban.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two observed failure modes:
1. Smoke-test style truncation (`| head -N`) in bash commands defeats the
whole point of load-context.mjs — Claude needs the FULL file contents,
not the first few lines of JSON.
2. The old protocol didn't clearly explain session caching, leading to
repeated load-context.mjs calls across commands in the same session
(thousands of wasted tokens on 3-5KB files re-fetched 3-5 times).
Context Gathering Protocol rewrite:
- PRODUCT.md required (blocker), DESIGN.md optional (one-line nudge if
missing). Greenfield projects can't yet have a DESIGN.md to document.
- Explicit session cache: if content is in conversation history, do not
re-fetch. Exceptions listed (after teach/document/manual edit).
- Explicit "never truncate" rule: consume the full load-context.mjs
output, never pipe through head/tail/grep/jq with field filters.
- Content validity check: hasProduct=true but content <200 chars or
full of [TODO] markers = treat as missing, run teach.
- Missing-PRODUCT.md flow spells out task resumption: user asked for
/impeccable polish ButtonGroup, we must run teach, then RESUME polish
of ButtonGroup with fresh context — not silently abandon intent.
- Three explicit exceptions to the protocol:
- /impeccable teach skips it (teach creates PRODUCT.md)
- /impeccable document loads PRODUCT.md only (creates DESIGN.md)
- /impeccable live already warms context via live.mjs — don't also
run load-context.mjs
teach.md Step 6 and document.md Step 5 now re-run load-context.mjs at
the end so the freshly-written files surface in conversation history
and subsequent commands use the new version, not a stale earlier read.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The format at https://stitch.withgoogle.com/docs/design-md/format/ defines
exactly six sections in a fixed order: Overview, Colors, Typography,
Elevation, Components, Do's and Don'ts. Our previous format used
non-compliant names (Visual Theme & Atmosphere, Color Palette & Roles,
Typography Rules, Component Stylings), a non-existent "Layout Principles"
section, and had no Do's and Don'ts.
Changes to reference/document.md:
- Fixed section list to match the spec character-for-character
- Added mandatory "Creative North Star" pattern at top of Overview
- Added Named Rules pattern (e.g. "The No-Line Rule") — stickier than
bullet lists for AI consumers, mirrors Stitch's own generator output
- Added explicit Do's and Don'ts section with concrete, forceful guardrails
- Elevation is now its own section (was buried in Components)
- Layout/motion/responsive content folds into Overview + Components
rather than inventing new top-level sections
- Guidance on forceful voice ("prohibited"/"forbidden"/"never") matching
PRODUCT.md's expert-decisive tone
- Pitfalls section warns against renaming sections or adding new ones
Changes to our DESIGN.md:
- Rewrote to use spec-compliant section headers with evocative subtitles
(e.g. "## 2. Colors: The Warm-Paper Palette")
- Opened with "Creative North Star: The Editorial Sanctuary"
- Added 11 Named Rules across sections (The One Voice Rule, The Paper-
Not-White Rule, The OKLCH-Only Rule, The Italic-Is-Voice Rule,
The 1.6 Leading Rule, The Fluid-Headlines-Only Rule, The Flat-By-
Default Rule, The Low-Alpha Rule, The Tinted-Shadow-Only-For-Accent
Rule, plus the existing implicit ones)
- Full Do's and Don'ts section with 10 Dos and 15 Don'ts, many of which
translate PRODUCT.md anti-references into concrete prohibitions
- Elevation section documents shadow vocabulary separately from Components
- Layout/spacing/motion content relocated to a sub-section under Components
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pioneers a two-file convention for project context:
- PRODUCT.md (strategic): users, brand, principles — answers who/what/why
- DESIGN.md (visual): follows Google's Stitch DESIGN.md spec — answers how-it-looks
Both files live at the repo root. Filename matching is case-insensitive.
DESIGN.md wins on visual conflicts, PRODUCT.md wins on strategic/voice.
Legacy .impeccable.md is auto-migrated to PRODUCT.md on first read by the
new shared loader. This is silent and one-shot — the rename is permanent.
What changed:
- New scripts/load-context.mjs: shared context loader used by every command
that needs project context. Reads both files, handles legacy migration.
- New reference/document.md: /impeccable document command that generates
DESIGN.md by auto-extracting tokens (colors, typography, spacing, radii,
shadows, components) from CSS/Tailwind/theme files, then asking the user
to confirm descriptive language for atmosphere and color character.
Follows Google's Stitch DESIGN.md format for tool compatibility.
- SKILL.md Context Gathering Protocol updated to load both files and
nudge the user to run /impeccable document when DESIGN.md is missing.
- reference/teach.md rewritten to split discovery cleanly: strategic
questions go to PRODUCT.md, visual/design-system work is delegated to
/impeccable document (skipped on empty projects).
- reference/live.md consumes {product, design, productPath, designPath,
migrated} from the loader instead of a single context blob.
- scripts/live.mjs uses the shared loader instead of inline file reading.
- Command count updated 22 → 23 (new: document). Metadata, router table,
command menu, periodic table viz, and homepage data all updated.
- .gitignore adds PRODUCT.md + DESIGN.md (repo-local, not shared).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Previously only bolder/quieter/animate/colorize/typeset/layout had
variant diversity rules. Added the same level of guidance for distill,
polish, adapt, delight, and overdrive so every live action has a
clear "each variant must differ on THIS axis" rule.
Also noted that overdrive should skip its reference's "propose and ask"
step in live mode (it's non-interactive — the user picks from variants).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two failure modes observed:
1. Claude generates N near-identical variants (small shade/size tweaks)
instead of meaningfully different design directions
2. When a sub-command like /bolder is chosen in the picker, Claude skips
loading reference/bolder.md and generates generic variants
Fixes:
- "Load reference file" is now a MANDATORY Step 2a, separate and
non-negotiable, called out as a critical failure to skip
- Added Step 2b "Plan 3+ distinctly different directions" with 7
structural axes variants must differ on (hierarchy, layout topology,
typography system, color strategy, density, tone, decomposition)
- Added action-specific diversity rules (bolder = different dimensions,
animate = different motion vocabulary, colorize = different hues, etc.)
- Freeform prompt guidance: honor the prompt direction but explore
meaningfully different interpretations, not three near-copies
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Previously, starting live mode required ~5-6 sequential bash calls:
read .impeccable.md, start server, check config, read reference, inject
tag, verify. The new live.mjs does all of this in a single command
(~340ms cold, ~90ms when reusing a running server) and returns everything
the agent needs in one JSON blob.
Workflow is now:
1. node live.mjs # start + inject + load context (1 bash call)
2. navigate browser # optional MCP call
3. node live-poll.mjs # enter poll loop
Reference doc collapsed to a single "Start Live Mode" section with the
one-command path plus a first-time config creation fallback.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
First live run: agent auto-detects framework and writes a small config.json
(file, insertBefore/insertAfter anchor, comment syntax). Every subsequent
run: live-inject.mjs handles insert/remove deterministically, no LLM needed.
The config lives at {scripts_path}/config.json and is gitignored — it's a
per-project cache that wipes on skill update and regenerates on next use.
- New live-inject.mjs: --port (insert), --remove, --check modes
- Idempotent insert: re-running with a different port replaces cleanly
- Reference doc: one-time detection step, then instant insert/remove
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Arrow keys now pass through to element picker when the freeform input
is empty, instead of being swallowed by stopPropagation
- Arrow nav works in both PICKING and CONFIGURING states, so you can
change your element selection while the config bar is open
- Clicking outside the selected element and bar returns to PICKING mode,
matching the expected deselect behavior
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Accept and discard in live variant mode are now handled by a deterministic
script (live-accept.mjs) that runs inside the poller before returning to
the agent. The browser updates the DOM instantly on click (fire-and-forget)
so the user is never blocked waiting for LLM-driven file cleanup.
Key changes:
- New live-accept.mjs: deterministic accept/discard file operations
- Poller auto-runs accept script for accept/discard events (_acceptResult)
- Browser handleAccept() now commits DOM change instantly, no SAVING state
- CSS+HTML colocated in one write (style tag inside variant wrapper)
- SSE heartbeat every 30s prevents silent connection drops
- Poll timeout increased from 2min to 10min
- EventSource onopen resets retry counter for reliable reconnection
- Server --background flag for clean single-command startup
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Comprehensive architecture decision record covering the live variant
mode: context, key decisions (source modification over DOM patching,
SSE over WebSocket, self-contained skill scripts, HTTP long-poll for
agent), full architecture diagram with message flows, variant wrapper
format, browser UI states, session persistence, security model,
server resilience, performance optimizations, test coverage, known
limitations, and future work.
Also picks up improvements from parallel thread: poll timeout bumped
to 10 min, SSE heartbeat every 30s, and other minor fixes.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
os.tmpdir() returns /var/folders/.../T/ on macOS, not /tmp/. The skill
reference was telling the agent to cat /tmp/impeccable-live.json which
didn't exist. Moving the PID file to the project root makes it
predictable across platforms and project-scoped (multiple projects can
run independent live sessions).
Changed in: live-server.mjs, live-poll.mjs, live.md reference.
Added .impeccable-live.json to .gitignore.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
CI was running `bun test` which ran jsdom fixture tests in bun, causing
timeouts. Now uses `bun run test` which runs unit tests in bun and fixture
tests in node.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add first-class Pi (pi.dev) provider with transformer, tests, and build integration
- Fix CODEOWNERS username (@paulbakaus → @pbakaus)
- Add missing providers to issue/PR templates (Copilot, Kiro, OpenCode, Pi)
- Add Pi and OpenCode logos to homepage hero and install sections
- Move /onboard from "system" to "enhancement" category
- Update README and DEVELOP.md with all supported providers
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Run tests on push and PR to main
- Build project and upload artifacts
- Use Bun for fast JavaScript runtime
This ensures code quality and prevents regressions.
