impeccable 3.1.0 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable CLI
2
2
 
3
- Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 44 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 46 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
56
56
 
57
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
58
58
 
59
- 44 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 46 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
60
60
 
61
61
  ## Exit Codes
62
62
 
@@ -75,7 +75,7 @@ impeccable detect [options] [file-or-dir-or-url...]
75
75
 
76
76
  ## Requirements
77
77
 
78
- - Node.js 24+
78
+ - Node.js 22.12+
79
79
  - `jsdom` (included as dependency, used for HTML scanning)
80
80
  - `puppeteer` (optional, only needed for URL scanning)
81
81
 
package/README.npm.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable CLI
2
2
 
3
- Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 44 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
3
+ Detect UI anti-patterns and design quality issues from the command line. Scans HTML, CSS, JSX, TSX, Vue, and Svelte files for 46 deterministic rules, including AI-generated UI tells, accessibility violations, and general design quality problems.
4
4
 
5
5
  ## Quick Start
6
6
 
@@ -56,7 +56,7 @@ npx impeccable detect --fast src/
56
56
 
57
57
  **Quality**: tiny body text, cramped padding, long line lengths, small touch targets
58
58
 
59
- 44 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 46 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
60
60
 
61
61
  ## Exit Codes
62
62
 
@@ -75,7 +75,7 @@ impeccable detect [options] [file-or-dir-or-url...]
75
75
 
76
76
  ## Requirements
77
77
 
78
- - Node.js 24+
78
+ - Node.js 22.12+
79
79
  - `jsdom` (included as dependency, used for HTML scanning)
80
80
  - `puppeteer` (optional, only needed for URL scanning)
81
81
 
package/README.repo.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Impeccable
2
2
 
3
- Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 44 deterministic detector rules for AI-generated frontend design.
3
+ Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 46 deterministic detector rules for AI-generated frontend design.
4
4
 
