The design language that makes your AI harness better at design.
JavaScript
Calm the register of older command references (#853) (#1046)
Paul Bakaus497064cc22c1
diff --git a/scripts/build.js b/scripts/build.jsindex d1c3eefa2..84c4a2291 100644--- a/scripts/build.js+++ b/scripts/build.js@@ -433,10 +433,10 @@ function validateSkillProse(rootDir) {* Validate that every `{{ask_instruction}}` interpolation starts a sentence.** The placeholder's per-provider values are complete capitalized sentences- * ("STOP and call the AskUserQuestion tool to clarify."), so a call site that+ * ("Ask with the AskUserQuestion tool and wait for the answer before continuing."), so a call site that* splices it mid-sentence ships malformed guidance to every provider at once:- * `stop and STOP and call the AskUserQuestion tool to clarify. before expanding- * it`. Four reference files shipped exactly that before this gate existed, and+ * `stop and Ask with the AskUserQuestion tool and wait for the answer before+ * continuing. before expanding it`. Four reference files shipped exactly that before this gate existed, and* a comment in PROVIDER_PLACEHOLDERS asking authors to keep the contract is* what failed to prevent it.*diff --git a/scripts/lib/utils.js b/scripts/lib/utils.jsindex 82fd85a80..0bd721bc3 100644--- a/scripts/lib/utils.js+++ b/scripts/lib/utils.js@@ -415,7 +415,7 @@ export const PROVIDER_PLACEHOLDERS = {'claude-code': {model: 'Claude',config_file: 'CLAUDE.md',- ask_instruction: 'STOP and call the AskUserQuestion tool to clarify.',+ ask_instruction: 'Ask with the AskUserQuestion tool and wait for the answer before continuing.',command_prefix: '/'},'cursor': {@@ -427,7 +427,7 @@ export const PROVIDER_PLACEHOLDERS = {'dsh': {model: 'DeepSeek',config_file: 'AGENTS.md',- ask_instruction: 'STOP and call the ask_user_question tool to clarify.',+ ask_instruction: 'Ask with the ask_user_question tool and wait for the answer before continuing.',command_prefix: '/'},'gemini': {@@ -443,7 +443,7 @@ export const PROVIDER_PLACEHOLDERS = {// {{ask_instruction}} call site is sentence-initial. That is enforced by// validateAskInstructionSites() in scripts/build.js, not left to authors:// four reference files had already spliced the placeholder mid-sentence.- ask_instruction: "STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.",+ ask_instruction: "Ask with Codex's structured user-input/question tool when available, or directly in chat if it is not, and wait for the answer before continuing.",command_prefix: '$'},'agents': {@@ -461,7 +461,7 @@ export const PROVIDER_PLACEHOLDERS = {opencode: {model: 'Claude',config_file: 'AGENTS.md',- ask_instruction: 'STOP and call the `question` tool to clarify.',+ ask_instruction: 'Ask with the `question` tool and wait for the answer before continuing.',command_prefix: '/'},'pi': {@@ -509,7 +509,7 @@ export const PROVIDER_PLACEHOLDERS = {'grok': {model: 'Grok',config_file: 'AGENTS.md',- ask_instruction: 'STOP and call the AskUserQuestion tool to clarify.',+ ask_instruction: 'Ask with the AskUserQuestion tool and wait for the answer before continuing.',command_prefix: '/'},'antigravity': {diff --git a/skill/agents/impeccable-finish-reviewer.md b/skill/agents/impeccable-finish-reviewer.mdindex ab1afa661..d8c944313 100644--- a/skill/agents/impeccable-finish-reviewer.md+++ b/skill/agents/impeccable-finish-reviewer.md@@ -32,7 +32,7 @@ Expect: the original request; the confirmed user answers; the artifact path(s);3. **Ceiling.** Against the QUALITY BAR card: name the world's native devices the build left unused, frame, depth, lettering treatment, ornament density, motion. The card governs commitment and finish, never composition.4. **Contract, promise by promise.** First verify FORM carries the seed reference the concept roll printed (`seed:` and 16 hex), corroborated against the roll output the parent saw or with `impeccable concept-seed --check-seed <reference>` (exit 0 means this machine rolled it). A raw seed key in FORM is itself a material fix: the brief is committed, and the key must not be. `seed: none (unavailable)` stands only when the roll printed SEED REFERENCE unavailable, which `--check-seed none` confirms with exit 0. Any other contract with no reference, or one neither source corroborates, means the roll was skipped, a material fix ahead of any craft point. Then, for each of the five blocks: does the render keep the promise? Apply the memory test to the first viewport.5. **Truth.** Demonstration data authored and labeled synthetic; no invented commercial claims; unanswered claims present as marked placeholders, not omissions. Every raster region of the spec shipped as its plate (the spec names the file; the page references it; the region's diff row is not `missing`), not a gradient, an inline SVG, or a many-vertex `clip-path` standing in for it, and every produced asset visibly present in the screenshots; an asset applied at near-zero opacity or buried behind a wash is a compliance token, not a shipped material, and the detector's `buried-raster` and `organic-clip-path` findings in the packet are material fixes.-6. **Floor.** Read the craft floor's Refuse list and hold the screenshots against it: kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces, gradient text, side stripes, and the rest. A banned element is a material fix even when it matches nothing in the comp: the builder loaded the same ban before writing it, and fidelity to a comp cannot authorize what the floor refuses. The parent's hook findings cover this mechanically where hooks run; this check exists because hookless harnesses reach you with none, and the last two live sessions shipped five kickers past a reviewer that never looked.+6. **Floor.** Read the craft floor's Refuse list and hold the screenshots against it: kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces, gradient text, side stripes, and the rest. A banned element is a material fix even when it matches nothing in the comp: the builder loaded the same ban before writing it, and fidelity to a comp cannot authorize what the floor refuses. The parent's hook findings cover this mechanically where hooks run; this check exists because hookless harnesses reach you with none, and on those harnesses a banned element you miss ships.Do not run a second detector pass; mechanical findings belong to the parent's hooks.diff --git a/skill/reference/adapt.md b/skill/reference/adapt.mdindex 25a95fcf6..e6add003e 100644--- a/skill/reference/adapt.md+++ b/skill/reference/adapt.md@@ -28,7 +28,7 @@ Understand what needs adaptation and why:- What won't work? (Hover states on touch, tiny touch targets)- What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)-**CRITICAL**: Adaptation is rethinking the experience for the new context, not scaling pixels.+Adaptation is rethinking the experience for the new context, not scaling pixels.## Plan Adaptation Strategy@@ -165,9 +165,9 @@ Choose appropriate breakpoints:- Persistent side navigation on desktop- Breadcrumbs on smaller screens for context-**IMPORTANT**: Test on real devices. Device emulation in DevTools is helpful but not perfect.+Test on real devices. DevTools emulation is a useful first pass but misses real touch, performance, and browser chrome.-**NEVER**:+**Avoid**:- Hide core functionality on mobile (if it matters, make it work)- Assume desktop = powerful device (consider accessibility, older machines)- Use different information architecture across contexts (confusing)diff --git a/skill/reference/adapt.native.md b/skill/reference/adapt.native.mdindex 4307b559f..f601c33dc 100644--- a/skill/reference/adapt.native.md+++ b/skill/reference/adapt.native.md@@ -50,7 +50,7 @@ Reconform, don't reflow. Replace web navigation with the platform's model, HTML-When the adaptation feels native to each context, hand off to `{{command_prefix}}impeccable polish` for the final pass.-**NEVER**:+**Avoid**:- Ship a stretched phone layout on a tablet- Port one platform's controls or navigation onto the other- Hide core functionality on smaller devices (if it matters, make it work)diff --git a/skill/reference/audit.md b/skill/reference/audit.mdindex 25bc07787..7865aae66 100644--- a/skill/reference/audit.md+++ b/skill/reference/audit.md@@ -129,9 +129,9 @@ After presenting the summary, tell the user:>> Re-run `{{command_prefix}}impeccable audit` after fixes to see your score improve.-**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.+Keep P3s few: a long tail of minor issues buries the ones that matter.-**NEVER**:+**Avoid**:- Report issues without explaining impact (why does this matter?)- Provide generic recommendations (be specific and actionable)- Skip positive findings (celebrate what works)diff --git a/skill/reference/audit.native.md b/skill/reference/audit.native.mdindex 9a51dd8a2..b158b602f 100644--- a/skill/reference/audit.native.md+++ b/skill/reference/audit.native.md@@ -129,9 +129,9 @@ After presenting the summary, tell the user:>> Re-run `{{command_prefix}}impeccable audit` after fixes to see your score improve.-**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.+Keep P3s few: a long tail of minor issues buries the ones that matter.-**NEVER**:+**Avoid**:- Report issues without explaining impact (why does this matter?)- Provide generic recommendations (be specific and actionable)- Skip positive findings (celebrate what works)diff --git a/skill/reference/critique.md b/skill/reference/critique.mdindex a437df269..03acd2f77 100644--- a/skill/reference/critique.md+++ b/skill/reference/critique.md@@ -113,7 +113,7 @@ Codex failure accounting: final Run Notes must include target slug, ignore list,### Generate Combined Critique Report-Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives.+Synthesize both assessments into a single report. Do not simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives.The chat response is the primary user-facing deliverable. Present the full structured critique below in chat; do not replace it with a summary and a link. The persisted snapshot is an archive of that run.@@ -273,7 +273,7 @@ This is fire-and-forget. Do not show the user the helper's JSON output; only theAsk in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers.-Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions):+Ask questions along these lines (adapt to the specific findings; do not ask generic questions):1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options.diff --git a/skill/reference/distill.md b/skill/reference/distill.mdindex bc0f6e964..394dc062c 100644--- a/skill/reference/distill.md+++ b/skill/reference/distill.md@@ -23,7 +23,7 @@ Analyze what makes the design feel complex or cluttered:If any of these are unclear from the codebase, do not guess. {{ask_instruction}}-**CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence.+Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence.## Plan Simplification@@ -34,7 +34,7 @@ Create a ruthless editing strategy:- **Progressive disclosure**: What can be hidden until needed?- **Consolidation opportunities**: What can be combined or integrated?-**IMPORTANT**: Simplification is hard. It requires saying no to good ideas to make room for great execution. Be ruthless.+Expect to say no to good ideas to make room for great execution.## Simplify the Design@@ -83,7 +83,7 @@ Systematically remove complexity across these dimensions:- **Consolidate styles**: Merge similar styles, use utilities consistently- **Reduce variants**: Does that component need 12 variations, or can 3 cover 90% of cases?-**NEVER**:+**Avoid**:- Remove necessary functionality (simplicity ≠ feature-less)- Sacrifice accessibility for simplicity (clear labels and ARIA still required)- Make things so simple they're unclear (mystery ≠ minimalism)diff --git a/skill/reference/extract.md b/skill/reference/extract.mdindex 0f49cfbaa..c4d5a402f 100644--- a/skill/reference/extract.md+++ b/skill/reference/extract.md@@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and consFind the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions.-**CRITICAL**: If no design system exists, do not create one yet. {{ask_instruction}} Understand the preferred location and structure first.+If no design system exists, do not create one yet. {{ask_instruction}} Understand the preferred location and structure first.## Step 2: Identify Patterns@@ -31,7 +31,7 @@ Create a systematic plan:- **Naming conventions**: Component names, token names, prop names that match existing patterns- **Migration path**: How to refactor existing uses to consume the new shared versions-**IMPORTANT**: Design systems grow incrementally. Extract what is clearly reusable now, not everything that might someday be reusable.+Design systems grow incrementally. Extract what is clearly reusable now, not everything that might someday be reusable.## Step 4: Extract & Enrich@@ -59,7 +59,7 @@ Update design system documentation:- Add examples and guidelines- Update any Storybook or component catalog-**NEVER**:+**Avoid**:- Extract one-off, context-specific implementations without generalization- Create components so generic they are useless- Extract without considering existing design system conventionsdiff --git a/skill/reference/harden.md b/skill/reference/harden.mdindex e8a0567c5..86145c148 100644--- a/skill/reference/harden.md+++ b/skill/reference/harden.md@@ -28,7 +28,7 @@ Identify weaknesses and edge cases:- Number formats (1,000 vs 1.000)- Currency symbols-**CRITICAL**: Designs that only work with perfect data aren't production-ready. Harden against reality.+Designs that only work with perfect data aren't production-ready.## Hardening Dimensions@@ -313,9 +313,7 @@ const throttledScroll = throttle(handleScroll, 100);- Visual regression tests- Accessibility tests (axe, WAVE)-**IMPORTANT**: Hardening is about expecting the unexpected. Real users will do things you never imagined.--**NEVER**:+**Avoid**:- Assume perfect input (validate everything)- Ignore internationalization (design for global)- Leave error messages generic ("Error occurred")diff --git a/skill/reference/onboard.md b/skill/reference/onboard.mdindex e6f835b46..e1bec71d3 100644--- a/skill/reference/onboard.md+++ b/skill/reference/onboard.md@@ -23,7 +23,7 @@ Understand what users need to learn and why:- What's the key action we want them to take? (First project? First invite?)- How do we know onboarding worked? (Completion rate? Time to value?)-**CRITICAL**: Onboarding should get users to value as quickly as possible, not teach everything possible.+Onboarding should get users to value as quickly as possible, not teach everything possible.## Onboarding Principles@@ -208,9 +208,9 @@ localStorage.setItem('onboarding-completed', 'true');localStorage.setItem('feature-tooltip-seen-reports', 'true');```-**IMPORTANT**: Don't show same onboarding twice (annoying). Track completion and respect dismissals.+Show onboarding once: track completion and respect dismissals.-**NEVER**:+**Avoid**:- Force users through long onboarding before they can use product- Patronize users with obvious explanations- Show same tooltip repeatedly (respect dismissals)diff --git a/skill/reference/optimize.md b/skill/reference/optimize.mdindex 9c7bb144a..d0613371e 100644--- a/skill/reference/optimize.md+++ b/skill/reference/optimize.md@@ -17,7 +17,7 @@ Understand current performance and identify problems:- How bad is it? (Perceivable? Annoying? Blocking?)- Who's affected? (All users? Mobile only? Slow connections?)-**CRITICAL**: Measure before and after. Premature optimization wastes time. Optimize what actually matters.+Measure before and after. Optimizing without a measurement spends effort on things that do not matter.## Optimization Strategy@@ -233,9 +233,9 @@ const observer = new IntersectionObserver((entries) => {- Bundle size- Request count-**IMPORTANT**: Measure on real devices with real network conditions. Desktop Chrome with fast connection isn't representative.+Measure on real devices with real network conditions. Desktop Chrome on a fast connection isn't representative.-**NEVER**:+**Avoid**:- Optimize without measuring (premature optimization)- Sacrifice accessibility for performance- Break functionality while optimizingdiff --git a/skill/reference/quieter.md b/skill/reference/quieter.mdindex 8483d305d..a59a20bfb 100644--- a/skill/reference/quieter.md+++ b/skill/reference/quieter.md@@ -30,7 +30,7 @@ Analyze what makes the design feel too intense:If any of these are unclear from the codebase, do not guess. {{ask_instruction}}-**CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness.+"Quieter" means refined and easier on the eyes, not generic. Generic quiet looks like gray text on white, one sans at a uniform weight, and a grid of identical cards; restraint still needs a point of view.## Plan Refinement@@ -41,7 +41,7 @@ Create a strategy to reduce intensity while maintaining impact:- **Simplification approach**: What can be removed entirely?- **Sophistication approach**: How can we signal quality through restraint?-**IMPORTANT**: Subtlety requires precision. Quiet without intent collapses to generic.+Subtlety requires precision. Quiet without intent collapses to generic.## Refine the Design@@ -80,7 +80,7 @@ Systematically reduce intensity across these dimensions:- **Align to grid**: Bring rogue elements back into systematic alignment- **Even out spacing**: Replace extreme spacing variations with consistent rhythm-**NEVER**:+**Avoid**:- Make everything the same size/weight (hierarchy still matters)- Remove all color (quiet ≠ grayscale)- Eliminate all personality (maintain character through refinement)diff --git a/tests/lib/transformers/providers.test.js b/tests/lib/transformers/providers.test.jsindex f96546cb4..db9f38a39 100644--- a/tests/lib/transformers/providers.test.js+++ b/tests/lib/transformers/providers.test.js@@ -86,7 +86,7 @@ for (const [key, config] of Object.entries(PROVIDERS)) {references: [{ name: 'polish', content: 'Run `{{scripts_path}}/impeccable detect`.', filePath: '/fake/polish.md' }],}], TEST_DIR);const content = fs.readFileSync(skillPath(config, 'impeccable'), 'utf8');- expect(content).toContain('call the ask_user_question tool');+ expect(content).toContain('Ask with the ask_user_question tool');expect(content).toContain('.dsh/skills/impeccable/scripts/impeccable context');expect(parseFrontmatter(content).frontmatter['allowed-tools']).toBeUndefined();const root = path.join(TEST_DIR, 'dsh', '.dsh');diff --git a/tests/lib/utils.test.js b/tests/lib/utils.test.jsindex 93ac0a67c..6716316c9 100644--- a/tests/lib/utils.test.js+++ b/tests/lib/utils.test.js@@ -620,7 +620,7 @@ describe('replacePlaceholders', () => {test('should replace {{ask_instruction}} with provider-specific value', () => {const result = replacePlaceholders('{{ask_instruction}}', 'claude-code');- expect(result).toBe('STOP and call the AskUserQuestion tool to clarify.');+ expect(result).toBe('Ask with the AskUserQuestion tool and wait for the answer before continuing.');const cursorResult = replacePlaceholders('{{ask_instruction}}', 'cursor');expect(cursorResult).toBe('Ask the user directly to clarify what you cannot infer.');@@ -652,7 +652,7 @@ describe('replacePlaceholders', () => {test('should replace multiple placeholders in the same string', () => {const result = replacePlaceholders('{{model}} uses {{config_file}} and {{ask_instruction}}', 'claude-code');- expect(result).toBe('Claude uses CLAUDE.md and STOP and call the AskUserQuestion tool to clarify.');+ expect(result).toBe('Claude uses CLAUDE.md and Ask with the AskUserQuestion tool and wait for the answer before continuing.');});test('should replace multiple occurrences of the same placeholder', () => {