From e640a0141b8965d318ebebbc646bbb1fcd3decb5 Mon Sep 17 00:00:00 2001 From: HUSEIN Date: Mon, 16 Mar 2026 12:22:23 +0300 Subject: [PATCH] Add /help command and sync command metadata --- .claude-plugin/marketplace.json | 4 +- .claude-plugin/plugin.json | 2 +- .claude/skills/audit/SKILL.md | 4 +- .claude/skills/critique/SKILL.md | 2 +- .claude/skills/help/SKILL.md | 80 ++++++++++++++++++++++++++++++++ AGENTS.md | 3 +- NOTICE.md | 2 +- README.md | 8 ++-- public/cheatsheet.html | 6 ++- public/index.html | 10 ++-- public/js/data.js | 4 +- public/js/demo-renderer.js | 41 +++++++++++++++- source/skills/help/SKILL.md | 80 ++++++++++++++++++++++++++++++++ tests/command-metadata.test.js | 57 +++++++++++++++++++++++ 14 files changed, 282 insertions(+), 21 deletions(-) create mode 100644 .claude/skills/help/SKILL.md create mode 100644 source/skills/help/SKILL.md create mode 100644 tests/command-metadata.test.js diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 39e6814..a4fa4fa 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -2,7 +2,7 @@ "$schema": "https://anthropic.com/claude-code/marketplace.schema.json", "name": "impeccable", "metadata": { - "description": "Design fluency for AI harnesses. 1 skill, 17 commands, and curated anti-patterns for impeccable frontend design." + "description": "Design fluency for AI harnesses. 1 skill, 18 commands, and curated anti-patterns for impeccable frontend design." }, "owner": { "name": "Paul Bakaus", @@ -11,7 +11,7 @@ "plugins": [ { "name": "impeccable", - "description": "Design vocabulary and skills for frontend development. Includes 17 commands (/polish, /distill, /audit, /bolder, /quieter, etc.) and an enhanced frontend-design skill with curated anti-patterns.", + "description": "Design vocabulary and skills for frontend development. Includes 18 commands (/help, /polish, /distill, /audit, /bolder, /quieter, etc.) and an enhanced frontend-design skill with curated anti-patterns.", "version": "1.3.0", "author": { "name": "Paul Bakaus", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ff9296b..e08f953 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "impeccable", - "description": "Design vocabulary and skills for frontend development. Includes 18 skills (17 user-invokable: /polish, /distill, /audit, /bolder, /quieter, etc.) and an enhanced frontend-design skill with curated anti-patterns.", + "description": "Design vocabulary and skills for frontend development. Includes 19 skills (18 user-invokable: /help, /polish, /distill, /audit, /bolder, /quieter, etc.) and an enhanced frontend-design skill with curated anti-patterns.", "version": "1.3.0", "author": { "name": "Paul Bakaus", diff --git a/.claude/skills/audit/SKILL.md b/.claude/skills/audit/SKILL.md index e1ae379..e6fee8e 100644 --- a/.claude/skills/audit/SKILL.md +++ b/.claude/skills/audit/SKILL.md @@ -71,7 +71,7 @@ For each issue, document: - **Impact**: How it affects users - **WCAG/Standard**: Which standard it violates (if applicable) - **Recommendation**: How to fix it -- **Suggested command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /critique, /colorize — or other installed skills you're sure exist) +- **Suggested command**: Which command to use (prefer: /quieter, /polish, /normalize, /clarify, /harden, /distill, /adapt, /animate, /optimize, /audit, /help, /bolder, /extract, /critique, /delight, /onboard, /colorize — or other installed skills you're sure exist) #### Critical Issues [Issues that block core functionality or violate WCAG A] @@ -108,7 +108,7 @@ Create actionable plan: ### Suggested Commands for Fixes -Map issues to available commands. Prefer these: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /critique, /colorize. You may also suggest other installed skills you're sure exist, but never invent commands. +Map issues to available commands. Prefer these: /quieter, /polish, /normalize, /clarify, /harden, /distill, /adapt, /animate, /optimize, /audit, /help, /bolder, /extract, /critique, /delight, /onboard, /colorize. You may also suggest other installed skills you're sure exist, but never invent commands. Examples: - "Use `/normalize` to align with design system (addresses N theming issues)" diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index eb0d663..e4f0420 100644 --- a/.claude/skills/critique/SKILL.md +++ b/.claude/skills/critique/SKILL.md @@ -102,7 +102,7 @@ For each issue: - **What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /critique, /colorize — or other installed skills you're sure exist) +- **Command**: Which command to use (prefer: /quieter, /polish, /normalize, /clarify, /harden, /distill, /adapt, /animate, /optimize, /audit, /help, /bolder, /extract, /critique, /delight, /onboard, /colorize — or other installed skills you're sure exist) ### Minor Observations Quick notes on smaller issues worth addressing. diff --git a/.claude/skills/help/SKILL.md b/.claude/skills/help/SKILL.md new file mode 100644 index 0000000..a91f5cb --- /dev/null +++ b/.claude/skills/help/SKILL.md @@ -0,0 +1,80 @@ +--- +name: help +description: Explain what each Impeccable command does and recommend the right next command or sequence for the user's design goal. +user-invokable: true +--- + +Help the user choose the right Impeccable command for their current situation. + +This is a navigation command. Do NOT run `teach-impeccable` just to answer `/help`. + +## What To Do + +1. Infer the user's goal from recent context when possible. +2. If their goal is still unclear, ask one short clarifying question before recommending commands. +3. Explain the available commands grouped by purpose. +4. Recommend the best next command or short sequence for the user's specific situation. +5. Never invent commands. Only recommend installed commands: /quieter, /polish, /normalize, /clarify, /harden, /distill, /adapt, /animate, /optimize, /audit, /help, /bolder, /extract, /critique, /delight, /onboard, /colorize. + +## Command Map + +### Setup +- `/teach-impeccable` — Gather project design context and save it for future sessions +- `/help` — Explain the command set and recommend the best next step + +### Diagnose +- `/audit` — Find technical quality issues across accessibility, performance, theming, and responsiveness +- `/critique` — Review UX and visual design quality + +### Quality +- `/normalize` — Align work with the design system and core standards +- `/polish` — Do a final refinement pass before shipping +- `/optimize` — Improve performance and runtime efficiency +- `/harden` — Improve resilience, error handling, and edge cases + +### Adaptation +- `/clarify` — Improve unclear UX writing and labels +- `/distill` — Remove excess and simplify the interface +- `/adapt` — Improve the experience for different devices and contexts + +### Intensity +- `/bolder` — Push a weak or timid design further +- `/quieter` — Tone down a design that feels too loud or heavy + +### Enhancement +- `/animate` — Add purposeful motion +- `/colorize` — Introduce strategic color +- `/delight` — Add charm, personality, or surprise +- `/onboard` — Improve onboarding and guided flows + +### System +- `/extract` — Pull repeated design patterns into reusable components + +## Default Recommendations + +- New project or no design context yet: start with `/teach-impeccable` +- You do not know what is wrong yet: start with `/audit` for technical issues or `/critique` for design issues +- The UI mostly works but feels inconsistent: use `/normalize` +- The UI is close and needs one final pass: use `/polish` +- The design feels bland: use `/bolder`, `/colorize`, or `/delight` +- The design feels busy or overworked: use `/quieter` or `/distill` + +## Response Format + +Use this structure unless the user asks for just a raw list: + +### Best next step +- Name the single best command and why + +### Good alternatives +- List 2-4 relevant commands with one-line guidance + +### Suggested sequence +1. First command +2. Second command +3. Final command + +### Example invocations +- Include 1-3 concrete examples when helpful, such as `/audit header` or `/polish checkout-form` + +Keep the answer brief and practical. The goal is to help the user move, not to dump documentation. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 03e9b0a..aa84356 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Impeccable -The vocabulary you didn't know you needed. 1 skill, 17 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI. +The vocabulary you didn't know you needed. 1 skill, 18 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI. ## Repository Purpose @@ -247,4 +247,3 @@ End users can copy files directly without needing build tools. - [Gemini CLI GEMINI.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md) - [Codex CLI Slash Commands](https://developers.openai.com/codex/guides/slash-commands) - [Codex CLI Skills](https://developers.openai.com/codex/skills/) - diff --git a/NOTICE.md b/NOTICE.md index 1920a33..f22b9a5 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -13,5 +13,5 @@ The `frontend-design` skill in this project builds on Anthropic's original front This project extends the original with: - 7 domain-specific reference files (typography, color-and-contrast, spatial-design, motion-design, interaction-design, responsive-design, ux-writing) -- 17 steering commands +- 18 steering commands - Expanded patterns and anti-patterns diff --git a/README.md b/README.md index 973da61..a493de9 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Impeccable -The vocabulary you didn't know you needed. 1 skill, 17 commands, and curated anti-patterns for impeccable frontend design. +The vocabulary you didn't know you needed. 1 skill, 18 commands, and curated anti-patterns for impeccable frontend design. > **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles. @@ -12,7 +12,7 @@ Every LLM learned from the same generic templates. Without guidance, you get the Impeccable fights that bias with: - **An expanded skill** with 7 domain-specific reference files ([view source](source/skills/frontend-design/)) -- **17 steering commands** to audit, review, polish, distill, animate, and more +- **18 steering commands** to audit, review, polish, distill, animate, and more - **Curated anti-patterns** that explicitly tell the AI what NOT to do ## What's Included @@ -31,11 +31,12 @@ A comprehensive design skill with 7 domain-specific references ([view skill](sou | [responsive-design](source/skills/frontend-design/reference/responsive-design.md) | Mobile-first, fluid design, container queries | | [ux-writing](source/skills/frontend-design/reference/ux-writing.md) | Button labels, error messages, empty states | -### 17 Commands +### 18 Commands | Command | What it does | |---------|--------------| | `/teach-impeccable` | One-time setup: gather design context, save to config | +| `/help` | List available commands and recommend the best next step | | `/audit` | Run technical quality checks (a11y, performance, responsive) | | `/critique` | UX design review: hierarchy, clarity, emotional resonance | | `/normalize` | Align with design system standards | @@ -127,6 +128,7 @@ cp -r dist/codex/.codex/* ~/.codex/ Once installed, use commands in your AI harness: ``` +/help # Pick the right command /audit # Find issues /normalize # Fix inconsistencies /polish # Final cleanup diff --git a/public/cheatsheet.html b/public/cheatsheet.html index 179a093..70e3329 100644 --- a/public/cheatsheet.html +++ b/public/cheatsheet.html @@ -4,7 +4,7 @@ Impeccable Command Cheatsheet - + @@ -160,7 +160,7 @@

Impeccable Commands

-

Quick reference for all 17 design commands

+

Quick reference for all 18 design commands

← Back to impeccable.style
@@ -186,6 +186,7 @@

Impeccable Commands

const commandCategories = { 'teach-impeccable': 'system', + 'help': 'system', 'audit': 'diagnostic', 'critique': 'diagnostic', 'normalize': 'quality', @@ -206,6 +207,7 @@

Impeccable Commands

const commandRelationships = { 'teach-impeccable': { flow: 'One-time project context gathering' }, + 'help': { leadsTo: ['teach-impeccable', 'audit', 'critique'], flow: 'Discover the right next command' }, 'audit': { leadsTo: ['normalize', 'harden', 'optimize', 'adapt', 'clarify'], flow: 'Technical quality audit' }, 'critique': { leadsTo: ['polish', 'distill', 'bolder', 'quieter'], flow: 'UX and design review' }, 'normalize': { combinesWith: ['clarify', 'adapt'], flow: 'Align with design system' }, diff --git a/public/index.html b/public/index.html index 220094f..ac48acd 100644 --- a/public/index.html +++ b/public/index.html @@ -4,7 +4,7 @@ Impeccable: The missing upgrade to Anthropic's frontend-design skill - + @@ -12,7 +12,7 @@ - + @@ -20,7 +20,7 @@ - + @@ -57,7 +57,7 @@

Impeccable

Enhanced frontend-design skill + anti-patterns · - 17 design skills: /polish, /audit, /distill, /bolder... + 18 design skills: /help, /polish, /audit, /distill...
@@ -162,7 +162,7 @@

The Antidote

The Framework

-

One comprehensive skill with deep expertise, plus 17 commands that form the language of design.

+

One comprehensive skill with deep expertise, plus 18 commands that form the language of design.

diff --git a/public/js/data.js b/public/js/data.js index 15f3f6c..93ac274 100644 --- a/public/js/data.js +++ b/public/js/data.js @@ -38,6 +38,7 @@ export const skillReferenceDomains = [ export const commandProcessSteps = { 'teach-impeccable': ['Gather', 'Clarify', 'Document', 'Save'], + 'help': ['Inspect', 'List', 'Recommend'], 'audit': ['Scan', 'Document', 'Prioritize', 'Recommend'], 'critique': ['Evaluate', 'Critique', 'Prioritize', 'Suggest'], 'normalize': ['Analyze', 'Identify', 'Align', 'Verify'], @@ -58,6 +59,7 @@ export const commandProcessSteps = { export const commandCategories = { 'teach-impeccable': 'system', + 'help': 'system', 'audit': 'diagnostic', 'critique': 'diagnostic', 'normalize': 'quality', @@ -87,6 +89,7 @@ export const skillRelationships = { export const commandRelationships = { 'teach-impeccable': { flow: 'Setup: One-time project context gathering' }, + 'help': { leadsTo: ['teach-impeccable', 'audit', 'critique'], flow: 'System: Discover the right command' }, 'audit': { leadsTo: ['normalize', 'harden', 'optimize', 'adapt', 'clarify'], flow: 'Diagnostic: Technical quality audit' }, 'critique': { leadsTo: ['polish', 'distill', 'bolder', 'quieter'], flow: 'Diagnostic: UX and design review' }, 'normalize': { combinesWith: ['clarify', 'adapt'], flow: 'Quality: Align with design system' }, @@ -104,4 +107,3 @@ export const commandRelationships = { 'adapt': { combinesWith: ['normalize', 'clarify'], flow: 'Adaptation: Different devices/contexts' }, 'onboard': { combinesWith: ['clarify', 'delight'], flow: 'Enhancement: Onboarding & empty states' } }; - diff --git a/public/js/demo-renderer.js b/public/js/demo-renderer.js index 08ab6d7..88691dc 100644 --- a/public/js/demo-renderer.js +++ b/public/js/demo-renderer.js @@ -50,6 +50,46 @@ export function renderCommandDemo(commandId) {
`; } + if (commandId === 'help') { + return ` +
+
+
+
What it helps with
+
+
+ 1. + Shows the command set grouped by purpose +
+
+ 2. + Recommends the right next command for your goal +
+
+ 3. + Suggests a short sequence when one command is not enough +
+
+
Common starts
+
+
+ → + New project: /teach-impeccable +
+
+ → + Something feels wrong: /audit or /critique +
+
+ → + Nearly done: /polish +
+
+
+
+
+ `; + } return `
@@ -165,4 +205,3 @@ export function setupDemoTabs() { } - diff --git a/source/skills/help/SKILL.md b/source/skills/help/SKILL.md new file mode 100644 index 0000000..c56be6f --- /dev/null +++ b/source/skills/help/SKILL.md @@ -0,0 +1,80 @@ +--- +name: help +description: Explain what each Impeccable command does and recommend the right next command or sequence for the user's design goal. +user-invokable: true +--- + +Help the user choose the right Impeccable command for their current situation. + +This is a navigation command. Do NOT run `teach-impeccable` just to answer `/help`. + +## What To Do + +1. Infer the user's goal from recent context when possible. +2. If their goal is still unclear, ask one short clarifying question before recommending commands. +3. Explain the available commands grouped by purpose. +4. Recommend the best next command or short sequence for the user's specific situation. +5. Never invent commands. Only recommend installed commands: {{available_commands}}. + +## Command Map + +### Setup +- `/teach-impeccable` — Gather project design context and save it for future sessions +- `/help` — Explain the command set and recommend the best next step + +### Diagnose +- `/audit` — Find technical quality issues across accessibility, performance, theming, and responsiveness +- `/critique` — Review UX and visual design quality + +### Quality +- `/normalize` — Align work with the design system and core standards +- `/polish` — Do a final refinement pass before shipping +- `/optimize` — Improve performance and runtime efficiency +- `/harden` — Improve resilience, error handling, and edge cases + +### Adaptation +- `/clarify` — Improve unclear UX writing and labels +- `/distill` — Remove excess and simplify the interface +- `/adapt` — Improve the experience for different devices and contexts + +### Intensity +- `/bolder` — Push a weak or timid design further +- `/quieter` — Tone down a design that feels too loud or heavy + +### Enhancement +- `/animate` — Add purposeful motion +- `/colorize` — Introduce strategic color +- `/delight` — Add charm, personality, or surprise +- `/onboard` — Improve onboarding and guided flows + +### System +- `/extract` — Pull repeated design patterns into reusable components + +## Default Recommendations + +- New project or no design context yet: start with `/teach-impeccable` +- You do not know what is wrong yet: start with `/audit` for technical issues or `/critique` for design issues +- The UI mostly works but feels inconsistent: use `/normalize` +- The UI is close and needs one final pass: use `/polish` +- The design feels bland: use `/bolder`, `/colorize`, or `/delight` +- The design feels busy or overworked: use `/quieter` or `/distill` + +## Response Format + +Use this structure unless the user asks for just a raw list: + +### Best next step +- Name the single best command and why + +### Good alternatives +- List 2-4 relevant commands with one-line guidance + +### Suggested sequence +1. First command +2. Second command +3. Final command + +### Example invocations +- Include 1-3 concrete examples when helpful, such as `/audit header` or `/polish checkout-form` + +Keep the answer brief and practical. The goal is to help the user move, not to dump documentation. diff --git a/tests/command-metadata.test.js b/tests/command-metadata.test.js new file mode 100644 index 0000000..070687d --- /dev/null +++ b/tests/command-metadata.test.js @@ -0,0 +1,57 @@ +import { describe, expect, test } from 'bun:test'; +import fs from 'fs'; +import path from 'path'; +import { parseFrontmatter } from '../scripts/lib/utils.js'; +import { commandCategories, commandProcessSteps } from '../public/js/data.js'; + +function getUserInvokableCommandIds() { + const skillsDir = path.join(process.cwd(), 'source', 'skills'); + const entries = fs.readdirSync(skillsDir, { withFileTypes: true }); + + return entries + .filter((entry) => entry.isDirectory()) + .map((entry) => { + const skillPath = path.join(skillsDir, entry.name, 'SKILL.md'); + if (!fs.existsSync(skillPath)) return null; + + const content = fs.readFileSync(skillPath, 'utf-8'); + const { frontmatter } = parseFrontmatter(content); + const isUserInvokable = frontmatter['user-invokable'] === true || frontmatter['user-invokable'] === 'true'; + + return isUserInvokable ? (frontmatter.name || entry.name) : null; + }) + .filter(Boolean) + .sort(); +} + +describe('public command metadata', () => { + test('covers every user-invokable skill in public/js/data.js', () => { + const commandIds = getUserInvokableCommandIds(); + + for (const id of commandIds) { + expect(commandProcessSteps).toHaveProperty(id); + expect(commandCategories).toHaveProperty(id); + } + }); + + test('covers every user-invokable skill in the cheatsheet category map', () => { + const commandIds = getUserInvokableCommandIds(); + const cheatsheet = fs.readFileSync(path.join(process.cwd(), 'public', 'cheatsheet.html'), 'utf-8'); + const categoryBlockMatch = cheatsheet.match(/const commandCategories = \{([\s\S]*?)\n \};/); + + expect(categoryBlockMatch).not.toBeNull(); + + const categoryBlock = categoryBlockMatch[1]; + for (const id of commandIds) { + expect(categoryBlock).toContain(`'${id}':`); + } + }); + + test('keeps the cheatsheet command count in sync', () => { + const commandIds = getUserInvokableCommandIds(); + const cheatsheet = fs.readFileSync(path.join(process.cwd(), 'public', 'cheatsheet.html'), 'utf-8'); + + expect(cheatsheet).toContain(`Quick reference for all ${commandIds.length} Impeccable commands.`); + expect(cheatsheet).toContain(`Quick reference for all ${commandIds.length} design commands`); + }); +});