5
5
  > **Quick start:** From your project root, run `npx impeccable install`, then run `/impeccable init` inside your AI coding tool. Full docs: [impeccable.style](https://impeccable.style).
6
6
 
@@ -13,7 +13,7 @@ Every model trained on the same SaaS templates. Skip the guidance and you get th
13
13
  Impeccable adds:
14
14
  - **One setup flow.** `/impeccable init` writes `PRODUCT.md` and offers `DESIGN.md`, so later commands know the audience, brand/product lane, voice, anti-references, colors, type, and components.
15
15
  - **23 commands.** A shared design vocabulary with your AI: `polish`, `audit`, `critique`, `distill`, `animate`, `bolder`, `quieter`, and more.
16
- - **44 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
16
+ - **46 deterministic detector rules** plus LLM-only critique checks. The CLI and browser extension run the deterministic rules with no LLM and no API key.
17
17
 
18
18
  ## What's Included
19
19
 
@@ -91,7 +91,7 @@ The skill includes explicit guidance on what to avoid:
91
91
 
92
92
  ## See It In Action
93
93
 
94
- Visit [impeccable.style](https://impeccable.style#casestudies) to see before/after case studies of real projects transformed with Impeccable commands.
94
+ Visit [the Neo Mirai case study](https://impeccable.style/cases/neo-mirai) to see a before/after case study of a real project transformed with Impeccable commands.
95
95
 
96
96
  ## Installation
97
97
 
@@ -103,7 +103,7 @@ From the root of your project, run:
103
103
  npx impeccable install
104
104
  ```
105
105
 
106
- This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, and Codex, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, and every other supported tool. Reload your harness afterward.
106
+ This shows the harness folders it detected (for example `~/.claude`, `~/.codex`, or project-local `.cursor`), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use `--providers=claude,codex,cursor` and `--scope=project|global` to skip those choices in scripts. On Claude Code, Cursor, and Codex, it also installs the provider-native hook manifest for the current project. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, and every other supported tool. Reload your harness afterward.
107
107
 
108
108
  To refresh an existing install, run:
109
109
 
@@ -133,11 +133,27 @@ git submodule update --remote .impeccable
133
133
  npx impeccable link --source=.impeccable --providers=claude,cursor
134
134
  ```
135
135
 
136
- ### Option 3: Download from Website
136
+ ### Option 3: Plugin install
137
+
138
+ **Claude Code:**
139
+ ```bash
140
+ /plugin marketplace add pbakaus/impeccable
141
+ ```
142
+
143
+ > Claude Code only. After adding the marketplace, open `/plugin` and install Impeccable from the list.
144
+
145
+ **Grok Build:**
146
+ ```bash
147
+ grok plugin install pbakaus/impeccable --trust
148
+ ```
149
+
150
+ > Grok Build only. Then run `/impeccable init` in a Grok session.
151
+
152
+ ### Option 4: Download from Website
137
153
 
138
154
  Visit [impeccable.style](https://impeccable.style), download the ZIP for your tool, and extract to your project.
139
155
 
140
- ### Option 4: Copy from Repository
156
+ ### Option 5: Copy from Repository
141
157
 
142
158
  **Cursor:**
143
159
  ```bash
@@ -258,6 +274,46 @@ If you reach for one command often, pin it with `/impeccable pin audit` to get `
258
274
 
259
275
  **Note:** Codex uses skills here, not `/prompts:` commands. Open `/skills` or type `$impeccable`. Repo-local installs live in `.agents/skills/`; user-wide installs live in `~/.agents/skills/`. GitHub Copilot uses `.github/skills/`. Restart the tool if a newly installed skill does not appear.
260
276
 
277
+ ## Keeping `.impeccable` out of git
278
+
279
+ As you run commands, Impeccable writes working files under `.impeccable/`: critique and polish screenshots, live-mode session and preview state, runtime caches, and per-developer config. Most of it is ephemeral and should not be committed, while a few files are shared project artifacts that belong in the repo. Add this block to your project's `.gitignore`:
280
+
281
+ ```gitignore
282
+ # impeccable-ignore-start
283
+ # Ephemeral output, runtime state, and per-dev overrides.
284
+ # Unanchored: .impeccable may sit at the repo root or under a nested
285
+ # workspace (apps/web/.impeccable/...); anchored patterns would miss it.
286
+ # Shared artifacts stay tracked: config.json, live/config.json,
287
+ # design.json, critique/*.md.
288
+ .impeccable/config.local.json
289
+ .impeccable/hook.cache.json
290
+ .impeccable/hook.pending.json
291
+ .impeccable/*.png
292
+ .impeccable/live/server.json
293
+ .impeccable/live/sessions/
294
+ .impeccable/live/previews/
295
+ .impeccable/live/annotations/
296
+ .impeccable/live/cache/
297
+ .impeccable/live/manual-edit-apply-transaction.json
298
+ .impeccable/live/manual-edit-events.jsonl
299
+ .impeccable/live/manual-edit-evidence/
300
+ .impeccable/live/pending-manual-edits.json
301
+ .impeccable/live/deferred-svelte-component-accepts.json
302
+ .impeccable/live/*.png
303
+ # impeccable-ignore-end
304
+ ```
305
+
306
+ The block is wrapped in `# impeccable-ignore-start` / `# impeccable-ignore-end` markers so you can recognize and refresh it later. Patterns are unanchored on purpose: in a monorepo the active project (and its `.impeccable/` directory) often lives under a nested workspace path like `apps/web/`, and a root-anchored pattern would miss it.
307
+
308
+ **Keep these tracked** (they are shared project artifacts, do not add them to `.gitignore`):
309
+
310
+ - `.impeccable/config.json` (unified shared config)
311
+ - `.impeccable/live/config.json` (live-mode framework wiring)
312
+ - `.impeccable/design.json` (shared design spec)
313
+ - `.impeccable/critique/*.md` (review reports)
314
+
315
+ If an ephemeral file (a screenshot, `config.local.json`) was committed before you added the block, `.gitignore` will not untrack it automatically. Run `git rm --cached <path>` to stop tracking it without deleting your local copy.
316
+
261
317
  ## Design hook
262
318
 
263
319
  On Claude Code, GitHub Copilot, Codex, and Cursor, `npx impeccable install` and `npx impeccable update` install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, and Codex surface findings after the edit. Cursor blocks bad proposed writes before they land.
@@ -301,7 +357,7 @@ npx impeccable ignores add-file "src/legacy/**"
301
357
  npx impeccable ignores add-value overused-font Inter --reason "Brand font"
302
358
  ```
303
359
 
304
- The detector catches 44 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
360
+ The detector catches 46 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
305
361
 
306
362
  By default, `detect` respects the same `.impeccable/config.json` and `.impeccable/config.local.json` detector config as the design hook: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. Hook lifecycle settings such as `hook.enabled` only affect automatic hook execution.
307
363
 
@@ -316,6 +372,7 @@ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/do
316
372
  - [GitHub Copilot](https://github.com/features/copilot)
317
373
  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
318
374
  - [Codex CLI](https://github.com/openai/codex)
375
+ - [Grok Build](https://x.ai/cli)
319
376
  - [OpenCode](https://opencode.ai)
320
377
  - [Pi](https://pi.dev)
321
378
  - [Kiro](https://kiro.dev)
@@ -59,6 +59,13 @@ const PROVIDER_DISPLAY = {
59
59
  };
60
60
  const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev'];
61
61
 
62
+ // Providers whose GLOBAL (home) skills dir is not `<provider>/skills`.
63
+ // Pi discovers global skills from ~/.pi/agent/skills/; project scope
64
+ // stays .pi/skills/. See issue #327.
65
+ const HOME_SKILLS_DIR_OVERRIDES = {
66
+ '.pi': join('.pi', 'agent', 'skills'),
67
+ };
68
+
62
69
  // When a project has no harness folder yet, infer the target from globally
63
70
  // installed harnesses (~/.claude, ~/.codex, ...). Codex reads skills from
64
71
  // .agents/skills, so ~/.codex maps to the .agents bundle variant.
@@ -69,6 +76,7 @@ const GLOBAL_HARNESS_HINTS = [
69
76
  { home: '.gemini', provider: '.gemini' },
70
77
  { home: '.kiro', provider: '.kiro' },
71
78
  { home: '.opencode', provider: '.opencode' },
79
+ { home: '.pi', provider: '.pi' },
72
80
  { home: '.qoder', provider: '.qoder' },
73
81
  { home: '.rovodev', provider: '.rovodev' },
74
82
  ];
@@ -111,6 +119,45 @@ const PROVIDER_HOOK_ARTIFACTS = {
111
119
  ],
112
120
  };
113
121
 
122
+ function userProviderSkillsDir(home, provider) {
123
+ if (HOME_SKILLS_DIR_OVERRIDES[provider]) return join(home, HOME_SKILLS_DIR_OVERRIDES[provider]);
124
+ return join(home, provider, 'skills');
125
+ }
126
+
127
+ // Compare via realpath: the project root comes from process.cwd() (symlinks
128
+ // resolved) while homedir() reflects $HOME verbatim, so a home dir reached
129
+ // through a symlink (e.g. /tmp -> /private/tmp) would fail a string compare.
130
+ function isHomeDir(root) {
131
+ if (root === homedir()) return true;
132
+ try {
133
+ return realpathSync(root) === realpathSync(homedir());
134
+ } catch {
135
+ return false;
136
+ }
137
+ }
138
+
139
+ // Every layout a provider's installed skills can live in under `root`.
140
+ // `scope` narrows the answer when the caller knows which install it is
141
+ // acting on: 'user' means the provider's global layout, 'project' means
142
+ // `<provider>/skills`. Without a scope (update/check, where installs of
143
+ // either kind may live under `root`) both layouts are candidates when
144
+ // `root` is the home dir, since an overridden provider (Pi) keeps its
145
+ // global skills elsewhere while a repo rooted at ~ still uses the project
146
+ // layout. Scoping matters for the same reason: a project-scope install in
147
+ // a home-rooted repo must not be conflated with an existing global one.
148
+ function providerSkillsDirCandidates(root, provider, scope) {
149
+ if (scope === 'user') return [userProviderSkillsDir(root, provider)];
150
+ const dirs = [join(root, provider, 'skills')];
151
+ if (scope !== 'project' && HOME_SKILLS_DIR_OVERRIDES[provider] && isHomeDir(root)) {
152
+ dirs.unshift(userProviderSkillsDir(root, provider));
153
+ }
154
+ return dirs;
155
+ }
156
+
157
+ function existingSkillsDirs(root, provider, scope) {
158
+ return providerSkillsDirCandidates(root, provider, scope).filter(existsSync);
159
+ }
160
+
114
161
  let pipedAnswers = null;
115
162
  class PromptAbortError extends Error {
116
163
  constructor() {
@@ -415,13 +462,15 @@ async function showHelp() {
415
462
  /**
416
463
  * Read the skills version from the impeccable SKILL.md frontmatter.
417
464
  */
418
- function getSkillsVersion(root) {
465
+ function getSkillsVersion(root, scope) {
419
466
  for (const d of PROVIDER_DIRS) {
420
- const skillMd = join(root, d, 'skills', 'impeccable', 'SKILL.md');
421
- if (!existsSync(skillMd)) continue;
422
- const content = readFileSync(skillMd, 'utf-8');
423
- const match = content.match(/^version:\s*(.+)$/m);
424
- if (match) return match[1].trim().replace(/^["']|["']$/g, '');
467
+ for (const skillsDir of providerSkillsDirCandidates(root, d, scope)) {
468
+ const skillMd = join(skillsDir, 'impeccable', 'SKILL.md');
469
+ if (!existsSync(skillMd)) continue;
470
+ const content = readFileSync(skillMd, 'utf-8');
471
+ const match = content.match(/^version:\s*(.+)$/m);
472
+ if (match) return match[1].trim().replace(/^["']|["']$/g, '');
473
+ }
425
474
  }
426
475
  return null;
427
476
  }
@@ -535,14 +584,17 @@ function hashSkillFile(filePath) {
535
584
  * per unique real path. The first provider that maps to a real path
536
585
  * wins (so the bundle uses that provider's build).
537
586
  */
538
- function deduplicateProviders(root, providers) {
587
+ function deduplicateProviders(root, providers, scope) {
539
588
  const seen = new Map(); // realPath -> { provider, localSkillsDir }
540
589
  for (const provider of providers) {
541
- const skillsDir = join(root, provider, 'skills');
542
- if (!existsSync(skillsDir)) continue;
543
- const real = realpathSync(skillsDir);
544
- if (!seen.has(real)) {
545
- seen.set(real, { provider, localSkillsDir: skillsDir });
590
+ // A provider can hold real installs in more than one layout (a home-rooted
591
+ // repo may carry both ~/.pi/agent/skills and ~/.pi/skills). Keep each as
592
+ // its own entry so update/check touch every tree, not just the first.
593
+ for (const skillsDir of existingSkillsDirs(root, provider, scope)) {
594
+ const real = realpathSync(skillsDir);
595
+ if (!seen.has(real)) {
596
+ seen.set(real, { provider, localSkillsDir: skillsDir });
597
+ }
546
598
  }
547
599
  }
548
600
  return [...seen.values()];
@@ -556,8 +608,8 @@ function deduplicateProviders(root, providers) {
556
608
  * SKILL.md, so script-only fixes and removed files are detected.
557
609
  * Returns true if every bundle skill matches the local copy.
558
610
  */
559
- function isUpToDate(root, providers, bundleDir) {
560
- const unique = deduplicateProviders(root, providers);
611
+ function isUpToDate(root, providers, bundleDir, scope) {
612
+ const unique = deduplicateProviders(root, providers, scope);
561
613
  if (unique.length === 0) return false;
562
614
 
563
615
  for (const { provider, localSkillsDir } of unique) {
@@ -621,20 +673,20 @@ async function check() {
621
673
  // ─── skills install ───────────────────────────────────────────────────────────
622
674
 
623
675
  // Check if impeccable skills are already present in any provider folder
624
- function isAlreadyInstalled(root) {
676
+ function isAlreadyInstalled(root, scope) {
625
677
  for (const d of PROVIDER_DIRS) {
626
- const skillsDir = join(root, d, 'skills');
627
- if (!existsSync(skillsDir)) continue;
628
- try {
629
- const entries = readdirSync(skillsDir);
630
- // Look for 'impeccable' skill (or prefixed variant, or legacy 'teach-impeccable')
631
- if (entries.some(e =>
632
- e === 'impeccable' || e.endsWith('-impeccable') ||
633
- e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
634
- )) {
635
- return d;
636
- }
637
- } catch {}
678
+ for (const skillsDir of existingSkillsDirs(root, d, scope)) {
679
+ try {
680
+ const entries = readdirSync(skillsDir);
681
+ // Look for 'impeccable' skill (or prefixed variant, or legacy 'teach-impeccable')
682
+ if (entries.some(e =>
683
+ e === 'impeccable' || e.endsWith('-impeccable') ||
684
+ e === 'teach-impeccable' || e.endsWith('-teach-impeccable')
685
+ )) {
686
+ return d;
687
+ }
688
+ } catch {}
689
+ }
638
690
  }
639
691
  return null;
640
692
  }
@@ -678,26 +730,26 @@ function isRealSkillDir(skillsDir, name) {
678
730
  * by name -- never touches third-party skills that happen to start with `i-`.
679
731
  * Returns the number of skills migrated.
680
732
  */
681
- function migrateUnprefixImpeccable(root) {
733
+ function migrateUnprefixImpeccable(root, scope) {
682
734
  let migrated = 0;
683
735
  for (const d of PROVIDER_DIRS) {
684
- const skillsDir = join(root, d, 'skills');
685
- if (!existsSync(skillsDir)) continue;
686
- let entries;
687
- try { entries = readdirSync(skillsDir); } catch { continue; }
688
- for (const name of entries) {
689
- // A prefixed impeccable skill is `<prefix>impeccable`, not the canonical
690
- // `impeccable` and not an unrelated legacy skill name.
691
- if (name === 'impeccable' || name === 'teach-impeccable') continue;
692
- if (!name.endsWith('-impeccable')) continue;
693
- if (!isRealSkillDir(skillsDir, name)) continue;
694
-
695
- const dest = join(skillsDir, 'impeccable');
696
- try {
697
- rmSync(dest, { recursive: true, force: true });
698
- renameSync(join(skillsDir, name), dest);
699
- migrated++;
700
- } catch {}
736
+ for (const skillsDir of existingSkillsDirs(root, d, scope)) {
737
+ let entries;
738
+ try { entries = readdirSync(skillsDir); } catch { continue; }
739
+ for (const name of entries) {
740
+ // A prefixed impeccable skill is `<prefix>impeccable`, not the canonical
741
+ // `impeccable` and not an unrelated legacy skill name.
742
+ if (name === 'impeccable' || name === 'teach-impeccable') continue;
743
+ if (!name.endsWith('-impeccable')) continue;
744
+ if (!isRealSkillDir(skillsDir, name)) continue;
745
+
746
+ const dest = join(skillsDir, 'impeccable');
747
+ try {
748
+ rmSync(dest, { recursive: true, force: true });
749
+ renameSync(join(skillsDir, name), dest);
750
+ migrated++;
751
+ } catch {}
752
+ }
701
753
  }
702
754
  }
703
755
  return migrated;
@@ -774,7 +826,7 @@ function uniquePaths(paths) {
774
826
 
775
827
  function userSkillProbePaths(home, harnessDir, provider) {
776
828
  return uniquePaths([
777
- join(home, provider, 'skills'),
829
+ userProviderSkillsDir(home, provider),
778
830
  join(home, harnessDir, 'skills'),
779
831
  ]);
780
832
  }
@@ -804,7 +856,7 @@ function collectInstallDetections(root, home = homedir()) {
804
856
  scope: 'user',
805
857
  foundPath,
806
858
  installRoot: home,
807
- installPath: join(home, provider, 'skills'),
859
+ installPath: userProviderSkillsDir(home, provider),
808
860
  skillProbePaths,
809
861
  hasRealSkills: skillProbePaths.some(hasRealSkillEntries),
810
862
  reason: 'user harness folder',
@@ -1010,22 +1062,58 @@ async function chooseInstallPlan(projectRoot, flags, { yes } = {}) {
1010
1062
  return { targets, scope, installRoot, hookRoot: projectRoot, detections };
1011
1063
  }
1012
1064
 
1065
+ /**
1066
+ * Whether `localSkillsDir` is a symlink that points at ANOTHER in-project
1067
+ * provider's skills dir (e.g. `.claude/skills -> ../.agents/skills`, the shape a
1068
+ * prior `npx skills` install can leave behind). Only these get dropped so each
1069
+ * provider can receive its own compiled variant. A symlink to anywhere else -
1070
+ * notably a user's external shared skills dir (`~/.claude/skills ->
1071
+ * ~/.config/agents/skills`) - is preserved and written through. See issue #295.
1072
+ */
1073
+ function isInProjectProviderLink(localSkillsDir, root, provider) {
1074
+ let target;
1075
+ try {
1076
+ if (!lstatSync(localSkillsDir).isSymbolicLink()) return false;
1077
+ target = readlinkSync(localSkillsDir);
1078
+ } catch {
1079
+ return false; // not a symlink, or unreadable
1080
+ }
1081
+ // Resolve the link's TARGET lexically against the link's own directory. We
1082
+ // deliberately do NOT realpathSync the target:
1083
+ // * it lets a not-yet-created in-project target still match, so a dangling
1084
+ // `.claude/skills -> ../.agents/skills` is still dropped;
1085
+ // * it compares the ACTUAL target, not a shared realpath, so two providers
1086
+ // pointing at the SAME external dir are never misread as in-project.
1087
+ const resolvedTarget = resolve(dirname(localSkillsDir), target);
1088
+ for (const other of PROVIDER_DIRS) {
1089
+ if (other === provider) continue;
1090
+ if (resolvedTarget === join(root, other, 'skills')) return true;
1091
+ }
1092
+ return false;
1093
+ }
1094
+
1013
1095
  /**
1014
1096
  * Copy each target provider's compiled skill variant from an extracted bundle
1015
1097
  * into the project. Writes real directories (copy, never symlink) so every
1016
1098
  * harness keeps the build that was compiled for it. Returns skills written.
1099
+ * `scope: 'user'` writes to the provider's global skills layout (see
1100
+ * HOME_SKILLS_DIR_OVERRIDES); anything else writes `<provider>/skills`.
1017
1101
  */
1018
- function copyProviderSkills(bundleDir, root, targets) {
1102
+ function copyProviderSkills(bundleDir, root, targets, { scope } = {}) {
1019
1103
  let written = 0;
1020
1104
  for (const provider of targets) {
1021
1105
  const srcDir = join(bundleDir, provider, 'skills');
1022
1106
  if (existsSync(srcDir)) {
1023
- const localSkillsDir = join(root, provider, 'skills');
1107
+ const localSkillsDir = scope === 'user'
1108
+ ? userProviderSkillsDir(root, provider)
1109
+ : join(root, provider, 'skills');
1024
1110
  // A previous `npx skills` install may have left this provider's skills dir
1025
- // as a symlink to another provider's canonical copy. Drop the link so we
1026
- // write a real, provider-specific directory instead of writing through it.
1111
+ // as a symlink to ANOTHER in-project provider's canonical copy. Drop only
1112
+ // that link so we write a real, provider-specific directory. A user's
1113
+ // external shared-skills symlink (e.g. ~/.claude/skills ->
1114
+ // ~/.config/agents/skills) is preserved and written through. See #295.
1027
1115
  try {
1028
- if (lstatSync(localSkillsDir).isSymbolicLink()) unlinkSync(localSkillsDir);
1116
+ if (isInProjectProviderLink(localSkillsDir, root, provider)) unlinkSync(localSkillsDir);
1029
1117
  } catch {}
1030
1118
  for (const skill of readdirSync(srcDir, { withFileTypes: true })) {
1031
1119
  if (!skill.isDirectory()) continue;
@@ -1040,8 +1128,8 @@ function copyProviderSkills(bundleDir, root, targets) {
1040
1128
  return written;
1041
1129
  }
1042
1130
 
1043
- function refreshProviderSkills(bundleDir, root, providers) {
1044
- const unique = deduplicateProviders(root, providers);
1131
+ function refreshProviderSkills(bundleDir, root, providers, scope) {
1132
+ const unique = deduplicateProviders(root, providers, scope);
1045
1133
  let updated = 0;
1046
1134
  for (const { provider, localSkillsDir } of unique) {
1047
1135
  const srcDir = join(bundleDir, provider, 'skills');
@@ -1500,13 +1588,13 @@ async function install(flags) {
1500
1588
  }
1501
1589
 
1502
1590
  const { targets, installRoot, hookRoot, scope } = plan;
1503
- const existing = isAlreadyInstalled(installRoot);
1591
+ const existing = isAlreadyInstalled(installRoot, scope);
1504
1592
 
1505
1593
  if (existing && !force) {
1506
1594
  console.log(`Impeccable skills are already installed (found in ${existing}/).`);
1507
- const installedTargets = findInstalledProviders(installRoot);
1595
+ const installedTargets = findInstalledProviders(installRoot, scope);
1508
1596
  const selectedInstalledTargets = targets.filter(provider => installedTargets.includes(provider));
1509
- const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets);
1597
+ const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets, scope);
1510
1598
  const copyTargets = selectedInstalledTargets.filter(provider => !linkedTargets.includes(provider));
1511
1599
  const hookTargets = selectedInstalledTargets;
1512
1600
  const wantHooks = installHooks && await decideHookInstall(hookRoot, hookTargets, { yes });
@@ -1533,10 +1621,10 @@ async function install(flags) {
1533
1621
  }
1534
1622
  }
1535
1623
 
1536
- if (!updateCheckSkipped && copyTargets.length > 0 && !isUpToDate(installRoot, copyTargets, bundleDir)) {
1537
- migrateUnprefixImpeccable(installRoot);
1538
- updated = refreshProviderSkills(bundleDir, installRoot, copyTargets);
1539
- const v = getSkillsVersion(installRoot);
1624
+ if (!updateCheckSkipped && copyTargets.length > 0 && !isUpToDate(installRoot, copyTargets, bundleDir, scope)) {
1625
+ migrateUnprefixImpeccable(installRoot, scope);
1626
+ updated = refreshProviderSkills(bundleDir, installRoot, copyTargets, scope);
1627
+ const v = getSkillsVersion(installRoot, scope);
1540
1628
  console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
1541
1629
  }
1542
1630
 
@@ -1549,7 +1637,7 @@ async function install(flags) {
1549
1637
  console.log('Existing skills were left unchanged.');
1550
1638
  console.log('Run with --force to reinstall.\n');
1551
1639
  } else if (updated === 0 && writtenHookTargets.length === 0) {
1552
- const v = getSkillsVersion(installRoot);
1640
+ const v = getSkillsVersion(installRoot, scope);
1553
1641
  console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
1554
1642
  console.log('Run with --force to reinstall.\n');
1555
1643
  } else {
@@ -1588,12 +1676,12 @@ async function install(flags) {
1588
1676
 
1589
1677
  // Retire any old `i-`-prefixed install so the fresh copy lands on the
1590
1678
  // canonical `impeccable` dir instead of orphaning the prefixed one.
1591
- migrateUnprefixImpeccable(installRoot);
1679
+ migrateUnprefixImpeccable(installRoot, scope);
1592
1680
 
1593
1681
  let written = 0;
1594
1682
  let hookTargets = [];
1595
1683
  try {
1596
- written = copyProviderSkills(bundleDir, installRoot, targets);
1684
+ written = copyProviderSkills(bundleDir, installRoot, targets, { scope });
1597
1685
  hookTargets = wantHooks ? copyProviderHooks(bundleDir, hookRoot, targets, { force, skillRoot: installRoot }) : [];
1598
1686
  } catch (e) {
1599
1687
  rmSync(bundleDir, { recursive: true, force: true });
@@ -1623,27 +1711,31 @@ function findProjectRoot() {
1623
1711
  return process.cwd();
1624
1712
  }
1625
1713
 
1626
- function findInstalledProviders(root) {
1714
+ function findInstalledProviders(root, scope) {
1627
1715
  const found = [];
1628
1716
  for (const d of PROVIDER_DIRS) {
1629
- const skillsDir = join(root, d, 'skills');
1630
- if (!existsSync(skillsDir)) continue;
1631
- try {
1632
- const entries = readdirSync(skillsDir);
1633
- if (entries.some(name => isSkillDir(skillsDir, name))) found.push(d);
1634
- } catch {}
1717
+ for (const skillsDir of existingSkillsDirs(root, d, scope)) {
1718
+ try {
1719
+ const entries = readdirSync(skillsDir);
1720
+ if (entries.some(name => isSkillDir(skillsDir, name))) {
1721
+ found.push(d);
1722
+ break;
1723
+ }
1724
+ } catch {}
1725
+ }
1635
1726
  }
1636
1727
  return found;
1637
1728
  }
1638
1729
 
1639
- function findLinkedProviders(root, providers) {
1730
+ function findLinkedProviders(root, providers, scope) {
1640
1731
  return providers.filter(provider => {
1641
- const skillDir = join(root, provider, 'skills', 'impeccable');
1642
- try {
1643
- return lstatSync(skillDir).isSymbolicLink();
1644
- } catch {
1645
- return false;
1732
+ for (const skillsDir of providerSkillsDirCandidates(root, provider, scope)) {
1733
+ const skillDir = join(skillsDir, 'impeccable');
1734
+ try {
1735
+ if (lstatSync(skillDir).isSymbolicLink()) return true;
1736
+ } catch {}
1646
1737
  }
1738
+ return false;
1647
1739
  });
1648
1740
  }
1649
1741
 
@@ -2,6 +2,7 @@ import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
 
4
4
  import { loadDesignSystemForCwd } from '../design-system.mjs';
5
+ import { RULE_SCOPES, filterByScopes } from '../registry/antipatterns.mjs';
5
6
  import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
6
7
  import { detectHtml } from '../engines/static-html/detect-html.mjs';
7
8
  import { detectText } from '../engines/regex/detect-text.mjs';
@@ -93,6 +94,8 @@ Options:
93
94
  --quiet In text mode, only print the final findings count
94
95
  --gpt Also report GPT-specific provider tells (off by default)
95
96
  --gemini Also report Gemini-specific provider tells (off by default)
97
+ --scope <name> Only report rules in the given design domain
98
+ (type, layout). Comma-separated.
96
99
  --no-config Do not apply project config, detector ignores, inline
97
100
  ignore comments, or DESIGN.md
98
101
  --no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
@@ -151,6 +154,33 @@ async function detectCli() {
151
154
  const providers = [];
152
155
  if (args.includes('--gpt')) providers.push('gpt');
153
156
  if (args.includes('--gemini')) providers.push('gemini');
157
+ const scopes = [];
158
+ for (let i = 0; i < args.length; i++) {
159
+ if (args[i] !== '--scope' && !args[i].startsWith('--scope=')) continue;
160
+ const inline = args[i].startsWith('--scope=');
161
+ const value = inline ? args[i].slice('--scope='.length) : args[i + 1];
162
+ const parsed = (value && !value.startsWith('--'))
163
+ ? value.split(',').map(s => s.trim()).filter(Boolean)
164
+ : [];
165
+ // A bare `--scope` would otherwise fall out of `targets` and scan unscoped;
166
+ // fail loudly so a mistyped pre-scan never runs the wrong rule set.
167
+ if (parsed.length === 0) {
168
+ process.stderr.write(
169
+ `Error: --scope requires a value. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
170
+ );
171
+ process.exit(1);
172
+ }
173
+ scopes.push(...parsed);
174
+ args.splice(i, inline ? 1 : 2);
175
+ i -= 1;
176
+ }
177
+ const unknownScopes = scopes.filter(s => !RULE_SCOPES.has(s));
178
+ if (unknownScopes.length > 0) {
179
+ process.stderr.write(
180
+ `Error: unknown --scope value(s): ${unknownScopes.join(', ')}. Valid scopes: ${[...RULE_SCOPES].join(', ')}\n`,
181
+ );
182
+ process.exit(1);
183
+ }
154
184
  const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
155
185
  const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
156
186
  // Inline `impeccable-disable*` waivers are part of the scanned file, so they
@@ -276,6 +306,7 @@ async function detectCli() {
276
306
  }
277
307
 
278
308
  allFindings = filterDetectionFindings(allFindings, detectionConfig);
309
+ allFindings = filterByScopes(allFindings, scopes);
279
310
 
280
311
  if (allFindings.length > 0) {
281
312
  if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');