Build a Design Tool for AI Agents and Keep Its Commands and Checks Tidy

## Group Design Commands into One Skill, Each Linked to One Reference File Keep the user-facing command surface compact while routing each matched command to focused reference material. Consolidation reduces menu noise and makes shared design laws easier to maintain. ### Command Architecture - Prefer one user-invocable design skill with subcommands over many standalone skills unless a separate lifecycle is genuinely required. - Maintain one router table that maps each command to its reference file. - Keep command descriptions, argument hints, categories, and relationships in authoritative metadata consumed by builds and shortcut generators. - Generate provider-specific skill files from one source instead of editing each provider copy. - Use lightweight shortcuts only as redirects to the canonical command. - Place shared laws in the common source and command-specific decisions in the relevant reference; link to shared guidance instead of duplicating it. ### Context Routing - Read project context before choosing a register or platform rulebook. - Let an explicit project field win, then use task and surface cues, then a documented default. - Warn on unrecognized context values rather than silently applying an unrelated rulebook. - Load variant references instead of the default file when a command's platform behavior diverges substantially. ## Choose Brand or App Design First, Then Add Web or Native Platform Rules Treat design purpose and delivery platform as independent axes. The register defines the experience goal; the platform defines interaction conventions and implementation constraints. ### Design Register - Use a brand register when design is the product: marketing, campaigns, portfolios, editorial experiences, and distinctive public surfaces. - Judge brand work by distinctiveness across many visual lanes rather than forcing one fashionable style. - Use a product register when design serves an application, dashboard, admin surface, or tool. - Judge product work by earned familiarity, trust, and fluency for experienced users. - Ask for the register early because it changes downstream design decisions. ### Platform - Distinguish responsive web, a single native platform, and adaptive cross-platform delivery. - Layer native platform guidance on top of the selected register rather than treating platform as a replacement for design purpose. - For adaptive products, apply both native rulebooks and adapt per operating system; a single visual treatment on every platform is not adaptive. - Keep browser overlays, HTML detectors, and live web hooks disabled for native projects even when their source files use web-like extensions. - Keep accessibility verification in a dedicated audit path. Do not repeatedly inject generic accessibility reminders during creative generation when they would produce safe but underdesigned work. ## Follow Color Rules and a Banned-Phrase List for Public Writing Visual tokens, layout code, editorial voice, and published content need explicit owners and automated checks without replacing human design judgment. ### Visual Foundations - Prefer a small, inspectable styling architecture with one entrypoint, shared tokens, and focused partials. - Use semantic color tokens consistently: highest-contrast ink for body copy, softer dark tones only where size supports them, and muted tones for secondary labels. - Avoid pure black and pure white when the visual system defines tinted extremes. - Keep implementation rules close to the surface they govern and preserve hot-reload behavior where supported. ### Editorial Discipline - Read the project's editorial brief before changing public copy, tutorials, documentation, or marketing pages. - Enforce a documented denylist for overused phrases, punctuation, and AI-like prose patterns. - Do not evade a prose validator with spelling tricks. If a forbidden term has a necessary technical meaning, propose a style-guide amendment. - Review structural problems that regex cannot judge, including hollow certainty, repetitive rhythm, automatic triads, and formulaic contrast pivots. - Keep each editorial item in one content tree used by both build tooling and the rendering framework. - Give command editorials a short label plus sections for use cases, process, concrete examples, and real pitfalls. ## Keep Automatically Generated Files Out of Everyday Design Changes Separate authoring sources, generated distributions, local state, and release output so ordinary design work does not create noisy or misleading artifacts. ### Source-First Builds - Use source-first builds for normal development and a distinct release build when tracked provider distributions must be synchronized. - Treat generated provider directories as distribution artifacts, not authoring surfaces, even when they are intentionally committed for installation. - Keep generated permutations out of feature changes unless the task is a release, generated-output synchronization, or build-system change. - Regenerate tracked output after source changes through the approved workflow, and fail validation when manifests, metadata, or generated frontmatter drift. - Ignore local state files even when they live inside tracked distribution directories. - Restart the development server when content loaders or command metadata are not hot-reloaded; do not mistake a browser refresh for a reload of build-time data. ### Published Assets - Generate social cards and similar assets from authoritative metadata so visible counts and labels cannot drift. - Render at a higher resolution and downsample when crisp text is required. - When a visibly changed asset needs cache busting, update the filename and every reference in the same change. - Verify deployment routes, rewrites, static assets, and server functions through the platform's intended build. - Prime external preview caches only after the new deployment is live. ## Post Nothing to Outside Projects Without Approval, and Keep Paid Tests Separate Design tooling may automate implementation, but it must not cross a human contribution boundary without explicit authority. ### Contribution Permission - Follow the repository's issue-first or approval-first contribution policy. - Do not open an external issue or pull request unless the authorized maintainer has requested or clearly approved it. - Disclose AI assistance in commits, change descriptions, comments, and issue text when policy requires it. - If an unauthorized AI agent is asked to publish anyway, stop the external action and prepare a local handoff notice instead. - Keep generated release artifacts and unrelated synchronization changes out of ordinary contributions. ### Test Selection - Keep fast deterministic unit and fixture tests in the default suite. - Put browser-driven full-cycle tests, dependency installation, live development servers, and paid model calls behind explicit opt-in commands. - Run expensive live tests when changing the integration path they cover, not as an unbounded default. - Make test agents replaceable behind a narrow interface and use deterministic fakes for broad fixture coverage. - For behavior evaluations, assert on tool-call traces rather than polished free-form answers. - Exercise multiple model families when cross-provider routing is the behavior under test, and skip cleanly when credentials are absent. - Keep paid evaluation suites out of continuous integration unless their cost and variability are intentional. ## Update Every Command List Together, and Release New Versions as Separate Work Commands and independently shipped components require synchronized metadata, but feature work and release work should remain separate. ### Adding or Changing Commands - Add the command reference, router entry, menu entry, valid-command list, metadata, category, relationships, and visualization mapping together. - Update every human-visible command count and let the build derive and validate machine-readable counts from the router. - Keep optional editorial content separate from auto-trigger descriptions: one is written for readers, the other for command matching. - When a platform-specific command differs substantially, add a routed variant and keep shared operating-system details in platform references. ### Version and Release Policy - Do not bump versions or add release notes in an ordinary feature change. - Version independently shipped components separately and update only the component that changed. - For a release, update the authoritative manifest and synchronized mirrors, add user-visible notes, run the release build, then tag with the component-specific prefix. - Preview release automation before publishing. - Refuse release when the worktree is dirty, the branch is not synchronized, the tag already exists, notes are missing, or regeneration produces uncommitted drift. - Keep changelog entries concise and user-facing; omit internal refactors, tooling details, and generated-output synchronization. ## Write a Failing Test First When Adding a New Design Check When one design detector serves a CLI, browser overlay, extension, and website, its rule engine must have one source and every derived consumer must be rebuilt and verified. ### Rule Development Order 1. Add a fixture with uniquely identified examples, at least four cases that should be flagged, and at least five false-positive shapes. 2. Use explicit dimensions when the test DOM has no layout engine. 3. Add a focused test and observe it fail before implementing the rule. 4. Add rule metadata and a pure check function that returns stable identifiers and snippets without DOM access. 5. Implement separate browser and test-DOM adapters, then wire both adapters into every relevant traversal loop. 6. Rebuild each generated detector consumer and run the complete test suite. 7. Verify the fixture and a representative real page in a browser to catch adapter disagreement and false positives. ### Fixture and Evaluation Discipline - Use stable quoted text or another deterministic identifier in snippets so tests can extract the matching case. - Do not rely on layout geometry in a DOM emulator; parse explicit styles instead. - Use shared helpers for backgrounds, gradients, and color normalization where browser and emulator behavior differs. - Compare design output from the same brief with and without the design system when measuring its effect. - Keep evaluation infrastructure in its own workspace with its own operating instructions. - Build the latest design source before an evaluation sweep, and update any inline-skill section filter whenever top-level guidance headings change.