-
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`);
+ });
+});