@dittowords/spec-cli 0.0.1-alpha.6 → 0.0.1-alpha.8

package/README.md

@@ -37,12 +37,29 @@ surfaces:
 rules:
   - name: Confirmation dialogs should be direct
     description: Keep confirmation copy terse and unambiguous
+    styleguide: Acme Inc.
+    section: Voice & Tone
   - surface: actionText
     name: Calls to action should use active voice
     description: Always lead with a verb
     examples:
       - from: "Your settings"
         to: "Open settings"
+    styleguide: Acme Inc.
+    section: Voice & Tone
+  - term: sign up
+    disallowed:
+      - signup
+      - sign-up
+    description: Always use as two words (verb form)
+    styleguide: Acme Inc.
+    section: Terminology
+locales:
+  de-DE:
+    - name: Use informal address
+      description: Use "Du" instead of "Sie" for all user-facing copy
+      styleguide: German
+      section: Formality
 ---
 ```
 
@@ -55,7 +72,17 @@ A repo may have a single `workspace.ditto.md` somewhere under the CLI's configur
 workspace: true
 # Managed by Ditto — do not edit below
 tags: [body, button, call-to-action, dialog-title, heading, nav]
-rules: []
+rules:
+  - name: Write in active voice
+    description: Lead with verbs, avoid passive constructions
+    styleguide: Acme Inc.
+    section: Voice & Tone
+locales:
+  de-DE:
+    - name: Use informal address
+      description: Use "Du" instead of "Sie" for all user-facing copy
+      styleguide: German
+      section: Formality
 ---
 ```
 
@@ -63,7 +90,7 @@ rules: []
 
 **Developer-owned keys**: `component`, `tags`, `surfaces`. Edit these freely.
 
-**CLI-managed keys**: `rules` and workspace `tags`. Overwritten by `ditto-spec pull`. Do not edit by hand.
+**CLI-managed keys**: `rules`, `locales`, and workspace `tags`. Overwritten by `ditto-spec pull`. Do not edit by hand. Rules come in two shapes: style rules (`name`/`description`/`examples`) and terminology entries (`term`/`disallowed`/`description`).
 
 **Surface keys** identify each distinct piece of user-facing text the component renders. For text passed as props, use the prop path as the key — dot-notation works for nested props (e.g., `primaryAction.label`). Use `$children` for text via the `children` prop. For hardcoded or internal strings, use a descriptive role name (e.g., `headline`, `bodyText`, `submitLabel`).
 
@@ -71,13 +98,16 @@ rules: []
 
 **`maxLength` / `minLength`** are hard layout constraints, not stylistic preferences. Stylistic guidance belongs on the platform as rules.
 
-### Three-level rule hierarchy
+### Rule hierarchy
 
 | Scope | Where | Applies to |
 |---|---|---|
 | **Workspace** | `workspace.ditto.md` `rules[]` | Every surface in every component |
 | **Component-level** | Component's `rules[]`, no `surface` field | Every surface in this component |
 | **Per-surface** | Component's `rules[]`, with `surface: "<key>"` | That one surface |
+| **Locale-scoped** | `locales.<code>[]` (workspace or component) | Same hierarchy as above, but only when writing copy for that locale |
+
+Base rules in `rules` always apply. Locale-scoped rules in `locales` apply only when writing copy for the matching locale — they never conflict with each other because each locale is a separate scope.
 
 ## CLI commands
 
