Get Started
In this section
Back to reference

6. Naming Conventions

aDNA Specification v2.5 Section 6 of 20 Full text

Scan: Underscores not hyphens, type_descriptive_name.md pattern, ALLCAPS governance list, directory naming, type_ prefix convention.

Decisions: C3

6.1 File Naming

Content files MUST use underscores for word separation. Hyphens MUST NOT be used in aDNA content files.

Pattern: type_descriptive_name.md

Examples:

  • mission_adna_standard.md
  • session_{username}_20260211_120000_gap_analysis.md
  • customer_acme_corp.md
  • context_research_ancient_dna.md

Exception: Code-adjacent files in the project content layer (not inside the triad) MAY use hyphens to respect ecosystem conventions (npm, pip, etc.).

Exception: Tool-generated files (e.g., how/tasks/ with plugin-generated names) MAY retain their generated naming format.

6.2 Governance File Naming

Governance files MUST use ALLCAPS names. The exhaustive list:

  • CLAUDE.md
  • MANIFEST.md
  • STATE.md
  • AGENTS.md
  • README.md

No other files SHOULD use ALLCAPS naming. This list MUST NOT be extended without a standard revision.

6.3 Directory Naming

Directories MUST use lowercase with underscores: context_library/, missions/.

Exception: .agentic/ uses a dot prefix (embedded triad convention).

6.4 Type Prefix Convention

The type_ prefix pattern is RECOMMENDED for aDNA content files. It enables sorting, filtering, and at-a-glance identification. Common prefixes:

PrefixContent
mission_Missions (legacy: plan_)
session_Session files
template_Templates
customer_Customer records
context_Context library files
idea_Backlog ideas
skill_Skill procedures

6.5 Rename Protocol

When a vault, project, or persona is renamed, the rename MUST, at rename-time, sweep the vault’s own live-routing governance files (CLAUDE.md, STATE.md, AGENTS.md) of self-references to the old name. A vault whose routing files still point at its prior identity is out-by-event (OBE) residue — masked when a back-compat shim keeps the stale references resolving, which is exactly why the sweep is mandatory rather than incidental.

Scope discipline (the load-bearing rule): the sweep targets the live-routing self-reference subset ONLY — a file’s own governance/routing prose that names the vault. It MUST NOT rewrite legitimate historical cross-references: provenance prose, session history, ADR lineage, and changelog entries are retained verbatim (archive-don’t-delete, §15). A naive whole-vault grep over-counts the defect by sweeping this history; the rename recipe carries a keep/strip classifier to separate the two.

Recipe: how/skills/skill_project_rename.md. Decision: ADR-042.