@dittowords/spec-cli 0.0.1-alpha.1 → 0.0.1-alpha.10

package/dist/parse.d.ts

@@ -0,0 +1,24 @@
+export interface SurfaceLike {
+    tags?: string[];
+    maxLength?: number;
+}
+export interface SpecLike {
+    tags?: string[];
+    surfaces?: Record<string, SurfaceLike>;
+}
+export interface ParsedSpec {
+    kind: "component" | "workspace";
+    name?: string;
+    spec: Record<string, unknown>;
+    filePath: string;
+}
+export declare class ParseError extends Error {
+    filePath: string;
+    reason: string;
+    constructor(filePath: string, reason: string);
+}
+export declare function parseSpecFile(filePath: string): ParsedSpec;
+export declare function extractFrontmatter(source: string, filePath: string): {
+    yaml: string;
+    afterFrontmatter: string;
+};

package/dist/parse.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParseError = void 0;
+exports.parseSpecFile = parseSpecFile;
+exports.extractFrontmatter = extractFrontmatter;
+const fs_1 = __importDefault(require("fs"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+class ParseError extends Error {
+    constructor(filePath, reason) {
+        super(`${filePath}: ${reason}`);
+        this.filePath = filePath;
+        this.reason = reason;
+    }
+}
+exports.ParseError = ParseError;
+function parseSpecFile(filePath) {
+    const source = fs_1.default.readFileSync(filePath, "utf8");
+    const { yaml: frontmatter } = extractFrontmatter(source, filePath);
+    const raw = js_yaml_1.default.load(frontmatter);
+    if (!raw || typeof raw !== "object") {
+        throw new ParseError(filePath, "frontmatter must be a YAML object");
+    }
+    const spec = raw;
+    if (spec.workspace === true) {
+        return { kind: "workspace", spec, filePath };
+    }
+    if (typeof spec.component !== "string" || !spec.component) {
+        throw new ParseError(filePath, "missing required 'component' key (string)");
+    }
+    return { kind: "component", name: spec.component, spec, filePath };
+}
+function extractFrontmatter(source, filePath) {
+    const cleaned = source.replace(/^\uFEFF/, "");
+    const match = cleaned.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) {
+        throw new ParseError(filePath, "no YAML frontmatter found (expected --- delimiters)");
+    }
+    return { yaml: match[1], afterFrontmatter: cleaned.slice(match[0].length) };
+}

package/dist/serialize.d.ts

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

package/dist/serialize.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rewriteManagedKeys = rewriteManagedKeys;
+const fs_1 = __importDefault(require("fs"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const parse_1 = require("./parse");
+const MANAGED_COMMENT = "# Managed by Ditto — do not edit below";
+function rewriteManagedKeys(filePath, updates) {
+    const source = fs_1.default.readFileSync(filePath, "utf8");
+    const { yaml: frontmatterYaml, afterFrontmatter } = (0, parse_1.extractFrontmatter)(source, filePath);
+    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) {
+        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,
+        noRefs: true,
+        sortKeys: false,
+        quotingType: '"',
+    })
+        .trimEnd();
+    dumped = insertManagedComment(dumped, updates.tags !== undefined);
+    fs_1.default.writeFileSync(filePath, `---\n${dumped}\n---${afterFrontmatter}`);
+}
+function insertManagedComment(dumped, managedTagsPresent) {
+    const targetKey = managedTagsPresent ? "tags" : "rules";
+    const idx = dumped.search(new RegExp(`^${targetKey}:`, "m"));
+    if (idx === -1)
+        return dumped;
+    const before = dumped.slice(0, idx);
+    if (before.includes(MANAGED_COMMENT))
+        return dumped;
+    return before + MANAGED_COMMENT + "\n" + dumped.slice(idx);
+}

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/dist/skills.d.ts

@@ -0,0 +1,4 @@
+export declare const SKILL_SPEC_COMPONENT = "---\ndescription: Analyze a component, create ditto specs for it and its dependencies, and auto-fill surfaces and tags\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, and sync rules from the platform.\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   - Whether the target already has a spec (and what surfaces it declares)\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\n**If the component already has a spec**, compare the existing surfaces against what the code declares. Report any new surfaces that aren't in the spec yet, and any spec surfaces that no longer exist in the code. Propose additions/removals.\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 or modifying any files.** Let them add, remove, or modify surfaces and tags.\n\n---\n\n## Phase 3: Create or Update Specs\n\nAfter user approval:\n\n**For new specs:**\n\n1. 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` or `locales` by hand.\n\n**For existing specs getting new surfaces:**\n\n1. Edit the existing `index.ditto.md` to add the approved new surfaces and tags.\n\n**Then for all specs (new and updated):**\n\n3. Run `npx ditto-spec pull` to populate the `rules` and `locales` sections from the platform.\n4. Run `npx ditto-spec check` to validate all spec files.\n\nReport which specs were created/updated and how many rules were pulled.\n\n---\n\n## Reference: Ditto Spec Conventions\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`, `locales` (and workspace `tags`) \u2014 **never write by hand**. Populated by `ditto-spec pull`.\n- **Rule shapes**: style rules have `name`, `description`, optional `examples`, and `section`. Terminology entries have `term`, `disallowed`, `description`, and `section`.\n- **Locale-scoped rules**: the `locales` key contains rules keyed by locale code (e.g. `de-DE`). These apply in addition to base `rules` when writing for that locale.\n- **Rule hierarchy**: workspace rules (apply everywhere) \u2192 component-level rules (no `surface` field) \u2192 per-surface rules (with `surface: \"<key>\"`). Locale-scoped rules follow the same hierarchy.\n- **Parent-child layering**: if a parent passes text to a child, the parent declares a surface in its own spec. 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.\n";
+export declare const SKILL_SPEC_AUDIT = "---\ndescription: Audit component copy against ditto spec rules and report violations\nargument-hint: <ComponentName or path> (optional \u2014 omit to audit all)\nallowed-tools: [Read, Bash, Grep, Glob, Agent]\n---\n\n# Spec Audit\n\nEvaluate user-facing copy in component instances against the rules in their `.ditto.md` specs. Reports violations with file locations and suggested corrections.\n\n## Input\n\n$ARGUMENTS\n\nIf a component name or path is given, audit only that component. If omitted, audit all components that have specs.\n\n---\n\n## Phase 1: Load Specs\n\n1. Read `workspace.ditto.md` at the project root for workspace-level rules, tags, and locale-scoped rules.\n2. If a specific component was given, find its `index.ditto.md`. If auditing all, run `npx ditto-spec list` to discover all specced components, then read each `index.ditto.md`.\n3. For each component, build the full rule set:\n   - Workspace rules (apply to all surfaces)\n   - Component-level rules (no `surface` field \u2014 apply to all surfaces in this component)\n   - Per-surface rules (with `surface: \"<key>\"` \u2014 apply only to that surface)\n   - Locale-scoped rules from `locales` (if present, at workspace or component level)\n\n---\n\n## Phase 2: Find Instances\n\n1. Search the codebase for all files that import and render each component being audited.\n2. For each instance, read the **actual copy** being passed to the component's text surfaces:\n   - String literals and template strings passed as props\n   - Children rendered as text\n   - Variables with obvious values (trace one level if needed)\n   - Hardcoded strings in the component source itself\n\n---\n\n## Phase 3: Evaluate\n\nFor each instance, evaluate the copy against every applicable rule:\n\n- **Style rules** (`name`/`description`/`examples`): check that copy follows the described guidance. Use `examples` (before/after pairs) as concrete reference for tone, length, and shape.\n- **Terminology entries** (`term`/`disallowed`): check that copy uses the `term` form and never uses any `disallowed` alternative. Check all surface text, not just exact matches \u2014 look for the disallowed forms appearing within longer strings.\n- **`maxLength` / `minLength`**: flag any text that exceeds or falls short of the constraint.\n- **Locale-scoped rules**: if the copy targets a specific locale (identifiable from file path, i18n keys, or surrounding context), also evaluate against the matching `locales.<code>` rules.\n\nEach rule carries a `section` field (e.g. \"Voice & Tone\", \"Terminology\") \u2014 use this to group violations in the report.\n\n---\n\n## Phase 4: Report\n\nPresent violations grouped by component, then by file:\n\nFor each violation:\n- **File and line** where the instance appears\n- **Surface** the text maps to\n- **Text** that violates the rule\n- **Rule** that is violated (name or term, plus section)\n- **Suggested correction**\n\nIf no violations are found, say so explicitly \u2014 a clean audit is useful information.\n\nEnd with a summary: total components audited, total instances checked, total violations found.\n\n---\n\n## Reference: Ditto Spec Conventions\n\n- **Rule shapes**: style rules have `name`, `description`, optional `examples`, and `section`. Terminology entries have `term`, `disallowed`, `description`, and `section`.\n- **Locale-scoped rules**: the `locales` key contains rules keyed by locale code (e.g. `de-DE`). These apply in addition to base `rules` when writing for that locale.\n- **Rule hierarchy**: workspace rules (apply everywhere) \u2192 component-level rules (no `surface` field) \u2192 per-surface rules (with `surface: \"<key>\"`). Locale-scoped rules follow the same hierarchy.\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";
+export declare const SKILL_SPEC_GAPS = "---\ndescription: Analyze copy across component instances to find rule gaps, then create new rules on the platform\nargument-hint: <ComponentName or path> (optional \u2014 omit to analyze all)\nallowed-tools: [Read, Bash, Edit, Grep, Glob, Agent]\n---\n\n# Spec Gaps\n\nIdentify copy patterns in component instances that should be rules but aren't. Propose new style rules or terminology entries, and create approved ones on the Ditto platform.\n\n## Input\n\n$ARGUMENTS\n\nIf a component name or path is given, analyze only that component's instances. If omitted, analyze all components that have specs.\n\n---\n\n## Phase 1: Load Existing Rules\n\n1. Read `workspace.ditto.md` for workspace-level rules and tags.\n2. Read each relevant component's `index.ditto.md` for component-level and per-surface rules.\n3. Build a complete picture of what's already covered \u2014 every style rule, terminology entry, and locale-scoped rule currently in the spec files.\n\n---\n\n## Phase 2: Analyze Copy\n\n1. Search the codebase for **instances where each component is used** \u2014 find all files that import and render it.\n2. For each instance, read the **actual copy** being passed to the component's text surfaces (string literals, template strings, variables with obvious values).\n3. Analyze the copy across all instances for patterns no existing rule covers:\n   - **Terminology inconsistencies**: the same concept referred to with different forms (e.g. \"sign up\" vs \"signup\" vs \"sign-up\"). These should become terminology entries.\n   - **Tone mismatches**: some instances formal, others casual. These should become style rules.\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\").\n\n---\n\n## Phase 3: Propose Rules\n\nIf **no meaningful gaps** are found, say so and stop.\n\nIf gaps are found, propose new rules. Rules come in two shapes:\n\n**Style rules:**\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\n**Terminology entries:**\n- **term**: the canonical form\n- **disallowed**: list of variant forms to reject\n- **description**: why this form is preferred\n- **tags**: which tags it should apply to\n\nIf any proposed tags don't exist in the workspace yet, warn the user. Only existing workspace tags can be assigned to rules.\n\n**STOP HERE. Present proposals and ask the user which rules (if any) to create.**\n\n---\n\n## Phase 4: Create Rules\n\nFor each approved rule, run:\n\n```\nnpx ditto-spec create-rule --name \"<rule name>\" --description \"<description>\" --tags \"<tag1,tag2>\" --examples '<json array of {from,to}>'\n```\n\nIf a rule uses tags that don't exist yet, warn the user and omit those tags from the command.\n\nAfter all rules are created:\n\n1. Run `npx ditto-spec pull` to sync the new rules into spec files.\n2. Read the updated `index.ditto.md` files and verify the new rules appear.\n3. Report which rules were created and which specs they landed in.\n\n---\n\n## Reference: Ditto Spec Conventions\n\n- **Rule shapes**: style rules have `name`, `description`, optional `examples`, and `section`. Terminology entries have `term`, `disallowed`, `description`, and `section`.\n- **CLI-managed keys**: `rules`, `locales` (and workspace `tags`) \u2014 **never write by hand**. Populated by `ditto-spec pull`.\n- **Tag matching**: rules match specs by tag intersection. Any shared tag triggers the match. Rules with no tags are workspace-universal (apply to all surfaces).\n- **Rule hierarchy**: workspace rules (apply everywhere) \u2192 component-level rules (no `surface` field) \u2192 per-surface rules (with `surface: \"<key>\"`).\n";
+export declare const SKILLS: Record<string, string>;

package/dist/skills.js

@@ -0,0 +1,278 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILLS = exports.SKILL_SPEC_GAPS = exports.SKILL_SPEC_AUDIT = exports.SKILL_SPEC_COMPONENT = void 0;
+exports.SKILL_SPEC_COMPONENT = `---
+description: Analyze a component, create ditto specs for it and its dependencies, and auto-fill surfaces and tags
+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, and sync rules from the platform.
+
+## 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
+   - Whether the target already has a spec (and what surfaces it declares)
+   - 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.
+
+**If the component already has a spec**, compare the existing surfaces against what the code declares. Report any new surfaces that aren't in the spec yet, and any spec surfaces that no longer exist in the code. Propose additions/removals.
+
+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 or modifying any files.** Let them add, remove, or modify surfaces and tags.
+
+---
+
+## Phase 3: Create or Update Specs
+
+After user approval:
+
+**For new specs:**
+
+1. 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\` or \`locales\` by hand.
+
+**For existing specs getting new surfaces:**
+
+1. Edit the existing \`index.ditto.md\` to add the approved new surfaces and tags.
+
+**Then for all specs (new and updated):**
+
+3. Run \`npx ditto-spec pull\` to populate the \`rules\` and \`locales\` sections from the platform.
+4. Run \`npx ditto-spec check\` to validate all spec files.
+
+Report which specs were created/updated and how many rules were pulled.
+
+---
+
+## Reference: Ditto Spec Conventions
+
+- **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\`, \`locales\` (and workspace \`tags\`) — **never write by hand**. Populated by \`ditto-spec pull\`.
+- **Rule shapes**: style rules have \`name\`, \`description\`, optional \`examples\`, and \`section\`. Terminology entries have \`term\`, \`disallowed\`, \`description\`, and \`section\`.
+- **Locale-scoped rules**: the \`locales\` key contains rules keyed by locale code (e.g. \`de-DE\`). These apply in addition to base \`rules\` when writing for that locale.
+- **Rule hierarchy**: workspace rules (apply everywhere) → component-level rules (no \`surface\` field) → per-surface rules (with \`surface: "<key>"\`). Locale-scoped rules follow the same hierarchy.
+- **Parent-child layering**: if a parent passes text to a child, the parent declares a surface in its own spec. 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.
+`;
+exports.SKILL_SPEC_AUDIT = `---
+description: Audit component copy against ditto spec rules and report violations
+argument-hint: <ComponentName or path> (optional — omit to audit all)
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Spec Audit
+
+Evaluate user-facing copy in component instances against the rules in their \`.ditto.md\` specs. Reports violations with file locations and suggested corrections.
+
+## Input
+
+$ARGUMENTS
+
+If a component name or path is given, audit only that component. If omitted, audit all components that have specs.
+
+---
+
+## Phase 1: Load Specs
+
+1. Read \`workspace.ditto.md\` at the project root for workspace-level rules, tags, and locale-scoped rules.
+2. If a specific component was given, find its \`index.ditto.md\`. If auditing all, run \`npx ditto-spec list\` to discover all specced components, then read each \`index.ditto.md\`.
+3. For each component, build the full rule set:
+   - Workspace rules (apply to all surfaces)
+   - Component-level rules (no \`surface\` field — apply to all surfaces in this component)
+   - Per-surface rules (with \`surface: "<key>"\` — apply only to that surface)
+   - Locale-scoped rules from \`locales\` (if present, at workspace or component level)
+
+---
+
+## Phase 2: Find Instances
+
+1. Search the codebase for all files that import and render each component being audited.
+2. For each instance, read the **actual copy** being passed to the component's text surfaces:
+   - String literals and template strings passed as props
+   - Children rendered as text
+   - Variables with obvious values (trace one level if needed)
+   - Hardcoded strings in the component source itself
+
+---
+
+## Phase 3: Evaluate
+
+For each instance, evaluate the copy against every applicable rule:
+
+- **Style rules** (\`name\`/\`description\`/\`examples\`): check that copy follows the described guidance. Use \`examples\` (before/after pairs) as concrete reference for tone, length, and shape.
+- **Terminology entries** (\`term\`/\`disallowed\`): check that copy uses the \`term\` form and never uses any \`disallowed\` alternative. Check all surface text, not just exact matches — look for the disallowed forms appearing within longer strings.
+- **\`maxLength\` / \`minLength\`**: flag any text that exceeds or falls short of the constraint.
+- **Locale-scoped rules**: if the copy targets a specific locale (identifiable from file path, i18n keys, or surrounding context), also evaluate against the matching \`locales.<code>\` rules.
+
+Each rule carries a \`section\` field (e.g. "Voice & Tone", "Terminology") — use this to group violations in the report.
+
+---
+
+## Phase 4: Report
+
+Present violations grouped by component, then by file:
+
+For each violation:
+- **File and line** where the instance appears
+- **Surface** the text maps to
+- **Text** that violates the rule
+- **Rule** that is violated (name or term, plus section)
+- **Suggested correction**
+
+If no violations are found, say so explicitly — a clean audit is useful information.
+
+End with a summary: total components audited, total instances checked, total violations found.
+
+---
+
+## Reference: Ditto Spec Conventions
+
+- **Rule shapes**: style rules have \`name\`, \`description\`, optional \`examples\`, and \`section\`. Terminology entries have \`term\`, \`disallowed\`, \`description\`, and \`section\`.
+- **Locale-scoped rules**: the \`locales\` key contains rules keyed by locale code (e.g. \`de-DE\`). These apply in addition to base \`rules\` when writing for that locale.
+- **Rule hierarchy**: workspace rules (apply everywhere) → component-level rules (no \`surface\` field) → per-surface rules (with \`surface: "<key>"\`). Locale-scoped rules follow the same hierarchy.
+- **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).
+`;
+exports.SKILL_SPEC_GAPS = `---
+description: Analyze copy across component instances to find rule gaps, then create new rules on the platform
+argument-hint: <ComponentName or path> (optional — omit to analyze all)
+allowed-tools: [Read, Bash, Edit, Grep, Glob, Agent]
+---
+
+# Spec Gaps
+
+Identify copy patterns in component instances that should be rules but aren't. Propose new style rules or terminology entries, and create approved ones on the Ditto platform.
+
+## Input
+
+$ARGUMENTS
+
+If a component name or path is given, analyze only that component's instances. If omitted, analyze all components that have specs.
+
+---
+
+## Phase 1: Load Existing Rules
+
+1. Read \`workspace.ditto.md\` for workspace-level rules and tags.
+2. Read each relevant component's \`index.ditto.md\` for component-level and per-surface rules.
+3. Build a complete picture of what's already covered — every style rule, terminology entry, and locale-scoped rule currently in the spec files.
+
+---
+
+## Phase 2: Analyze Copy
+
+1. Search the codebase for **instances where each component is used** — find all files that import and render it.
+2. For each instance, read the **actual copy** being passed to the component's text surfaces (string literals, template strings, variables with obvious values).
+3. Analyze the copy across all instances for patterns no existing rule covers:
+   - **Terminology inconsistencies**: the same concept referred to with different forms (e.g. "sign up" vs "signup" vs "sign-up"). These should become terminology entries.
+   - **Tone mismatches**: some instances formal, others casual. These should become style rules.
+   - **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").
+
+---
+
+## Phase 3: Propose Rules
+
+If **no meaningful gaps** are found, say so and stop.
+
+If gaps are found, propose new rules. Rules come in two shapes:
+
+**Style rules:**
+- **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
+
+**Terminology entries:**
+- **term**: the canonical form
+- **disallowed**: list of variant forms to reject
+- **description**: why this form is preferred
+- **tags**: which tags it should apply to
+
+If any proposed tags don't exist in the workspace yet, warn the user. Only existing workspace tags can be assigned to rules.
+
+**STOP HERE. Present proposals and ask the user which rules (if any) to create.**
+
+---
+
+## Phase 4: Create Rules
+
+For each approved rule, 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.
+
+After all rules are created:
+
+1. Run \`npx ditto-spec pull\` to sync the new rules into spec files.
+2. Read the updated \`index.ditto.md\` files and verify the new rules appear.
+3. Report which rules were created and which specs they landed in.
+
+---
+
+## Reference: Ditto Spec Conventions
+
+- **Rule shapes**: style rules have \`name\`, \`description\`, optional \`examples\`, and \`section\`. Terminology entries have \`term\`, \`disallowed\`, \`description\`, and \`section\`.
+- **CLI-managed keys**: \`rules\`, \`locales\` (and workspace \`tags\`) — **never write by hand**. Populated by \`ditto-spec pull\`.
+- **Tag matching**: rules match specs by tag intersection. Any shared tag triggers the match. Rules with no tags are workspace-universal (apply to all surfaces).
+- **Rule hierarchy**: workspace rules (apply everywhere) → component-level rules (no \`surface\` field) → per-surface rules (with \`surface: "<key>"\`).
+`;
+exports.SKILLS = {
+    "spec-component.md": exports.SKILL_SPEC_COMPONENT,
+    "spec-audit.md": exports.SKILL_SPEC_AUDIT,
+    "spec-gaps.md": exports.SKILL_SPEC_GAPS,
+};

package/package.json

@@ -1,19 +1,33 @@
 {
   "name": "@dittowords/spec-cli",
-  "version": "0.0.1-alpha.1",
+  "version": "0.0.1-alpha.10",
   "description": "CLI for syncing .ditto.md content specs with the Ditto platform.",
-  "main": "src/cli.ts",
+  "main": "dist/cli.js",
   "bin": {
-    "ditto-spec": "src/bin.js"
+    "ditto-spec": "dist/bin.js"
   },
+  "files": [
+    "dist"
+  ],
   "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
     "ditto-spec": "tsx src/cli.ts"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
+    "@dittowords/spec-cli": "^0.0.1-alpha.0",
     "dotenv": "^16.0.0",
     "glob": "^11.0.1",
-    "js-yaml": "^4.1.0",
-    "tsx": "^4.0.0"
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
   },
   "license": "Proprietary"
 }