@@ -102,9 +132,11 @@ Use `--path <dir>` to specify where the file is created (defaults to the current
 Syncs rules from the platform into spec files.
 
 1. Discovers all `.ditto.md` files under configured roots
-2. Fetches all workspace rules from `GET /v2/rules/mcp`
-3. Matches rules to specs by tag intersection (client-side)
-4. Rewrites the `rules` key in each file's YAML frontmatter
+2. Fetches style guides from `GET /v2/styleguides`
+3. Flattens rules and wordlist entries across all guides (or only those named in `styleguides` config)
+4. Separates base rules from locale-scoped rules (included when `locales` is configured)
+5. Matches rules to specs by tag intersection (client-side)
+6. Rewrites the `rules` and `locales` keys in each file's YAML frontmatter
 
 Use `--dry-run` to see what would change without writing.
 
@@ -133,6 +165,8 @@ Create `dittospec.config.json` at your repo root (or any ancestor directory):
 | `apiBase` | Ditto API base URL |
 | `workspaceId` | Your workspace ID |
 | `roots` | Repo-relative directories to search for `.ditto.md` files. Defaults to `["."]`. |
+| `styleguides` | Optional list of style guide names to pull. Defaults to all. |
+| `locales` | Optional list of locale codes (e.g. `["de-DE", "fr-FR"]`). Includes locale-scoped style guides matching these codes. Base (no-variant) guides are always included. |
 
 Set `DITTO_API_KEY` in your environment or in a `.env` file at the repo root.
 
@@ -144,7 +178,11 @@ When writing or editing user-facing text for a component:
 2. Read the component's `index.ditto.md`. Match each piece of text you're writing to a surface key.
 3. Respect `maxLength` — it's a layout invariant, not a suggestion.
 4. Follow all rules in `rules[]`. Entries without `surface` apply to every surface; entries with `surface` apply only to that surface.
-5. When a rule includes `examples`, reference them as concrete tone/shape guidance.
+5. Rules come in two shapes:
+   - **Style rules** have `name`, `description`, and optional `examples` (before/after pairs). Use `examples` as concrete tone/shape guidance.
+   - **Terminology entries** have `term` and `disallowed`. Always use the `term` form; never use any of the `disallowed` alternatives.
+6. Each rule carries `styleguide` and `section` metadata indicating its source on the platform.
+7. If a `locales` key is present, it contains locale-scoped rules keyed by locale code (e.g. `de-DE`). When writing copy for a specific locale, follow the matching `locales.<code>` rules **in addition to** the base `rules`. When writing for the default/base locale, only follow `rules`. Locale-scoped rules never conflict — each locale is a separate boundary.
 
 ### Creating specs
 

package/dist/api.d.ts

@@ -1,7 +1,11 @@
 import type { Config } from "./config";
-export interface RuleResponse {
+export interface StyleguideVariant {
+    id: string;
+    name: string;
+    localeCode: string | null;
+}
+export interface StyleRule {
     name: string;
-    type: "style" | "wordlist";
     description: string;
     examples: {
         from: string;
@@ -9,11 +13,51 @@ export interface RuleResponse {
     }[];
     tags: string[];
 }
+export interface WordlistEntry {
+    term: string;
+    disallowed: string[];
+    description: string;
+    tags: string[];
+}
+export interface StyleguideSection {
+    name: string;
+    kind: "rules" | "wordlist";
+    rules: StyleRule[] | WordlistEntry[];
+}
+export interface Styleguide {
+    name: string;
+    description: string;
+    variant: StyleguideVariant | null;
+    sections: StyleguideSection[];
+}
+export type FlatRule = {
+    kind: "style";
+    styleguide: string;
+    section: string;
+    localeCode: string | null;
+    name: string;
+    description: string;
+    examples: {
+        from: string;
+        to: string;
+    }[];
+    tags: string[];
+} | {
+    kind: "wordlist";
+    styleguide: string;
+    section: string;
+    localeCode: string | null;
+    term: string;
+    disallowed: string[];
+    description: string;
+    tags: string[];
+};
+export declare function flattenStyleguides(guides: Styleguide[], filter?: string[]): FlatRule[];
 export declare class DittoApi {
     private readonly config;
     private readonly apiKey;
     constructor(config: Config, apiKey: string);
-    getRules(): Promise<RuleResponse[]>;
+    getStyleguides(): Promise<Styleguide[]>;
     private fetch;
     private headers;
 }

package/dist/api.js

@@ -1,16 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DittoApi = void 0;
+exports.flattenStyleguides = flattenStyleguides;
+function flattenStyleguides(guides, filter) {
+    const selected = filter?.length ? guides.filter((g) => filter.includes(g.name)) : guides;
+    const result = [];
+    for (const guide of selected) {
+        for (const section of guide.sections) {
+            if (section.kind === "rules") {
+                for (const rule of section.rules) {
+                    result.push({
+                        kind: "style",
+                        styleguide: guide.name,
+                        section: section.name,
+                        localeCode: guide.variant?.localeCode ?? null,
+                        name: rule.name,
+                        description: rule.description,
+                        examples: rule.examples,
+                        tags: rule.tags,
+                    });
+                }
+            }
+            else {
+                for (const entry of section.rules) {
+                    result.push({
+                        kind: "wordlist",
+                        styleguide: guide.name,
+                        section: section.name,
+                        localeCode: guide.variant?.localeCode ?? null,
+                        term: entry.term,
+                        disallowed: entry.disallowed,
+                        description: entry.description,
+                        tags: entry.tags,
+                    });
+                }
+            }
+        }
+    }
+    return result;
+}
 class DittoApi {
     constructor(config, apiKey) {
         this.config = config;
         this.apiKey = apiKey;
     }
-    async getRules() {
-        const url = new URL("/v2/rules/mcp", this.config.apiBase);
+    async getStyleguides() {
+        const url = new URL("/v2/styleguides", this.config.apiBase);
         const res = await this.fetch(url, { method: "GET" });
         const data = (await res.json());
-        return data.workspaceRules;
+        return data.styleguides;
     }
     async fetch(url, init) {
         const res = await fetch(url.toString(), {

package/dist/commands/create-rule.d.ts

@@ -0,0 +1,8 @@
+interface CreateRuleOptions {
+    name: string;
+    description: string;
+    tags?: string;
+    examples?: string;
+}
+export declare function createRule(opts: CreateRuleOptions): Promise<void>;
+export {};

package/dist/commands/create-rule.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRule = createRule;
+const api_1 = require("../api");
+const config_1 = require("../config");
+async function createRule(opts) {
+    const { config } = (0, config_1.loadConfig)();
+    const apiKey = (0, config_1.getApiKey)();
+    const api = new api_1.DittoApi(config, apiKey);
+    if (!config.styleguideId) {
+        throw new Error('No "styleguideId" in dittospec.config.json. Add the ID of the style guide you want rules created in.');
+    }
+    const info = await api.getStyleguideInfo();
+    if (!info) {
+        throw new Error("Could not discover style guide sections. Check that your workspace has at least one style guide with rules.");
+    }
+    const sectionId = info.sectionId;
+    let examples;
+    if (opts.examples) {
+        try {
+            examples = JSON.parse(opts.examples);
+        }
+        catch {
+            throw new Error('--examples must be valid JSON, e.g. \'[{"from":"bad","to":"good"}]\'');
+        }
+    }
+    const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()).filter(Boolean) : undefined;
+    const result = await api.createRule({
+        styleguideId: config.styleguideId,
+        sectionId,
+        name: opts.name,
+        description: opts.description,
+        examples,
+        tags,
+    });
+    console.log(`✓ Created rule "${result.name}" (${result.id})`);
+}

package/dist/commands/init.js

@@ -42,6 +42,9 @@ When writing or editing text props for a component:
 2. Check for ${c("index.ditto.md")} next to the component for surface-specific rules and constraints.
 3. Respect ${c("maxLength")} — it's a layout constraint, not a suggestion.
 4. Follow all rules in the ${c("rules")} key. Rules without a ${c("surface")} field apply to every surface; rules with ${c("surface")} apply only to that surface.
+5. Rules come in two shapes: style rules (${c("name")}, ${c("description")}, ${c("examples")}) and terminology entries (${c("term")}, ${c("disallowed")}). For terminology entries, always use the ${c("term")} form and never use the ${c("disallowed")} alternatives.
+6. Each rule carries ${c("styleguide")} and ${c("section")} metadata indicating its source.
+7. If a ${c("locales")} key is present, it contains locale-scoped rules keyed by locale code. When writing copy for a specific locale, follow the matching locale's rules in addition to the base ${c("rules")}. When writing for the default locale, only follow ${c("rules")}.
 
 ${h3} Creating specs
 

package/dist/commands/pull.js

@@ -44,53 +44,65 @@ async function pull(opts = {}) {
         const paths = workspaceFiles.map((w) => path_1.default.relative(root, w.file.abs)).join(", ");
         throw new Error(`Found multiple workspace specs (${paths}). Expected at most one.`);
     }
-    const allRules = await api.getRules();
-    console.log(`Fetched ${allRules.length} rule${allRules.length === 1 ? "" : "s"} from workspace.`);
-    const platformTags = [...new Set(allRules.flatMap((r) => r.tags))].filter(Boolean).sort();
+    const guides = await api.getStyleguides();
+    const allRules = (0, api_1.flattenStyleguides)(guides, config.styleguides);
+    const baseRules = allRules.filter((r) => r.localeCode === null);
+    const configuredLocales = config.locales ?? [];
+    const localeRules = configuredLocales.length > 0
+        ? allRules.filter((r) => r.localeCode !== null && configuredLocales.includes(r.localeCode))
+        : [];
+    const localeGroups = groupByLocale(localeRules);
+    const activeRules = [...baseRules, ...localeRules];
+    console.log(`Fetched ${activeRules.length} rule${activeRules.length === 1 ? "" : "s"} from ${guides.length} style guide(s).`);
+    const platformTags = [...new Set(activeRules.flatMap((r) => r.tags))].filter(Boolean).sort();
     let written = 0;
     let unchanged = 0;
     if (workspaceFiles.length === 1) {
         const { file, parsed } = workspaceFiles[0];
-        const universalRules = allRules.filter((r) => r.tags.length === 0).map(toRuleObj);
-        if (rulesMatch(parsed.spec.rules, universalRules) && tagsMatch(parsed.spec.tags, platformTags)) {
+        const universalBaseRules = baseRules.filter((r) => r.tags.length === 0).map(toRuleObj);
+        const universalLocales = {};
+        for (const [code, rules] of localeGroups) {
+            const universal = rules.filter((r) => r.tags.length === 0).map(toRuleObj);
+            if (universal.length > 0)
+                universalLocales[code] = universal;
+        }
+        if (jsonMatch(parsed.spec.rules, universalBaseRules) &&
+            jsonMatch(parsed.spec.tags, platformTags) &&
+            jsonMatch(parsed.spec.locales, Object.keys(universalLocales).length > 0 ? universalLocales : undefined)) {
             unchanged++;
         }
         else if (opts.dryRun) {
-            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${universalRules.length} workspace rule(s), ${platformTags.length} tag(s))`);
+            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${universalBaseRules.length} workspace rule(s), ${platformTags.length} tag(s), ${Object.keys(universalLocales).length} locale(s))`);
         }
         else {
-            (0, serialize_1.rewriteManagedKeys)(file.abs, { tags: platformTags, rules: universalRules });
+            (0, serialize_1.rewriteManagedKeys)(file.abs, { tags: platformTags, rules: universalBaseRules, locales: universalLocales });
             written++;
-            console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${universalRules.length} workspace rule(s), ${platformTags.length} tag(s)`);
+            console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${universalBaseRules.length} workspace rule(s), ${platformTags.length} tag(s), ${Object.keys(universalLocales).length} locale(s)`);
         }
     }
     for (const { file, parsed } of componentFiles) {
         const specLike = parsed.spec;
         const componentTags = specLike.tags ?? [];
         const surfaces = specLike.surfaces ?? {};
-        const componentMatches = rulesForTags(allRules, componentTags);
-        const consumed = new Set(componentMatches);
-        const matchedRules = [];
-        for (const rule of componentMatches) {
-            matchedRules.push(toRuleObj(rule));
-        }
-        for (const [surfaceKey, surface] of Object.entries(surfaces)) {
-            const matches = rulesForTags(allRules, surface.tags ?? []).filter((r) => !consumed.has(r));
-            for (const rule of matches) {
-                matchedRules.push(toSurfaceRuleObj(surfaceKey, rule));
-            }
+        const matchedBaseRules = matchRulesForSpec(baseRules, componentTags, surfaces);
+        const matchedLocales = {};
+        for (const [code, rules] of localeGroups) {
+            const matched = matchRulesForSpec(rules, componentTags, surfaces);
+            if (matched.length > 0)
+                matchedLocales[code] = matched;
         }
-        if (rulesMatch(parsed.spec.rules, matchedRules)) {
+        if (jsonMatch(parsed.spec.rules, matchedBaseRules) &&
+            jsonMatch(parsed.spec.locales, Object.keys(matchedLocales).length > 0 ? matchedLocales : undefined)) {
             unchanged++;
             continue;
         }
         if (opts.dryRun) {
-            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${matchedRules.length} rule(s))`);
+            console.log(`~ ${path_1.default.relative(root, file.abs)} (would write ${matchedBaseRules.length} rule(s), ${Object.keys(matchedLocales).length} locale(s))`);
             continue;
         }
-        (0, serialize_1.rewriteManagedKeys)(file.abs, { rules: matchedRules });
+        (0, serialize_1.rewriteManagedKeys)(file.abs, { rules: matchedBaseRules, locales: matchedLocales });
         written++;
-        console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${matchedRules.length} rule(s)`);
+        console.log(`✓ ${path_1.default.relative(root, file.abs)} — ${matchedBaseRules.length} rule(s), ${Object.keys(matchedLocales).length} locale(s)`);
     }
     console.log(`\nDone. ${written} updated, ${unchanged} unchanged.`);
     if (failed > 0) {
@@ -98,6 +110,31 @@ async function pull(opts = {}) {
         process.exit(1);
     }
 }
+function matchRulesForSpec(rules, componentTags, surfaces) {
+    const componentMatches = rulesForTags(rules, componentTags);
+    const consumed = new Set(componentMatches);
+    const matched = [];
+    for (const rule of componentMatches) {
+        matched.push(toRuleObj(rule));
+    }
+    for (const [surfaceKey, surface] of Object.entries(surfaces)) {
+        const surfaceMatches = rulesForTags(rules, surface.tags ?? []).filter((r) => !consumed.has(r));
+        for (const rule of surfaceMatches) {
+            matched.push(toSurfaceRuleObj(surfaceKey, rule));
+        }
+    }
+    return matched;
+}
+function groupByLocale(rules) {
+    const groups = new Map();
+    for (const rule of rules) {
+        const code = rule.localeCode;
+        if (!groups.has(code))
+            groups.set(code, []);
+        groups.get(code).push(rule);
+    }
+    return groups;
+}
 function rulesForTags(rules, tags) {
     if (tags.length === 0)
         return [];
@@ -105,21 +142,28 @@ function rulesForTags(rules, tags) {
     return rules.filter((r) => r.tags.length > 0 && r.tags.some((t) => tagSet.has(t)));
 }
 function toRuleObj(rule) {
-    const out = {
-        name: rule.name,
-        description: rule.description,
-    };
-    if (rule.examples.length > 0) {
-        out.examples = rule.examples.map((ex) => ({ from: ex.from, to: ex.to }));
+    const out = {};
+    if (rule.kind === "wordlist") {
+        out.term = rule.term;
+        out.disallowed = rule.disallowed;
+        if (rule.description)
+            out.description = rule.description;
     }
+    else {
+        out.name = rule.name;
+        if (rule.description)
+            out.description = rule.description;
+        if (rule.examples.length > 0) {
+            out.examples = rule.examples.map((ex) => ({ from: ex.from, to: ex.to }));
+        }
+    }
+    out.styleguide = rule.styleguide;
+    out.section = rule.section;
     return out;
 }
 function toSurfaceRuleObj(surface, rule) {
     return { surface, ...toRuleObj(rule) };
 }
-function rulesMatch(existing, incoming) {
-    return JSON.stringify(existing ?? []) === JSON.stringify(incoming);
-}
-function tagsMatch(existing, incoming) {
-    return JSON.stringify(existing ?? []) === JSON.stringify(incoming);
+function jsonMatch(existing, incoming) {
+    return JSON.stringify(existing ?? undefined) === JSON.stringify(incoming ?? undefined);
 }

package/dist/config.d.ts

@@ -2,6 +2,8 @@ export interface Config {
     apiBase: string;
     workspaceId: string;
     roots?: string[];
+    styleguides?: string[];
+    locales?: string[];
 }
 export declare class ConfigNotFoundError extends Error {
     constructor(cwd: string);

package/dist/config.js

@@ -54,6 +54,20 @@ function validate(c, source) {
             throw new Error(`${source}: every entry in "roots" must be a string.`);
         }
     }
+    if (obj.styleguides !== undefined) {
+        if (!Array.isArray(obj.styleguides))
+            throw new Error(`${source}: "styleguides" must be an array of strings if present.`);
+        if (obj.styleguides.some((s) => typeof s !== "string")) {
+            throw new Error(`${source}: every entry in "styleguides" must be a string.`);
+        }
+    }
+    if (obj.locales !== undefined) {
+        if (!Array.isArray(obj.locales))
+            throw new Error(`${source}: "locales" must be an array of strings if present.`);
+        if (obj.locales.some((l) => typeof l !== "string")) {
+            throw new Error(`${source}: every entry in "locales" must be a string.`);
+        }
+    }
 }
 function getApiKey() {
     try {

package/dist/serialize.d.ts

@@ -1,4 +1,5 @@
 export declare function rewriteManagedKeys(filePath: string, updates: {
     tags?: string[];
     rules?: unknown[];
+    locales?: Record<string, unknown[]>;
 }): void;

package/dist/serialize.js

@@ -14,12 +14,29 @@ function rewriteManagedKeys(filePath, updates) {
     const spec = js_yaml_1.default.load(frontmatterYaml);
     if (updates.tags !== undefined) {
         const savedRules = spec.rules;
+        const savedLocales = spec.locales;
         delete spec.rules;
+        delete spec.locales;
         spec.tags = updates.tags;
         spec.rules = savedRules;
+        if (savedLocales !== undefined)
+            spec.locales = savedLocales;
     }
-    if (updates.rules !== undefined)
+    if (updates.rules !== undefined) {
+        const savedLocales = spec.locales;
+        delete spec.locales;
         spec.rules = updates.rules;
+        if (savedLocales !== undefined)
+            spec.locales = savedLocales;
+    }
+    if (updates.locales !== undefined) {
+        if (Object.keys(updates.locales).length > 0) {
+            spec.locales = updates.locales;
+        }
+        else {
+            delete spec.locales;
+        }
+    }
     let dumped = js_yaml_1.default
         .dump(spec, {
         lineWidth: -1,

package/dist/skill-content.d.ts

@@ -0,0 +1 @@
+export declare const SPEC_COMPONENT_SKILL = "---\ndescription: Analyze a component, create ditto specs for it and its dependencies, identify rule gaps, and audit copy\nargument-hint: <ComponentName or path/to/component>\nallowed-tools: [Read, Bash, Edit, Write, Grep, Glob, Agent]\n---\n\n# Spec Component\n\nAnalyze a design system component, scaffold `.ditto.md` content specs (including child components that lack specs), auto-fill surfaces and tags, identify style guide rule gaps from real code usage, create new rules on the platform, and audit copy compliance.\n\n## Input\n\n$ARGUMENTS\n\nAccept either a component name (e.g. `Button`) or a file path (e.g. `src/components/Button/index.tsx`). If a name is given, search the codebase to find the component. If multiple matches exist, ask the user to clarify.\n\n---\n\n## Phase 1: Discovery\n\nFind the target component and map its dependencies.\n\n1. Locate the component source file.\n2. Read the component code. Walk imports to find **child components that render user-facing text** (components that accept string props, children rendered as text, or contain hardcoded strings). Skip utility imports, style imports, icon imports, and non-text components.\n3. Check which components already have an `index.ditto.md` spec by looking for the file in each component's directory.\n4. Read `workspace.ditto.md` at the project root (if it exists) for existing platform tags and universal rules.\n5. Report:\n   - Target component and its location\n   - Child components needing specs (no existing `index.ditto.md`)\n   - Existing specs found (already covered)\n\n---\n\n## Phase 2: Surface Analysis\n\nFor each component that needs a new spec (target + unspecced children):\n\n1. Read the TypeScript interface / props type definition.\n2. Identify every **text surface** \u2014 each piece of user-facing copy the component renders:\n   - **String props** rendered in JSX \u2192 use the prop name as the surface key\n   - **`children`** when used as text \u2192 use `$children` as the surface key\n   - **Nested props** \u2192 use dot notation (e.g. `primaryAction.label`)\n   - **Hardcoded strings** in JSX \u2192 use a descriptive role name (e.g. `headline`, `submitLabel`, `bodyText`)\n3. For each surface, suggest **tags** from the `workspace.ditto.md` tag inventory, matched by semantic role (e.g. `heading`, `body`, `button`, `call-to-action`). Prefer reusing existing tags. Only propose a new tag if nothing fits \u2014 and note it will be new.\n4. Estimate **`maxLength`** where layout context provides constraints (e.g. single-line headings, button widths). Omit if no clear constraint.\n\nPresent the proposed spec for each component in exact YAML format:\n\n```yaml\n---\ncomponent: ComponentName\ntags: [relevant-tags]\nsurfaces:\n  surfaceKey:\n    tags: [semantic-tags]\n    maxLength: 60\n# Managed by Ditto \u2014 do not edit below\nrules: []\n---\n```\n\n**STOP HERE. Ask the user to review and approve the proposed surfaces before creating any files.** Let them add, remove, or modify surfaces and tags.\n\n---\n\n## Phase 3: Create Specs\n\nAfter user approval:\n\n1. For each component, run:\n   ```\n   npx ditto-spec scaffold <ComponentName> --path <component-directory>\n   ```\n2. Edit each created `index.ditto.md` to replace the empty `surfaces: {}` and `tags: []` with the approved values. Only edit developer-owned keys (`component`, `tags`, `surfaces`). Never write `rules` by hand.\n3. Run `npx ditto-spec pull` to populate the `rules` section from the platform.\n4. Run `npx ditto-spec check` to validate all spec files.\n\nReport which specs were created and how many rules were pulled.\n\n---\n\n## Phase 4: Rule Gap Analysis\n\nIdentify copy patterns that should be rules but aren't.\n\n1. Read all rules now in the spec files (workspace-level from `workspace.ditto.md` + component-level and per-surface from each `index.ditto.md`).\n2. Search the codebase for **instances where the target component is used** \u2014 find all files that import and render it.\n3. For each usage instance, read the **actual copy** being passed to the component's text surfaces (string literals, template strings, variables with obvious values).\n4. Analyze the copy across instances for patterns no existing rule covers:\n   - Inconsistent terminology across instances\n   - Tone mismatches (e.g. some formal, some casual)\n   - Anti-patterns: passive voice in CTAs, overly long descriptions, redundant words\n   - Surface-specific conventions that should be formalized (e.g. \"all action buttons start with a verb\")\n5. If **no meaningful gaps** are found, say so and skip to Phase 6.\n6. If gaps are found, propose new rules. For each:\n   - **name**: short rule name\n   - **description**: what the rule enforces\n   - **tags**: which tags it should apply to (determines which surfaces it matches)\n   - **examples**: `{from, to}` pairs drawn from actual code showing the pattern\n\nIf any proposed tags don't exist in the workspace yet, warn the user. Currently, only existing workspace tags can be assigned to rules. New tags may need to be created on the platform first.\n\n**STOP HERE. Present proposals and ask the user which rules (if any) to create.**\n\n---\n\n## Phase 5: Create Rules and Re-Pull\n\nFor each approved rule:\n\n1. Run:\n   ```\n   npx ditto-spec create-rule --name \"<rule name>\" --description \"<description>\" --tags \"<tag1,tag2>\" --examples '<json array of {from,to}>'\n   ```\n   If a rule uses tags that don't exist yet, warn the user and omit those tags from the command (the API rejects unknown tags).\n\n2. After all rules are created, run `npx ditto-spec pull` to sync the new rules into spec files.\n\n3. Verify the specs now contain the expected rules by reading the updated `index.ditto.md` files.\n\n---\n\n## Phase 6: Copy Audit\n\nEvaluate all component instances against the full rule set.\n\n1. Re-read the fully-populated spec files (workspace + component + surface rules).\n2. Find all instances of the component in the codebase.\n3. For each instance, evaluate the actual copy against every applicable rule:\n   - Workspace rules apply to all surfaces\n   - Component-level rules (no `surface` field) apply to all surfaces\n   - Per-surface rules (with `surface` field) apply only to that surface\n   - Respect `maxLength` constraints \u2014 flag any text that exceeds the limit\n4. Report violations:\n   - File and line where the instance appears\n   - The text that violates the rule\n   - Which rule is violated\n   - Suggested corrected copy\n\n---\n\n## Reference: Ditto Spec Conventions\n\nThese conventions are essential for creating correct specs:\n\n- **Surface keys**: prop name for props, `$children` for children text, dot-notation for nested props (`primaryAction.label`), descriptive role for hardcoded strings (`headline`, `bodyText`).\n- **Tags**: lowercase, hyphenated. Match semantic role (e.g. `heading`, `body`, `button`, `call-to-action`, `dialog-title`). Check `workspace.ditto.md` `tags` key for the full inventory.\n- **Developer-owned keys**: `component`, `tags`, `surfaces` \u2014 edit freely.\n- **CLI-managed keys**: `rules` (and workspace `tags`) \u2014 **never write by hand**. Populated by `ditto-spec pull`.\n- **Three-level rule hierarchy**: workspace rules (apply everywhere) \u2192 component-level rules (no `surface` field, apply to all surfaces in that component) \u2192 per-surface rules (with `surface: \"<key>\"`, apply only to that surface).\n- **Parent-child layering**: if a parent component passes text to a child (e.g. a label to a Button), the parent declares a surface in its own spec. Both parent and child rules apply \u2014 the parent's rules (e.g. dialog-level tone) layer with the child's rules (e.g. button-level constraints). A child having its own spec does NOT exempt the parent from declaring surfaces for text it provides.\n- **Tag matching**: rules match specs by tag intersection. Any shared tag triggers the match. If a rule matches both component-level and surface-level tags, it emits at component level (broader scope wins).\n";

package/dist/skill-content.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPEC_COMPONENT_SKILL = void 0;
+exports.SPEC_COMPONENT_SKILL = `---
+description: Analyze a component, create ditto specs for it and its dependencies, identify rule gaps, and audit copy
+argument-hint: <ComponentName or path/to/component>
+allowed-tools: [Read, Bash, Edit, Write, Grep, Glob, Agent]
+---
+
+# Spec Component
+
+Analyze a design system component, scaffold \`.ditto.md\` content specs (including child components that lack specs), auto-fill surfaces and tags, identify style guide rule gaps from real code usage, create new rules on the platform, and audit copy compliance.
+
+## Input
+
+$ARGUMENTS
+
+Accept either a component name (e.g. \`Button\`) or a file path (e.g. \`src/components/Button/index.tsx\`). If a name is given, search the codebase to find the component. If multiple matches exist, ask the user to clarify.
+
+---
+
+## Phase 1: Discovery
+
+Find the target component and map its dependencies.
+
+1. Locate the component source file.
+2. Read the component code. Walk imports to find **child components that render user-facing text** (components that accept string props, children rendered as text, or contain hardcoded strings). Skip utility imports, style imports, icon imports, and non-text components.
+3. Check which components already have an \`index.ditto.md\` spec by looking for the file in each component's directory.
+4. Read \`workspace.ditto.md\` at the project root (if it exists) for existing platform tags and universal rules.
+5. Report:
+   - Target component and its location
+   - Child components needing specs (no existing \`index.ditto.md\`)
+   - Existing specs found (already covered)
+
+---
+
+## Phase 2: Surface Analysis
+
+For each component that needs a new spec (target + unspecced children):
+
+1. Read the TypeScript interface / props type definition.
+2. Identify every **text surface** — each piece of user-facing copy the component renders:
+   - **String props** rendered in JSX → use the prop name as the surface key
+   - **\`children\`** when used as text → use \`$children\` as the surface key
+   - **Nested props** → use dot notation (e.g. \`primaryAction.label\`)
+   - **Hardcoded strings** in JSX → use a descriptive role name (e.g. \`headline\`, \`submitLabel\`, \`bodyText\`)
+3. For each surface, suggest **tags** from the \`workspace.ditto.md\` tag inventory, matched by semantic role (e.g. \`heading\`, \`body\`, \`button\`, \`call-to-action\`). Prefer reusing existing tags. Only propose a new tag if nothing fits — and note it will be new.
+4. Estimate **\`maxLength\`** where layout context provides constraints (e.g. single-line headings, button widths). Omit if no clear constraint.
+
+Present the proposed spec for each component in exact YAML format:
+
+\`\`\`yaml
+---
+component: ComponentName
+tags: [relevant-tags]
+surfaces:
+  surfaceKey:
+    tags: [semantic-tags]
+    maxLength: 60
+# Managed by Ditto — do not edit below
+rules: []
+---
+\`\`\`
+
+**STOP HERE. Ask the user to review and approve the proposed surfaces before creating any files.** Let them add, remove, or modify surfaces and tags.
+
+---
+
+## Phase 3: Create Specs
+
+After user approval:
+
+1. For each component, run:
+   \`\`\`
+   npx ditto-spec scaffold <ComponentName> --path <component-directory>
+   \`\`\`
+2. Edit each created \`index.ditto.md\` to replace the empty \`surfaces: {}\` and \`tags: []\` with the approved values. Only edit developer-owned keys (\`component\`, \`tags\`, \`surfaces\`). Never write \`rules\` by hand.
+3. Run \`npx ditto-spec pull\` to populate the \`rules\` section from the platform.
+4. Run \`npx ditto-spec check\` to validate all spec files.
+
+Report which specs were created and how many rules were pulled.
+
+---
+
+## Phase 4: Rule Gap Analysis
+
+Identify copy patterns that should be rules but aren't.
+
+1. Read all rules now in the spec files (workspace-level from \`workspace.ditto.md\` + component-level and per-surface from each \`index.ditto.md\`).
+2. Search the codebase for **instances where the target component is used** — find all files that import and render it.
+3. For each usage instance, read the **actual copy** being passed to the component's text surfaces (string literals, template strings, variables with obvious values).
+4. Analyze the copy across instances for patterns no existing rule covers:
+   - Inconsistent terminology across instances
+   - Tone mismatches (e.g. some formal, some casual)
+   - Anti-patterns: passive voice in CTAs, overly long descriptions, redundant words
+   - Surface-specific conventions that should be formalized (e.g. "all action buttons start with a verb")
+5. If **no meaningful gaps** are found, say so and skip to Phase 6.
+6. If gaps are found, propose new rules. For each:
+   - **name**: short rule name
+   - **description**: what the rule enforces
+   - **tags**: which tags it should apply to (determines which surfaces it matches)
+   - **examples**: \`{from, to}\` pairs drawn from actual code showing the pattern
+
+If any proposed tags don't exist in the workspace yet, warn the user. Currently, only existing workspace tags can be assigned to rules. New tags may need to be created on the platform first.
+
+**STOP HERE. Present proposals and ask the user which rules (if any) to create.**
+
+---
+
+## Phase 5: Create Rules and Re-Pull
+
+For each approved rule:
+
+1. Run:
+   \`\`\`
+   npx ditto-spec create-rule --name "<rule name>" --description "<description>" --tags "<tag1,tag2>" --examples '<json array of {from,to}>'
+   \`\`\`
+   If a rule uses tags that don't exist yet, warn the user and omit those tags from the command (the API rejects unknown tags).
+
+2. After all rules are created, run \`npx ditto-spec pull\` to sync the new rules into spec files.
+
+3. Verify the specs now contain the expected rules by reading the updated \`index.ditto.md\` files.
+
+---
+
+## Phase 6: Copy Audit
+
+Evaluate all component instances against the full rule set.
+
+1. Re-read the fully-populated spec files (workspace + component + surface rules).
+2. Find all instances of the component in the codebase.
+3. For each instance, evaluate the actual copy against every applicable rule:
+   - Workspace rules apply to all surfaces
+   - Component-level rules (no \`surface\` field) apply to all surfaces
+   - Per-surface rules (with \`surface\` field) apply only to that surface
+   - Respect \`maxLength\` constraints — flag any text that exceeds the limit
+4. Report violations:
+   - File and line where the instance appears
+   - The text that violates the rule
+   - Which rule is violated
+   - Suggested corrected copy
+
+---
+
+## Reference: Ditto Spec Conventions
+
+These conventions are essential for creating correct specs:
+
+- **Surface keys**: prop name for props, \`$children\` for children text, dot-notation for nested props (\`primaryAction.label\`), descriptive role for hardcoded strings (\`headline\`, \`bodyText\`).
+- **Tags**: lowercase, hyphenated. Match semantic role (e.g. \`heading\`, \`body\`, \`button\`, \`call-to-action\`, \`dialog-title\`). Check \`workspace.ditto.md\` \`tags\` key for the full inventory.
+- **Developer-owned keys**: \`component\`, \`tags\`, \`surfaces\` — edit freely.
+- **CLI-managed keys**: \`rules\` (and workspace \`tags\`) — **never write by hand**. Populated by \`ditto-spec pull\`.
+- **Three-level rule hierarchy**: workspace rules (apply everywhere) → component-level rules (no \`surface\` field, apply to all surfaces in that component) → per-surface rules (with \`surface: "<key>"\`, apply only to that surface).
+- **Parent-child layering**: if a parent component passes text to a child (e.g. a label to a Button), the parent declares a surface in its own spec. Both parent and child rules apply — the parent's rules (e.g. dialog-level tone) layer with the child's rules (e.g. button-level constraints). A child having its own spec does NOT exempt the parent from declaring surfaces for text it provides.
+- **Tag matching**: rules match specs by tag intersection. Any shared tag triggers the match. If a rule matches both component-level and surface-level tags, it emits at component level (broader scope wins).
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dittowords/spec-cli",
-  "version": "0.0.1-alpha.6",
+  "version": "0.0.1-alpha.8",
   "description": "CLI for syncing .ditto.md content specs with the Ditto platform.",
   "main": "dist/cli.js",
   "bin": {