@dittowords/spec-cli 0.0.1-alpha.13 → 0.0.1-alpha.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/skills.d.ts +2 -2
- package/dist/skills.js +4 -4
- package/package.json +1 -1
package/dist/skills.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
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";
|
|
2
|
-
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 & Resolve Instances\n\n1. Search the codebase for all files that import and render each component being audited.\n2. For each instance, resolve the **actual copy** bound to each text surface. Copy is often not an inline literal \u2014 it may be a reference to a string stored elsewhere. Follow the binding to wherever the real text lives, working down this ladder:\n\n **a. Inline** \u2014 string literals, template strings passed as props, children rendered as text, hardcoded strings in the component source, and variables with obvious values (trace one level if needed). Read the value directly.\n\n **b. i18n key** \u2014 the surface is bound to a translation lookup such as `t('dialog.headline')`, `i18n.t(...)`, `$t('key')`, `<FormattedMessage id=\"...\">`, `intl.formatMessage({ id })`, `<Trans i18nKey=\"...\">`, or a Rails `t('.key')`. Resolve it:\n - Locate the catalog file(s) by convention (see **Resolving copy sources** below) and look up the key, supporting nested/dot keys and namespaces.\n - Resolve the value in **every** available locale catalog, not just the default. Each locale's value is a separate instance to evaluate, and it activates that locale's `locales.<code>` rules.\n - Resolve **plural forms** (i18next `_one`/`_other`/`_zero`/`_many`, ICU `{count, plural, \u2026}`, `.stringsdict`, Android `<plurals>`) \u2014 evaluate each form.\n - Treat **interpolation placeholders** (`{{var}}`, `{var}`, `%s`, `%@`, `%1$s`, ICU `{name}`) as opaque tokens \u2014 audit the copy around them, never the token.\n\n **c. Ditto text item** \u2014 the surface resolves to a string Ditto manages, fetched through a key-lookup call. **The deciding signal is key-resolvability, not the function name:** whenever a surface is bound to any lookup-style call passing a string literal (e.g. `getDittoText('open-in-figma')`, `t('style-guides')`, `ditto.t(...)`, `getText('...')`) that the inline (**a**) and i18n (**b**) branches did not already resolve, treat the literal as a candidate Ditto **Developer ID** and try to resolve it. An accessor name containing \"ditto\" (case-insensitive \u2014 `getDittoText`, `useDittoText`, `dittoText`, `ditto.t`) or an import tracing to a Ditto module is a corroborating hint, not a requirement.\n - Locate the Ditto output: the `ditto/` folder, or the `outDir` in `ditto/config.yml`.\n - **Grep the specific literal id as a key** across the `{project}___{variant}.json` and `components__{variant}.json` files \u2014 do not read whole files or index all keys. Prefer an exact key match; only if none exists, try a normalized (kebab/camel) form of the id.\n - If the key is found, it **is** a Ditto text item: resolve its value in **every** variant file that contains it (each variant is a separate instance, parallel to the every-locale rule in **b**; infer the variant/locale from the file name), resolve `_one`/`_other` plural forms (evaluate each), and treat `{{variableId}}` placeholders as opaque tokens. Record the source as **Ditto**, naming the Developer ID and variant.\n - If the id is **not a string literal** (e.g. `getDittoText('item-' + type)`) or **no ditto file contains the key**, drop to **d** \u2014 never log a Ditto source you could not key-match.\n\n **d. Unresolvable / dynamic** \u2014 the value is computed at runtime, the key is itself a variable (e.g. `t('item.' + type)`), the key or catalog can't be found, or the string is assembled from fragments. **Never skip silently.** Evaluate whatever is statically knowable (literal fragments, the message skeleton) and record an explicit **unresolved \u2014 manual review** entry naming the surface, the binding you found, and why it could not be resolved.\n\nThis skill **reads** from every source but **never modifies any of them** \u2014 inline code, i18n catalogs, and Ditto text items are each owned by their own workflow. Auditing is report-only.\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**: when a resolved string comes from a specific locale (identifiable from its catalog file path/name, i18n key, Ditto variant, or surrounding context), also evaluate it against the matching `locales.<code>` rules, in addition to the base rules.\n- **Interpolation placeholders**: treat `{{var}}`, `{var}`, `%s`, `%@`, `%1$s`, and ICU `{name}` tokens as opaque \u2014 evaluate the copy around them, not the token itself.\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- **Source** where the copy lives: `inline (code)`, `i18n catalog: <file>#<key> [locale]`, or `ditto text item: <developer-id> [variant]`\n- **Text** that violates the rule\n- **Rule** that is violated (name or term, plus section)\n- **Suggested correction** \u2014 for inline copy this is a code change; for i18n catalogs and Ditto text items it is **advisory only**: the string is owned by that workflow and must be changed there, not edited in component code. Never present it as a code edit, and never modify the catalog or text item.\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. If any surfaces could not be resolved (Phase 2d), list them under **Unresolved surfaces** with their bindings \u2014 never let a resolution gap pass silently.\n\n---\n\n## Reference: Resolving copy sources\n\nConventions for locating externally-stored copy. Infer the **locale** from the file path or name (e.g. `de-DE`, `/de/`, `__spanish`, `values-de/`) so locale-scoped rules apply.\n\n- **Ditto** \u2014 `ditto/` (or the `outDir` in `ditto/config.yml`); files `{project}___{variant}.json`, `components__{variant}.json`, plus `variables.json`. Keys are Developer IDs; plurals use `_one`/`_other` suffixes; variables are `{{variableId}}`. Output may also be Android XML or iOS `.strings`/`.stringsdict`. **Detect Ditto bindings by key-resolvability, not function name:** any string-literal argument to a lookup-style call (whatever it's named) that matches a Developer-ID key in these files is a Ditto text item. Grep the specific id as a key \u2014 never read entire files to find it.\n- **i18next / react-intl / FormatJS** \u2014 `locales/`, `public/locales/<lng>/<ns>.json`, `i18n/`, `lang/`, `messages.*.json`.\n- **Flutter** \u2014 `.arb` files. **gettext** \u2014 `.po`/`.pot`. **Rails** \u2014 `config/locales/*.yml`. **Apple** \u2014 `*.strings`, `*.stringsdict`, `*.xcstrings`. **Android** \u2014 `res/values*/strings.xml`.\n\nWhen key resolution is ambiguous (e.g. multiple catalogs or namespaces in a monorepo), prefer the catalog nearest the importing instance or matching the configured namespace; if still ambiguous, mark the surface unresolved (Phase 2d) rather than guessing. Look copy up by key \u2014 do not read entire catalogs into context.\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";
|
|
3
|
-
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,
|
|
2
|
+
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 & Resolve Instances\n\n1. Search the codebase for all files that import and render each component being audited.\n2. For each instance, evaluate the **actual copy** bound to **every** text surface. A surface's value may be an inline literal or a reference to a string stored elsewhere \u2014 and a single instance commonly mixes both. These layers are **not** mutually exclusive: evaluate every one that applies, and resolving an externalized source never lets you skip the inline copy.\n\n **a. Inline (always \u2014 the baseline).** Read and audit the literal text present directly in the code: string literals and template strings passed as props, children rendered as text, hardcoded strings in the component/JSX, and variables with obvious values (trace one level if needed). **This pass is mandatory and is never skipped \u2014 auditing hardcoded copy is the default job of this skill, so do it for every instance even when the component also uses i18n or Ditto.**\n\n **b. i18n key** \u2014 the surface is bound to a translation lookup such as `t('dialog.headline')`, `i18n.t(...)`, `$t('key')`, `<FormattedMessage id=\"...\">`, `intl.formatMessage({ id })`, `<Trans i18nKey=\"...\">`, or a Rails `t('.key')`. Resolve it:\n - Locate the catalog file(s) by convention (see **Resolving copy sources** below) and look up the key, supporting nested/dot keys and namespaces.\n - Resolve the value in **every** available locale catalog, not just the default. Each locale's value is a separate instance to evaluate, and it activates that locale's `locales.<code>` rules.\n - Resolve **plural forms** (i18next `_one`/`_other`/`_zero`/`_many`, ICU `{count, plural, \u2026}`, `.stringsdict`, Android `<plurals>`) \u2014 evaluate each form.\n - Treat **interpolation placeholders** (`{{var}}`, `{var}`, `%s`, `%@`, `%1$s`, ICU `{name}`) as opaque tokens \u2014 audit the copy around them, never the token.\n\n **c. Ditto text item** \u2014 the surface resolves to a string Ditto manages, fetched through a key-lookup call. **The deciding signal is key-resolvability, not the function name:** whenever a surface is bound to any lookup-style call passing a string literal (e.g. `getDittoText('open-in-figma')`, `t('style-guides')`, `ditto.t(...)`, `getText('...')`) that the inline (**a**) and i18n (**b**) branches did not already resolve, treat the literal as a candidate Ditto **Developer ID** and try to resolve it. An accessor name containing \"ditto\" (case-insensitive \u2014 `getDittoText`, `useDittoText`, `dittoText`, `ditto.t`) or an import tracing to a Ditto module is a corroborating hint, not a requirement.\n - Locate the Ditto output: the `ditto/` folder, or the `outDir` in `ditto/config.yml`.\n - **Grep the specific literal id as a key** across the `{project}___{variant}.json` and `components__{variant}.json` files \u2014 do not read whole files or index all keys. Prefer an exact key match; only if none exists, try a normalized (kebab/camel) form of the id.\n - If the key is found, it **is** a Ditto text item: resolve its value in **every** variant file that contains it (each variant is a separate instance, parallel to the every-locale rule in **b**; infer the variant/locale from the file name), resolve `_one`/`_other` plural forms (evaluate each), and treat `{{variableId}}` placeholders as opaque tokens. Record the source as **Ditto**, naming the Developer ID and variant.\n - If the id is **not a string literal** (e.g. `getDittoText('item-' + type)`) or **no ditto file contains the key**, drop to **d** \u2014 never log a Ditto source you could not key-match.\n\n **d. Unresolvable / dynamic** \u2014 the value is computed at runtime, the key is itself a variable (e.g. `t('item.' + type)`), the key or catalog can't be found, or the string is assembled from fragments. **Never skip silently.** Evaluate whatever is statically knowable (literal fragments, the message skeleton) and record an explicit **unresolved \u2014 manual review** entry naming the surface, the binding you found, and why it could not be resolved.\n\nThis skill **reads** from every source but **never modifies any of them** \u2014 inline code, i18n catalogs, and Ditto text items are each owned by their own workflow. Auditing is report-only.\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**: when a resolved string comes from a specific locale (identifiable from its catalog file path/name, i18n key, Ditto variant, or surrounding context), also evaluate it against the matching `locales.<code>` rules, in addition to the base rules.\n- **Interpolation placeholders**: treat `{{var}}`, `{var}`, `%s`, `%@`, `%1$s`, and ICU `{name}` tokens as opaque \u2014 evaluate the copy around them, not the token itself.\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- **Source** where the copy lives: `inline (code)`, `i18n catalog: <file>#<key> [locale]`, or `ditto text item: <developer-id> [variant]`\n- **Text** that violates the rule\n- **Rule** that is violated (name or term, plus section)\n- **Suggested correction** \u2014 for inline copy this is a code change; for i18n catalogs and Ditto text items it is **advisory only**: the string is owned by that workflow and must be changed there, not edited in component code. Never present it as a code edit, and never modify the catalog or text item.\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. If any surfaces could not be resolved (Phase 2d), list them under **Unresolved surfaces** with their bindings \u2014 never let a resolution gap pass silently.\n\n---\n\n## Reference: Resolving copy sources\n\nConventions for locating externally-stored copy. Infer the **locale** from the file path or name (e.g. `de-DE`, `/de/`, `__spanish`, `values-de/`) so locale-scoped rules apply.\n\n- **Ditto** \u2014 `ditto/` (or the `outDir` in `ditto/config.yml`); files `{project}___{variant}.json`, `components__{variant}.json`, plus `variables.json`. Keys are Developer IDs; plurals use `_one`/`_other` suffixes; variables are `{{variableId}}`. Output may also be Android XML or iOS `.strings`/`.stringsdict`. **Detect Ditto bindings by key-resolvability, not function name:** any string-literal argument to a lookup-style call (whatever it's named) that matches a Developer-ID key in these files is a Ditto text item. Grep the specific id as a key \u2014 never read entire files to find it.\n- **i18next / react-intl / FormatJS** \u2014 `locales/`, `public/locales/<lng>/<ns>.json`, `i18n/`, `lang/`, `messages.*.json`.\n- **Flutter** \u2014 `.arb` files. **gettext** \u2014 `.po`/`.pot`. **Rails** \u2014 `config/locales/*.yml`. **Apple** \u2014 `*.strings`, `*.stringsdict`, `*.xcstrings`. **Android** \u2014 `res/values*/strings.xml`.\n\nWhen key resolution is ambiguous (e.g. multiple catalogs or namespaces in a monorepo), prefer the catalog nearest the importing instance or matching the configured namespace; if still ambiguous, mark the surface unresolved (Phase 2d) rather than guessing. Look copy up by key \u2014 do not read entire catalogs into context.\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";
|
|
3
|
+
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, gather the **actual copy** bound to **every** text surface \u2014 inline and externalized alike. An instance often mixes both, so never skip the inline copy just because some surfaces resolve to a catalog:\n - **Inline (always \u2014 the baseline).** String literals, template strings, children, hardcoded strings, and variables with obvious values. Always gather these; hardcoded copy is the default and is never skipped.\n - **i18n key** \u2014 a lookup like `t('key')`, `<FormattedMessage id=\"...\">`, or `$t('key')`: resolve the key in the catalog file(s) (`locales/`, `public/locales/<lng>/<ns>.json`, `.arb`, `.po`, `config/locales/*.yml`, `*.strings`, `res/values*/strings.xml`), across **all** locales, including plural forms. Look copy up by key \u2014 do not read entire catalogs into context.\n - **Ditto text item** \u2014 any lookup-style call passing a string literal (e.g. `getDittoText('id')`, `t('id')`, `ditto.t`) whose id matches a Developer-ID key in the project's Ditto output (`ditto/` folder, or `outDir` in `ditto/config.yml`; `{project}___{variant}.json` keyed by Developer ID, plurals suffixed `_one`/`_other`, variables `{{variableId}}`). Detect by key-resolvability, not function name; a \"ditto\"-ish name or import is just a hint. Grep the specific id as a key \u2014 do not read entire catalogs \u2014 and resolve per variant. If the id isn't a literal or no file has the key, treat as unresolvable.\n - **Unresolvable / dynamic** \u2014 runtime-computed values or missing keys: analyze what is statically knowable and skip the rest. This skill only **reads** these sources; it never modifies catalogs or text items.\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\nBefore creating any rules, determine which style guide to target:\n\n1. Check `dittospec.config.json` for a `defaultStyleguide` value.\n2. If present, tell the user which style guide will be used and ask for confirmation.\n3. If absent (or the user wants a different one), ask the user for the exact style guide name to create the rules in \u2014 it must match a style guide that exists in the workspace (visible on the Ditto platform). `create-rule` rejects an unrecognized `--styleguide` value and lists the valid names, so a wrong name fails loudly instead of silently targeting the wrong guide.\n\nFor each approved rule, run:\n\n```\nnpx ditto-spec create-rule --name \"<rule name>\" --description \"<description>\" --styleguide \"<chosen style guide>\" --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";
|
|
4
4
|
export declare const SKILLS: Record<string, string>;
|
package/dist/skills.js
CHANGED
|
@@ -139,9 +139,9 @@ If a component name or path is given, audit only that component. If omitted, aud
|
|
|
139
139
|
## Phase 2: Find & Resolve Instances
|
|
140
140
|
|
|
141
141
|
1. Search the codebase for all files that import and render each component being audited.
|
|
142
|
-
2. For each instance,
|
|
142
|
+
2. For each instance, evaluate the **actual copy** bound to **every** text surface. A surface's value may be an inline literal or a reference to a string stored elsewhere — and a single instance commonly mixes both. These layers are **not** mutually exclusive: evaluate every one that applies, and resolving an externalized source never lets you skip the inline copy.
|
|
143
143
|
|
|
144
|
-
**a. Inline
|
|
144
|
+
**a. Inline (always — the baseline).** Read and audit the literal text present directly in the code: string literals and template strings passed as props, children rendered as text, hardcoded strings in the component/JSX, and variables with obvious values (trace one level if needed). **This pass is mandatory and is never skipped — auditing hardcoded copy is the default job of this skill, so do it for every instance even when the component also uses i18n or Ditto.**
|
|
145
145
|
|
|
146
146
|
**b. i18n key** — the surface is bound to a translation lookup such as \`t('dialog.headline')\`, \`i18n.t(...)\`, \`$t('key')\`, \`<FormattedMessage id="...">\`, \`intl.formatMessage({ id })\`, \`<Trans i18nKey="...">\`, or a Rails \`t('.key')\`. Resolve it:
|
|
147
147
|
- Locate the catalog file(s) by convention (see **Resolving copy sources** below) and look up the key, supporting nested/dot keys and namespaces.
|
|
@@ -241,8 +241,8 @@ If a component name or path is given, analyze only that component's instances. I
|
|
|
241
241
|
## Phase 2: Analyze Copy
|
|
242
242
|
|
|
243
243
|
1. Search the codebase for **instances where each component is used** — find all files that import and render it.
|
|
244
|
-
2. For each instance,
|
|
245
|
-
- **Inline
|
|
244
|
+
2. For each instance, gather the **actual copy** bound to **every** text surface — inline and externalized alike. An instance often mixes both, so never skip the inline copy just because some surfaces resolve to a catalog:
|
|
245
|
+
- **Inline (always — the baseline).** String literals, template strings, children, hardcoded strings, and variables with obvious values. Always gather these; hardcoded copy is the default and is never skipped.
|
|
246
246
|
- **i18n key** — a lookup like \`t('key')\`, \`<FormattedMessage id="...">\`, or \`$t('key')\`: resolve the key in the catalog file(s) (\`locales/\`, \`public/locales/<lng>/<ns>.json\`, \`.arb\`, \`.po\`, \`config/locales/*.yml\`, \`*.strings\`, \`res/values*/strings.xml\`), across **all** locales, including plural forms. Look copy up by key — do not read entire catalogs into context.
|
|
247
247
|
- **Ditto text item** — any lookup-style call passing a string literal (e.g. \`getDittoText('id')\`, \`t('id')\`, \`ditto.t\`) whose id matches a Developer-ID key in the project's Ditto output (\`ditto/\` folder, or \`outDir\` in \`ditto/config.yml\`; \`{project}___{variant}.json\` keyed by Developer ID, plurals suffixed \`_one\`/\`_other\`, variables \`{{variableId}}\`). Detect by key-resolvability, not function name; a "ditto"-ish name or import is just a hint. Grep the specific id as a key — do not read entire catalogs — and resolve per variant. If the id isn't a literal or no file has the key, treat as unresolvable.
|
|
248
248
|
- **Unresolvable / dynamic** — runtime-computed values or missing keys: analyze what is statically knowable and skip the rest. This skill only **reads** these sources; it never modifies catalogs or text items.
|