Naming Standards

This page is the System of Names SSOT for this repo. It is the front door for naming decisions: classify the thing, then follow the authority that governs that name class.

Names are fittings between humans, agents, scripts, docs, DB records, and handoffs. Inconsistent names leak: agents translate, humans re-interpret, scripts need custom glue.

Core rule: classify the thing before naming it.

Five naming rules:

• One concept, one canonical name.
• Related artifacts share one stable prefix.
• Inputs and outputs are named so the next Unit of Work can consume them.
• Abbreviations expanded at the standard boundary before shorthand.
• File names, DB records, receipts, and specs use the same term for the same thing.

How to Decide a Name

Answer in order. Do not name the artifact until the sequence resolves the class and authority.

1. Surface — which repo path owns this? Use the Repo Surfaces section.
2. Class — what kind of thing is it: route, page job, canonical term, symbol, skill, component, generated data, or private state?
3. Consumer — who or what reads it first: person, agent, script, renderer, CLI, or build gate?
4. Lifecycle — is it source, generated, routed, staged, durable private state, or deprecated history?
5. Pattern — use the narrowest existing pattern before inventing a new one.
6. Name — apply casing, prefix, suffix, and uniqueness rules for that class.
7. Authority — update the source of truth, not a mirror page.

If two rules conflict, stop. Route to drmg-language-curator for terminology or agent-ops-lead for agent/skill configuration.

The Three Layers

• Taxonomy — structured classification (domains, subdomains, artifact types). Missing → same concept appears in several places.
• Nomenclature — naming rules (format, casing, prefix, version, uniqueness). Missing → search depends on memory or luck.
• Ontology — concept relationships (governs, depends on, emits, validates). Missing → agents cannot tell whether two names mean the same thing.

Taxonomy gives structure. Nomenclature gives labels. Ontology gives semantics.

Folder structure is taxonomy. Filename is nomenclature. Links and frontmatter are ontology.

Name Authority Matrix

Use this matrix when the question is, "Where is the SSOT for naming this thing?" This page maps the class. The named authority owns the detailed rule.

Folders And Files

Class — source files, docs files, folders, indexes, templates, and flat artifact sets.

Authority — this page: Files And Folders, Folder Structure, and Repo Surfaces.

Rule — classify the surface and lifecycle first. Use folder structure for taxonomy and filenames for nomenclature.

Docs Routes And Page Jobs

Class — /playbook routes, page types, index patterns, templates, and page-job frontmatter.

Authority — Page Types for page jobs and index patterns; Wiki Schema for the Map-First edit contract.

Rule — choose the page job before writing. index.md or index.mdx is a pattern applied to a page type, not a page type by itself.

Top-Level Docs Placement

Class — public docs section placement and folder banding.

Authority — Information Architecture Standard.

Rule — place by primary subject and top-level organizing axis. Return here only after placement to name the route and files.

Canonical Terms

Class — durable cross-domain language, overloaded terms, aliases to avoid, and shared definitions.

Authority — DDL Nomenclature, sourced from src/pages/agents/_ddl-nomenclature.data.ts.

Rule — add or sharpen the DDL term before changing mirror prose. Domain glossaries may explain local dialects, but DDL arbitrates cross-domain names.

Agent Notation And Symbols

Class — compressed agent notation, DML codes, A&ID symbols, and cross-density language links.

Authority — Dreamineering Symbols, sourced from src/pages/agents/_dreamineering-symbols.data.ts; cross-density bindings live in src/pages/agents/_language-crosswalk.data.ts.

Rule — add a symbol only when agents need compact notation. A canonical term can exist without a DML symbol.

Skills

Class — reusable agent capabilities, skill folder names, trigger language, and SKILL.md contracts.

Authority — this page's Agent Skills section for folder patterns; each skill's SKILL.md frontmatter for trigger and scope.

Rule — name the capability by cluster-job or verb-object. Search existing skill triggers before creating another name.

Components

