Base/Extension
Problem
A shared standard has to be stable enough that teams can build on it, but flexible enough to handle work the authors never imagined. If every team changes the core, nothing lines up across projects. If the core is locked down, teams can’t capture the things their work actually needs — and the standard stops being useful.
Solution
aDNA separates entity types into a base layer (14 types defined by the spec) and an extension layer (domain-specific types added by projects). The rule (§5): extensions MUST NOT modify base types — they add alongside them.
Base layer (shared across all aDNA instances):
| Triad | Base Entities |
|---|---|
| WHO | governance, team, coordination |
| WHAT | context, decisions, modules, lattices |
| HOW | campaigns, missions, sessions, templates, skills, pipelines, backlog |
Extension rules:
- New types go under the correct triad leg (apply the question test)
- Each extension type gets its own subdirectory under the triad leg
- Each subdirectory gets an AGENTS.md and a template
- Extension types use the same frontmatter conventions as base types (
type,created,updated,status,last_edited_by,tags) - Base types are never modified, renamed, or removed
This gives projects full freedom to represent their domain while preserving the shared vocabulary that makes cross-project tools and agent orientation possible.
When to Use
- When a project needs to represent domain knowledge that doesn’t fit existing entity types
- When forking the base template into a new project
- When designing ontology for a new domain (biotech, education, legal, etc.)
- When evaluating whether a proposed change belongs in the base spec or as a project extension
Example: This Vault
This vault (aDNA.aDNA/) extends the base 14 types with 10 project-specific types:
| Extension | Triad | Directory | Purpose |
|---|---|---|---|
concept | WHAT | what/concepts/ | Core aDNA concepts at dual-audience depth |
tutorial | WHAT | what/tutorials/ | Step-by-step learning paths |
pattern | WHAT | what/patterns/ | Reusable architectural patterns (you’re reading one) |
glossary_entry | WHAT | what/glossary/ | Canonical term definitions |
use_case | WHAT | what/use_cases/ | Adoption stories by domain |
comparison | WHAT | what/comparisons/ | aDNA vs. other architectures |
community | WHO | who/community/ | Community roles and contribution paths |
adopter | WHO | who/adopters/ | Adopter personas and deployment profiles |
workshop | HOW | how/workshops/ | Workshop kits and facilitation guides |
publishing | HOW | how/publishing/ | Vault-to-web publishing pipeline |
Each extension directory has an AGENTS.md and a template in how/templates/. The base types (context, campaigns, missions, sessions, etc.) are unchanged — they work exactly as the spec defines. An agent familiar with any aDNA project can navigate the base layer here; the extensions are additive.
Anti-Pattern
Modifying base types: Renaming sessions to logs or changing the missions frontmatter schema. This breaks every tool and agent that expects the standard vocabulary.
Extension sprawl: Creating 30 extension types for a project that only needs 5. Each type requires a directory, AGENTS.md, and template — the overhead compounds. Only extend when existing types genuinely don’t fit.
Extension without AGENTS.md: Adding a new directory under what/ without creating an AGENTS.md. The extension exists structurally but is invisible to agents following the routing protocol.
Triad misplacement: Creating an extension type under the wrong leg (e.g., community under HOW instead of WHO). Apply the question test — “Who is involved?” → WHO.
Related
- Ontology — the entity type system that base/extension partitions
- Open Standard — the governance model that keeps the base stable
- Question Test — how to determine which triad leg an extension belongs under