impeccable 2.1.9 → 2.2.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.repo.md CHANGED
@@ -19,7 +19,7 @@ Impeccable adds:
19
19
 
20
20
  ### The Skill: impeccable
21
21
 
22
- A comprehensive design skill with 7 domain-specific references ([view skill](skill/SKILL.md)):
22
+ A comprehensive design skill with 7 domain-specific references ([view skill](skill/SKILL.src.md)):
23
23
 
24
24
  | Reference | Covers |
25
25
  |-----------|--------|
@@ -38,7 +38,7 @@ All commands are accessed through `/impeccable`:
38
38
  | Command | What it does |
39
39
  |---------|--------------|
40
40
  | `/impeccable craft` | Full shape-then-build flow with visual iteration |
41
- | `/impeccable teach` | One-time setup: gather design context, write root PRODUCT.md and DESIGN.md |
41
+ | `/impeccable init` | One-time setup: gather design context, write PRODUCT.md and DESIGN.md, configure live mode, recommend next steps |
42
42
  | `/impeccable document` | Generate root DESIGN.md from existing project code |
43
43
  | `/impeccable extract` | Pull reusable components and tokens into the design system |
44
44
  | `/impeccable shape` | Plan UX/UI before writing code |
@@ -93,11 +93,23 @@ Visit [impeccable.style](https://impeccable.style#casestudies) to see before/aft
93
93
 
94
94
  ## Installation
95
95
 
96
- ### Option 1: Download from Website (Recommended)
96
+ ### Option 1: CLI installer (Recommended)
97
+
98
+ From the root of your project, run:
99
+
100
+ ```bash
101
+ npx impeccable skills install
102
+ ```
103
+
104
+ This auto-detects your harness and writes the build compiled for it to the right location (`.claude/skills/`, `.cursor/skills/`, etc.). Works with Cursor, Claude Code, Gemini CLI, Codex CLI, and every other supported tool. Reload your harness afterward.
105
+
106
+ Claude Code users can alternatively install the plugin with `/plugin marketplace add pbakaus/impeccable`. The general-purpose `npx skills add pbakaus/impeccable` also works, though it installs one shared build for all harnesses rather than the one compiled for yours.
107
+
108
+ ### Option 2: Download from Website
97
109
 
98
110
  Visit [impeccable.style](https://impeccable.style), download the ZIP for your tool, and extract to your project.
99
111
 
100
- ### Option 2: Copy from Repository
112
+ ### Option 3: Copy from Repository
101
113
 
102
114
  **Cursor:**
103
115
  ```bash
@@ -195,22 +207,26 @@ cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/
195
207
 
196
208
  ## Usage
197
209
 
198
- Once installed, use commands in your AI harness:
210
+ Once installed, every command runs through the single `/impeccable` skill:
199
211
 
200
212
  ```
201
- /audit # Find issues
202
- /normalize # Fix inconsistencies
203
- /polish # Final cleanup
204
- /distill # Remove complexity
213
+ /impeccable audit # Find issues
214
+ /impeccable polish # Final cleanup
215
+ /impeccable distill # Remove complexity
216
+ /impeccable critique # Full design review
205
217
  ```
206
218
 
219
+ Type `/impeccable` alone to see the full command list.
220
+
207
221
  Most commands accept an optional argument to focus on a specific area:
208
222
 
209
223
  ```
210
- /audit header
211
- /polish checkout-form
224
+ /impeccable audit the header
225
+ /impeccable polish the checkout form
212
226
  ```
213
227
 
228
+ If you reach for one command often, pin it with `/impeccable pin audit` to get `/audit` as a standalone shortcut.
229
+
214
230
  **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.
215
231
 
216
232
  ## CLI
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * Usage:
5
5
  * impeccable skills help Show all available skills and commands
6
- * impeccable skills install Install skills via npx skills add
6
+ * impeccable skills install Install compiled skills from the universal bundle
7
7
  * impeccable skills update Update skills to latest version
8
8
  */
9
9
 
@@ -14,7 +14,7 @@ import { createInterface } from 'node:readline';
14
14
  import { fileURLToPath } from 'node:url';
15
15
  import { get } from 'node:https';
16
16
  import { createHash } from 'node:crypto';
17
- import { tmpdir } from 'node:os';
17
+ import { tmpdir, homedir } from 'node:os';
18
18
 
19
19
  const __dirname = dirname(fileURLToPath(import.meta.url));
20
20
  const API_BASE = 'https://impeccable.style';
@@ -22,6 +22,23 @@ const API_BASE = 'https://impeccable.style';
22
22
  // Provider folder names in project roots
23
23
  const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.agents', '.github', '.kiro', '.opencode', '.pi', '.qoder', '.trae', '.trae-cn'];
24
24
 
25
+ // When a project has no harness folder yet, infer the target from globally
26
+ // installed harnesses (~/.claude, ~/.codex, ...). Codex reads skills from
27
+ // .agents/skills, so ~/.codex maps to the .agents bundle variant.
28
+ const GLOBAL_HARNESS_HINTS = [
29
+ { home: '.claude', provider: '.claude' },
30
+ { home: '.codex', provider: '.agents' },
31
+ { home: '.cursor', provider: '.cursor' },
32
+ { home: '.gemini', provider: '.gemini' },
33
+ { home: '.kiro', provider: '.kiro' },
34
+ { home: '.opencode', provider: '.opencode' },
35
+ { home: '.qoder', provider: '.qoder' },
36
+ ];
37
+
38
+ // Last-resort default when nothing is detected: Claude Code + the universal
39
+ // (.agents, also Codex) folder, which covers the most common setups.
40
+ const DEFAULT_TARGETS = ['.claude', '.agents'];
41
+
25
42
  function ask(question) {
26
43
  const rl = createInterface({ input: process.stdin, output: process.stdout });
27
44
  return new Promise(r => rl.question(question, ans => { rl.close(); r(ans.trim().toLowerCase()); }));
@@ -321,10 +338,71 @@ function renameSkillsWithPrefix(root, prefix) {
321
338
  return count;
322
339
  }
323
340
 
341
+ /**
342
+ * Decide which provider folders to install into.
343
+ * 1. An explicit --providers=.claude,.cursor list wins.
344
+ * 2. Otherwise, harness folders already present in the project.
345
+ * 3. Otherwise, infer from globally installed harnesses (~/.claude, ~/.codex).
346
+ * 4. Otherwise, a sensible default (.claude + .agents).
347
+ */
348
+ function resolveInstallTargets(root, providersValue) {
349
+ if (providersValue) {
350
+ const wanted = providersValue
351
+ .split(',')
352
+ .map(s => s.trim())
353
+ .filter(Boolean)
354
+ .map(s => (s.startsWith('.') ? s : `.${s}`))
355
+ .filter(p => PROVIDER_DIRS.includes(p));
356
+ return [...new Set(wanted)];
357
+ }
358
+
359
+ const inProject = PROVIDER_DIRS.filter(d => existsSync(join(root, d)));
360
+ if (inProject.length > 0) return inProject;
361
+
362
+ const home = homedir();
363
+ const inferred = [];
364
+ for (const { home: h, provider } of GLOBAL_HARNESS_HINTS) {
365
+ if (existsSync(join(home, h)) && !inferred.includes(provider)) inferred.push(provider);
366
+ }
367
+ if (inferred.length > 0) return inferred;
368
+
369
+ return [...DEFAULT_TARGETS];
370
+ }
371
+
372
+ /**
373
+ * Copy each target provider's compiled skill variant from an extracted bundle
374
+ * into the project. Writes real directories (copy, never symlink) so every
375
+ * harness keeps the build that was compiled for it. Returns skills written.
376
+ */
377
+ function copyProviderSkills(bundleDir, root, targets) {
378
+ let written = 0;
379
+ for (const provider of targets) {
380
+ const srcDir = join(bundleDir, provider, 'skills');
381
+ if (!existsSync(srcDir)) continue;
382
+ const localSkillsDir = join(root, provider, 'skills');
383
+ // A previous `npx skills` install may have left this provider's skills dir
384
+ // as a symlink to another provider's canonical copy. Drop the link so we
385
+ // write a real, provider-specific directory instead of writing through it.
386
+ try {
387
+ if (lstatSync(localSkillsDir).isSymbolicLink()) unlinkSync(localSkillsDir);
388
+ } catch {}
389
+ for (const skill of readdirSync(srcDir, { withFileTypes: true })) {
390
+ if (!skill.isDirectory()) continue;
391
+ const src = join(srcDir, skill.name);
392
+ const dest = join(localSkillsDir, skill.name);
393
+ rmSync(dest, { recursive: true, force: true });
394
+ copyDirSync(src, dest);
395
+ written++;
396
+ }
397
+ }
398
+ return written;
399
+ }
400
+
324
401
  async function install(flags) {
325
402
  const force = flags.includes('--force');
326
403
  const yes = flags.includes('-y') || flags.includes('--yes');
327
404
  const prefixFlag = flags.find(f => f.startsWith('--prefix='));
405
+ const providersFlag = flags.find(f => f.startsWith('--providers='));
328
406
  const root = findProjectRoot();
329
407
  const existing = isAlreadyInstalled(root);
330
408
 
@@ -334,12 +412,51 @@ async function install(flags) {
334
412
  process.exit(0);
335
413
  }
336
414
 
337
- console.log('Installing impeccable skills via npx skills...\n');
415
+ // Decide which harness folders to install into, then copy each harness's own
416
+ // compiled variant from the universal bundle. We deliberately do NOT shell out
417
+ // to `npx skills add`: its name-based discovery can install the uncompiled
418
+ // source, and its symlink default points every harness at one shared variant.
419
+ // Copying per-provider variants is the only correct install for this skill.
420
+ const targets = resolveInstallTargets(root, providersFlag ? providersFlag.split('=')[1] : null);
421
+ if (targets.length === 0) {
422
+ console.error('Could not determine a target harness folder.');
423
+ console.error('Pass one explicitly, e.g. --providers=.claude,.cursor');
424
+ process.exit(1);
425
+ }
426
+
427
+ if (!yes) {
428
+ console.log(`Target harness folder(s): ${targets.join(', ')}`);
429
+ const ans = await ask(`Install impeccable skills into ${targets.length} folder(s)? (Y/n) `);
430
+ if (ans === 'n' || ans === 'no') {
431
+ console.log('Aborted. Re-run with --providers=<dirs> to choose explicitly (e.g. --providers=.claude,.cursor).');
432
+ process.exit(0);
433
+ }
434
+ }
435
+
436
+ console.log('\nDownloading impeccable skills...');
437
+ let bundleDir;
338
438
  try {
339
- execSync(`npx skills add pbakaus/impeccable${yes ? ' -y' : ''}`, { stdio: 'inherit' });
439
+ bundleDir = await downloadAndExtractBundle();
340
440
  } catch (e) {
341
- process.exit(e.status ?? 1);
441
+ console.error(`Download failed: ${e.message}`);
442
+ process.exit(1);
443
+ }
444
+
445
+ let written = 0;
446
+ try {
447
+ written = copyProviderSkills(bundleDir, root, targets);
448
+ } catch (e) {
449
+ rmSync(bundleDir, { recursive: true, force: true });
450
+ console.error(`Install failed: ${e.message}`);
451
+ process.exit(1);
452
+ }
453
+ rmSync(bundleDir, { recursive: true, force: true });
454
+
455
+ if (written === 0) {
456
+ console.error(`Nothing was installed: the bundle had no variants for ${targets.join(', ')}.`);
457
+ process.exit(1);
342
458
  }
459
+ console.log(`Installed impeccable into: ${targets.join(', ')}`);
343
460
 
344
461
  // Ask about prefixing (skip in CI mode unless --prefix= is set)
345
462
  let prefix = '';
@@ -374,7 +491,7 @@ async function install(flags) {
374
491
  // Cleanup script not available -- skip
375
492
  }
376
493
 
377
- console.log(`\nDone! Run /${prefix}impeccable teach in your AI harness to set up design context.\n`);
494
+ console.log(`\nDone! Run /${prefix}impeccable init in your AI harness to set up design context.\n`);
378
495
  }
379
496
 
380
497
  /** Detect prefix by looking for the 'impeccable' skill (or legacy 'teach-impeccable') */