voices-codingstandaarden

name: voices-codingstandaarden description: >- Slash /codingstandaarden — SSOT- en DRY-lagen in Cursor (rules, AGENTS, skills), stack-index 381, code-unificatie 357, golden path 028. Copy: /copy + check:ui-copy-hygiene (§1h). SEO/LLM-metadata: /seo (§1j). Theme parity: /dark + theme-dark-scan (§1k). Command .cursor/commands/codingstandaarden.md = dunne pointer (DRY, zelfde patroon als /dark). Geen tweede grondwet: pointers naar .mdc en docs. disable-model-invocation: true

Codingstandaarden in Cursor (/codingstandaarden)

Doel: In één herleesbare plek uitleggen waar bij Voices de SSOT (één waarheid) en DRY (geen nutteloze duplicatie) in Cursor leven, en wat je niet opnieuw uittypt in chat of in een skill. Slash: /codingstandaarden.

Slash-entry (DRY, zelfde patroon als /dark): .cursor/commands/codingstandaarden.md is een dunne pointer naar dit bestand; normatieve meta-uitleg staat hier, niet in het command.

1) Wanneer deze skill lezen

• Owner of agent vraagt: “Is dit SSOT?”, “Is dit DRY?”, “Waar staat de canon?” vóór of na een refactor.
• Nieuwe skill of command schrijven: check slash-DRY en skills README policy.
• Twijfel tussen .cursorrules, .cursor/AGENTS.md, en een .mdc: lees §2 hieronder, dan 386.

1b) Wél in deze skill (kort)

• Lagenplaat: waar SSOT en DRY in Cursor zitten (entry vs werklus vs wet).
• Pointers: rule-nummers en bestandsnamen, geen volledige rule-tekst.
• Verwarring uit de weg: slash-DRY, WET voor UI vs DRY voor logica (zie §4).
• Copy-toon: zelfde keten als /copy en check:ui-copy-hygiene (§1h), geen tweede checklist hier.
• SEO/LLM-metadata rook: zelfde cadans-idee als copy (§1j): /seo → voices-seo-check; geen tweede npm-legenda.
• Theme parity / dark-light: zelfde pointer-idee (§1k): /dark → theme-dark-scan; geen tweede procedure in deze skill.
• Verwante skills: één tabel, §6.

1c) Niet in deze skill (harde grens)

• Volledige gate-matrix of alle audit:unification-*-namen: alleen §7 + GATES-LEGEND + package.json.
• Lange rule-index zoals 022 inline: link naar .cursor/rules/022-AGENT-PERSONAS-RULE-POINTERS.mdc, uitklappen daar.
• Productdomein (orders, Yuki, actors, checkout, …) uitleggen: gebruik /contract en de domein-.mdc, niet deze meta-skill.
• Docs bijwerken na codewerk: /ssot (voices-ssot-doc-sync), niet /codingstandaarden.
• Nieuwe normen verzinnen: gedrag wijzigt via .mdc of canonieke docs, niet via uitbreiding van deze skill.
• Genummerde rules spiegelen in deze skill: verboden; normatieve tekst wijzigt in .mdc (owner UNLOCK / 900). Deze skill blijft index.

1d) Rule vs skill (beslisboom)

1. App-gedrag, contract, straf, security, commerce: open de genummerde .mdc die het domein lockt.
2. Welke npm-gate, wanneer gate:fast, localhost, connecties-tabel: .cursor/AGENTS.md + GATES-LEGEND + package.json.
3. “Waar zitten SSOT en DRY in Cursor?” (meta): deze skill (§2–§5).
4. Docs en hub-satelliet na wijzigingen: /ssot.
5. Thema nog onduidelijk: /contract.
6. «Helpt deze wijziging de zaakvoerder bij zijn doelen?»: rule 029 + hub docs/01-FOUNDATION/03-VOICES-DOELSTELLINGEN-SSOT.md (één rij per World/dwarsdoel; reflex landt in 027-lens, niet als apart hoofdstuk).

1e) Termen (mini-glossarium)

1f) Onboarding (één pad, DRY)

Veel genummerde rules in de UI (Active Rules) is bedoeld (één concern per .mdc). Lees in volgorde: 386 → .cursor/AGENTS.md (paragraaf Eerste 60 seconden) → docs/01-FOUNDATION/DOCUMENTATIE-LAAGEN-EN-TERMEN.md §2b → .cursor/agents/README.md. Open 022 en concrete .mdc pas bij de taak. Repo-skills vs plugin-skills: .cursor/skills/README.md (sectie Repo-skills vs plugin-skills).

1g) Cadans audit:cursor-rules

