impeccable 2.1.9 → 2.3.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,101 @@ 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
+
401
+ /**
402
+ * Codex reads custom subagents from `.codex/agents/*.toml`, a sibling of the
403
+ * skill dir that the skills/ copy never touches. Treat it as a sidecar: only
404
+ * write it for projects that actually use Codex, so a pure Claude project
405
+ * doesn't get a stray `.codex/` folder. Codex-likely = the .agents (Codex
406
+ * skills) variant is a target, or a global ~/.codex install exists.
407
+ */
408
+ function isCodexLikely(targets) {
409
+ return targets.includes('.agents') || existsSync(join(homedir(), '.codex'));
410
+ }
411
+
412
+ /**
413
+ * Copy the Codex subagent definitions from the bundle's top-level `.codex/agents`
414
+ * into the project's `.codex/agents`. Returns the number of files written (0 when
415
+ * the bundle has none).
416
+ */
417
+ function installCodexAgents(bundleDir, root) {
418
+ const srcDir = join(bundleDir, '.codex', 'agents');
419
+ if (!existsSync(srcDir)) return 0;
420
+ const destDir = join(root, '.codex', 'agents');
421
+ let written = 0;
422
+ for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
423
+ if (!entry.isFile()) continue;
424
+ mkdirSync(destDir, { recursive: true });
425
+ writeFileSync(join(destDir, entry.name), readFileSync(join(srcDir, entry.name)));
426
+ written++;
427
+ }
428
+ return written;
429
+ }
430
+
324
431
  async function install(flags) {
325
432
  const force = flags.includes('--force');
326
433
  const yes = flags.includes('-y') || flags.includes('--yes');
327
434
  const prefixFlag = flags.find(f => f.startsWith('--prefix='));
435
+ const providersFlag = flags.find(f => f.startsWith('--providers='));
328
436
  const root = findProjectRoot();
329
437
  const existing = isAlreadyInstalled(root);
330
438
 
@@ -334,13 +442,60 @@ async function install(flags) {
334
442
  process.exit(0);
335
443
  }
336
444
 
337
- console.log('Installing impeccable skills via npx skills...\n');
445
+ // Decide which harness folders to install into, then copy each harness's own
446
+ // compiled variant from the universal bundle. We deliberately do NOT shell out
447
+ // to `npx skills add`: its name-based discovery can install the uncompiled
448
+ // source, and its symlink default points every harness at one shared variant.
449
+ // Copying per-provider variants is the only correct install for this skill.
450
+ const targets = resolveInstallTargets(root, providersFlag ? providersFlag.split('=')[1] : null);
451
+ if (targets.length === 0) {
452
+ console.error('Could not determine a target harness folder.');
453
+ console.error('Pass one explicitly, e.g. --providers=.claude,.cursor');
454
+ process.exit(1);
455
+ }
456
+
457
+ if (!yes) {
458
+ console.log(`Target harness folder(s): ${targets.join(', ')}`);
459
+ const ans = await ask(`Install impeccable skills into ${targets.length} folder(s)? (Y/n) `);
460
+ if (ans === 'n' || ans === 'no') {
461
+ console.log('Aborted. Re-run with --providers=<dirs> to choose explicitly (e.g. --providers=.claude,.cursor).');
462
+ process.exit(0);
463
+ }
464
+ }
465
+
466
+ console.log('\nDownloading impeccable skills...');
467
+ let bundleDir;
338
468
  try {
339
- execSync(`npx skills add pbakaus/impeccable${yes ? ' -y' : ''}`, { stdio: 'inherit' });
469
+ bundleDir = await downloadAndExtractBundle();
340
470
  } catch (e) {
341
- process.exit(e.status ?? 1);
471
+ console.error(`Download failed: ${e.message}`);
472
+ process.exit(1);
342
473
  }
343
474
 
475
+ let written = 0;
476
+ let codexAgents = 0;
477
+ try {
478
+ written = copyProviderSkills(bundleDir, root, targets);
479
+ // Codex users also need the asset-producer subagent, which lives in
480
+ // .codex/agents/ (a sibling of the skill dir, not part of skills/). Do this
481
+ // before the bundle is cleaned up below. Best-effort: never fail the install.
482
+ if (isCodexLikely(targets)) {
483
+ try { codexAgents = installCodexAgents(bundleDir, root); } catch {}
484
+ }
485
+ } catch (e) {
486
+ rmSync(bundleDir, { recursive: true, force: true });
487
+ console.error(`Install failed: ${e.message}`);
488
+ process.exit(1);
489
+ }
490
+ rmSync(bundleDir, { recursive: true, force: true });
491
+
492
+ if (written === 0) {
493
+ console.error(`Nothing was installed: the bundle had no variants for ${targets.join(', ')}.`);
494
+ process.exit(1);
495
+ }
496
+ console.log(`Installed impeccable into: ${targets.join(', ')}`);
497
+ if (codexAgents > 0) console.log(`Installed ${codexAgents} Codex subagent(s) into .codex/agents/`);
498
+
344
499
  // Ask about prefixing (skip in CI mode unless --prefix= is set)
345
500
  let prefix = '';
346
501
  if (prefixFlag) {
@@ -374,7 +529,7 @@ async function install(flags) {
374
529
  // Cleanup script not available -- skip
375
530
  }
376
531
 
377
- console.log(`\nDone! Run /${prefix}impeccable teach in your AI harness to set up design context.\n`);
532
+ console.log(`\nDone! Run /${prefix}impeccable init in your AI harness to set up design context.\n`);
378
533
  }
379
534
 
380
535
  /** Detect prefix by looking for the 'impeccable' skill (or legacy 'teach-impeccable') */
@@ -548,9 +703,18 @@ async function update(flags = []) {
548
703
 
549
704
  // Compare local vs remote -- skip if already up to date
550
705
  if (isUpToDate(root, providers, tmpDir)) {
706
+ // Skills match, but the Codex subagent sidecar may still be missing (e.g.
707
+ // an `npx skills add` install that only carried skills/). Heal it before
708
+ // declaring nothing to do.
709
+ let healed = 0;
710
+ if (isCodexLikely(providers)
711
+ && !existsSync(join(root, '.codex', 'agents', 'impeccable_asset_producer.toml'))) {
712
+ try { healed = installCodexAgents(tmpDir, root); } catch {}
713
+ }
551
714
  rmSync(tmpDir, { recursive: true, force: true });
552
715
  const v = getSkillsVersion(root);
553
- console.log(`Skills are up to date${v ? ` (v${v})` : ''}. Nothing to do.`);
716
+ if (healed > 0) console.log(`Installed ${healed} Codex subagent(s) into .codex/agents/`);
717
+ console.log(`Skills are up to date${v ? ` (v${v})` : ''}.${healed > 0 ? '' : ' Nothing to do.'}`);
554
718
  process.exit(0);
555
719
  }
556
720
 
@@ -587,6 +751,11 @@ async function update(flags = []) {
587
751
  }
588
752
  }
589
753
 
754
+ // Refresh the Codex subagent sidecar (.codex/agents/) alongside the skills.
755
+ if (isCodexLikely(providers)) {
756
+ try { installCodexAgents(tmpDir, root); } catch {}
757
+ }
758
+
590
759
  rmSync(tmpDir, { recursive: true, force: true });
591
760
 
592
761
  // Re-apply prefix if detected