Class — React primitives, composites, page-private components, design tokens, and visual-system contracts.

Authority — this page's React Components section and src/components/DESIGN.md.

Rule — classify primitive, composite, or page-private before naming. Promote page-private components when reuse crosses the second page.

Generated Docs Navigation Data

Class — docs manifest, docs projections, sidebar/menu data, and generated navigation artifacts.

Authority — scripts/artifacts/generate-playbook-manifest.mjs and the generated files under src/data/playbook-navigation/.

Rule — never hand-author generated navigation as canon. Change source frontmatter or the generator, then regenerate or run the generator check.

Private Project State

Class — plans, demand stories, decisions, delivery traces, project status, and engineering handoff state.

Authority — the drmg operating system and its schemas, run from /home/wik/code/sm/stackmates.

Rule — keep private state out of public docs. Use public docs only for reusable patterns, not project-specific state.

Agent Profiles And Command Wrappers

Class — agent profile files and human-invoked command wrapper names.

Authority — this page's Agent Profiles and Command Wrappers rules; local agent or wrapper contracts own narrower fields.

Rule — profile filename and frontmatter name match exactly. Command wrappers use stable verb-object or domain-prefix names.

Workchart Modules And Handoff Cards

Class — reusable Workchart Modules, bound Workflow Tasks, and Stackmates engineering handoff cards.

Authority — this page's Workchart Modules and Stackmates Handoff Cards sections; execution state belongs to the operating system.

Rule — name durable capability classes, not host phases. Handoff cards use P-NNN-{slug}.md only in the engineering handoff lane.

Operations Vocabulary

Use these terms with precision. Substitutes leak meaning.

• Standard — measurable compliance contract. Not "policy", "guideline", or "rule".
• Process — flow from trigger to outcome. Not "system" or "function".
• Workflow — one executable activity. Not "SOP", "procedure", or "playbook".
• Checklist — verification of work. Not the work itself.
• Protocol — sequenced principles under defined conditions (coordination, governance).
• Playbook — a collection of related workflows for one function.
• Practice — informal pattern not yet hardened to a standard.
• Workchart — a flow.json Spine that references reusable Modules as nodes. Public label: "work chart" / "Work Mapping".
• Unit of Work — the smallest action of value. A skill executes one. A module templates one. Do not call it a skill, module, task, job, or step unless the narrower artifact type is the point.

Hierarchies:

STANDARD (Why) → PROCESS (What) → WORKFLOW (How) → CHECKLIST (Verify)
UNIT OF WORK → WORKFLOW → PROCESS → WORKCHART → BUSINESS OPERATING MODEL

Casing Signal

Casing carries semantic weight across the repo.

Rules:

• UPPERCASE — root standard, operating substrate, or forcing-function. Reading the name reminds the agent of the discipline.
• lowercase — utility, infrastructure, scoped override, or configuration.
• UPPERCASE is reserved for names that act as a forcing function. Do not UPPERCASE for emphasis.
• Do not mix casing within one set — a sibling in lowercase stays lowercase unless explicitly promoted to root-standard.

Examples:

DESIGN.md      CLAUDE.md      ← root standards
design.md      agent config folders      ← scoped or utility

Files And Folders

Rules:

• Folders use kebab-case.
• Files use kebab-case.md or kebab-case.mdx unless a narrower rule overrides.
• Index files: index.md or index.mdx for docs hubs; index.tsx for routed React pages.
• Forbidden in Markdown paths: spaces, underscores, camelCase, PascalCase.

Examples:

docs/systems/process-optimisation/
.agents/skills/validate-demand/
private venture design memory
naming-standards.mdx
process-optimisation.md
2026-05-23-stackmates-01-demand-triage.md

Folder Structure

Folder structure is taxonomy before nomenclature. Decide the classification axis before naming the folder.

Decision order:

1. Surface — route by owning surface first: /playbook, /rhetoric, /src/pages, /src/components, src/data, .FLOW, or durable CLI state.
2. Lifecycle — split when edit rules differ: generated, source, api, fixture, parked.
3. Domain — split when siblings share one lifecycle and audience: prds, ventures, prompt-decks, industries.
4. 5P frame — use principles, performance, platform, process, players when a subject of consequence needs a Tight Five journey.
5. Time — use dated folders or slugs only for articles, logs, receipts, and time-bound traces.

For data shelves, "like data" can outrank lifecycle when one consumer expects a coherent family. Keep PRDs with PRDs, prompt decks with prompt decks, and playbook-navigation data with playbook-navigation data. Use lifecycle as a folder only when the edit rule is so different that colocating files would cause mistakes.

Knowledge schema test:

Use the Knowledge Schema before creating a new folder.

Gap type	Folder action
Direct mapping	Mirror the nearest established pattern.
Different model	Document why this folder axis differs before adding more siblings.
Absence	Do not create a folder for concepts the target surface does not need.
Genuinely new	Add a local README.md, _category_.json, or contract first.

Depth rules:

• Discoverable knowledge areas default to three levels deep or less.
• Deeper structures are allowed for generated artifacts, code modules, and domain catalogs only when an index or README explains the route.
• Every non-obvious folder needs a local contract: README.md for data/code, _category_.json for docs navigation, or a scoped agent instruction file where the surface requires it.
• Do not create misc, common, stuff, archive, or legacy-data buckets. Use parked only with a connect/delete/offload decision.
• If a folder exists only because one file has no home, keep the file flat until the second real sibling appears.
• Use a prefix when related files must stay flat for compatibility; use a folder when there are three or more siblings, a folder API, or a different validation contract.

Situational wisdom test:

A good folder helps the next reader or agent choose the right action in context. Before moving files, ask:

• What decision does this structure make easier?
• Which consumer proves this grouping is real?
• What stale path will rg catch after the move?
• Can a reader reach the right next five items without opening the whole tree?

Repo Surfaces

Each surface owns one kind of content with one naming rule. Use the surface, do not infer scope from channel names.

/playbook/

• Owns — evergreen explanation, standards, guides, reference.
• Naming — kebab-case folders; index.md or index.mdx for hubs.

/rhetoric/

• Owns — published narrative, dated insights, arguments.
• Naming — numbered or dated article slugs; never use as raw working memory.

/src/pages/

• Owns — public decision and product surfaces.
• Naming — route folders in kebab-case; page code in index.tsx where routed.

/src/components/

• Owns — React components and design primitives.
• Naming — PascalCase.tsx; public imports through barrels.

.agents/skills/

• Owns — reusable agent capabilities.
• Naming — skill folders in kebab-case; one SKILL.md per skill.

Agent profiles

• Owns — Claude sub-agent profiles.
• Naming — {domain-or-role}-{function}.md; frontmatter name matches filename.

Command wrappers

• Owns — human-invoked command wrappers.
• Naming — verb-object.md or stable domain prefix.

Stackmates engineering handoff lane

• Owns — stackmates engineering handoff lane.
• Naming — product-lead only; station folders with P-NNN-{slug}.md cards.

Scope Test

Channel labels (cli, prod, chain, mkt, flow) are not enough. The test is where the code change lands.

• Resolves by changing /home/wik/code/drmg/drmg-mental-model/ only → dream repo work; stage and route per flow-routing rule.
• Resolves by changing /home/wik/code/sm/stackmates/ → route to product-lead for stackmates card authoring.

Artifact Naming

Stackmates Handoff Cards

The stackmates lane is only for work requiring code changes in /home/wik/code/sm/stackmates/.

Rules:

• Only product-lead may create, edit, or promote cards in this lane.
• state: frontmatter equals the enclosing station folder.
• One P-NNN card exists in only one station at a time.
• Promotion is a move, not a copy.
• Dream-only work never enters this lane.

Pattern:

private handoff lane/
  01-demand/
  02-delivery-plan/
  03-priority-value/
  04-in-progress/
  05-qa-commissioning/
    P-NNN-{slug}.md

Frontmatter:

---
id: P-NNN
state: 01-demand
title: Human-readable demand title
---

Examples:

private handoff lane / 01-demand / P-006-control-system-recalibration.md
private handoff lane / 04-in-progress / P-014-agent-receipt-v2.md

Enforcement — write-time gate in agent hooks; station rules live beside the private handoff lane.

Agent Profiles

Agent files live in the agent profile folder.

Rules:

• Filename is lowercase and hyphenated.
• Frontmatter name exactly matches the filename without .md.
• Description has three sentences: what it does, when to invoke it, when not to invoke it.
• permissionMode, tools, and disallowedTools match the smallest workable authority.
• New or audited agents declare artifact_outputs, route_on_success, and route_on_failure.

Pattern:

.claude/agents/{domain-or-role}-{function}.md

Examples:

.claude/agents/priorities-nav.md
.claude/agents/product-lead.md
.claude/agents/eng-systems-lead.md
.claude/agents/drmg-language-curator.md

SSOT — .claude/agents/_template.md. Audit checklist — .claude/agents/CLAUDE.md.

Agent Skills

Skill directories live in .agents/skills/ and use kebab-case.

Rules — two naming patterns:

• {cluster}-{job} — skill belongs to a named pipeline or system.
• {verb}-{object} — skill is a standalone cross-cluster action.

Rules — mode suffixes:

• none — strategy or full execution.
• -audit — diagnostic only.
• -loop — repeating cycle.

Before creating, check for overlap:

