Naming Standards

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

Five 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. Stop at the first rule that resolves the name.

1. Surface — which repo path owns this? Use the Repo Surfaces section.
2. Kind — concept, artifact, or work item? Concepts → DDL/glossaries. Artifacts → file conventions. Work items → lane rules.
3. Pattern — use the narrowest existing pattern before inventing a new one.
4. Prefix — a related set must be findable with one stable prefix.
5. SSOT — 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.

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

Repo Surfaces

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

/docs/

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

/meta/

• 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.