Na wijzigingen aan stack-semantiek in .cursorrules of .cursor/rules/: npm run audit:cursor-rules lokaal. On-demand CI: gate-fast-on-demand.yml (workflow_dispatch) draait gate:fast, die audit:cursor-rules via gate:audit:static-discipline meeneemt (docs/01-FOUNDATION/GATES-AND-NPM-SCRIPTS-LEGEND.md).

1h) Copy- en tooncheck (zelfde keten als /copy)

Zichtbare taal raakt 303, 336, 367 en de repo-gate check:ui-copy-hygiene. Dit is geen tweede norm naast /copy: dezelfde cadans, hier alleen als pointer voor agents die /codingstandaarden openen.

1. Review-workflow: /copy → .cursor/commands/copy.md → .cursor/skills/copy-review/SKILL.md (voices-copy-review).
2. Smalle canon + gates: /tone-of-voice → .cursor/skills/tone-of-voice/SKILL.md.
3. Na wijzigingen aan defaultText, placeholders of andere zichtbare strings in apps/web: npm run check:ui-copy-hygiene verplicht meedraaien (zelfde script zit in npm run gate:agent-micro en gate:fast; faalt op geblokkeerde jargon-patronen in die strings).
4. Docs na inhoudelijke copy: /ssot (voices-ssot-doc-sync), niet deze meta-skill.

Niet verwarren: /mensentaal = owner-antwoordstijl (018); /heal = Voiceglot-bundel in Postgres.

1i) Andere codingstandaarden (wel canon, niet hier uitwerken)

Deze skill blijft meta (waar SSOT/DRY in Cursor zitten). Veel app- en repo-wetten staan niet bovenstaand uitgeschreven; volg .cursor/rules/022-AGENT-PERSONAS-RULE-POINTERS.mdc of /contract, dan de .mdc:

Niet exhaustief: on-demand rules en pilot-lijst: 386 §5 · .cursor/plans/slices/03-always-on-rules-pilot.md.

1j) SEO- en LLM-metadata check (zelfde «pointer»-idee als §1h)

Metadata, llms.txt, JSON-LD/excerpt-keten en etalage-delivery raken doc 50, seo:automation en de etalage-metadata-seo-smoke in gate:fast. Dit is geen tweede norm naast /copy: zichtbare taal blijft 303/336/367 + check:ui-copy-hygiene (§1h).

1. Workflow: /seo → .cursor/commands/seo.md → .cursor/skills/seo-check/SKILL.md (voices-seo-check).
2. Snelle rook (na route/metadata-wijziging): repo-root npm run seo:automation; npm --workspace apps/web run metadata:verify.
3. PR-kwaliteit / CI-pariteit: volledige subketen npm run gate:verify:etalage-metadata-seo-smoke (zie package.json); zit al in npm run gate:fast.
4. Proces + checklist mens: docs/02-ARCHITECTURE/50-PUBLIC-ROUTE-DELIVERY-CHECKLIST.md · .github/SEO_AND_CI.md.

1k) Theme parity en /dark (pointer, geen tweede procedure)

Visuele light + dark-consistentie raakt 301, 200 (theme parity), 385 waar interactieve VA-ink geldt. Dit is geen tweede norm naast /dark: dezelfde cadans, hier alleen als pointer voor agents die /codingstandaarden openen.

1. Workflow: /dark → .cursor/commands/dark.md → .cursor/skills/theme-dark-scan/SKILL.md (theme-dark-scan).
2. Smalle statische gate (na UI-touch onder apps/web): npm run theme:check-tokens in apps/web waar Tailwind/tokens/focus/hover geraakt worden (zie 301).
3. Brede rook: npm run theme:verify of npm run dark:scan volgens PRD .cursor/plans/prd-theme-dark-scan-gates.md en theme-dark-scan skill (geen commando-lijst hier dupliceren).
4. PR-checklist: .github/pull_request_template.md — sectie UI / theme parity wanneer styling of componenten wijzigen.

Niet verwarren: /contrast = gerichte contrast-scan (voices-contrast); /dark = volledige theme-sweep-SSOT.

2) SSOT: drie lagen (Cursor-meta, geen product-domein)

Semver / Next / React: uitsluitend apps/web/package.json als cijfer-SSOT; interpretatie en index: .cursor/rules/005-CURSOR-ARCHITECTURE.mdc §0, .cursor/rules/381-NEXT-REACT-TURBOPACK-CODING-STANDARDS-SSOT.mdc, .cursor/rules/006-RUNTIME-AND-TOOLING-SSOT.mdc. Na wijzigingen in .cursor/ of .cursorrules die stack beweren: npm run audit:cursor-rules.

3) SSOT: product en repo (naast Cursor-meta)

