@bcelep/capint 0.4.2 → 0.6.5

package/skills/impeccable/references/WCAG.md

@@ -0,0 +1,191 @@
+# WCAG 2.2 Quick Reference
+
+## Success criteria by level
+
+### Level A (minimum)
+
+| Criterion | Description |
+|-----------|-------------|
+| **1.1.1** Non-text Content | All images, icons have text alternatives |
+| **1.2.1** Audio-only/Video-only | Provide transcript or audio description |
+| **1.2.2** Captions | Video with audio has captions |
+| **1.2.3** Audio Description | Video has audio description |
+| **1.3.1** Info and Relationships | Information conveyed through presentation is available programmatically |
+| **1.3.2** Meaningful Sequence | Reading order is logical |
+| **1.3.3** Sensory Characteristics | Instructions don't rely solely on shape, color, size, location, orientation, or sound |
+| **1.4.1** Use of Color | Color is not the only visual means of conveying information |
+| **1.4.2** Audio Control | Audio playing automatically can be paused/stopped |
+| **2.1.1** Keyboard | All functionality available via keyboard |
+| **2.1.2** No Keyboard Trap | Keyboard focus can be moved away from any component |
+| **2.1.4** Character Key Shortcuts | Single-key shortcuts can be turned off or remapped |
+| **2.2.1** Timing Adjustable | Time limits can be extended |
+| **2.2.2** Pause, Stop, Hide | Moving/blinking content can be paused |
+| **2.3.1** Three Flashes | Nothing flashes more than 3 times per second |
+| **2.4.1** Bypass Blocks | Skip link or landmark navigation available |
+| **2.4.2** Page Titled | Pages have descriptive titles |
+| **2.4.3** Focus Order | Focus order preserves meaning |
+| **2.4.4** Link Purpose | Link purpose clear from link text or context |
+| **2.5.1** Pointer Gestures | Multi-point gestures have single-pointer alternatives |
+| **2.5.2** Pointer Cancellation | Down-event doesn't trigger action (use up-event or click) |
+| **2.5.3** Label in Name | Accessible name contains visible label text |
+| **2.5.4** Motion Actuation | Motion-triggered functions have alternatives |
+| **3.1.1** Language of Page | Default language specified in HTML |
+| **3.2.1** On Focus | Focus doesn't trigger unexpected changes |
+| **3.2.2** On Input | Input doesn't trigger unexpected changes |
+| **3.2.6** Consistent Help | Help mechanisms appear in the same relative order across pages |
+| **3.3.1** Error Identification | Input errors clearly described |
+| **3.3.2** Labels or Instructions | Form inputs have labels or instructions |
+| **3.3.7** Redundant Entry | Information previously entered is auto-populated or available to select |
+| **4.1.2** Name, Role, Value | UI components have accessible names and correct roles |
+
+### Level AA (standard)
+
+| Criterion | Description |
+|-----------|-------------|
+| **1.2.4** Captions (Live) | Live audio has captions |
+| **1.2.5** Audio Description | Pre-recorded video has audio description |
+| **1.3.4** Orientation | Content doesn't restrict orientation |
+| **1.3.5** Identify Input Purpose | Input purpose can be programmatically determined |
+| **1.4.3** Contrast (Minimum) | 4.5:1 for normal text, 3:1 for large text |
+| **1.4.4** Resize Text | Text can be resized to 200% without loss of functionality |
+| **1.4.5** Images of Text | Text used instead of images of text |
+| **1.4.10** Reflow | Content reflows at 320px width without horizontal scroll |
+| **1.4.11** Non-text Contrast | UI components have 3:1 contrast |
+| **1.4.12** Text Spacing | Content adapts to text spacing changes |
+| **1.4.13** Content on Hover/Focus | Additional content is dismissible, hoverable, persistent |
+| **2.4.5** Multiple Ways | Multiple ways to find pages |
+| **2.4.6** Headings and Labels | Headings and labels are descriptive |
+| **2.4.7** Focus Visible | Focus indicator is visible |
+| **2.4.11** Focus Not Obscured (Minimum) | Focused element is not entirely hidden by author-created content |
+| **2.5.7** Dragging Movements | Dragging actions have single-pointer alternatives |
+| **2.5.8** Target Size (Minimum) | Interactive targets are at least 24×24 CSS pixels (with exceptions) |
+| **3.1.2** Language of Parts | Language changes are marked |
+| **3.2.3** Consistent Navigation | Navigation is consistent across pages |
+| **3.2.4** Consistent Identification | Same functionality uses same labels |
+| **3.3.3** Error Suggestion | Error corrections suggested when known |
+| **3.3.4** Error Prevention (Legal) | Actions can be reversed or confirmed |
+| **3.3.8** Accessible Authentication (Minimum) | No cognitive function test for login unless an alternative or assistance is provided |
+| **4.1.3** Status Messages | Status messages announced to screen readers |
+
+### Level AAA (enhanced)
+
+| Criterion | Description |
+|-----------|-------------|
+| **1.4.6** Contrast (Enhanced) | 7:1 for normal text, 4.5:1 for large text |
+| **1.4.8** Visual Presentation | Foreground/background colors can be selected |
+| **1.4.9** Images of Text (No Exception) | No images of text |
+| **2.1.3** Keyboard (No Exception) | All functionality keyboard accessible |
+| **2.2.3** No Timing | No time limits |
+| **2.2.4** Interruptions | Interruptions can be postponed |
+| **2.2.5** Re-authenticating | Data preserved on re-authentication |
+| **2.2.6** Timeouts | Users warned about data loss from inactivity |
+| **2.3.2** Three Flashes | No content flashes more than 3 times |
+| **2.3.3** Animation from Interactions | Motion animation can be disabled |
+| **2.4.8** Location | User location within site is available |
+| **2.4.9** Link Purpose (Link Only) | Link purpose clear from link text alone |
+| **2.4.10** Section Headings | Sections have headings |
+| **2.4.12** Focus Not Obscured (Enhanced) | No part of the focused element is hidden by author-created content |
+| **2.4.13** Focus Appearance | Focus indicator has sufficient area, contrast, and is not obscured |
+| **3.1.3** Unusual Words | Definitions available for unusual words |
+| **3.1.4** Abbreviations | Abbreviations expanded |
+| **3.1.5** Reading Level | Alternative content for complex text |
+| **3.1.6** Pronunciation | Pronunciation available where needed |
+| **3.2.5** Change on Request | Changes initiated only by user |
+| **3.3.5** Help | Context-sensitive help available |
+| **3.3.6** Error Prevention (All) | All form submissions can be reviewed |
+| **3.3.9** Accessible Authentication (Enhanced) | No cognitive function test for login (no object or personal content recognition exceptions) |
+
+## Common ARIA patterns
+
+### Buttons
+```html
+<button>Label</button>
+<!-- or -->
+<button aria-label="Close dialog">×</button>
+```
+
+### Links
+```html
+<a href="/page">Descriptive link text</a>
+<!-- External links -->
+<a href="https://external.com" target="_blank" rel="noopener">
+  External site
+  <span class="visually-hidden">(opens in new tab)</span>
+</a>
+```
+
+### Form fields
+```html
+<label for="email">Email address</label>
+<input type="email" id="email" aria-describedby="email-hint">
+<p id="email-hint">We'll never share your email.</p>
+```
+
+### Error states
+```html
+<label for="email">Email</label>
+<input type="email" id="email" aria-invalid="true" aria-describedby="email-error">
+<p id="email-error" role="alert">Please enter a valid email address.</p>
+```
+
+### Navigation
+```html
+<nav aria-label="Main">
+  <ul>
+    <li><a href="/" aria-current="page">Home</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+```
+
+### Modals
+```html
+<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Confirm Action</h2>
+  <!-- content -->
+</div>
+```
+
+### Live regions
+```html
+<!-- Polite (waits for pause in speech) -->
+<div aria-live="polite">Status update here</div>
+
+<!-- Assertive (interrupts immediately) -->
+<div aria-live="assertive" role="alert">Error message here</div>
+
+<!-- Status (polite, implicit) -->
+<div role="status">Loading complete</div>
+```
+
+## What changed from 2.1 to 2.2
+
+| Change | Criterion | Level |
+|--------|-----------|-------|
+| **Removed** | 4.1.1 Parsing | A |
+| **Added** | 2.4.11 Focus Not Obscured (Minimum) | AA |
+| **Added** | 2.4.12 Focus Not Obscured (Enhanced) | AAA |
+| **Added** | 2.4.13 Focus Appearance | AAA |
+| **Added** | 2.5.7 Dragging Movements | AA |
+| **Added** | 2.5.8 Target Size (Minimum) | AA |
+| **Added** | 3.2.6 Consistent Help | A |
+| **Added** | 3.3.7 Redundant Entry | A |
+| **Added** | 3.3.8 Accessible Authentication (Minimum) | AA |
+| **Added** | 3.3.9 Accessible Authentication (Enhanced) | AAA |
+
+## Testing tools
+
+| Tool | Type | URL |
+|------|------|-----|
+| axe DevTools | Browser extension | [deque.com/axe](https://www.deque.com/axe/) |
+| WAVE | Browser extension | [wave.webaim.org](https://wave.webaim.org/) |
+| Lighthouse | Built into Chrome | DevTools → Lighthouse |
+| NVDA | Screen reader (Windows) | [nvaccess.org](https://www.nvaccess.org/) |
+| VoiceOver | Screen reader (Mac) | Built into macOS |
+| Colour Contrast Analyser | Desktop app | [tpgi.com](https://www.tpgi.com/color-contrast-checker/) |
+
+## Sources
+
+- [WCAG 2.2 W3C Recommendation](https://www.w3.org/TR/WCAG22/)
+- [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/)
+- [What's New in WCAG 2.2](https://www.w3.org/WAI/standards-guidelines/wcag/new-in-22/)

package/skills/impeccable/scripts/cleanup-deprecated.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * Cleans up deprecated Impeccable skill files, symlinks, and
+ * skills-lock.json entries left over from previous versions.
+ *
+ * Safe to run repeatedly -- it is a no-op when nothing needs cleaning.
+ *
+ * Usage (from the project root):
+ *   node {{scripts_path}}/cleanup-deprecated.mjs
+ *
+ * What it does:
+ *   1. Finds every harness-specific skills directory (.claude/skills,
+ *      .cursor/skills, .agents/skills, etc.).
+ *   2. For each deprecated skill name (with and without i- prefix),
+ *      checks if the directory exists and its SKILL.md mentions
+ *      "impeccable" (to avoid deleting unrelated user skills).
+ *   3. Deletes confirmed matches (files, directories, or symlinks).
+ *   4. Removes the corresponding entries from skills-lock.json.
+ */
+
+import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+// Skills that were renamed, merged, or folded in v2.0, v2.1, and v3.0.
+const DEPRECATED_NAMES = [
+  // v2.0 renames
+  'frontend-design',    // renamed to impeccable
+  'teach-impeccable',   // folded into /impeccable teach
+  // v2.1 merges
+  'arrange',            // renamed to layout
+  'normalize',          // merged into polish
+  'onboard',            // merged into harden
+  'extract',            // merged into /impeccable extract
+  // v3.0 consolidation: all standalone skills -> /impeccable sub-commands
+  'adapt',
+  'animate',
+  'audit',
+  'bolder',
+  'clarify',
+  'colorize',
+  'critique',
+  'delight',
+  'distill',
+  'harden',
+  'layout',
+  'optimize',
+  'overdrive',
+  'polish',
+  'quieter',
+  'shape',
+  'typeset',
+];
+
+// All known harness directories that may contain a skills/ subfolder.
+const HARNESS_DIRS = [
+  '.claude', '.cursor', '.gemini', '.codex', '.agents',
+  '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
+];
+
+// Per-skill fingerprints for SKILL.md bodies that never mentioned
+// "impeccable" in their v2.x source. Used as a last-resort match
+// when no skills-lock.json exists and the word heuristic fails.
+// The strings are lifted verbatim from the v2.x frontmatter
+// descriptions, so collisions with hand-written user skills are
+// vanishingly unlikely.
+const SKILL_FINGERPRINTS = {
+  harden: 'Make interfaces production-ready: error handling, empty states',
+  optimize: 'Diagnoses and fixes UI performance across loading speed',
+};
+
+/**
+ * Walk up from startDir until we find a directory that looks like a
+ * project root (has package.json, .git, or skills-lock.json).
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  const { root } = { root: '/' };
+  while (dir !== root) {
+    if (
+      existsSync(join(dir, 'package.json')) ||
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, 'skills-lock.json'))
+    ) {
+      return dir;
+    }
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(startDir);
+}
+
+/**
+ * Load skills-lock.json from the project root, or null if missing/unreadable.
+ */
+export function loadLock(projectRoot) {
+  const lockPath = join(projectRoot, 'skills-lock.json');
+  if (!existsSync(lockPath)) return null;
+  try {
+    return JSON.parse(readFileSync(lockPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check whether a skill directory belongs to Impeccable. Three layered
+ * signals, in order of reliability:
+ *   1. Lock source equals "pbakaus/impeccable" (authoritative).
+ *   2. SKILL.md body contains the word "impeccable".
+ *   3. SKILL.md body contains a per-skill fingerprint (for harden and
+ *      optimize, whose v2.x SKILL.md never mentioned the pack name).
+ */
+export function isImpeccableSkill(skillDir, { skillName, lock } = {}) {
+  // 1. Authoritative: the lock file claims this skill is ours.
+  if (skillName && lock?.skills?.[skillName]?.source === 'pbakaus/impeccable') {
+    return true;
+  }
+  const skillMd = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillMd)) return false;
+  let content;
+  try {
+    content = readFileSync(skillMd, 'utf-8');
+  } catch {
+    return false;
+  }
+  // 2. Word-level content heuristic.
+  if (/impeccable/i.test(content)) return true;
+  // 3. Per-skill fingerprint for old skills that never mentioned the pack.
+  //    Strip the i- prefix so both `harden` and `i-harden` resolve to the
+  //    same fingerprint entry.
+  const unprefixed = skillName?.startsWith('i-') ? skillName.slice(2) : skillName;
+  const fingerprint = unprefixed && SKILL_FINGERPRINTS[unprefixed];
+  if (fingerprint && content.includes(fingerprint)) return true;
+  return false;
+}
+
+/**
+ * Build the full list of names to check: each deprecated name, plus
+ * its i-prefixed variant.
+ */
+export function buildTargetNames() {
+  const names = [];
+  for (const name of DEPRECATED_NAMES) {
+    names.push(name);
+    names.push(`i-${name}`);
+  }
+  return names;
+}
+
+/**
+ * Find every skills directory across all harness dirs in the project.
+ * Returns absolute paths that exist on disk.
+ */
+export function findSkillsDirs(projectRoot) {
+  const dirs = [];
+  for (const harness of HARNESS_DIRS) {
+    const candidate = join(projectRoot, harness, 'skills');
+    if (existsSync(candidate)) {
+      dirs.push(candidate);
+    }
+  }
+  return dirs;
+}
+
+/**
+ * Remove deprecated skill directories/symlinks from all harness dirs.
+ * Reads skills-lock.json so the authoritative "source" field can
+ * drive deletion even when SKILL.md never mentions impeccable.
+ * Returns an array of paths that were deleted.
+ */
+export function removeDeprecatedSkills(projectRoot, lock) {
+  if (lock === undefined) lock = loadLock(projectRoot);
+  const targets = buildTargetNames();
+  const skillsDirs = findSkillsDirs(projectRoot);
+  const deleted = [];
+
+  for (const skillsDir of skillsDirs) {
+    for (const name of targets) {
+      const skillPath = join(skillsDir, name);
+
+      // Use lstat to detect symlinks (existsSync follows symlinks and
+      // returns false for dangling ones).
+      let stat;
+      try {
+        stat = lstatSync(skillPath);
+      } catch {
+        continue; // does not exist at all
+      }
+
+      if (stat.isSymbolicLink()) {
+        // Symlink: check the target if it's alive, otherwise treat
+        // dangling symlinks to deprecated names as safe to remove.
+        const targetAlive = existsSync(skillPath);
+        const isMatch = targetAlive
+          ? isImpeccableSkill(skillPath, { skillName: name, lock })
+          : true;
+        if (isMatch) {
+          unlinkSync(skillPath);
+          deleted.push(skillPath);
+        }
+        continue;
+      }
+
+      // Regular directory -- verify it belongs to impeccable
+      if (isImpeccableSkill(skillPath, { skillName: name, lock })) {
+        rmSync(skillPath, { recursive: true, force: true });
+        deleted.push(skillPath);
+      }
+    }
+  }
+
+  return deleted;
+}
+
+/**
+ * Remove deprecated entries from skills-lock.json.
+ * Only removes entries whose source is "pbakaus/impeccable".
+ * Returns the list of removed skill names.
+ */
+export function cleanSkillsLock(projectRoot) {
+  const lockPath = join(projectRoot, 'skills-lock.json');
+  if (!existsSync(lockPath)) return [];
+
+  let lock;
+  try {
+    lock = JSON.parse(readFileSync(lockPath, 'utf-8'));
+  } catch {
+    return [];
+  }
+
+  if (!lock.skills || typeof lock.skills !== 'object') return [];
+
+  const targets = buildTargetNames();
+  const removed = [];
+
+  for (const name of targets) {
+    const entry = lock.skills[name];
+    if (!entry) continue;
+    // Only remove if it belongs to impeccable
+    if (entry.source === 'pbakaus/impeccable') {
+      delete lock.skills[name];
+      removed.push(name);
+    }
+  }
+
+  if (removed.length > 0) {
+    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf-8');
+  }
+
+  return removed;
+}
+
+/**
+ * Run the full cleanup. Returns a summary object.
+ *
+ * Order matters: read the lock and delete directories first, then
+ * strip lock entries. Otherwise the authoritative signal is gone by
+ * the time directory deletion runs.
+ */
+export function cleanup(projectRoot) {
+  const root = projectRoot || findProjectRoot();
+  const lock = loadLock(root);
+  const deletedPaths = removeDeprecatedSkills(root, lock);
+  const removedLockEntries = cleanSkillsLock(root);
+  return { deletedPaths, removedLockEntries, projectRoot: root };
+}
+
+// CLI entry point
+if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
+  const result = cleanup();
+  if (result.deletedPaths.length === 0 && result.removedLockEntries.length === 0) {
+    console.log('No deprecated Impeccable skills found. Nothing to clean up.');
+  } else {
+    if (result.deletedPaths.length > 0) {
+      console.log(`Removed ${result.deletedPaths.length} deprecated skill(s):`);
+      for (const p of result.deletedPaths) console.log(`  - ${p}`);
+    }
+    if (result.removedLockEntries.length > 0) {
+      console.log(`Cleaned ${result.removedLockEntries.length} entry/entries from skills-lock.json:`);
+      for (const name of result.removedLockEntries) console.log(`  - ${name}`);
+    }
+  }
+}

package/skills/impeccable/scripts/command-metadata.json

@@ -0,0 +1,94 @@
+{
+  "craft": {
+    "description": "Full confirmed-brief-then-build flow. Runs multi-round shape discovery first, resolves visual probe and north-star mock gates when available, then builds and visually iterates. Use when building a new feature end-to-end.",
+    "argumentHint": "[feature description]"
+  },
+  "teach": {
+    "description": "Gathers design context for a project. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles) and, when code exists to analyze, DESIGN.md (visual: colors, typography, components). Every other command reads these files before doing work. Use once per project.",
+    "argumentHint": ""
+  },
+  "document": {
+    "description": "Generate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible. Use when you need a visual design spec an AI agent can follow to stay on-brand.",
+    "argumentHint": ""
+  },
+  "extract": {
+    "description": "Pull reusable patterns, components, and design tokens into the design system. Identifies repeated patterns and consolidates them. Use when you have drift across the codebase and want to bring things back to a consistent system.",
+    "argumentHint": "[target]"
+  },
+  "live": {
+    "description": "Interactive live variant mode. Select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via HMR. Requires a running dev server. Use when you want to visually experiment with design alternatives in real time.",
+    "argumentHint": ""
+  },
+  "adapt": {
+    "description": "Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. Use when the user mentions responsive design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility.",
+    "argumentHint": "[target] [context (mobile, tablet, print...)]"
+  },
+  "animate": {
+    "description": "Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive.",
+    "argumentHint": "[target]"
+  },
+  "audit": {
+    "description": "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review.",
+    "argumentHint": "[area (feature, page, component...)]"
+  },
+  "bolder": {
+    "description": "Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. Use when the user says the design looks bland, generic, too safe, lacks personality, or wants more visual impact and character.",
+    "argumentHint": "[target]"
+  },
+  "clarify": {
+    "description": "Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing.",
+    "argumentHint": "[target]"
+  },
+  "colorize": {
+    "description": "Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette.",
+    "argumentHint": "[target]"
+  },
+  "critique": {
+    "description": "Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, automated anti-pattern detection, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component.",
+    "argumentHint": "[area (feature, page, component...)]"
+  },
+  "delight": {
+    "description": "Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.",
+    "argumentHint": "[target]"
+  },
+  "distill": {
+    "description": "Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when the user asks to simplify, declutter, reduce noise, remove elements, or make a UI cleaner and more focused.",
+    "argumentHint": "[target]"
+  },
+  "harden": {
+    "description": "Make interfaces production-ready: error handling, i18n, text overflow, edge case management, and resilience under real-world data. Use when the user asks to harden, make production-ready, handle edge cases, add error states, or fix overflow and i18n issues.",
+    "argumentHint": "[target]"
+  },
+  "onboard": {
+    "description": "Design onboarding flows, first-run experiences, and empty states that guide new users to value. Covers welcome screens, account setup, progressive disclosure, contextual tooltips, feature announcements, and activation moments. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, new user flows, or the aha moment.",
+    "argumentHint": "[target]"
+  },
+  "layout": {
+    "description": "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition.",
+    "argumentHint": "[target]"
+  },
+  "optimize": {
+    "description": "Diagnoses and fixes UI performance across loading speed, rendering, animations, images, and bundle size. Use when the user mentions slow, laggy, janky, performance, bundle size, load time, or wants a faster, smoother experience.",
+    "argumentHint": "[target]"
+  },
+  "overdrive": {
+    "description": "Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary.",
+    "argumentHint": "[target]"
+  },
+  "polish": {
+    "description": "Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great.",
+    "argumentHint": "[target]"
+  },
+  "quieter": {
+    "description": "Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when the user mentions too bold, too loud, overwhelming, aggressive, garish, or wants a calmer, more refined aesthetic.",
+    "argumentHint": "[target]"
+  },
+  "shape": {
+    "description": "Plan UX and UI before code. Runs a required multi-round discovery interview, uses visual probes when available, and produces a user-confirmed design brief for implementation.",
+    "argumentHint": "[feature to shape]"
+  },
+  "typeset": {
+    "description": "Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography.",
+    "argumentHint": "[target]"
+  }
+}