Rewrite the routed bolder reference around what wins scoped
"make this section bolder" asks vs the frontend-design competitor.
Old prose was all visual levers and treated copy as secondary, so
the model kept flat placeholder copy verbatim and reached for a
decorative import for heft. New prose: scope stays sovereign;
diagnose flatness as opting out of the system's own moves; amplify
the system's own vocabulary; let content carry the weight; commit
then clarify; give the section its own scroll rhythm; a skeleton
test scoped to the section; a placeholder is a job, not a photo cue.
Drops the opening named-slop enumeration (self-priming) and the
120-line checklist (ceremony tax); now 31 lines.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Detect a missing CLI before worker startup, keep Live usable through the foreground poller, and surface actionable status in Live and Live Lab.\n\nAI-assisted implementation.
Opus probe (r10-opus-wireframe): control articulates loose skeletons,
wireframe arm names them (dubbing script sheet, timecode gutter spine)
and diffs against the standard stack every time. Targets Paul's
layout-diversity question: concept-atom commitment with template
skeletons underneath.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Paul: 'way better to have the first iteration land fully committed to
the concept, because that's the genuinely hard part. the next pass can
make sure it is clear and effective.' The check selected against the
original lektor site itself, the campaign's 10/10 reference.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The inverse-probe extracted this from Paul's NewRelic review and it won
in the batch4 forward test; it was never ported. Craft diagnosis: pages
lose on rhythm monotony (one treatment uniformly applied), not defects.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Paul: no stochastic challenger-assignment mode (unreproducible bad draws
= undebuggable bug reports); keep the weigh-off. Every roll now prints
its key so any field report can be replayed with --from.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contract-probe campaign findings (evals repo, notes/fable-oneshot-craft-plan.md):
a single model's resonance ranking is deterministic (30/35 identical
concepts across 16 framings); dice must come from the script, mirroring
the palette-seed result. Derived candidates stay grounded in the
audience's world + subject's cultural home; challengers win only on
identification x clarity; incumbent-with-deliberate-idea overrides the
roll. Validated at contract level on 01-observability + r10-lektor
(teletext ranks #3 for lektor; assigned index 3 produced it).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Four lines from the r10 dual consultation (codex gpt-5.6-sol + gemini
3.5-pro on the actual HTMLs) and the hero-probe micro-eval: the probe
isolated a first-viewport monoculture (same split template in every
sample, control and skill alike) and showed these lines break it while
codex's raw 15-liner alone does not. The incumbent sentence swap fixes
the r10 root cause both consultants independently identified.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Return after a durable starting record, overlap app-server initialization with page startup, dynamically reclaim generation after worker failure, and cap hard-crash leases at 15 seconds.\n\nAI-assisted: OpenAI Codex.
Update Live Lab and the Live reference with the default Sol worker, full-task quality gate, Spark control, cold readiness, and production architecture.\n\nAI-assisted: OpenAI Codex.
Default Codex to a dedicated Sol/medium app-server worker with native skill and image inputs, inherited project context, bounded source neighborhood evidence, and progressive context refresh. Other harnesses retain the portable foreground path.\n\nAI-assisted: OpenAI Codex.
Introduce a Live-owned app-server supervisor with progressive fenced publishing, partitioned control polling, cancellation and recovery safety, and measured integration coverage.
AI-assisted implementation under maintainer direction.
Transcript evidence (a12 01-observability): plans commit and deliver on
the axes with contract-strength language (palette, type, even theme
inversion) and stay default on the axis without one (layout gets a
single conventional breath). And plans living in invisible reasoning
means nothing can hold a build to its intent. The direction is now
written as a comment block at the top of the artifact answering: the
concept, the hour-later memory, why not the modal competitor page, the
signature, the first viewport's move. Critics and evals can score
delivery-against-contract; a mood is not an answer.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Paul's a10 review: palettes are refreshed (the palette-exclusivity
line's fingerprint) while layouts stay boring in every version. Same
cure, same shape: the layout has exactly two legitimate sources, the
concept or the content's own structure; the category's habitual
skeleton is neither.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Paul's a11 review: heroes are safe SaaS viewports, everything
predictable; mobile Operate ships dark despite a brief that specifies
outdoors-in-motion use. Decide-then-build now opens with three
one-line directions differing in concept (the instinctive pick that
any studio would reach for is the default wearing your name); the
Operate mode adds: the usage scene is part of the spec, the theme
follows the scene, not the category's habit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per Paul: rather than gating a second file, fold what made the craft
path superior into the file both models already read 21/21 through the
gate. new-work.md gains 'Decide, then build' (direction as one
confirmable paragraph; attended pauses, unattended records-and-goes;
codex.md mock flow when image generation exists) and 'Finish like a
studio' (inspect, honest critique, patch, detector). craft becomes a
deprecated alias like teach: invoking it forces attended checkpoints,
nothing else differs; the reference is a redirect stub. codex.md
retargeted. Existing-world feature builds remain governed by the core
floor (unmeasured path, noted in the plan doc).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
a7 transcript evidence: 01-observability samples drew orange-honey and
green seeds, recited the color-strategy menu, and shipped dark
category-reflex palettes anyway; the model applied the subject's
workmanlike grammar to its own landing page. Two generic lines: the
mode belongs to the surface, not the subject (a landing page for a
dense tool is still Persuade; deciding a page can be plain because its
subject is workmanlike is the category error in reverse), and the
palette has exactly two legitimate sources (seed or the subject's
world; the category's habitual palette is neither).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Fix batch from the visitor-mode bias audit. The skill's four modes
(Persuade / Operate / Read / Experience) now reach the places that were
still hard-coded to a SaaS-marketing default:
- palette.mjs: rewrote 45 seed blurbs in material/world terms. The 29
tech-tool-world moods (13 Linear-indigo variants, 6 Figma-era, 5
climate-tech, 3 fintech, 2 Glossier DTC, incl. seed-201's docs-page
CTA red) lose all company names and product-category words; Aesop
trimmed from 17 blurbs to 4 and Klim from 7 to 4, excess rewritten
as unnamed material terms. Also carries the earlier bg-block rewrite
(brand refs out of the composition doc).
- init.md: register explainer now names the four modes and the family
each belongs to (stored value stays brand/product for compatibility);
Conversion & proof interview + PRODUCT.md section gated to Persuade
surfaces only (Experience/Read get no CTA/belief-ladder/proof).
- critique.md: Nielsen heuristics 7 and 10 may score n/a on Persuade
and Experience surfaces, total renormalized to the applicable max,
snapshot records which were n/a; working-memory examples diversified
beyond dashboard/pricing anatomy.
- Register headers in bolder/delight/quieter/colorize/layout/animate/
typeset renamed from Brand:/Product: to Persuade + Experience: /
Operate + Read:; typeset and layout gain one Read-specific sentence
(steady reading measure; navigable linearity).
- animate.md: plan checklist and implementation order lead with
feedback and transitions; the single entrance moment comes after,
scoped to modes that invite it.
- codex.md: mock inventory says "primary-action treatment (when the
surface has one)" instead of assuming a CTA.
- delight.md: loading/empty-state/console-egg examples diversified
beyond SaaS; streaks/badges scoped to Operate surfaces with
recurring tasks.
- distill.md: step-removal and next-action lines neutralized away
from signup/checkout/CTA vocabulary.
- document.md: canonical button label GET STARTED -> SAVE CHANGES;
signature components gain a non-marketing example.
- antipatterns registry: single-font rule renamed to "Single font
without hierarchy" with a description that permits one family when
weight/size contrast carries hierarchy.
Staged provider copies regenerated via build:skills:release for the
touched files only.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Paul: the mode-governs section was de-biasing a persuade-tinted
playbook rather than writing neutral prose, the exact compensating-
paragraph anti-pattern. Rewritten: the corrective section is gone; the
first-viewport thesis speaks of the concept doing its job (the work,
the product, the content, the task); everything-bold's form list
includes the exact-system form natively; prove-don't-claim covers
content delivering; type guidance is parameterized by mode in one
sentence. Net shorter.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Paul's gallery check of the a8 docs run: skill-on still SaaS-ified the
documentation page. The playbook was persuade-flavored end to end, so
gating a greenfield Read surface through it risked amplifying exactly
that. New leading section: on Operate and Read surfaces boldness means
a committed system (typographic voice, spacing rhythm, one owned
accent, inevitable structure), the thesis is the content or the task
itself, and nothing invented may stand between the visitor and what
they came to do.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The when-to-choose guidance sat inside the file that only loads after
the choice is made. SKILL.md's routing now says it: bare build requests
build directly through the gate and floor; craft is routed only when
named or when the user asks for a guided, checkpointed build. The
Commands row describes craft by its checkpoints. craft.md's intro just
describes the supervised flow it orchestrates.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Stubs removed per Paul (register: values remain harmless family hints;
nothing points at the files anymore). craft.md now opens by defining
itself against plain invocation: a bare build request goes straight
through the gate and the craft floor; craft is the supervised path with
guaranteed checkpoints and the mock pipeline. One shipping-discipline
line joins the core floor (real content, interaction states, respect
the build pipeline) so one-shots inherit the bar that previously lived
only in craft's Step 4.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Answering the obvious question the family-depth framing dodged: with
modes derived per task, files named for the old two-register taxonomy
had no architectural reason to exist. brand.md's surviving depth (lane
test + inverse test, reflex-reject lanes, color discipline, layout
moves, permissions) folds into new-work.md, where all of it belonged:
it is new-identity Persuade/Experience guidance. product.md's content
moves unchanged to operate.md, its true name. Both old files remain as
one-line redirect stubs because register: brand|product in existing
PRODUCT.md files and older links point there. All cross-references
retargeted (SKILL.md modes intro, context.mjs REGISTER hint, live.md,
typeset.md); 85 tests green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Overlap audit after the new-work split. brand.md slims to family depth
that exists nowhere else (aesthetic-lane tests, named-reference
discipline, brand layout moves and permissions); everything it
duplicated against new-work.md and the core (font procedure, reject
list, color strategy, imagery, scale/leading) is deleted, killing the
two-copies-drift hazard. product.md keeps its Operate depth nearly
intact (it was not duplicated) and gains a scope note covering Read
surfaces. craft.md becomes pure orchestration: gates, foundation,
shape handoff, image-gen flow, engineering bar, iterate, present;
its duplicated design guidance (imagery rules, visual-craft bullets,
mandatory reference reads) is replaced by pointers to SKILL.md's
craft floor and new-work.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Architecture per Paul: impeccable is primarily a daily driver on
existing codebases; the always-loaded core should serve that 90% path,
not carry the full generative arsenal on every invocation. SKILL.md now
holds brief-wins, existing-worlds (the headline path), the four visitor
modes, the full craft floor, and a hard gate: new identity work
(greenfield, or a redesign discarding the current look) MUST read
reference/new-work.md before any design decision. That file carries the
generative playbook (seed, subject grounding, plan/self-check/signature,
hero-thesis, everything-bold, prove-don't-claim, color commitment,
calibration, persuade type/imagery). context.mjs enforces the gate
mechanically: NEW_WORK directive when no PRODUCT.md/DESIGN.md exists,
and the old mandatory register-file read is replaced by a REGISTER
family hint. No surfaces: map anywhere; mode is derived per task.
Gate compliance is measurable via skillEvidence.directSkillFileReads.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Eval evidence showed the per-edit PostToolUse stream fires overwhelmingly
on copy-level rules (em-dash-overuse ~97x/session) and measurably makes
models more conservative, while a full-detector pass at completion is what
actually fixes contrast/padding/glow. Split the hook accordingly:
- Per-edit (PostToolUse) now surfaces only IMMEDIATE_TIER_RULES: broken
output (broken-image, text-overflow, clipped-overflow-container,
body-text-viewport-edge), objective contrast/legibility failures
(low-contrast, gray-on-color, tiny-text), single-property mechanical
slop (gradient-text, dark-glow), and design-system drift (the four
design-system-* rules, which compound if left uncorrected). Everything
else defers. Override with hook.perEditRules: "all" in
.impeccable/config.json. Tiering is off for Cursor/Copilot harnesses,
which have no Stop pass wired, so nothing gets silently dropped there.
- Stop deep pass (runStopHook): runs the FULL rule set over every UI file
touched this session (tracked via the existing hook.cache.json session
state; deferred-only edits now mark the file touched), dedupes against
everything already surfaced per-edit, honors ignore-rule/file/value and
inline disables, reuses the [impeccable@1] envelope, and no-ops fast
when no UI files were touched. Emits hookSpecificOutput
{ hookEventName: "Stop", additionalContext } per the Claude Code SDK
Stop contract (conversation continues so the model can act on it).
Second Stop fire is silent - deep-pass findings are remembered.
- Wiring: Stop entries (timeout 30) in plugin/hooks/hooks.json, the
.claude settings + .codex hooks manifests (transformers + hook-admin
repair path). Claude Code and Codex both dispatch a native Stop event;
Cursor's stop hook is inconsistently dispatched (pre-write gate stays)
and Copilot's agentStop/sessionEnd don't inject model context, so
neither gets a Stop entry - documented in reference/hooks.md.
- Tests: tiering split/override/harness gating, Stop dedupe + silent
no-touched-files + ignore machinery + kill switches; existing per-edit
tests moved to immediate-tier rule ids. 181 tests green; smoke-tested
the built dist skill end to end (glow surfaced per-edit, em-dash only
at Stop, second Stop silent).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Pairwise evals on Fable one-shot (6-task regression set, opus-4-8 judge,
position-bias-cancelled): the hand-distilled ~55-line lean core beat the
heavy v4 core 66% overall / 67% craft head-to-head, and moved the
decisive win-rate vs frontend-design from 13% to 27% (40% with the
completion-time QA scan; craft went positive 6-5 for the first time).
18/18 lean samples ran context.mjs + palette.mjs vs a minority under the
heavy core: shorter instructions get followed. Context weight itself was
suppressing both compliance and boldness.
Structure: persona + brief-wins + existing-worlds + subject-grounding +
plan/self-check + boldness + prove-don't-claim + commit + calibration +
compressed craft floor + two-paragraph registers. Commands table kept;
the no-arg context-aware menu logic moved to reference/routing.md (read
on demand in the only case that is inherently interactive). Provider
blocks and rule anchors preserved.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Eval evidence (cand-v4a1-prose): palette.mjs handed a random violet seed
to the Polish-TV lektor brief and the model anchored on it, overriding
subject-grounding; craft/shape user gates can't fire in one-shot runs
and each model improvises around them. Seed is now a reflex-check that
yields to a subject-dictated palette; craft/shape gain an explicit
unattended mode (same bar, no waiting); init interview is skipped when
no user can respond.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Add positioning and conversion questions to init flow
Expand init.md so PRODUCT.md captures audience splits, positioning,
and brand-register conversion/proof context before design work starts.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Fix init over-inference by raising the evidence bar for skipping questions.
Sparse repos were letting the model treat weak guesses as settled answers; Step 3 now asks unless the codebase provides strong, explicit evidence.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Improve init interview order and PRODUCT.md proof output shape.
Ask positioning in round 1, actively collect proof assets, and give Proof & conversion a plain bullet skeleton so generated PRODUCT.md stays lean.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Fix init interview bundling and write-time padding, verified via harness runs
Co-authored-by: Cursor <cursoragent@cursor.com>
* Revert init reference follow-up rule to advisory wording on line 88
Co-authored-by: Cursor <cursoragent@cursor.com>
* Tighten init interview rules after harness runs: split register, options, prose
Settle split register before brand-only questions, require standalone emotions
and confirmed secondary audiences, forbid compound options, and keep PRODUCT.md
bold minimal.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Ask brand-register init questions in magazine-editor voice, no skill jargon
Co-authored-by: Cursor <cursoragent@cursor.com>
* Fix init chat fallback to ask one question at a time
When no structured question tool exists, init should ask in chat with
lettered options and wait for each answer instead of dumping a list.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Resolve init review comments: split purpose question, gate template section
Purpose and success are now separate questions, and docs-stated purpose
is framed as a hypothesis below the strong-evidence bar rather than a
competing always-ask rule. The PRODUCT.md template now tells product
register to omit the Conversion & proof section including its heading.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Keep belief-sequence question out of skill jargon
Ask what visitors must believe in plain words; map the answer to the
template belief ladder in a parenthetical instead of leading with the term.
Co-authored-by: Cursor <cursoragent@cursor.com>
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Abdul Wahab <abdulwahab@Abduls-MacBook-Pro-2.local>
* Add mechanical pre-scan for typeset and layout commands.
Introduce --scope filtering, layout/type rule scopes, DESIGN.md font-size validation, and pre-scan steps in the skill references so agents run detect before LLM judgment.
Fixes#149
Co-authored-by: Cursor <cursoragent@cursor.com>
* Add isolated sub-agent orchestration for typeset and layout pre-scans.
Run the mechanical detector and visual assessment in parallel sub-agents so deterministic findings cannot anchor LLM judgment, matching the critique pattern Paul requested on PR #345.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Fix: reject bare --scope so detect never scans unscoped by mistake.
When --scope had no value, the CLI dropped the flag and ran a full scan instead of failing, which could silently use the wrong rule set during typeset/layout pre-scans.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Fix: require both typeset and layout assessments in sub-agents.
Close a loophole where agents ran only the mechanical pre-scan inline by interpreting "running both" as permitting one inline assessment.
Co-authored-by: Cursor <cursoragent@cursor.com>
---------
Co-authored-by: Abdul Wahab <abdulwahab@Abduls-MacBook-Pro-2.local>
Co-authored-by: Cursor <cursoragent@cursor.com>
* Route native projects to native command variants for audit and adapt
Follow-up to #269. The web audit.md and adapt.md carried "translate this
yourself" Platform notes, so a native invocation paid for the full web
file (~1.8k / ~2.6k tokens, mostly inapplicable) and did error-prone
run-time translation. Authored with AI assistance (Claude Code) under
maintainer direction.
- New reference/audit.native.md and reference/adapt.native.md: authored
native content (VoiceOver/TalkBack, platform conformance, adaptivity
dimensions; phone-to-tablet, platform-to-platform, web-to-native
strategies). One variant per command covers ios, android, and
adaptive; per-OS specifics stay in the platform refs Setup loads
regardless.
- SKILL.src.md: Commands table lists the variants; Setup step 2 reads
the variant instead of the web file when the platform is native.
- audit.md / adapt.md: Platform sections replaced with a one-line
web-only guard pointing at the variant.
- animate.md / layout.md: Platform sections deleted; the Motion and
Layout sections of the already-loaded platform refs carry that
content. Web users now pay zero tokens for the platform axis in
these files.
- Skill-behavior scenario 15 pins the route-instead behavior (passes
live on claude-sonnet-4-6); CLAUDE.md documents the variant
convention.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Phrase command-reference routing as one rule, not rule-plus-exception
Copilot review catch: step 2 said "MUST read reference/<command>.md"
and then carved out the native variant, which invites loading both
files. Now a single rule: read the web reference or the table's native
variant, one file, not both. Scenario 15 re-verified live. Applied with
AI assistance (Claude Code) under maintainer direction.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Anchor native runs in animate/layout, drop loaded-refs assumption
Review-thread fixes, applied with AI assistance (Claude Code) under
maintainer direction:
- Greptile: deleting the animate/layout Platform sections left native
runs alone with web tooling instructions (CSS keyframes, GSAP, Grid,
clamp()). Restore a one-line anchor in each pointing at the loaded
platform reference's Motion / Layout section (~20 tokens, not the old
restatements).
- Bugbot: audit.native.md and adapt.native.md asserted the platform
refs were "already loaded in Setup", but the command reference loads
at step 2, before step 5. Now they instruct: read the platform
reference first if Setup hasn't already.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Carry the native-variant rule into routing rules 2 and 3
Bugbot catch: Setup step 2 routed native projects to the variant, but
routing rules 2 and 3 (the operative text at command time) still said
to load the generic reference file. Both now reference the same
one-file variant rule. Applied with AI assistance (Claude Code) under
maintainer direction.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Point animate/layout native anchors at the files, not "loaded" refs
Bugbot catch, same class as the variant wording fix: the anchor lines
said "the loaded platform reference" but command files load at step 2,
before the platform refs at step 5. Both anchors now name the files and
instruct reading them first if Setup hasn't already. Applied with AI
assistance (Claude Code) under maintainer direction.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Add a platform axis (web / ios / android / adaptive) to the skill
Orthogonal to register: register decides whether design IS or SERVES the
product; platform decides the delivery target and which native conventions
apply. Set `## Platform` in PRODUCT.md; a missing field defaults to `web`,
so legacy projects are unaffected.
- extractPlatform() in skill/scripts/context.mjs (mirrors extractRegister);
the CLI appends a NEXT STEP directive to read the native reference(s).
`adaptive` (Flutter / RN / KMP shipping both iOS and Android) loads both
ios.md and android.md.
- New reference/ios.md (Apple HIG distilled) and reference/android.md
(Material 3 distilled); reference/web.md is a thin pointer. The native
refs frame register's role as narrow: platform conformance is the bar,
brand lives in the expressive layer the platform gives you, never by
breaking the rails.
- Setup step 5 loads the native reference(s) when platform is native. Live
mode and the detect CLI stay web-only, gated off ios/android/adaptive.
- init asks platform right after register; adapt/audit/animate/layout carry
short platform divergence notes; all secondary spots thread `adaptive`.
- a11y stays in audit.md (loading it at design time makes output timid), so
the native refs carry no Accessibility section; audit.md's Platform
section owns native a11y.
- Tests: extractPlatform unit coverage + skill-behavior scenario 10
(PRODUCT.md platform ios -> agent loads ios.md).
Source-first: only skill/, scripts/, tests/, CLAUDE.md, NOTICE.md, the
changelog and version are committed; the sync workflow regenerates the
provider trees and ./plugin on merge.
ios.md / android.md are distilled from the MIT-licensed
ehmo/platform-design-skills; attribution in NOTICE.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Address review: gate web tools on native platforms, drop version churn
Maintainer-review fixes applied with AI assistance (Claude Code), on top
of the rebased platform-axis commit:
- Design hook (post-edit and Cursor pre-edit) now resolves the project
platform via loadContext + extractPlatform and skips its web rule scan
for ios / android / adaptive projects, so React Native / Flutter code
never draws web-shaped findings (new hook-lib resolveProjectPlatform /
isNativePlatform helpers, covered by unit and subprocess tests).
- context.mjs CLI warns on an unrecognized ## Platform value (e.g. a
toolchain name like `flutter`) instead of silently defaulting to web;
extractRegister / extractPlatform now share extractSectionValue.
- Removed reference/web.md: nothing loaded it; CLAUDE.md carries the
"web has no extra rulebook" explanation.
- init.md: skip live-mode config (Step 6) for native platforms; note the
per-app PRODUCT.md pattern for repos shipping web + native.
- android.md: Material-everywhere apps that also ship on iPhone still
owe iOS OS guarantees (safe areas, Reduce Motion, edge-swipe back).
- ios.md: reworded a design-time line that framed Dynamic Type as an
accessibility check (a11y stays owned by audit.md).
- Renumbered the new skill-behavior scenario to 14 after main's 10-13;
updated CLAUDE.md scenario list; added android + unrecognized-value
CLI test cases.
- No version or changelog changes: versioning happens at release time.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Tighten platform reference prose
Editorial pass on the platform-axis text, applied with AI assistance
(Claude Code) under maintainer direction:
- ios.md / android.md rewritten to house style: single-line paragraphs
(no hard wraps), one-sentence scope intro, deduplicated intro/slop-test,
register-compression down to two sentences. In-file attribution
paragraphs removed (NOTICE.md owns attribution); "read on top of the
register reference" cruft removed (SKILL step 5 and the context.mjs
directive already say it). Bans sections dropped: they restated the
rules above them; the two additive items (tab-bar overload,
hover-dependent affordances) folded into rules. ~40% smaller each.
- Sub-command Platform sections (adapt, audit, animate, layout), SKILL
step 5, init.md platform prose, and the context.mjs directive trimmed
the same way.
Build (prose validators, counts) and both test runners green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Treat an empty PRODUCT.md section as absent, not the next heading
Copilot review catch: extractSectionValue read the next `## ...` heading
as the section value when a field was left empty, which made the CLI
warn "value `## Product Purpose` is not recognized". Stop at the next
heading and return null instead. Regression tests for extractPlatform,
extractRegister, and the CLI warning path. Applied with AI assistance
(Claude Code) under maintainer direction.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Only read a token list of both native targets as adaptive
Bugbot catch: after the exact platform tokens failed, any Platform line
containing the words ios and android was classified adaptive, so
negated or explanatory prose ("web only, not ios or android") silently
loaded both native refs and skipped the hook, with no warning. The
combo parse now accepts only list separators and the two platform
words; anything else falls through to the CLI's unrecognized-value
WARNING. Regression tests added. Applied with AI assistance (Claude
Code) under maintainer direction.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Paul Bakaus <paul.bakaus@gmail.com>
* Point DESIGN.md spec links at the open-source GitHub spec.
The Stitch docs site is client-rendered and unreliable for agent fetch; the
google-labs-code/design.md repo tracks the latest machine-readable spec.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Sync plugin and harness copies after DESIGN.md spec link update.
build:release copies skill/reference into plugin/ and all harness dirs, so
refresh those generated outputs here instead of leaving plugin/ stale.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Use raw GitHub URL for DESIGN.md spec in agent-facing refs.
The blob URL serves HTML; raw.githubusercontent.com returns plain markdown
that agents can fetch directly.
Co-authored-by: Cursor <cursoragent@cursor.com>
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
* Add inline, in-file ignore comments for the detector (issue #283)
Complement config ignores with eslint-disable-style waivers that live where
they apply and travel with the file when it leaves the repo. The motivating
case is a generated/exported standalone document that legitimately uses a
first-party brand typeface (on the overused-font list) and is later scanned
without .impeccable/config.json present.
Marker is comment-syntax-agnostic (works in //, /* */, <!-- -->, #, {/* */}):
impeccable-disable <rule>[, <rule>...] [-- reason | : reason] whole file
impeccable-disable-line <rule>... same line
impeccable-disable-next-line <rule>... next line
Bare directive or * means every rule; reason is optional and discarded at
scan time. Behavior is suppression, for parity with config ignores.
Implementation:
- New pure module cli/engine/shared/inline-ignores.mjs (parser + filter, no
Node deps). Static-HTML findings have no line number, so only whole-file
directives apply there -- exactly the standalone-document case; the
regex/text engine additionally honors the line-scoped forms.
- Wired into detectText and detectHtml, gated by options.inlineIgnores.
- detect CLI applies inline ignores by default; --no-inline-ignores skips
just them, --no-config skips config and inline ignores together.
Docs: config.md (new section), detector.md, README. skill/reference/hooks.md
reversed its prior "inline comments are not supported" guidance and now points
the agent to inline waivers for the travels-with-the-file case. Changelog 3.x.
Tests: tests/inline-ignores.test.mjs (parser units, detectText/detectHtml
integration, CLI end-to-end), registered in the detector suite.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Reconcile design hook wording with inline ignores
Two hook-side fixes prompted by review of the new inline-ignore feature:
1. Clean-ack steer line. The old line ("Keep typography hierarchy, spacing
rhythm, and color contrast intentional on the next change.") read as an
odd non-sequitur after "No anti-patterns." Reworded the whole clean ack to
say what it means: a clean scan only clears the deterministic rule set, not
overall design quality, so keep following the design system and skill
guidance. Now: "Design hook scanned X. No deterministic design-quality
issues found. That does not mean the design is good: keep following the
project design system and the impeccable skill guidance."
2. Directive footer. It still told the agent "Do not add source comments such
as `impeccable: ignore`; those pollute the code and do not suppress hook
findings." That is now misleading: the hook runs the same detector engine
as the CLI, which honors inline `impeccable-disable` waivers, so they DO
suppress hook findings (consistent with config ignores, which filterFindings
already honors). Reworded to: don't silence a real finding to skip fixing
it; suppress only after the user confirms intent; prefer a config ignore,
and reach for an inline `impeccable-disable <rule>` comment only when the
waiver must travel with a file that leaves the repo.
Added a hook test asserting an inline `impeccable-disable-line` comment makes
the hook scan the file clean (locks in the cross-cutting behavior), and updated
the clean-ack / footer assertions to the new wording.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Address review on inline-ignores parser
- Case-insensitive fast-path bail-out (Cursor): the cheap substring guard was
lowercase-only while DIRECTIVE_RE has the `i` flag, so a mixed-case marker
like `Impeccable-Disable` skipped parsing entirely and never suppressed.
Switched the guard to `/impeccable-disable/i.test(...)`. Added a regression
test.
- Removed the unreachable `-->` branch from TRAILING_CLOSER_RE (Greptile):
`--+>` already matches `-->` and any longer dash run.
- Replaced the always-truthy lazy-match + `if (sep)` reason strip with an
explicit first-separator slice (Greptile): clearer and drops the dead branch.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Align inline-ignore line numbering with the detector (CRLF/CR endings)
parseInlineIgnores split lines with /\r\n|\r|\n/, but detectText numbers lines
with split('\n'). On classic `\r`-only endings the two diverged, so a
disable-line / disable-next-line directive could key a different line than the
finding it should waive (Cursor review). Split on '\n' only, matching the
detector exactly; the directive regex already excludes '\r', so a trailing '\r'
on CRLF files is never captured into the rule list. Added a CRLF regression test
through the real detectText.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Context files (PRODUCT.md / DESIGN.md) resolve child-first then fall back to the repo root, and /impeccable live lets the user pick a child app in a monorepo. Single-app behavior is unchanged. Closes#202. Co-Authored-By: abdulwahabone
* Add GitHub Copilot hook support (CLI + cloud agent)
Wire the Impeccable design detector into GitHub Copilot's hook system so
direct file edits get the same post-edit design feedback the Claude Code,
Codex, and Cursor harnesses already receive.
GitHub Copilot's contract differs from the existing harnesses (verified
against Copilot CLI 1.0.63):
- Repo-level manifest at `.github/hooks/impeccable.json` (read by both the
CLI, once committed to the default branch, and the cloud/app agent).
- Flat `postToolUse` entries with `bash`/`timeoutSec` and a full-match
`matcher` regex; the file-editing tools are `edit` and `create`.
- The stdin event uses camelCase `toolName`/`toolArgs`, where `toolArgs` is
a JSON *string* carrying the touched file under `path`.
- Context is injected via a top-level `additionalContext` string.
Changes:
- hooks.js: buildGitHubHooksManifest() + route `github` in hooksJsonFor().
- providers.js: emitHooks/hooksManifestRel for the github provider.
- hook-lib.mjs: detect the github harness, normalize the camelCase event
(parse the JSON-string toolArgs -> tool_input.file_path), and emit the
`additionalContext` payload shape.
- hook-admin.mjs / skills.mjs: install + idempotent-repair the
`.github/hooks/impeccable.json` manifest (bash-aware marker stripping).
- hooks.md: document GitHub Copilot as a supported harness.
- Tests for the builder, routing, event normalization, and end-to-end run.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Cover Copilot apply_patch edits in the hook (live-verified)
The first cut matched only `edit|create`, the tool names `copilot -p` uses.
A live trace against Copilot CLI 1.0.63 in an interactive session showed it
edits files via `apply_patch`, whose toolArgs is a raw OpenAI-format patch
string (`*** Begin Patch` / `*** Add File:`), not JSON. With the narrow
matcher the hook command never ran.
- hooks.js / hook-admin.mjs: matcher -> `edit|create|apply_patch`.
- hook-lib.mjs: normalizeGitHubEvent now routes apply_patch's raw patch
string into tool_input.command (reusing the existing parseApplyPatchPaths /
resolveTargetFiles plumbing) and only JSON-parses toolArgs for the
edit/create/view tools. tool_name is normalized to apply_patch so the patch
path is extracted even if a future build relabels the tool.
- Tests: apply_patch matcher assertions, event normalization, and an
end-to-end runHook covering the interactive/cloud path.
Verified live: a trusted interactive `apply_patch` edit fires the hook and
returns the expected `additionalContext` design reminder.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Address review feedback + add changelog entry
- hook-lib.mjs (Bugbot, low): looksLikeApplyPatch no longer misroutes an
edit/create event whose edited *content* contains apply_patch markers. A
real apply_patch payload is a raw string that does not parse as JSON; an
edit payload is a JSON object, so only non-JSON-object strings are treated
as apply_patch. Edit events keep extracting `path`. Adds a regression test.
- skills.mjs (Bugbot, medium): document why `.github` is intentionally
excluded from hookScriptPathForProvider. Its hook manifest is committed and
shared (read by the Copilot cloud agent and teammates), so the command must
stay portable via `$(git rev-parse ...)`; rewriting it to a machine-local
absolute path would break those. GitHub skills are project-scoped, so the
project-relative path resolves.
- changelog: add an Upcoming (v3.x placeholder) entry for the Copilot hook.
Version is not bumped yet (batching with other changes).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(cli): interactive hook consent + unified .impeccable/config.json
Make the design-hook install a conscious choice and unify scattered config
into one file.
Interactive consent
- On an interactive `skills install`/`update`, the CLI explains what the hook
does and offers to install it (default yes), then records the per-developer
decision in the gitignored `.impeccable/config.local.json`, so it never
re-asks. A recorded decision or an already-installed hook short-circuits;
`-y`/non-TTY keeps the historical install-by-default behavior; `--no-hooks`
is a one-off skip that records nothing. The trigger keys on "is the hook
installed?" + "is there a recorded decision?", not a brittle version check.
Unified config
- `.impeccable/config.json` (shared) and `.impeccable/config.local.json`
(gitignored) now hold all Impeccable settings: hook settings under a `hook`
key, plus top-level `updateCheck`. `/impeccable hooks` writes the `hook`
subtree, preserving siblings. The hook runtime reads `hook.quiet` and
`hook.auditLog`; context boot reads `updateCheck`. The legacy
`IMPECCABLE_HOOK_DISABLED|QUIET|LOG` and `IMPECCABLE_NO_UPDATE_CHECK` env vars
still work and override config; docs now lead with config and treat env vars
as a legacy note.
- No backward compat for the pre-unification `hook.json`/`hook.local.json`
(the hook shipped an hour ago; nothing in the wild uses it). This repo's own
hook config is migrated to `.impeccable/config.json`.
The CLI and skill scripts are separate trees, so a small CLI-side config module
(cli/lib/impeccable-config.mjs) duplicates the config-path and .git/info/exclude
handling; comments flag the duplication.
Tests: new cli config unit test; skills-cli consent tests (declined skips,
accepted installs, --no-hooks records nothing); hook.test.mjs back-compat
removed and quiet/auditLog-from-config + gitexclude coverage added. Full suite
green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(hooks): preserve sibling config fields + resolve audit log from event cwd (Bugbot)
Two Bugbot findings:
- High: `/impeccable hooks` edits replaced the whole `hook` object with the
merge-helper output, dropping fields those helpers don't manage — so an
`ignore-value --local` could wipe the recorded install consent and make the
CLI re-prompt. writeConfig now merges over the existing hook object, keeping
consent/quiet/auditLog.
- Medium: config-based audit logging resolved hook.auditLog from process.cwd(),
which can differ from the hook event's project root (and Cursor's pre-edit
hook passed no cwd). The hook now stamps the resolved project root on the
audit entry, and writeAuditLog reads config from entry.cwd when present.
Tests: a /impeccable hooks edit preserves consent + quiet; writeAuditLog
resolves config auditLog from entry.cwd, not the fallback cwd.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(hooks): resolve a relative auditLog path against the project root (Bugbot)
A relative hook.auditLog was read from the project root but written relative to
the hook process cwd, so when those differ the log went to the wrong place.
writeAuditLog now resolves a relative target (from env or config) against the
same project root it reads config from. Absolute and ~/ paths are unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Fix hook consent recovery and smoke config
* Fix hook consent explainer for Cursor
* Fix empty hook target consent
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(hooks): package design hook in plugin, install to settings.local.json
Three related changes to how the Impeccable design hook is distributed,
plus an unrelated build fix discovered along the way.
Package the hook in the Claude Code plugin
- The marketplace / `/plugin install` path previously shipped the skill and
agents but no hook, so those users never got the design detector. The build
now emits `plugin/hooks/hooks.json` (auto-discovered at the plugin root),
resolving the script via `${CLAUDE_PLUGIN_ROOT}` so it works wherever Claude
Code unpacks the plugin instead of assuming a `.claude/skills/` layout.
CLI installs the hook into settings.local.json, not shared settings.json
- `npx impeccable skills install/update` now writes the Claude hook to the
gitignored `.claude/settings.local.json` (a machine-local install side
effect) rather than the team-shared `settings.json`, which could otherwise
be committed and break for teammates without the skill installed.
- Graceful handling (leave-it-never-duplicate): if our hook already lives in
the shared `settings.json` (a legacy install or a deliberate user move), it
is honored in place and never duplicated into the local override, which
would otherwise run the detector twice per edit.
- The skill's `/impeccable hooks on|off` toggle is unaffected: it only writes
`.impeccable/hook.json`, never the settings files.
Fix universal.zip build failure under archiver v8
- `archiver` was bumped to v8 (now ESM, factory function removed) but
`scripts/lib/zip.js` still used the old `archiver('zip', ...)` API, so every
build silently failed to produce `dist/universal.zip` (the skill-release
artifact). Switched to `new ZipArchive({...})`.
Also folds in a pre-existing local rename of the hook status message
("Scanning design" -> "Checking UI changes") and its regenerated provider
output.
Tests: new coverage for the plugin-packaged hook manifest and the
shared-settings honor-in-place path; existing CLI assertions moved to
settings.local.json. Full suite green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): detect hook by marker, not file existence (Bugbot)
hookInstalledForProvider treated any existing settings.local.json (or
hooks.json) as proof the hook was installed. Those files commonly hold
unrelated local settings, so the already-installed `skills install` path
would skip repairing a genuinely missing hook that `update` would add.
Detect the Impeccable marker in the file instead of mere existence. Adds a
test for the exact case: a settings.local.json with only permissions still
triggers hook repair and preserves the unrelated content.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* test(build): fail loud on a broken release zip + cover the zip writer
Close the gap that let the archiver v8 break ship a 0-byte universal.zip
with a green test suite:
- createProviderZip no longer swallows failures. It throws on a missing
source, an archive with zero entries, or a 0-byte output, and build() now
exits non-zero on any such rejection. A build that can't produce its release
artifact fails instead of deploying an empty bundle.
- New tests/zip.test.mjs exercises the real zip writer and round-trips through
extract-zip (the unpacker the CLI uses): a valid bundle unpacks to the skill
tree, and the empty/missing-source cases throw. Wired into the core suite so
it runs in `bun run test`.
Why this matters: the prior CLI e2e tests stub the bundle as a local
directory, so they never built, downloaded, or unzipped a real archive. The
zip writer had no coverage and failed soft, so Dependabot's archiver 7->8
major bump merged green and the deploy shipped an unusable bundle.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(cli): scope hook marker scan to the hooks subtree + prune local dupes (Bugbot)
Two follow-ups from Bugbot:
- fileHasImpeccableHookMarker scanned the whole settings file as raw text, so
an unrelated string (e.g. a permissions allow entry that mentions the hook
path) could falsely read as an installed hook and block install/repair or
the shared-settings skip. Now it parses the JSON and scans only the `hooks`
subtree.
- When the hook is honored in the shared settings.json, copyProviderHooks
skipped the local write but left a stale hook in settings.local.json from an
earlier machine-local install, so Claude Code loaded both and ran the
detector twice per edit. It now prunes the local copy (preserving unrelated
local settings, dropping the file if only our scaffolding remained).
Adds tests for both: a permissions string mentioning the hook path still
triggers repair, and a shared hook prunes the stale local duplicate while
keeping unrelated permissions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: add PRD for design detector hook integration
Plans a PostToolUse hook for Claude Code and Codex that runs the
existing design detector after every relevant file write and feeds
findings back to the agent as advisory system-reminder context. No
implementation in this commit; covers UX, technical design, build
pipeline changes, distribution, coverage tradeoffs, and rollout.
Co-authored-by: Cursor <cursoragent@cursor.com>
* docs: revise hook PRD with best-practices review
Folds in the P0/P1/P2 findings from an online best-practices critique
against the official Claude Code and Codex hook references plus 10+
2026 community guides and similar prior-art tools (claw-hooks,
claude-code-hooks-mastery).
Key changes:
- Exec form everywhere (Codex snippet was shell form), with Windows
rationale.
- Default timeout dropped from 10s to 5s.
- Re-entrancy guard (CLAUDE_HOOK_DEPTH) and per-file edit counter.
- Session-scoped finding dedup promoted from open question to v1.
- Per-language inline-ignore syntax map (HTML/JSX/CSS/JS).
- Hard-skip rules for sensitive paths and generated/lock files.
- Honest framing about Claude Code lacking per-plugin hook disable.
- Honest framing about Bash-written files being invisible in v1.
- Codex Windows-not-supported call-out, feature flag note, trust ceremony detail.
- Optional NDJSON audit log via IMPECCABLE_HOOK_LOG.
- Findings cap lowered 8 → 5 with attention-budget rationale.
- Versioned envelope ([impeccable@1]) on rendered template.
- Expanded test plan, decision log, and stdin payload appendix.
Co-authored-by: Cursor <cursoragent@cursor.com>
* feat(hooks): ship the design detector hook for Claude Code and Codex
Implements docs/hooks-prd.md: a PostToolUse hook that runs the
impeccable design detector after every Edit/Write/MultiEdit on a UI
file and pushes findings into the agent's next-turn context as a
short system reminder. Silent on clean files. Never blocks an edit.
Why this matters: today, design slop (side-tab borders, gradient
text, purple/cyan palettes, bounce easing, etc.) only gets caught
when a human notices or someone explicitly runs /impeccable audit.
The hook closes the loop at the moment slop is written.
What ships in v1
- skill/scripts/hook.mjs: PostToolUse entry. Reads stdin, runs the
detector in-process (no `npx impeccable` cold start), emits
hookSpecificOutput.additionalContext when fresh findings exist.
- skill/scripts/hook-lib.mjs: extracted helpers (config, cache,
filter, render, audit log, runHook orchestrator). 100% unit-testable.
- skill/scripts/hook-session-start.mjs: SessionStart greeting,
gated by a project-scannable probe + 30-day throttle.
- skill/scripts/hook-admin.mjs: backs /impeccable hooks
on/off/status/ignore-rule/ignore-file/reset.
Hardening built in
- Re-entrancy guard (IMPECCABLE_HOOK_DEPTH) so the hook can never
recursively spawn itself.
- Hard-skip regexes for sensitive paths (.env, .pem, id_rsa,
secrets, credentials, .git) and generated/lock/build output. These
fire before the file is even read; cannot be turned off via config.
- Path-traversal check on the inbound file_path.
- Session-scoped dedup keyed by (session, file, rule, line) so the
same finding never lands in context twice. Prevents the ~12.5K
wasted tokens per chatty session called out in the PRD.
- Per-(session, file) edit counter with a one-shot suppression
notice on the 7th edit, silent after.
- Fail-open contract: every error path returns exit 0 with no
stdout. Optional NDJSON audit log via IMPECCABLE_HOOK_LOG.
Three kill switches (precedence high to low):
1. IMPECCABLE_HOOK_DISABLED env var (1/true/yes/on, case-insensitive)
2. .impeccable/hook.json `enabled: false`
3. /impeccable hooks off slash command (writes the JSON)
Inline ignores are language-aware. `// impeccable: ignore <rule>` for
JS/TS, `<!-- impeccable: ignore <rule> -->` for HTML/Vue/Svelte/Astro,
`{/* impeccable: ignore <rule> */}` for JSX/TSX, `/* impeccable:
ignore <rule> */` for CSS. `*` matches any rule. Directive applies
to the next non-blank line. Same shape as ESLint, Stylelint, Biome.
Build pipeline
- scripts/lib/transformers/hooks.js: per-provider hooks.json
builders, plus the slim .codex-plugin/plugin.json manifest.
- providers.js: emitHooks: 'claude' for claude-code, emitHooks:
'codex' for codex and agents. Codex also emits emitCodexPlugin.
- factory.js: emits hooks/hooks.json next to the skills tree.
- build.js: syncs hooks/ into harness roots and into the slim
plugin/ subtree; writes .codex-plugin/plugin.json. Build is
idempotent (verified: 98 staged files unchanged across two runs).
Claude Code wiring uses exec form (command + args) and the
${CLAUDE_PLUGIN_ROOT} placeholder. Matcher: Edit|Write|MultiEdit.
`if:` glob filters to UI extensions before spawning Node. PostToolUse
timeout 5s, SessionStart timeout 3s.
Codex wiring uses ${PLUGIN_ROOT} (Codex's native placeholder),
matcher Edit|Write|apply_patch, no `if:` analog (the script does the
extension filter). macOS and Linux only; hooks are disabled on
Windows in current Codex builds. The trust ceremony and feature flag
are documented in README.md.
Routing
- /impeccable hooks lives outside the 23-command router table on
purpose: it is plumbing, not a design skill. The hidden
routing slot is added to SKILL.md alongside pin/unpin so the LLM
knows to dispatch it. The 23-command count and all stale-count
validators remain happy.
Tests
- tests/hook.test.mjs: 38 unit tests covering env parsing, config
load + defaults + malformed, cache round-trip + GC,
ignoreRules/minSeverity/inline ignores (all four languages),
globbing with **/*/{a,b}, render template with cap + clamp + 0-line
prefix drop, audit log NDJSON, payload event-name parameterization,
re-entrancy, kill switches, sensitive-path + generated-path +
traversal skips, allowlist filter, config ignoreFiles, edit
counter cycle including the 7th-edit notice, MultiEdit and
apply_patch payload shapes, detector throw swallow, malformed
stdin, missing file race.
- tests/hook-build.test.mjs: 18 integration tests covering hook
manifest shape (matcher, timeouts, exec form, if: glob, placeholders),
Codex differences (${PLUGIN_ROOT}, no if:, no SessionStart),
Codex plugin manifest (no inline hooks field to avoid the
duplicate-file error), routing across the hooksJsonFor table, and
presence of all three committed artifacts plus the bundled detector
the runtime relative-import path depends on.
Full suite: 175 bun tests + 186 node tests, all green.
Docs
- README.md: new "Design hook" section explaining default behavior,
per-project / global / inline disable paths, the JSON schema knobs,
the audit log debug flag, and the slop / a11y coverage split.
- HARNESSES.md: flips the `hooks` row for Codex from No -> Yes
(Claude was already Yes), adds a per-harness hook-surface table
with the manifest location and matcher each provider uses.
Open questions from the PRD intentionally deferred to v2: Bash-write
blind spot, effort-aware suppression, Stop-hook session summary,
per-rule severity, async hook mode. None block v1.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Fix Codex hook scanning: apply_patch paths and co-located stylesheets
Parse file targets from Codex apply_patch command bodies, co-scan imported
and sibling CSS when UI components are edited, drop the git-sweep PostToolUse
group, and align Codex SessionStart manifest and trust docs with the official
hooks spec.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Gitignore hook session cache and drop local test HTML
Hook dedup/throttle state in .impeccable/hook.cache.json is per-project
runtime data like other .impeccable/ sidecars. Remove an untracked
bad-nested-flexbox scratch page from site/public/.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Fix Claude Code hook: drop Edit-only if filter so Write/MultiEdit fire
Claude's if permission rule binds to one tool name, so Edit(*.{…}) never
spawned the hook on Write or MultiEdit despite the matcher listing them.
Extension filtering now lives in hook-lib on both Claude and Codex.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Surface Cursor design findings via stop-hook followup
Replace dropped postToolUse additional_context with afterFileEdit recording
and a one-shot stop followup_message so anti-pattern nudges reach the agent.
Co-authored-by: Cursor <cursoragent@cursor.com>
* Fix design hook packaging and scans
* Fix Cursor hook pending bucket fallback
* Fix Sass hook scan coverage
* Fix Cursor hook review findings
* Fix session start dead hook normalization
* Fix hook config and relative scan paths
* Remove SessionStart design hook
* Remove redundant afterFileEdit normalization
* Fix Cursor suppression and module style scans
* Fix sensitive path hook filter
* Fix disabled Cursor stop hook emission
* Refresh hook harness artifacts
* Fix Cursor hook manifest install
* Add hook ignore-value support
* Ignore hook runtime files locally
* Fix Codex plugin hook packaging
* fix: address PR review bot findings
Block numeric hook depth counters from re-entering.
Avoid following stylesheet imports from traversal-looking hook targets.
* fix: gate ignore-value suggestions by supported rules
Only render exact ignore-value commands when the same finding can be suppressed by ignoreValues.
* Package Codex plugin as hook-only
* Remove Codex plugin packaging
* Recover hook install probe plumbing
* Remove Codex hook packaging follow-up doc
* Remove extra hook docs and skill wording changes
* Install real design hooks via skills CLI
* Add provider hook smoke runner
* Fix Cursor hook delivery with preToolUse gate
* Simplify Cursor hook install to preToolUse
* Clarify confirmed hook exceptions
* Persist hook ignores in shared config
* Guard font hook exceptions
* Fix hook install after main rebase
* Fix hook scan target handling
* fix: address hook review findings
* Address hook review feedback
* Stabilize DeepSeek insert live fixture
* Fix Cursor hook Python shell write bypass
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
Paul BakausandClaude Fable 5
