impeccable 3.4.0 → 3.6.0

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 60 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 59 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
- 60 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 59 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 22.12+
78
+ - Node.js 22.18+
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 60 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 59 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
- 60 deterministic detector rules in total. See the full catalog at [impeccable.style/slop](https://impeccable.style/slop).
59
+ 59 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 22.12+
78
+ - Node.js 22.18+
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 60 deterministic detector rules for AI-generated frontend design.
3
+ Design guidance for AI coding agents. 1 skill, 23 commands, live browser iteration, and 59 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
- - **60 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
+ - **59 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
 
@@ -270,6 +270,16 @@ cp -r dist/grok/.grok/skills/* ~/.grok/skills/
270
270
 
271
271
  > Prefer `npx impeccable install --providers=grok` or `grok plugin install pbakaus/impeccable#plugin --trust` so the design hook installs too. Project hooks need `/hooks-trust` (or `--trust`) once per folder.
272
272
 
273
+ **Google Antigravity:**
274
+ ```bash
275
+ # Project-specific
276
+ cp -r dist/antigravity/.agent your-project/
277
+
278
+ # Or global (applies to all projects)
279
+ mkdir -p ~/.gemini/config/skills
280
+ cp -r dist/antigravity/.agent/skills/* ~/.gemini/config/skills/
281
+ ```
282
+
273
283
  ## Usage
274
284
 
275
285
  Once installed, every command runs through the single `/impeccable` skill:
@@ -351,6 +361,18 @@ On an interactive `install`/`update`, Impeccable explains the hook and offers to
351
361
 
352
362
  For debugging, set `hook.auditLog` in `.impeccable/config.json` to a path (or the legacy `IMPECCABLE_HOOK_LOG` env var) to write one NDJSON line per hook invocation. Leave it unset for normal use.
353
363
 
364
+ ## Build path: comp-first or code-first
365
+
366
+ When a new surface gets designed, Impeccable either generates a full-fidelity comp first and builds to match it, or builds straight in code with the ambition written into the direction contract and checked at the finish. Comp-first composes bolder and takes longer; code-first is leaner and faster. `/impeccable init` asks once and records the answer as `buildPath` in `.impeccable/config.json`:
367
+
368
+ ```json
369
+ { "buildPath": "comp" }
370
+ ```
371
+
372
+ The values are `comp` and `code`, and nothing else is read. Set it in the gitignored `.impeccable/config.local.json` to override the team's committed value on one machine, which is what you want when your harness has no image generation. In a monorepo, commit it once at the repo root and any workspace that wants something else sets its own. The choice appears at all only where image generation is available, since without it there is nothing to comp.
373
+
374
+ You do not have to re-run `init` to set it on a project that predates the setting, and you do not have to edit the file by hand either. Whatever is recorded is a default rather than a lock: every decision page carries a footer toggle, and flipping it binds that session only. Flip it on a project that has recorded nothing and Impeccable asks once, after the round, whether to keep it, then writes your answer. That is the whole migration path for an existing project: use the toggle when the default is wrong, and answer the question that follows.
375
+
354
376
  Codex requires one platform step that Impeccable cannot safely skip: open `/hooks` after install or update and approve the project hook. There is no Codex marketplace/plugin install flow for this hook.
355
377
 
356
378
  Full hook docs: [impeccable.style/docs/hooks](https://impeccable.style/docs/hooks).
@@ -377,7 +399,7 @@ npx impeccable ignores add-file "src/legacy/**"
377
399
  npx impeccable ignores add-value overused-font Inter --reason "Brand font"
378
400
  ```
379
401
 
380
- The detector catches 60 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).
402
+ The detector catches 59 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).
381
403
 
382
404
  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.
383
405
 
@@ -400,6 +422,7 @@ Full detector docs: [impeccable.style/docs/detector](https://impeccable.style/do
400
422
  - [Rovo Dev](https://www.atlassian.com/software/rovo)
401
423
  - [Qoder](https://qoder.com)
402
424
  - [Mistral Vibe](https://docs.mistral.ai/vibe/code/overview)
425
+ - [Google Antigravity](https://antigravity.google)
403
426
 
404
427
  ## Community & Ecosystem
405
428
 
package/cli/bin/cli.js CHANGED
@@ -77,6 +77,12 @@ Compatibility:
77
77
  process.argv = [process.argv[0], process.argv[1], ...args];
78
78
  const { detectCli } = await import('../engine/detect-antipatterns.mjs');
79
79
  await detectCli();
80
+ } else if (command === 'init') {
81
+ // The follow-up mistake from issue #472: `/impeccable init` belongs in an AI
82
+ // coding agent's chat, and a user who typed it into their shell is likely to
83
+ // retry it here as `npx impeccable init`.
84
+ console.error(`"init" is not a CLI command. Type /impeccable init in your AI coding agent's chat (Claude Code, Cursor, Codex, ...), not in this terminal.`);
85
+ process.exit(1);
80
86
  } else {
81
87
  // An unknown bareword: a mistyped command (or an old cached version run
82
88
  // against newer docs). Fail loudly instead of silently statting it as a path.
@@ -23,9 +23,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
23
23
  const API_BASE = 'https://impeccable.style';
24
24
 
25
25
  // Provider folder names in project roots
26
- const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.grok', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev', '.vibe'];
26
+ const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.agent', '.github', '.grok', '.hermes', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn', '.rovodev', '.vibe'];
27
27
  const PROVIDER_ALIASES = {
28
+ agent: '.agent',
28
29
  agents: '.agents',
30
+ antigravity: '.agent',
29
31
  claude: '.claude',
30
32
  'claude-code': '.claude',
31
33
  codex: '.agents',
@@ -35,6 +37,7 @@ const PROVIDER_ALIASES = {
35
37
  github: '.github',
36
38
  grok: '.grok',
37
39
  'grok-build': '.grok',
40
+ hermes: '.hermes',
38
41
  xai: '.grok',
39
42
  kiro: '.kiro',
40
43
  opencode: '.opencode',
@@ -48,22 +51,24 @@ const PROVIDER_ALIASES = {
48
51
  };
49
52
 
50
53
  const PROVIDER_DISPLAY = {
54
+ '.agent': { name: 'Antigravity', input: 'antigravity' },
51
55
  '.agents': { name: 'Codex CLI', input: 'codex' },
52
56
  '.claude': { name: 'Claude Code', input: 'claude' },
53
57
  '.cursor': { name: 'Cursor', input: 'cursor' },
54
58
  '.gemini': { name: 'Gemini CLI', input: 'gemini' },
55
59
  '.github': { name: 'GitHub Copilot', input: 'github' },
56
60
  '.grok': { name: 'Grok Build', input: 'grok' },
61
+ '.hermes': { name: 'Hermes Agent', input: 'hermes' },
57
62
  '.kiro': { name: 'Kiro', input: 'kiro' },
58
63
  '.opencode': { name: 'OpenCode', input: 'opencode' },
59
- '.pi': { name: 'Project Indigo', input: 'pi' },
64
+ '.pi': { name: 'Pi Coding Agent', input: 'pi' },
60
65
  '.qoder': { name: 'Qoder', input: 'qoder' },
61
66
  '.rovodev': { name: 'Rovo Dev', input: 'rovo-dev' },
62
67
  '.trae': { name: 'Trae', input: 'trae' },
63
68
  '.trae-cn': { name: 'Trae CN', input: 'trae-cn' },
64
69
  '.vibe': { name: 'Mistral Vibe', input: 'vibe' },
65
70
  };
66
- const PROVIDER_INPUT_ORDER = ['claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe'];
71
+ const PROVIDER_INPUT_ORDER = ['antigravity', 'claude', 'codex', 'cursor', 'gemini', 'github', 'grok', 'hermes', 'kiro', 'opencode', 'pi', 'qoder', 'trae', 'trae-cn', 'rovo-dev', 'vibe'];
67
72
 
68
73
  // OpenCode reads global skills from its config directory, not ~/.opencode:
69
74
  // $OPENCODE_CONFIG_DIR, else $XDG_CONFIG_HOME/opencode, else
@@ -75,11 +80,52 @@ function opencodeGlobalConfigDir(home) {
75
80
  return join(home, '.config', 'opencode');
76
81
  }
77
82
 
83
+ // Hermes reads skills from `$HERMES_HOME/skills/`, where $HERMES_HOME defaults
84
+ // to `~/.hermes` but is also set to a profile path (e.g.
85
+ // `~/.hermes/profiles/forge`) when a non-default profile is active. Reading
86
+ // the env var matters here at install time: writing to `~/.hermes/skills/`
87
+ // from a profile-scoped Hermes invocation would land in the wrong profile
88
+ // (the same cross-profile data-corruption class that the active_profile
89
+ // fallback warning in hermes_constants.py exists to detect). Used by
90
+ // HOME_SKILLS_DIR_OVERRIDES['.hermes'] only; GLOBAL_HARNESS_HINTS reads the
91
+ // fixed `~/.hermes` location so detection doesn't leak the developer's real
92
+ // HERMES_HOME into test output (test isolation).
93
+ //
94
+ // Ignore $HERMES_HOME when it doesn't sit under `home` (the caller-supplied
95
+ // home dir, which tests inject via HOME=/tmp/...). Without this guard, an
96
+ // inherited $HERMES_HOME=/home/<dev>/.hermes from the developer's shell leaks
97
+ // into test output even when the test sets HOME=/tmp/imp-home-xxx: tests
98
+ // expect ~/.hermes to live under their tmp home, not under the dev's real
99
+ // home. The check uses `resolve()` on both sides so a symlinked test home
100
+ // (e.g. /tmp -> /private/tmp on macOS) still compares correctly.
101
+ function hermesGlobalHome(home) {
102
+ const envHome = process.env.HERMES_HOME;
103
+ if (envHome) {
104
+ try {
105
+ const resolvedEnv = resolve(envHome);
106
+ const resolvedHome = resolve(home);
107
+ // Honor HERMES_HOME only when it lives under the active home (real
108
+ // ~/.hermes or ~/.hermes/profiles/<name>). Cross-home inheritance is
109
+ // treated as not-set, so a test running under HOME=/tmp/... doesn't
110
+ // pick up the developer's real ~/.hermes.
111
+ if (resolvedEnv === resolvedHome || resolvedEnv.startsWith(resolvedHome + sep)) {
112
+ return resolvedEnv;
113
+ }
114
+ } catch {
115
+ // fall through to default
116
+ }
117
+ }
118
+ return join(home, '.hermes');
119
+ }
120
+
78
121
  // Providers whose GLOBAL (home) skills dir is not `<provider>/skills`,
79
122
  // as a function of the home dir. Pi discovers global skills from
80
123
  // ~/.pi/agent/skills/ (issue #327); OpenCode from its config dir (issue
81
- // #406). Project scope stays `<provider>/skills` for both.
124
+ // #406); Hermes from $HERMES_HOME. Project scope stays `<provider>/skills`
125
+ // for all three.
82
126
  const HOME_SKILLS_DIR_OVERRIDES = {
127
+ '.agent': (home) => join(home, '.gemini', 'config', 'skills'),
128
+ '.hermes': (home) => join(hermesGlobalHome(home), 'skills'),
83
129
  '.pi': (home) => join(home, '.pi', 'agent', 'skills'),
84
130
  '.opencode': (home) => join(opencodeGlobalConfigDir(home), 'skills'),
85
131
  };
@@ -87,12 +133,27 @@ const HOME_SKILLS_DIR_OVERRIDES = {
87
133
  // When a project has no harness folder yet, infer the target from globally
88
134
  // installed harnesses (~/.claude, ~/.codex, ...). Codex reads skills from
89
135
  // .agents/skills, so ~/.codex maps to the .agents bundle variant.
136
+ //
137
+ // Hermes auto-detection uses the fixed `~/.hermes` location only. When a
138
+ // non-default Hermes profile is active (HERMES_HOME points to a profile path),
139
+ // the user is expected to be inside a Hermes invocation and can pass
140
+ // --providers=hermes explicitly. Auto-detection from a non-default HERMES_HOME
141
+ // would also defeat test isolation (tests inject HOME; HERMES_HOME leaks from
142
+ // the parent process and would surface the developer's real ~/.hermes in
143
+ // detection output). The install path honors $HERMES_HOME; detection does not.
90
144
  const GLOBAL_HARNESS_HINTS = [
145
+ { home: '.agent', provider: '.agent' },
146
+ // Antigravity nests under ~/.gemini/ too, so any of these also trips the
147
+ // .gemini hint above (harmless double-detection — both get pre-selected).
148
+ { home: '.gemini/antigravity', provider: '.agent' },
149
+ { home: '.gemini/antigravity-cli', provider: '.agent' },
150
+ { home: '.gemini/antigravity-ide', provider: '.agent' },
91
151
  { home: '.claude', provider: '.claude' },
92
152
  { home: '.codex', provider: '.agents' },
93
153
  { home: '.cursor', provider: '.cursor' },
94
154
  { home: '.gemini', provider: '.gemini' },
95
155
  { home: '.grok', provider: '.grok' },
156
+ { home: '.hermes', provider: '.hermes' },
96
157
  { home: '.kiro', provider: '.kiro' },
97
158
  { home: '.opencode', provider: '.opencode' },
98
159
  // OpenCode's real global config dir (issue #406); the ~/.opencode entry
@@ -598,7 +659,7 @@ async function copyOrExtractLocalBundle(sourceValue) {
598
659
  */
599
660
  function normalizeForHash(content) {
600
661
  return content
601
- .replace(/\.(claude|cursor|agents|github|gemini|codex|grok|kiro|opencode|pi|qoder|trae|trae-cn|rovodev|vibe)\/skills\//g, '.PROVIDER/skills/');
662
+ .replace(/\.(claude|cursor|agents|agent|github|gemini|codex|grok|hermes|kiro|opencode|pi|qoder|trae|trae-cn|rovodev|vibe)\/skills\//g, '.PROVIDER/skills/');
602
663
  }
603
664
 
604
665
  function hashSkillFile(filePath) {
@@ -1088,13 +1149,13 @@ async function chooseInstallScope(projectRoot, targets, detections, { yes, scope
1088
1149
  async function chooseInstallPlan(projectRoot, flags, { yes } = {}) {
1089
1150
  const providersValue = getFlagValue(flags, '--providers');
1090
1151
  const scopeValue = getInstallScopeValue(flags);
1091
- const { targets, detections } = await chooseInstallProviders(projectRoot, providersValue, { yes });
1152
+ const { targets, detections, explicit } = await chooseInstallProviders(projectRoot, providersValue, { yes });
1092
1153
  if (targets.length === 0) {
1093
1154
  throw new Error('Could not determine a target harness folder.');
1094
1155
  }
1095
1156
  const scope = await chooseInstallScope(projectRoot, targets, detections, { yes, scopeValue });
1096
1157
  const installRoot = installRootForScope(scope, projectRoot);
1097
- return { targets, scope, installRoot, hookRoot: projectRoot, detections };
1158
+ return { targets, scope, installRoot, hookRoot: projectRoot, detections, explicit };
1098
1159
  }
1099
1160
 
1100
1161
  /**
@@ -1189,6 +1250,71 @@ function copyProviderSkills(bundleDir, root, targets, { scope } = {}) {
1189
1250
  return written;
1190
1251
  }
1191
1252
 
1253
+ // Native subagent definitions that ship in the bundle next to a provider's
1254
+ // skills. GitHub Copilot's live at `.github/agents/impeccable-*.agent.md`:
1255
+ // project installs commit them at `<repo>/.github/agents/`, user-level
1256
+ // installs go to `~/.copilot/agents/` (Copilot's user-scope dir, NOT
1257
+ // `~/.github/`). On a name conflict Copilot lets the user-level file shadow
1258
+ // the project one, so both paths overwrite existing impeccable-* copies and a
1259
+ // project install reports any same-named user-level agents that would shadow
1260
+ // it. Cursor's live at `.cursor/agents/impeccable-*.md`, user scope
1261
+ // `~/.cursor/agents/`; project agents take precedence there, so no shadow
1262
+ // warning is needed.
1263
+ const PROVIDER_AGENT_ARTIFACTS = {
1264
+ '.github': {
1265
+ ext: '.agent.md',
1266
+ userDir: home => join(home, '.copilot', 'agents'),
1267
+ userShadowsProject: true,
1268
+ },
1269
+ '.cursor': {
1270
+ ext: '.md',
1271
+ userDir: home => join(home, '.cursor', 'agents'),
1272
+ userShadowsProject: false,
1273
+ },
1274
+ };
1275
+
1276
+ function copyProviderAgents(bundleDir, root, providers, { scope, home = homedir() } = {}) {
1277
+ const targets = Array.isArray(providers) ? providers : [providers];
1278
+ const results = [];
1279
+ for (const provider of targets) {
1280
+ const artifact = PROVIDER_AGENT_ARTIFACTS[provider];
1281
+ if (!artifact) continue;
1282
+ const srcDir = join(bundleDir, provider, 'agents');
1283
+ if (!existsSync(srcDir)) continue;
1284
+ const agentFiles = readdirSync(srcDir).filter(name => name.endsWith(artifact.ext));
1285
+ if (agentFiles.length === 0) continue;
1286
+
1287
+ const destDir = scope === 'user'
1288
+ ? artifact.userDir(root)
1289
+ : join(root, provider, 'agents');
1290
+ mkdirSync(destDir, { recursive: true });
1291
+ for (const name of agentFiles) {
1292
+ writeFileSync(join(destDir, name), readFileSync(join(srcDir, name)));
1293
+ }
1294
+
1295
+ // A project install can be shadowed by same-named agents in the user-level
1296
+ // dir; surface them so the freshly installed project agents actually apply.
1297
+ const userDir = artifact.userDir(home);
1298
+ const shadowed = artifact.userShadowsProject && scope !== 'user'
1299
+ ? agentFiles.filter(name => existsSync(join(userDir, name)))
1300
+ : [];
1301
+
1302
+ results.push({ provider, written: agentFiles.length, destDir, userDir, shadowed });
1303
+ }
1304
+ return results;
1305
+ }
1306
+
1307
+ function reportProviderAgents(results) {
1308
+ for (const result of results || []) {
1309
+ if (result.written === 0) continue;
1310
+ console.log(`Installed ${providerDisplayName(result.provider)} agents into: ${formatPathForDisplay(result.destDir)}`);
1311
+ if (result.shadowed.length > 0) {
1312
+ console.warn(`Warning: user-level agents in ${formatPathForDisplay(result.userDir)} shadow the project copies just installed: ${result.shadowed.join(', ')}.`);
1313
+ console.warn('Run `npx impeccable update --user` to refresh them, or remove them so the project agents apply.');
1314
+ }
1315
+ }
1316
+ }
1317
+
1192
1318
  function refreshProviderSkills(bundleDir, root, providers, scope) {
1193
1319
  const unique = deduplicateProviders(root, providers, scope);
1194
1320
  let updated = 0;
@@ -1263,8 +1389,53 @@ function hookScriptPathForProvider(skillRoot, provider) {
1263
1389
  // code when the file exists, so Claude's exit-2 blocking signal still reaches
1264
1390
  // the agent. POSIX-shell form, consistent with the project's other hook
1265
1391
  // commands (e.g. the GitHub manifest's `$(git rev-parse ...)`).
1266
- function guardHookCommand(quotedPath) {
1267
- return `[ ! -f ${quotedPath} ] || node ${quotedPath}`;
1392
+ //
1393
+ // On Windows that guard is a hard failure, not a degraded one (issue #452).
1394
+ // Codex runs hook commands through COMSPEC (`cmd.exe /C`), where `[` is not a
1395
+ // command: the guard errors noisily and `||` then runs node even when the file
1396
+ // is missing, trading the silent no-op for a MODULE_NOT_FOUND crash. Two
1397
+ // remedies, by provider:
1398
+ //
1399
+ // * Codex manifests support a `commandWindows` sibling that Codex 0.146.0+
1400
+ // selects on Windows (`command_windows.unwrap_or(command)` in its hook
1401
+ // discovery). rewriteHookCommandsForSkillRoot adds it with a cmd.exe
1402
+ // `if exist` guard (form contributed and Windows-tested by @PatrickSys in
1403
+ // issue #452; `exit /b` forwards node's errorlevel), so the same
1404
+ // .codex/hooks.json is correct on every OS no matter where it was
1405
+ // written, and `command` stays the plain POSIX guard.
1406
+ // * Claude and Cursor manifests have no per-platform field, so a Windows
1407
+ // install moves the existence check into node itself: a `node -e` wrapper
1408
+ // that exits 0 when the target is missing and otherwise re-spawns node on
1409
+ // it with inherited stdio, forwarding the hook's exit code. Cursor's
1410
+ // hooks.json is committable and can be consumed on a teammate's POSIX
1411
+ // machine, so the wrapper has to hold there too: it uses only characters
1412
+ // that survive PowerShell, cmd.exe (issue #445: shims re-parse through
1413
+ // `cmd /C`, which claims < > | & ^ % !), and sh double-quoting alike,
1414
+ // with single quotes for the inner string literals.
1415
+ const WIN32_HOOK_GUARD_SCRIPT = "const p=process.argv[1];const f=require('fs');if(f.existsSync(p)){const r=require('child_process').spawnSync(process.execPath,[p],{stdio:'inherit'});process.exit(r.status===null?1:r.status);}";
1416
+
1417
+ // POSIX single-quote escaping. JSON.stringify is not shell quoting: inside
1418
+ // double quotes /bin/sh still expands $(...), backticks, and ${}, and this
1419
+ // string is baked into a hook manifest the harness re-executes on every edit,
1420
+ // so an install path embedding $(...) would run it repeatedly (issue #476).
1421
+ // Windows command forms keep double quotes: cmd.exe treats ' as a literal
1422
+ // character and performs no command substitution.
1423
+ function shSingleQuote(value) {
1424
+ return `'${String(value).replace(/'/g, `'\\''`)}'`;
1425
+ }
1426
+
1427
+ function windowsHookCommand(quotedPath) {
1428
+ return `if exist ${quotedPath} (node ${quotedPath} & exit /b)`;
1429
+ }
1430
+
1431
+ // `quotedPath` carries one pre-quoted form per target shell: { posix, win32 }.
1432
+ function guardHookCommand(quotedPath, provider) {
1433
+ // `.agents` (Codex) keeps the POSIX form unconditionally: its Windows
1434
+ // consumers read the commandWindows sibling instead.
1435
+ if (provider !== '.agents' && process.platform === 'win32') {
1436
+ return `node -e "${WIN32_HOOK_GUARD_SCRIPT}" ${quotedPath.win32}`;
1437
+ }
1438
+ return `[ ! -f ${quotedPath.posix} ] || node ${quotedPath.posix}`;
1268
1439
  }
1269
1440
 
1270
1441
  // Transform bundled hook commands for the actual install target:
@@ -1275,25 +1446,30 @@ function guardHookCommand(quotedPath) {
1275
1446
  // when a project hook points at a skill installed elsewhere (--scope=global).
1276
1447
  // * otherwise — keep the bundle's own ${CLAUDE_PROJECT_DIR}-relative path,
1277
1448
  // which correctly resolves for a project-scoped install.
1278
- // Either way the command is wrapped with the missing-file guard.
1449
+ // Either way the command goes through guardHookCommand (POSIX shell guard, or
1450
+ // the shell-agnostic node -e guard when installing on Windows), and Codex hook
1451
+ // entries additionally get a `commandWindows` sibling for cmd.exe.
1279
1452
  function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute }) {
1280
1453
  const hookScript = hookScriptPathForProvider(skillRoot, provider);
1281
1454
  // Providers we don't own a `node "PATH"` command hook for (.github, .grok)
1282
1455
  // carry their own portable command forms; leave them untouched.
1283
1456
  if (!hookScript) return value;
1284
1457
 
1458
+ // Project-scope installs derive the provider's own project-relative path
1459
+ // rather than trusting the bundle token, which for Codex points at
1460
+ // `.codex/skills/...` while the CLI installs the skill at `.agents/skills/`.
1461
+ // The absolute path comes from the install root (project dir or $HOME), so
1462
+ // its POSIX form gets real single-quote escaping (issue #476). The relative
1463
+ // form is a per-provider constant and stays double-quoted, because Claude's
1464
+ // ${CLAUDE_PROJECT_DIR} token must keep expanding at hook time.
1465
+ const relPath = hookScriptRelPathForProvider(provider);
1466
+ const quotedPath = absolute
1467
+ ? { posix: shSingleQuote(hookScript), win32: JSON.stringify(hookScript) }
1468
+ : { posix: JSON.stringify(relPath), win32: JSON.stringify(relPath) };
1469
+
1285
1470
  if (typeof value === 'string') {
1286
1471
  if (!valueHasImpeccableHookMarker(value)) return value;
1287
- let quotedPath;
1288
- if (absolute) {
1289
- quotedPath = JSON.stringify(hookScript);
1290
- } else {
1291
- // Project-scope install: derive the provider's own project-relative path
1292
- // rather than trusting the bundle token, which for Codex points at
1293
- // `.codex/skills/...` while the CLI installs the skill at `.agents/skills/`.
1294
- quotedPath = JSON.stringify(hookScriptRelPathForProvider(provider));
1295
- }
1296
- return guardHookCommand(quotedPath);
1472
+ return guardHookCommand(quotedPath, provider);
1297
1473
  }
1298
1474
  if (Array.isArray(value)) {
1299
1475
  return value.map(item => rewriteHookCommandsForSkillRoot(item, provider, { skillRoot, absolute }));
@@ -1303,6 +1479,9 @@ function rewriteHookCommandsForSkillRoot(value, provider, { skillRoot, absolute
1303
1479
  for (const [key, child] of Object.entries(value)) {
1304
1480
  next[key] = rewriteHookCommandsForSkillRoot(child, provider, { skillRoot, absolute });
1305
1481
  }
1482
+ if (provider === '.agents' && typeof value.command === 'string' && valueHasImpeccableHookMarker(value.command)) {
1483
+ next.commandWindows = windowsHookCommand(quotedPath.win32);
1484
+ }
1306
1485
  return next;
1307
1486
  }
1308
1487
  return value;
@@ -1698,16 +1877,23 @@ async function install(flags) {
1698
1877
  process.exit(1);
1699
1878
  }
1700
1879
 
1701
- const { targets, installRoot, hookRoot, scope } = plan;
1880
+ const { targets, installRoot, hookRoot, scope, explicit } = plan;
1702
1881
  const existing = isAlreadyInstalled(installRoot, scope);
1703
-
1704
- if (existing && !force) {
1882
+ const installedTargets = existing ? findInstalledProviders(installRoot, scope) : [];
1883
+ // An explicit --providers list is a per-target request: a selected provider
1884
+ // with no install yet gets a fresh install instead of tripping the global
1885
+ // "already installed" early exit (issue #500). When every selected provider
1886
+ // is missing, skip the update branch entirely and take the fresh-install path.
1887
+ const missingSelectedTargets = (existing && !force && explicit)
1888
+ ? targets.filter(provider => !installedTargets.includes(provider))
1889
+ : [];
1890
+
1891
+ if (existing && !force && missingSelectedTargets.length < targets.length) {
1705
1892
  console.log(`Impeccable skills are already installed (found in ${existing}/).`);
1706
- const installedTargets = findInstalledProviders(installRoot, scope);
1707
1893
  const selectedInstalledTargets = targets.filter(provider => installedTargets.includes(provider));
1708
1894
  const linkedTargets = findLinkedProviders(installRoot, selectedInstalledTargets, scope);
1709
1895
  const copyTargets = selectedInstalledTargets.filter(provider => !linkedTargets.includes(provider));
1710
- const hookTargets = selectedInstalledTargets;
1896
+ const hookTargets = [...selectedInstalledTargets, ...missingSelectedTargets];
1711
1897
  const wantHooks = installHooks && await decideHookInstall(hookRoot, hookTargets, { yes });
1712
1898
  let bundleDir;
1713
1899
  try {
@@ -1722,11 +1908,11 @@ async function install(flags) {
1722
1908
  ? hookTargets.filter(provider => !hookInstalledForProvider(hookRoot, provider))
1723
1909
  : [];
1724
1910
  let updateCheckSkipped = false;
1725
- if (copyTargets.length > 0 || missingHookTargets.length > 0) {
1911
+ if (copyTargets.length > 0 || missingHookTargets.length > 0 || missingSelectedTargets.length > 0) {
1726
1912
  try {
1727
1913
  bundleDir = await downloadAndExtractBundle();
1728
1914
  } catch (e) {
1729
- if (missingHookTargets.length > 0) throw e;
1915
+ if (missingHookTargets.length > 0 || missingSelectedTargets.length > 0) throw e;
1730
1916
  updateCheckSkipped = true;
1731
1917
  console.log(`Could not check for skill updates: ${e.message}`);
1732
1918
  }
@@ -1735,10 +1921,22 @@ async function install(flags) {
1735
1921
  if (!updateCheckSkipped && copyTargets.length > 0 && !isUpToDate(installRoot, copyTargets, bundleDir, scope)) {
1736
1922
  migrateUnprefixImpeccable(installRoot, scope);
1737
1923
  updated = refreshProviderSkills(bundleDir, installRoot, copyTargets, scope);
1924
+ reportProviderAgents(copyProviderAgents(bundleDir, installRoot, copyTargets, { scope }));
1738
1925
  const v = getSkillsVersion(installRoot, scope);
1739
1926
  console.log(`Updated ${updated} skill(s)${v ? ` to v${v}` : ''}.`);
1740
1927
  }
1741
1928
 
1929
+ let freshWritten = 0;
1930
+ if (!updateCheckSkipped && missingSelectedTargets.length > 0) {
1931
+ freshWritten = copyProviderSkills(bundleDir, installRoot, missingSelectedTargets, { scope });
1932
+ if (freshWritten === 0) {
1933
+ console.error(`Nothing was installed: the bundle had no variants for ${missingSelectedTargets.join(', ')}.`);
1934
+ process.exit(1);
1935
+ }
1936
+ console.log(`Installed impeccable into: ${missingSelectedTargets.join(', ')} (${scope === 'user' ? 'global' : 'project'})`);
1937
+ reportProviderAgents(copyProviderAgents(bundleDir, installRoot, missingSelectedTargets, { scope }));
1938
+ }
1939
+
1742
1940
  const writtenHookTargets = missingHookTargets.length > 0
1743
1941
  ? copyProviderHooks(bundleDir, hookRoot, missingHookTargets, { skillRoot: installRoot })
1744
1942
  : [];
@@ -1747,7 +1945,7 @@ async function install(flags) {
1747
1945
  if (updateCheckSkipped) {
1748
1946
  console.log('Existing skills were left unchanged.');
1749
1947
  console.log('Run with --force to reinstall.\n');
1750
- } else if (updated === 0 && writtenHookTargets.length === 0) {
1948
+ } else if (updated === 0 && writtenHookTargets.length === 0 && freshWritten === 0) {
1751
1949
  const v = getSkillsVersion(installRoot, scope);
1752
1950
  console.log(`Skills are up to date${v ? ` (v${v})` : ''}.`);
1753
1951
  console.log('Run with --force to reinstall.\n');
@@ -1791,8 +1989,10 @@ async function install(flags) {
1791
1989
 
1792
1990
  let written = 0;
1793
1991
  let hookTargets = [];
1992
+ let agentResults = [];
1794
1993
  try {
1795
1994
  written = copyProviderSkills(bundleDir, installRoot, targets, { scope });
1995
+ agentResults = copyProviderAgents(bundleDir, installRoot, targets, { scope });
1796
1996
  hookTargets = wantHooks ? copyProviderHooks(bundleDir, hookRoot, targets, { force, skillRoot: installRoot }) : [];
1797
1997
  } catch (e) {
1798
1998
  rmSync(bundleDir, { recursive: true, force: true });
@@ -1806,9 +2006,10 @@ async function install(flags) {
1806
2006
  process.exit(1);
1807
2007
  }
1808
2008
  console.log(`Installed impeccable into: ${targets.join(', ')} (${scope === 'user' ? 'global' : 'project'})`);
2009
+ reportProviderAgents(agentResults);
1809
2010
  if (hookTargets.length > 0) console.log(`Installed hooks into: ${hookTargets.join(', ')}`);
1810
2011
 
1811
- console.log('\nDone! Run /impeccable init in your AI harness to set up design context.\n');
2012
+ console.log('\nDone! Now type /impeccable init in your AI coding agent\'s chat (not in this terminal) to set up design context.\n');
1812
2013
  }
1813
2014
 
1814
2015
  // ─── skills update ────────────────────────────────────────────────────────────
@@ -2062,6 +2263,7 @@ async function update(flags = []) {
2062
2263
  if (migrated > 0) console.log('Migrated a prefixed install back to /impeccable (the i- prefix is no longer used).');
2063
2264
 
2064
2265
  const updated = refreshProviderSkills(tmpDir, root, copyProviders, scope);
2266
+ reportProviderAgents(copyProviderAgents(tmpDir, root, copyProviders, { scope }));
2065
2267
  const wantHooks = installHooks && await decideHookInstall(root, providers, { yes });
2066
2268
  const hookTargets = wantHooks ? copyProviderHooks(tmpDir, root, providers, { force }) : [];
2067
2269
 
@@ -2096,12 +2298,15 @@ function copyDirSync(src, dest) {
2096
2298
  // reimplementation in a helper script (which is how bugs slip through).
2097
2299
  export {
2098
2300
  collectInstallDetections,
2301
+ copyProviderAgents,
2099
2302
  copyProviderHooks,
2100
2303
  copyProviderSkills,
2101
2304
  decideHookInstall,
2102
2305
  expectedHookDests,
2103
2306
  extractZip,
2104
2307
  formatInstallDetectionLines,
2308
+ hermesGlobalHome,
2309
+ HOME_SKILLS_DIR_OVERRIDES,
2105
2310
  linkProviderSkills,
2106
2311
  mergeHookManifests,
2107
2312
  migrateUnprefixImpeccable,