rg "Activates for|description:" .agents/skills/*/SKILL.md

If the trigger overlaps an existing skill in the same cluster, merge or sharpen the boundary instead of adding another name.

Examples:

.agents/skills/rfp-intake/SKILL.md                ← cluster-job
.agents/skills/stackmates-comms-post/SKILL.md     ← cluster-job
.agents/skills/sui-move-patterns/SKILL.md         ← cluster-job
.agents/skills/create-prd/SKILL.md                ← verb-object
.agents/skills/fix-links/SKILL.md                 ← verb-object
.agents/skills/validate-demand/SKILL.md           ← verb-object
.agents/skills/seo/SKILL.md                       ← no suffix
.agents/skills/seo-audit/SKILL.md                 ← -audit suffix
.agents/skills/design-critique-loop/SKILL.md      ← -loop suffix

Workchart Modules

A Module is a reusable capability bundle a Workchart composes — the class. A host workflow-task is the bound instance. Use Module, not "unit", "work unit", "plugin", or "package".

Required files — every Module:

• CLAUDE.md — human-readable module contract, adoption rules, anti-patterns.
• task.json — unbound Workflow Task template; host assigns id, phase, step, depends_on.

Conditional files — add only when the Module emits a structured result or a score/verdict:

• schema.json — output/result schema fragment; hosts $ref this file.
• calibration-anchors.md — scoring anchors, gates, rubrics.

Rules — folder naming, choose one:

• {object}-{function} — module gates, scores, verifies, or transforms one reusable object.
• {domain}-{investigation} — module investigates a reusable opportunity or risk across many host workcharts.

Rules — composition:

• Name the durable capability, not the host phase.
• Folder is noun-led. Put the execution verb in task.json as verb + object.
• Use a stable prefix that search can route.
• Do not include host workchart names in module folders unless intentionally host-specific.
• Do not name a Module task, unit, common, shared, helper, or util.
• If a Module emits a score or verdict, document the compute rule in CLAUDE.md and the anchors in calibration-anchors.md.

React Components

Rules — three layers:

• Primitive — src/components/design-system/. Atomic, no business meaning.
• Composite — src/components/{domain}/. Reused by multiple pages.
• Page-private — src/pages/{route}/_components/. Used by one page only.

Rules — casing:

• Files use PascalCase.tsx.
• Folders use kebab-case.
• Promotion rule — if a page-private component is imported by a second page, move it to src/components/{domain}/ in the same change.

Examples:

src/components/design-system/Button.tsx
src/components/venture/VentureCard.tsx
src/pages/vessel/_components/Hero.tsx

Templates

Blank stencils use underscore prefix and -template suffix.

Rules:

• Underscore prefix sorts utility files above content.
• -template suffix names the intent.
• Never ship a filled artifact with a template filename.

Pattern:

_{slug}-template.md

Design Memory

Uppercase DESIGN.md means root standard. Lowercase design.md means scoped override.

Rules — scope and path:

• System design bible — src/components/DESIGN.md
• Per-venture override — private venture design memory
• Per-workchart override — design.md scoped to the workchart folder.
• Per-deck override — src/components/{deck}/design.md

Examples:

src/components/DESIGN.md
src/components/journeys/design.md

Frontmatter

Rules:

• Use existing tags before creating new ones.
• Tags are singular where possible.
• Tags capitalised unless the term is a canonical acronym.

Pattern:

---
title: Page Title
sidebar_label: Short Label
description: SEO description
tags:
  - Standards
---

Canonical Language

Use the DDL and symbol surfaces before adding or renaming cross-domain terms. Update the data source first; rendered or prose explanations follow.

• /agents/ddl-nomenclature — human-readable canonical language.
• /agents/dreamineering-symbols — DML wire-format decoder.
• src/pages/agents/_ddl-nomenclature.data.ts — DDL source of truth.
• src/pages/agents/_dreamineering-symbols.data.ts — DML source of truth.
• src/pages/agents/_language-crosswalk.data.ts — DDL to DML to A&ID crosswalk.

Ontology

The relationship layer behind the names. Every naming rule should make one of these relationships easier to verify. This is a genuine reference grid — row × column intersection is the point.

Relationship	Example	Encoded By
standard GOVERNS artifact	Naming Standards governs skill names	This page and hooks
agent EMITS artifact	product-lead emits a stackmates card	Agent contract fields
card MOVES_TO station	01-demand → 02-delivery-plan	Stackmates station rules
term HAS wire_code	DDL term has DML code	Language crosswalk data
receipt VERIFIES outcome	A receipt proves a loop iteration	Receipt store

Search & Verify

Rules — names should be:

• Stable enough to survive scope changes.
• Specific enough to avoid false positives.
• Short enough to scan in file listings.
• Predictable enough that the next agent can guess them.

Examples — prefix search:

rg "P-057" <private-handoff-lane>
rg "artifact_outputs" <agent-profile-folder>
rg "stackmates-" .agents/skills
rg "blueprint-finance-" docs <private-project-state>

Audit questions:

• Where do two names point to the same concept?
• Where does one name hide two different concepts?
• Which naming drift would break an agent route, a hook, or a search query?
• What source of truth should be updated before any mirror page changes?

Change Log

Date	Change	Reason
2026-05-27	Split rules from examples per artifact section; restructured for mobile-first IA	Tables broke 320px viewport; rule-vs-example separation aids scan
2026-05-24	Added first-class Workchart Module naming convention	Make reusable Modules composable across spines without naming drift
2026-05-23	Reframed page as agent-first operational standard and replaced retired production path with _drmg-mental-model_ / stackmates lane rules	Align naming standards with current repo structure and author gates
2026-05-18	Locked React component taxonomy and promotion rule	Prevent flat component drift
2026-05	Added utility template convention	Keep stencils distinct from filled artifacts
2026-02	Added taxonomy, nomenclature, ontology framework	Separate structure, labels, and semantics
2025-12	Adopted 5P folder structure standard	Provide reusable domain schema
2024-12	Established operations terminology hierarchy	Standardize process documentation

Context

• Standards — standards hub.
• Process Optimisation — operational hierarchy.
• Protocols — coordination standards.
• Matrix Thinking — naming as grid resolution.
• DDL Nomenclature — canonical cross-domain language.