Problem
Specialism IDs use kebab-case and often don't match the tool families or enum values they imply. A few cases a fresh builder hits:
-
`inventory-lists` specialism → `property_list` tools. The specialism is named for the concept ("lists of inventory") but every tool says "property list" (`create_property_list`, `validate_property_delivery`). Flagged by the fresh builder as real onboarding friction.
-
`sales-streaming-tv` specialism → `channels: ['ctv']`. The specialism title is "Streaming TV" but the `MediaChannel` enum uses `ctv`. Same for specialism id vs channel id.
-
Specialism id vs storyboard category id. `sales-broadcast-tv` (kebab) vs `media_buy_broadcast_seller` (snake) — same thing, three different names (plus the yaml title). Readers must learn the mapping by induction.
-
`delivery_type: 'non_guaranteed'` (underscore) vs prose "non-guaranteed" (hyphen). Every builder fumbled this at least once.
-
`signal_type: 'custom'` — in the enum but never defined in the spec; builders don't know when to use it vs `owned`.
Requested resolution
- Add a canonical "terminology" section to `docs/` (or the llms.txt preamble) that explains: specialism ID kebab-case, storyboard category id snake_case, the yaml title is prose — and shows the mapping.
- Normalize one of the inventory-lists ↔ property-list naming pairs. Either rename the specialism `property-lists` (kebab) or rename the tool family `inventory_list_*`. Rename inventory-lists is my recommendation — cheaper.
- Document when `signal_type: 'custom'` applies.
- Add to each specialism's `index.json` entry the set of tool families it uses (e.g. for `audience-sync`: `["sync_audiences", "list_accounts"]`) so discoverability doesn't require reading the whole yaml.
Context
Discovered via a 21-specialism fresh-builder test; every report flagged at least one terminology mismatch. Internal reports in `@adcp/client` `.context/specialism-tests/`.
Problem
Specialism IDs use kebab-case and often don't match the tool families or enum values they imply. A few cases a fresh builder hits:
`inventory-lists` specialism → `property_list` tools. The specialism is named for the concept ("lists of inventory") but every tool says "property list" (`create_property_list`, `validate_property_delivery`). Flagged by the fresh builder as real onboarding friction.
`sales-streaming-tv` specialism → `channels: ['ctv']`. The specialism title is "Streaming TV" but the `MediaChannel` enum uses `ctv`. Same for specialism id vs channel id.
Specialism id vs storyboard category id. `sales-broadcast-tv` (kebab) vs `media_buy_broadcast_seller` (snake) — same thing, three different names (plus the yaml title). Readers must learn the mapping by induction.
`delivery_type: 'non_guaranteed'` (underscore) vs prose "non-guaranteed" (hyphen). Every builder fumbled this at least once.
`signal_type: 'custom'` — in the enum but never defined in the spec; builders don't know when to use it vs `owned`.
Requested resolution
Context
Discovered via a 21-specialism fresh-builder test; every report flagged at least one terminology mismatch. Internal reports in `@adcp/client` `.context/specialism-tests/`.