5. Directory Structure

aDNA Specification · v2.5 · Section 5 of 20 · Full text

Scan: Required/recommended/optional subdirectories for each triad leg, registry pattern, ontology artifact, starter/standard/full skeletons.

Decisions: C5, C6, C7, C11, C12, C14, C15

5.1 what/ — Knowledge Layer

what/ contains everything the project KNOWS.

Required subdirectories:

Recommended subdirectories:

Optional subdirectories (add based on project domain):

Registry pattern: what/ serves as a registry layer. Entries in what/ subfolders describe and link to objects — they do not duplicate source material. Example registry entry:

# what/models/model_llama_3.md
---
type: model
status: active
source: "src/models/llama3/"    # link to implementation
tags: [model, llm, inference]
---
Brief description, capabilities, constraints. Links to source — does not duplicate code.

Ontology artifact: An aDNA instance SHOULD include what/ontology.md with a Mermaid ER diagram mapping entity types, triad categories, and relationships. Minimal skeleton:

erDiagram
    what ||--o{ context : contains
    what ||--o{ decisions : contains
    what ||--o{ inventory : contains
    what ||--o{ domain_entities : contains
    how ||--o{ missions : contains
    how ||--o{ sessions : contains
    how ||--o{ templates : contains
    how ||--o{ pipelines : contains
    how ||--o{ skills : contains
    how ||--o{ backlog : contains
    who ||--o{ coordination : contains
    who ||--o{ governance : contains
    who ||--o{ identity : contains
    who ||--o{ people : contains
    missions ||--o{ sessions : "tracked by"
    sessions ||--o{ coordination : "may produce"
    pipelines ||--o{ stages : "flow through"
    campaigns ||--o{ missions : "decompose into"
    missions ||--o{ objectives : "decompose into"

Projects extend this skeleton with domain-specific entities (e.g., customers, models, hardware). Knowledge-base environments MAY additionally maintain what/ontology.canvas for interactive exploration.

5.2 who/ — Organization Layer

who/ contains everything about WHO is involved and WHY.

Required subdirectories:

Optional subdirectories (add based on organizational needs):

5.3 how/ — Operations Layer

how/ contains everything about HOW the project works.

Required subdirectories:

Recommended subdirectories:

Optional subdirectories:

5.4 Universal Skeleton

The minimum viable aDNA instance. Graduated by project complexity:

Starter Skeleton (minimum for any aDNA project):

{root}/
├── CLAUDE.md
├── MANIFEST.md
├── README.md
├── what/
│   └── context/
├── how/
│   ├── missions/
│   ├── sessions/
│   └── templates/
└── who/
    ├── coordination/
    └── governance/

Standard Skeleton (active multi-agent projects — adds STATE.md, AGENTS.md, backlog):

{root}/
├── CLAUDE.md
├── MANIFEST.md
├── STATE.md
├── AGENTS.md
├── README.md
├── what/
│   ├── AGENTS.md
│   ├── context/
│   │   └── AGENTS.md
│   └── decisions/
├── how/
│   ├── AGENTS.md
│   ├── missions/
│   ├── sessions/
│   │   ├── active/
│   │   └── history/
│   ├── templates/
│   └── backlog/
└── who/
    ├── AGENTS.md
    ├── coordination/
    └── governance/

Full Skeleton (large projects — adds domain-specific directories):

Extends the Standard Skeleton with project-specific subdirectories in each triad leg. Examples: what/models/, what/hardware/, who/customers/, how/pipelines/, how/skills/.

For embedded triad deployments, the same skeletons apply inside .agentic/, with governance files remaining at the repository root.

5.5 Conformance Levels

The skeletons defined in §5.4 establish three normative conformance levels. A project claiming aDNA conformance MUST satisfy all MUST requirements at its declared level.

Level 1: Starter Conformance

An aDNA instance at Starter conformance MUST have:

1. Governance files: CLAUDE.md, MANIFEST.md, README.md at the root (bare) or repository root (embedded)
2. Triad directories: what/, how/, who/ (bare) or .agentic/what/, .agentic/how/, .agentic/who/ (embedded)
3. Required subdirectories: what/context/, how/missions/, how/sessions/, how/templates/, who/coordination/, who/governance/
4. Frontmatter: All content files inside the triad MUST include the base fields defined in §7.2, per its per-class profile (type, status, created, updated, last_edited_by, tags; status optional for directory_index + coordination — v2.5, ADR-044)

Starter conformance represents the minimum viable aDNA instance — sufficient for a single-agent project with basic session tracking.

Conformance-walk scope (v2.5, ADR-044): a conformance run validates the instance rooted at the directory being checked; it does NOT recurse into embedded standalone instances (in the reference vault: what/docs/examples/ and how/templates/template_node_adna_exemplar/). Each embedded instance is validated standalone if desired.

Level 2: Standard Conformance

An aDNA instance at Standard conformance MUST satisfy all Starter requirements AND:

5. Additional governance files: STATE.md and a root AGENTS.md
6. Per-directory AGENTS.md: Every triad leg (what/, how/, who/) MUST have an AGENTS.md file
7. Recommended directories: what/decisions/, how/backlog/, how/sessions/active/, how/sessions/history/
8. Session lifecycle: Sessions MUST follow the lifecycle defined in §8 (creation → execution → close-out with SITREP)

Standard conformance represents an active multi-agent project with operational discipline.

Level 3: Full Conformance

An aDNA instance at Full conformance MUST satisfy all Standard requirements AND:

9. Context library: what/context/ MUST contain at least one topic directory with its own AGENTS.md and at least one context file with token_estimate in frontmatter
10. FAIR metadata: Deployable objects (modules, datasets, lattices) MUST include a fair: frontmatter block with at minimum keywords and license
11. Ontology artifact: what/ontology.md MUST exist with a Mermaid ER diagram (per §5.1)
12. Template compliance: All content types used in the project MUST have corresponding templates in how/templates/

Full conformance represents a mature, federatable aDNA instance ready for cross-instance interoperation.

Conformance Declaration

Projects MAY declare their conformance level in MANIFEST.md using the adna_conformance frontmatter field:

adna_conformance: starter  # or: standard, full

An instance that does not declare a conformance level is assumed to be unverified. The adna_validate.py tool (see what/lattices/tools/) can determine conformance level programmatically.