• Database / Drizzle: één schema-export packages/database/schema.ts (311); kolommen snake_case in API/DB-contract (200).
• Publieke copy: Voiceglot-keys + bundel (367, 340); geen parallelle hardcoded etalage-zinnen als norm.
• UI-instrumenten, layout tokens, theme, admin-nav (index + rules 300/301/333/356): docs/02-ARCHITECTURE/VOICES-UI-SSOT-INDEX.md (geen tweede Instruments-essay in deze skill).
• Docs: hub vs satelliet, forensisch vs normatief: docs/01-FOUNDATION/DOCUMENTATIE-LAAGEN-EN-TERMEN.md; na codewerk vaak /ssot → .cursor/skills/ssot-doc-sync/SKILL.md.
• Admin Pexels featured (FAQ/blog, ontbrekend featured-beeld): rule 324 · lib apps/web/src/lib/blog/pexels-featured-service.ts · doc docs/02-ARCHITECTURE/IMAGES-VOICES-NEXT-IMAGE-SSOT.md · UI /admin/blog/images · POST /api/admin/blog/pexels/attach-featured. Geen sitewide “elke afbeelding via Pexels”; zie /ssot skill §8e.
• Voiceglot/klantcopy in docs/: satellieten en indexes houden een stabiele verwijzing naar VOICEGLOT-AND-CUSTOMER-COPY-ECOSYSTEM-SSOT (north star altijd §0–§1 hub + 367, geen tweede normatieve proza-laag); npm run verify:voiceglot-satellite-doc-hub-pointers zit in verify:foundation-docs-ssot-gate (GATES-LEGEND, 367). DB-check static-registry×locales: npm run verify:public-ui-static-registry-translations:when-db (in gate:verify:schema-and-voiceglot:when-db).
• Actor-tarieven (geen rates/pending_rates JSONB op public.actors): relationele SSOT actor_rates (002 §18, docs/VOICES-PRICING-SSOT.md). Gate met DB: npm run verify:actors-no-rates-json-columns:when-db (zelfde blok als gate:verify:schema-and-voiceglot:when-db). Idempotente DDL-spiegel: npm run db:apply:0539-actors-drop-rates-jsonb-if-present.

4) DRY: wat wij bedoelen (en wat niet)

Wel DRY (verplicht waar het kan):

• Geen tweede grondwet: geen lange kopie van .mdc-tekst in skills, commands, of AGENTS; alleen pointers (bestandsnaam + rule-nummer) (022, 386, .cursor/skills/README.md).
• Geen dubbele client-fetch / query voor hetzelfde feit: .cursor/rules/357-UNIFICATION-SSOT-NO-DUPLICATE-IMPLEMENTATION.mdc; audit-namen en keten: root package.json (hier geen audit:unification-*-opsomming).
• Performance: SSOT eerst op de server, client dedupe als net na die waarheid (028, perf-chris-dry-masterclass).
• Slash-DRY: name: in .cursor/commands/*.md ≠ name: in SKILL.md frontmatter, anders twee /-items in Cursor voor hetzelfde (AGENTS slash-DRY uitleg).

Niet verwarren met “alles abstract één functie”:

• UI-componenten: WET mag bewust (002 §32 in developer guidelines): liever leesbare duplicatie dan verkeerde abstractie. DRY geldt streng voor businesslogica, auth, fetch-paden, prijsengine, niet voor elke pixel.

5) Golden path en SSOT

• 028 — één canoniek pad; geen permanente “plan B” als vervanging van een slordige bron.
• 200 — root-cause boven frontend-pleister; past bij SSOT-denken.

6) Gerelateerde skills en commands

7) Gates (geen tweede legenda hier)

Exacte scriptnamen en ketens: docs/01-FOUNDATION/GATES-AND-NPM-SCRIPTS-LEGEND.md en root package.json. Snelle agentlus vs volledige gate: .cursor/AGENTS.md (gate:agent-micro vs gate:fast, macro zoals check:pre-vercel alleen waar AGENTS dat voorschrijft).

8) Non-goals

• Deze skill vervangt geen .mdc: bij twijfel over gedrag altijd de genummerde rule lezen.
• Geen nieuwe normen uitvinden in deze skill; alleen structureren en verwijzen.
• Omvang (Tier A): houd uitbreidingen kort; volledige auteurspolicy en “Niet doen”-lijst: .cursor/skills/README.md. Na wijziging van deze SKILL.md: npm run cursor:skills-manifest:write en npm run verify:cursor-skills-hygiene.
• Anti-patroon: twee alinea’s die hetzelfde zeggen als 386 §1 → verwijderen, vervangen door link naar 386.

Managed by Chris (integriteit, SSOT) + Bob (meta-lagen, 386).