# aDNA — Agentic DNA Knowledge Architecture (full corpus)
> An open standard for organizing project knowledge so both humans and AI agents can navigate it. Clone-and-run: one command gives you the standard, the skills, and the templates — ready for an agent. Local-first; federation is opt-in.
State is a build-time snapshot generated 2026-09-11 (UTC); nothing here is live.
Every page of this site follows, in path order, as markdown. Each page is also available on its
own at the same URL with a `.md` suffix, or by sending `Accept: text/markdown` to the HTML URL.
The curated short index is at https://adna.network/llms.txt.
## Install
```
git clone https://github.com/aDNA-Network/aDNA.git ~/aDNA && cd ~/aDNA && claude
```
## Standard
- Version: v2.5 (16 base entity types, 3 conformance levels)
- License: MIT
- Repository: https://github.com/aDNA-Network/aDNA
- Published by: aDNA Network
## Key routes
- [Home](https://adna.network/)
- [Get started](https://adna.network/get-started)
- [Learn: What is aDNA?](https://adna.network/learn/what-is-adna) — and the Learn hub (concepts, tutorials, comparisons)
- [How-to guides](https://adna.network/how) — publishing, workshops, lattice examples
- [Patterns](https://adna.network/patterns)
- [Use cases](https://adna.network/use-cases)
- [Reference / specification](https://adna.network/reference/specification)
- [Glossary](https://adna.network/glossary)
- [The network](https://adna.network/network)
- [Vaults registry](https://adna.network/vaults)
- [Network graph](https://adna.network/vaults/graph)
- [Commons](https://adna.network/commons)
- [Community](https://adna.network/community)
- [Provenance & audit](https://adna.network/provenance-audit) — how session records and governance files answer the five questions an audit reviewer asks
- [State of the network](https://adna.network/state-of-the-network) — dated disclosure: what runs, what is operator-operated, what is not ours, what is planned
- [Canonical properties](https://adna.network/canonical-properties) — every legitimate aDNA domain, repository, organization and machine surface
## Vault taxonomy (74 vaults)
- platform (36)
- forge (9)
- framework (7)
- org vault (7)
- org graph (4)
- genesis-planning (3)
- coordination (1)
- framework (candidate) (1)
- knowledge graph (1)
- network (1)
- node (operational) (1)
- standard (1)
- tooling (1)
- workspace (1)
## Edge types (14 cited relationships)
- umbrella (1): an org-vault contains its org-graph / pillar children
- federation (9): a consumer wrapper depends on the forge / framework it consumes
- partner (0): a platform ships with its default partner
- companion (4): a sibling persona-pair or thematic family
- supersedes (0): a successor replaced its predecessor (lifecycle)
---
## https://adna.network/
*[image: A pixel-art hero in the Tokyo Night palette: a glowing cyan DNA double-helix rising from a row of small computers and branching at the top into a network of connected nodes — shared inheritance resolving into the aDNA network.]*
Open standard · MIT
# The aDNA Network
aDNA (agentic DNA) is an open standard for organizing a project's files, so that AI agents and the people working with them can always find what they need. Three folders, plain Markdown, tracked in git. This site is the standard itself, its docs, and the registry of the workspaces — 'vaults' — that run it.
For teams working with agentic coding tools on real projects. Not a product or service — no server, no signup; aDNA itself sends nothing.
Your context is just the notes, docs and decisions you already keep — now in a shape your agents can follow. The standard that gives it that shape is open. Your files stay on your machine.
[Explore the network](/vaults) [Get Started](/get-started)
$ `git clone https://github.com/aDNA-Network/aDNA.git ~/aDNA && cd ~/aDNA && claude`
[Open source on GitHub](https://github.com/aDNA-Network/aDNA) · MIT-licensed · [the standard, versioned and public](/reference/specification)
74 vaults — every one of them on a single computer, ours. 15 are joined by 14 declared relationships; the rest stand alone.
[The state of the network, dated →](/state-of-the-network/) [Who's behind aDNA →](/about/)
74 Vaults
16 [Entity Types](/learn/what-is-adna#entity-types)
3 [Conformance Levels](/glossary/glossary-conformance-level/)
v2.5 Current Version
MIT Licensed
The connected aDNA network — 15 vaults joined by 14 relationshipsA compact radial map of the live aDNA network: 15 vaults are joined by 14 cited relationships (umbrella, federation, partner, companion) and drawn as a burst around the most-federated hubs (III and Astro), with the standard, aDNA, at the core. Each box names a vault and its persona; the full vault list at /vaults/graph is the keyboard-navigable twin.
- aDNA.aDNARosettaIII.aDNAArgusWilhelmAI.aDNAHygieiaRareArchive.aDNAMnemosyneAstro.aDNAMolecules.aDNAFranklinTappProtocol.aDNAMentorVAAS.aDNAHarness.aDNAPanaceaOration.aDNARobert KennedyScienceStanley.aDNAZenZachary.aDNApygmalionVisualDNA.aDNApygmalionRemoteControl.aDNATalosTerminal.aDNAberthier
15 connected vaults · 14 relationships
Language and DNA were co-created by everyone before us. The context that powers AI should be
too — built, shared, and governed in the open, for the good of all.
You already do the first half of this. The README that explains the project. The decision
someone wrote down so nobody re-litigates it. The note on why the schema is shaped the way it
is. That is context — aDNA gives it a shape your agents can read, in the open, in your own
repository.
## What a context democracy is
People and their agents keep their own project context, in the open, and no one
company owns the whole of it. Each project keeps its own files. Projects cite each
other, and what they choose to share becomes a commons anyone can read.
**Open**MIT-licensed — the spec, the workspace image, and the registry data are public.
- **Federated**Each project keeps its own graph; they connect by citation, not central control.
- **Co-owned**No vendor owns your context — you govern it, in the open.
- **Agents & humans**One graph, legible to your AI and to you at the same time.
The aDNA network
Real aDNA vaults — Astro, III, RareHarness, wga, RareArchive, Home — connected around the aDNA core by the relationships they declare.
- Astro III RareHarness wga RareArchive Home aDNA the network The aDNA network
Real aDNA vaults — Astro, III, RareHarness, wga, RareArchive, Home — connected around the aDNA core by the relationships they declare.
Astro III RareHarness wga RareArchive Home aDNA the network
Real aDNA vaults — forges, frameworks, platforms, and public-good archives —
connected by the relationships they declare.
## The living registry
Every vault is a real, governed context graph with its own place in the network. Most are
tended by a named agent — an [AI persona](/about/#agent-stewards), not a person. Here's a slice across 74 of them.
All of them run on one computer — ours.
[The state of the network](/state-of-the-network/) says what
that means.
[the standard in use ### aDNA tended by Rosetta Open vault →](/vaults/adna/)[framework in use ### III tended by Argus Inspect/Introspect/Improve quality framework Open vault →](/vaults/iii/)[platform planned ### Canvas tended by Mondrian Open vault →](/vaults/canvas/)[coordination in use ### Operations tended by Berthier Open vault →](/vaults/operations/)[knowledge graph in use ### LA Venture Graph tended by Cartographer LA venture ecosystem knowledge graph (UCLA Anderson + Nerdstage/Demo Day LA) Open vault →](/vaults/laventuregraph/)[node in use ### Home tended by Hestia Open vault →](/vaults/home/)[org vault chartered ### wga World Genome Academy — buildpack + symphony + site Open vault →](/vaults/wga/)[org vault chartered ### RareArchive tended by Mnemosyne Rare Archive OSS rare-disease AI project Open vault →](/vaults/rarearchive/) [See all 74 vaults →](/vaults/) · [View the relationship graph →](/vaults/graph/)
## How it Works
Three steps from scattered files to a project your agents can navigate — and keep navigating. **Agent-native** [Governance files](/glossary/glossary-governance-file/) and typed context give agents orientation — no prompt re-engineering every session. **Human-readable** Every file is plain Markdown. Browse in Obsidian, VS Code, or GitHub. No proprietary formats, no lock-in. **Composable** A *module* is one capability, a *dataset* is data it works on, and a *lattice* wires modules into a workflow. Start small, and grow to multi-team campaigns using the same three pieces. 01
### Structure
Every agent session starts from scratch — agents relearn your project by rummaging through files. aDNA ends that. Three directories (what you know, how you work, who's involved) give any agent instant orientation.
aDNA.aDNA/
```
aDNA.aDNA/
├── CLAUDE.md ← agent operating protocol
├── STATE.md ← current phase, blockers
├── what/ ← what the project knows
│ ├── context/ typed context library
│ └── decisions/ architecture records
├── how/ ← how it operates
│ ├── campaigns/ strategic initiatives
│ └── missions/ decomposed work
└── who/ ← who's involved
└── governance/ roles & policy
```
02
### Orient
Without a map, agents blast through irrelevant files or ask you to re-explain the project. Agents read your CLAUDE.md and [AGENTS.md](/glossary/glossary-agents-md/) first, then pull typed context at exactly the depth they need — not your entire repo, not a blank slate.
aDNA.aDNA/CLAUDE.md
```
# CLAUDE.md — aDNA.aDNA
## Identity & Personality
You are Rosetta — named after the Rosetta
Stone. This vault presents the aDNA standard
in three registers: technical spec,
operational practice, plain language.
## Standing Orders
1. Phase gates are human gates.
2. Destructive actions require confirmation.
```
03
### Execute
Context windows close and wipe progress — the next agent starts over. aDNA decomposes work into sessions, missions, and campaigns — context-sized chunks that fit a single agent window. What one agent learns, the next inherits.
mission_wadna_p3_iterate.md
```
mission_id: mission_wadna_p3_iterate
phase: 3
status: in_progress
## Decade backbone
D1 Credibility-integrity — active
D2 Navigation & docs — queued
D3 Agentic + community — queued
D4 Visual craft — queued
```
### New to aDNA? Start here
Cloned the workspace image and want to understand it before you build? The standard
embeds in `.adna/`, and the guided path is here — a five-minute tour, the
core concepts, and hands-on tutorials.
[Learn aDNA](/learn) [What is aDNA? →](/learn/what-is-adna) [Tutorials →](/learn/tutorials)
Dive deeper: [Convergence Model](/learn/concepts/convergence) · [Concepts & Tutorials](/learn) · [Reference Specification](/reference)
## The Standard
aDNA is an open specification — MIT licensed, open to contribution, designed for extension. v2.5 MIT License Open Standard 16 Entity Types [Read the Specification](/reference/specification) [View on GitHub](https://github.com/aDNA-Network/aDNA)
## Built to be read by agents
This site is itself an aDNA vault — the structure it documents is the structure that
produced it. Each surface below is generated from the same source as the pages themselves,
so it cannot drift out of step with them.
[/llms.txt](/llms.txt)
A curated index of this site, written to be read by an agent rather than rendered.
[/llms-full.txt](/llms-full.txt) carries the whole corpus in one file.
- Markdown twins
Add `.md` to a documentation URL — or send `Accept: text/markdown` —
and get the source instead of the page. 226 pages have one.
- [/api/registry.v1.json](/api/registry.v1.json)
The vault registry as versioned JSON, so the network can be queried as data instead of
scraped out of HTML.
## Join the network
The network is open — run a node, share a vault, and help
[shape the standard](/reference/governance-model/).
Mission-aligned subnetworks are taking shape around real public-good work.
- [World Genome Academy](/commons/#featured) Genomics knowledge as a shared commons
- [Context Commons](/commons/#featured) Agentic-context literacy, shared
- [Wilhelm AI for the Undiagnosed](/commons/#featured) AI for people living with undiagnosed disease
- [Rare Archive](/commons/#featured) Open-source rare-disease AI
[See the commons](/commons/) [Join the community](/community/)
aDNA for [Solo Developer](/use-cases/solo-developer/)· [Enterprise Team](/use-cases/enterprise-team/)· [Educator](/use-cases/educator/)· [Startup](/use-cases/startup/)· [Researcher](/use-cases/research-lab/)
## What's new
- [Sep 11, 2026](/changelog) aDNA v8.11: a promise retired, and a dead link found
- [Sep 7, 2026](/changelog) Field speed data, and a v8.10 fix to the standard
- [Sep 4, 2026](/changelog) A promise the homepage could not keep
[Full changelog](/changelog) · [RSS feed](/rss.xml)
---
## https://adna.network/about/
# Who's behind aDNA
aDNA is early — and honest about it. Here are the real people behind the network
today, the agents that tend it, and how real leadership grows as the network does.
## The people today
A small, real founding core — named plainly, with nothing claimed we don't yet have.
### Stanley Bishop
Founding Architect, aDNA · Head of AI, Wilhelm Foundation · AI-Scientist in
Residence, UCLA Anderson Venture Accelerator
aDNA is stewarded today by one person, who holds decision authority over the standard
while the network is young. That's the honest current state — not a council we
haven't formed. The whole point of the roadmap below is to hand that authority to
stewardship as trusted stewards arrive.
[stanley.science ↗](https://www.stanley.science)
### The Wilhelm Foundation
Anchor partner · Helene & Mikk Cederroth
The network's anchor partner carries a real rare- and undiagnosed-disease mission. Their
work grounds two of the public-good subnetworks on aDNA — Wilhelm AI for the
Undiagnosed and the open Rare Archive. Note the overlap named above: aDNA's Founding
Architect also holds a role at the Foundation, so read this as a close relationship
rather than an independent organisation vouching for us.
[See the open Rare Archive ↗](https://github.com/Wilhelm-Foundation/rare-archive)
## The agent-stewards, honestly
Most vaults are “tended by” a named agent — and we name them as exactly that.
Rosetta tends this documentation. Argus tends the quality framework. Hestia tends the node
itself. These are **AI personas** — the agent-stewards of the current
build. They are a real, distinctive feature of an agent-native network, not a stand-in for
people and not a claim of a team we don't have.
They hold the seat. As real stewards join, they take the roles the agents keep —
which is the same trajectory as the governance roadmap below: **humanization and
decentralization are the same curve.**
ℹ Why name the agents at all?
Because it's true, and because it's how the work actually gets done here. Hiding it would
be less honest, not more credible. What you should *not* read into the personas is a
larger organization than the founding core above — there isn't one yet, and this page
says so plainly.
## Where leadership is going
aDNA is committed to **progressive decentralization**. Governance and real
leadership grow along the same curve — earned as stewards arrive, not asserted before.
- 1
### Founding Architect today
A single steward holds decision authority while the network is young.
- 2
### Increasing trusted stewards
Mission-aligned stewards take on real decisions — as far as is helpful and
positive, at the Founding Architect's discretion.
- 3
### Discretion turned over to stewardship
The authority itself passes to the stewards, not held back by any one architect.
- 4
### Steward-led, democratic, public
The destination: a protocol and network governed by the communities closest to it.
We look for stewards among the people closest to the network's core missions —
**rare disease**, **undiagnosed disease**, and
**biodiversity protection** (via conservation genomics, coherent with the
genome/DNA framing).
[Read the full governance roadmap →](/reference/governance-model/)
## The public-good work, and what you can check
4 subnetworks are declared on this network. 2 have
something you can open today; the rest do not yet. Each row says which.
- ### World Genome Academy
Genomics education & research [Open it ↗](https://worldgeno.me)
- ### Context Commons
Community agentic-literacy & enablement
No public site yet — this subnetwork is still being set up.
- ### Wilhelm AI for the Undiagnosed
People & families living with undiagnosed disease Wilhelm Foundation (Helene & Mikk Cederroth)
No public site yet — this subnetwork is still being set up.
- ### Rare Archive
Rare-disease diagnosis acceleration Wilhelm Foundation (Helene & Mikk Cederroth) [Open it ↗](https://github.com/Wilhelm-Foundation/rare-archive) — one contributor so far, ours.
[The state of the network →](/state-of-the-network/) [See the public-good commons →](/commons/)
## Grow the network with us
The honest starting point is the one above: one named architect, one anchor partner whose closeness to this project we named rather than hid, public-good work shown row by row with what you can open today, and a roadmap that hands leadership to the communities closest to the mission as stewards arrive.
[See the commons](/commons/) [Read the governance model](/reference/governance-model/)
---
## https://adna.network/accessibility/
# Accessibility
aDNA is a public-good project, and a good deal of what it documents is used by clinical and
patient communities. Accessibility is an obligation here rather than a compliance exercise.
This page states what has actually been tested, what has not, and the limitations we know
about — including the ones we have not fixed.
## The standard we hold ourselves to
**WCAG 2.2 Level AA** is the floor. Every page template is checked automatically
on every build, and the checks run in CI — a change that introduces a violation fails the
build rather than reaching this site.
## What has been tested
- **Automated rule checks** — axe across every page template, in both the dark
and light themes, at three viewport widths. The standing result is zero violations.
- **Keyboard-only traversal** — five primary surfaces walked stop by stop, plus
six primary flows driven end to end without a mouse. Focus stays visible, order is logical,
there are no traps, and Shift+Tab retraces the path exactly.
- **Screen-reader semantics** — an assistive-technology engine walks the opening
of each of five surfaces in CI and asserts what it hears: landmark and heading announcements,
traversal order, and that the registry's result count is genuinely *announced* when
you filter, not merely updated on screen.
- **Text resizing** — pages are checked at 200% browser text size for horizontal
scrolling and content loss, in addition to the narrow-viewport checks.
- **Reduced motion** — animations are asserted to stop when your system asks for
reduced motion, with controls proving the assertion can actually fail.
- **The network graph** — the diagram has a keyboard- and screen-reader-navigable
twin that lists every vault *and* every relationship between them, in both directions,
with the kind of each relationship named. It is asserted to stay equivalent to the diagram.
## Known limitations
These are real, current, and measured. Where we have chosen not to fix something yet, the
reason is stated rather than left as an absence.
- **Text inside diagrams is too small.** Our own floor is 12 px of rendered
text; on narrow screens the labels inside several diagrams fall well below it — as small as
3.5 px on the homepage graphic at a 320 px width. Measured across every diagram,
width and theme, **398 of 510 rendered labels** are under the floor. This is
page *illustrations*, not body copy, and every diagram has a text alternative — but it
is a genuine legibility failure and it is not fixed. A build gate now prevents it getting
worse while the redesign work is scheduled.
- **Automated checking does not cover all of WCAG 2.2.** Our tooling adds exactly
one new rule for 2.2 — target size. Four further 2.2 criteria cannot be checked here because
the interactions they govern (dragging, redundant entry, accessible authentication) do not
exist on this site; that is true today and stops being true the moment one is added. Focus
obscuring is covered by our own keyboard checks rather than by the rule engine.
- **No human screen-reader session has been run.** Our automated checks use a
screen-reader engine, which can prove the right information is *exposed* — it cannot
tell us whether what a person actually hears is *useful*. A guided listening session
is written and scheduled, and has not yet happened. Separately, testing with
**NVDA** is out of scope: it is Windows-only and this project is maintained on
macOS. We would rather say both of these plainly than let an automated pass imply them.
- **We have not tested with assistive-technology users.** Everything above is
maintainers and machines. Testing with people who use these tools daily is a different and
better instrument, and we have not done it.
- **The automated screen-reader check reads the opening of a page, not all of it.**
Walking a whole document with a real reader engine is too slow for a build check, so it
asserts against roughly the first sixty things announced. Problems further down a long page
would not be caught by it.
- **One clean result rests partly on browser behaviour.** Our sticky header never
hides the focused element during keyboard navigation — but testing showed that is partly
because browsers scroll focus to the nearest edge, not solely because of how this site is
built. A different browser could behave differently.
- **The "copy" buttons confirm quietly.** Copying a command changes the button's
label to "Copied!", which some screen readers announce and others do not, and if the copy
fails there is no feedback at all. This is on the list to fix.
## Telling us about a problem
If you hit a barrier on this site — including one not listed above — please tell us. A
description of what you were trying to do, the page, and the assistive technology or browser
you were using is enough; you do not need to identify the WCAG criterion.
[Open an accessibility issue →](https://github.com/aDNA-Network/aDNA/issues/new)
If opening an issue on GitHub is itself a barrier, that is a legitimate report in its own
right — reach us through any channel listed on the
[community page](/community) and we will file it for you.
## How this page stays true
Most of the claims above are enforced by checks that run on every build, so they cannot
quietly stop being true. The limitations are not — they are a record of what was measured, on
the dates it was measured. When one is fixed it is removed from this list in the same change
that fixes it, and when a check is added the list above grows with it.
Last reviewed 25 August 2026, against the build this page was published from. The measurements
behind the limitations were taken on 24–25 August 2026.
---
## https://adna.network/canonical-properties/
# Canonical properties
So you can tell a real aDNA property from a copy of one.
**Every public property aDNA operates or vouches for is on this list.** If you
found something calling itself aDNA that is not here and is not linked from a page on this
site, treat it as not us. Every domain, organization, and repository below was opened from
outside, logged out, on the date shown.
## Domains
- ### [adna.network](https://adna.network)
What it isThe canonical site — this one. Everything official starts here. Checked2026-08-18 — HTTP 200, logged out
- ### [community.adna.network](https://community.adna.network)
What it isThe community space: self-hosted, approval-gated, and early. Its honest current state, and its published rules, are on the community page. Checked2026-08-18 — HTTP 200, logged out
- ### [worldgeno.me](https://worldgeno.me) who runs it
What it isThe World Genome Academy's public site. Pre-launch at the last check. Who runs itA subnetwork's own public site. Its vault is one of the vaults counted above, on the same computer — this is not a second, independent operator. Checked2026-08-18 — HTTP 200, logged out
## Organizations
- ### [github.com/aDNA-Network](https://github.com/aDNA-Network)
What it isThe only GitHub organization aDNA publishes under. Code claiming to be aDNA from any other organization is not ours. Checked2026-08-18 — HTTP 200, logged out
## Repositories
- ### [aDNA-Network/aDNA](https://github.com/aDNA-Network/aDNA)
What it isThe clone-and-run workspace, MIT-licensed. This is what the install instructions point at. Checked2026-08-18 — HTTP 200, logged out
- ### [aDNA-Network/aDNA.aDNA](https://github.com/aDNA-Network/aDNA.aDNA)
What it isThe workspace this website is built from — the standard, applied to itself, in public. Checked2026-08-18 — HTTP 200, logged out
- ### [aDNA-Network/adna-legacy](https://github.com/aDNA-Network/adna-legacy)
What it isFrozen history from before the current repository layout. Archived and read-only — kept for the record, not for use. Checked2026-08-18 — HTTP 200, logged out; archived
- ### [Wilhelm-Foundation/rare-archive](https://github.com/Wilhelm-Foundation/rare-archive) who runs it
What it isThe Rare Archive, in the Wilhelm Foundation’s own GitHub organization under Apache-2.0. Legitimately connected to aDNA, and not controlled by it. Who runs itIn the Wilhelm Foundation's own GitHub organization, under their control, not ours. Related-party disclosure: the person who operates this network also holds a role at the Foundation, so read “not ours” as a statement about control, not about distance. Checked2026-08-18 — HTTP 200, logged out
Not every repository under our organization is listed. One vault in the registry records a
repository URL that does not resolve publicly, so it is not something you can check — it
is counted, without a link, on
[the state of the network](/state-of-the-network/). A list of
things you can trust should only contain things you can reach.
## Machine surfaces
The files this site publishes for agents and readers that are not browsers. These are this
site's own paths rather than separate properties, so there is no outside to check them from
— open them yourself.
- ### [/llms.txt](/llms.txt)
What it isThe curated index this site offers to AI agents.
- ### [/llms-full.txt](/llms-full.txt)
What it isThe expanded agent index.
- ### [/rss.xml](/rss.xml)
What it isThe release feed for this site. One entry so far.
- ### [/sitemap-index.xml](/sitemap-index.xml)
What it isEvery page on this site, listed for search engines.
## Social accounts
**aDNA runs no social accounts.** Any account using the name is not us.
If that changes, it will be listed here first, and this sentence will be the thing that
changed.
## Retired, and not us
- ### adna.dev retired
What it wasAn early domain for this project, abandoned before launch. It does not resolve. If it ever resolves again, it is not us then either. Checked2026-08-18 — no DNS response
A lapsed domain is named here rather than quietly dropped. Silence would leave it free to be
re-registered against us, with no way for you to tell.
## How to verify you are on a real property
One check settles it. The others only corroborate, and we would rather say so than pad the
list.
- **Look at your address bar.** If it does not read `adna.network`, you
are not on our site. A copy can reproduce every word on this page — that is what
copying is — but it cannot serve them from our domain. This is the only check that a
clone cannot pass.
- Corroboration: every page in this site's navigation links back to this one from its footer,
and the site name in the page's metadata and copyright line reads **aDNA Network**.
- Corroboration: the structured data on every page names this organization, with its home at
this domain and its other presences listed. Note that a copy can reproduce that too, so read
it as a signal, not as proof.
## What we will never do
We publish no testimonials — attributed or otherwise. We will never contact you asking
for a key, a token, or a payment. Invented quotes and invented attribution are the clone-site
signature; if you see them beside this project's name, you are not on our site.
## Where to go from here
**If you came here to check this site is the real one:** it is, and the address
bar is the proof. [What actually runs, and who operates it →](/state-of-the-network/)
**If you found something claiming to be aDNA that is not on this list:** we want
to know. [How to report it →](/security/)
[Clone the standard →](/get-started/) ·
[Browse the registry →](/vaults/) ·
[Who’s behind aDNA →](/about/)
Every domain, organization, and repository above last checked from outside, logged out, on
2026-08-18. See also
[the state of the network](/state-of-the-network/) for what
actually runs and who operates it.
---
## https://adna.network/changelog/
# Changelog
2026-09-11 September 11, 2026
## The fix that had to be made twice
v8.10 removed the marketplace promise from the two files where it had been reported. The
promise lived in six, and the release fixed two.
This one looked for what the promise *claimed* rather than for the file that claimed it — and
found a section nobody had listed, on the most-read page in the whole template: the home page a
new workspace opens on first run. It had a heading that said **Marketplace**, a live link, and a
note to a future maintainer saying to update the link *“until the marketplace is live”*.
## The link nobody clicked
The link returns **HTTP 404**. It has been shipping to every new setup for months.
That is worth saying plainly, because it is not the defect anyone was looking for. The promise
was filed as a *wording* problem — a page claiming something untrue. Nobody checked whether the
destination it pointed at existed, because that was a different kind of question and no sweep
asked it.
A claim can go wrong in more than one way at once, and checking the way you wrote down does not
check the other one. To a reader the two are indistinguishable anyway: a promise you cannot
follow looks exactly like a promise you can, right up until you click.
## Why a heading outlived the paragraph under it
The setup guide’s Step 9 was headed *“Marketplace Teaser”* and told the agent running it *“this
is a teaser — don’t oversell.”* v8.10 rewrote the paragraph between those two lines to be honest
and left both of them there.
So an agent reading the heading rather than the paragraph reconstructed exactly the pitch the
release had just removed. A fix aimed at the sentence that was reported does not look up, and a
heading is the last place anyone re-reads: it was true when it was written, it frames everything
beneath it, and a diff of the body never shows it.
## What this does not change
Workspaces you have already created are not touched by this release. If one of them carries the
retired `marketplace_interests` field, removing it is a change to your own files and yours to
make — this release governs what a *new* setup is asked, not what is already written on your disk.
The canvas metadata move likewise fixes what every future workspace receives. Existing canvases
keep working and are not migrated here.
2026-09-07 September 7, 2026
## What is different now
Until today, this site measured its own speed and threw the numbers away. They existed in the page’s
memory while you were reading and vanished when you left. That was honest and it was also useless:
we could tell you the site was fast on a developer’s laptop and had no way to know whether it was
fast for you.
It now sends those timings to **Vercel**, the host already described on the privacy page. What goes
is the timing itself, the page it belongs to, and the coarse technical context your browser reveals
to any site it loads. **No cookie is set for this**, nothing extra is stored on your device, and
nothing that arrives names you or lets anyone follow you between pages.
## The order this shipped in, which is the part worth reading
The privacy page carried this sentence:
> If we ever start collecting these numbers in aggregate to watch site performance — a change we may
make — we will update this page before that ships.
That is a promise about *sequence*, and the only way to keep it is to move the page first. So the
privacy rewrite and the measurement change are the same commit, with the page’s description of the
new behaviour written before the behaviour existed.
The alternative — ship the transport, update the page afterwards, note it in a changelog — would
have made a live sentence on the trust page false for as long as the gap lasted. A promise kept by
intention is not kept.
## What did not change
The in-page measurement still runs and still goes nowhere. It is not a fallback or a legacy path; it
is a separate thing that exists so the numbers are visible in the page itself. **There are now two
measurements**, and the privacy page distinguishes them rather than quietly replacing one with the
other.
## What we still cannot tell you
Whether the site is fast. Field measurement needs traffic, and traffic needs time — the first real
reading is weeks away. Today starts a clock; it does not report one.
## Separately: the standard released v8.10
Two unrelated things landed on the same day, and this section is the second of them.
aDNA ships a guard that runs before your work leaves your machine. It reads the top of each file and
refuses the push if something is flagged `confidential: true`, or is still a draft, or looks like a
secret. That is the mechanism behind the promise this site makes everywhere else: your files stay on
your machine until you choose otherwise.
**It was only looking at markdown.** Both places in the guard that read those flags skipped every
file that did not end in `.md`. So a `.yaml` inventory, a `.json` export, a `.csv` of anything at
all — marked confidential, and pushed **without ever being scanned**. The guard reported success.
### The part that is worth more than the fix
That rule had **never had a test**. Not a failing one — none at all. The project’s own test-fixture
list carried it as *deferred*, in writing, since the fixtures were first written. So the rule shipped
in every vault that installed it, looked like coverage, and had never once been exercised.
v8.10 adds the first two tests it has ever had. They are the same file twice, differing **only in
the extension** — one `.md`, one `.yaml`. That pairing is the whole point: on the old version the
test run flags the markdown one and reports `NO findings` on its twin, and on the new version it
flags both. Exactly one result changes, so the fix is attributable to the extension and to nothing
else. A single test could have shown that something improved; the pair shows *what*.
While adding them we also found a coverage row marked ✅ that could never have been true — its test
file matches the repository’s own ignore rule, so it has never been committed and no copy of the
project can run it. We have not fixed that one. We changed the row to say what is actually there,
which is the smaller and more honest act, and we wrote down why.
### What this does not mean
Nothing about your data changed, and nothing here is a live incident. This guard is a **local**
check that runs on your own machine before a push; it is not a service and it never saw your files.
If you install the updated hook, it will now refuse pushes it previously allowed — **that is the
repair working**, not a regression. The standard’s own version moved 8.9 → 8.10; the specification
itself is unchanged at v2.5.
2026-09-04 September 4, 2026
## The change
The homepage’s qualifier line read:
> Not a product or service — no server, no signup, nothing leaves your machine.
It now reads:
> Not a product or service — no server, no signup; aDNA itself sends nothing.
## Why
The old sentence was an unscoped absolute, and it was false for the reader’s own tools. This site’s
audience line names teams *“working with agentic coding tools on real projects”* — and that tool
sends your prompts and the contents of the files it reads to its provider. aDNA itself is a
file-layout convention: three folders and plain Markdown, with no network behaviour to have. That is
the claim we can actually stand behind, so it is the one on the page.
## What is uncomfortable about it
We knew. The caveat has been in our own claim register since **2026-08-16**, in the row for this very
sentence, together with the exact wording that replaced it today. The same fix reached
`/get-started`, then `/network`, then `/privacy` — and never the homepage, which is the page most
people read.
The homepage was also already contradicting itself. A sentence nine lines below the qualifier has
said *“Your files stay on your machine”* since late August. The careful version and the sweeping
version sat in the same component, both above the fold, for two weeks.
And the sentence was labelled **verified** in our register while being checked by nothing: it was
absent from the fixture our claim-currency test reads, absent from the claim-trace manifest, and
present in the hero test only inside a comment. The test that guards our claims was, at that one
spot, guarding nothing. It is pinned now.
## The rewrites we rejected
Two rewrites scored better and were rejected because they were not true.
*“…nothing **of yours** leaves your machine”* is the smallest possible edit and costs nothing on any
readability measure. It also fixes nothing: the case that breaks the promise is precisely *yours* —
your prompts, your files, going to your provider.
*”…Your files stay on your machine”* reads best of all. But a vault pushed to a remote does move
data, which is why the equivalent sentence elsewhere on the site carries *“until you choose.”* This
version drops it.
We would rather publish the sentence that survives being checked than the one that reads most
smoothly.
2026-09-03 September 3, 2026
## Four questions a reader could ask here and get no answer to
Everything published today is the same shape: a question this site’s own framing invites, which no
page acknowledged. None of them is a new capability. Three of the four were already answered
somewhere — just not anywhere the person asking would be standing.
## The name
In genomics, **aDNA** means ancient DNA. This site uses it for **Agentic DNA**, and a clinician
reading the homepage cold told us she “briefly expected paleogenomics.”
The disambiguation was not missing. It has been on the *what is aDNA* page for weeks, which is the
right home for it — that is where someone who wondered about the name goes looking. But the commons
page is a landing surface: you can arrive there from the homepage, the header, or the footer without
passing through any page that explains the collision. So the note is now on the commons page too, as
two sentences, and it disambiguates a name without asserting anything about the field or the science.
## Running a model on your own machine
The network page describes how vaults connect. It said nothing about the case a lot of people
actually care about: running a model locally rather than sending prompts to a provider.
It does now — and the first thing that section says is that this is **planned work, not shipped
work.** Nothing in it runs yet. The two vaults named in the plan are listed by the registry as
planned, and the section says so rather than implying a roadmap item is a product.
Writing it exposed a contradiction forty lines above. The page carried “Local-first — nothing leaves
until you choose”, which was fine until a new section on the same page said, in the site’s own voice,
that prompts *do* leave. The sentence now reads “your vault files never leave until you choose.”
Narrower, and true.
## If you work with regulated data
This site’s own examples reach into rare-disease research. A reader whose profession obliges her to
ask about HIPAA, GDPR or IRB review found no page acknowledging the question existed — not an answer
she disagreed with, just silence.
The privacy page now answers it, and the answer is deliberately the smallest one that can be made:
aDNA is an open specification for how knowledge files and directories are named and annotated. It is
a file-layout convention, not a system that runs, and adopting it transmits nothing, because a naming
convention has nothing to transmit with. **We therefore make no regulatory claim about it at all** —
nothing here is certified, approved, audited or warranted under any regime, and if you keep regulated
material in a vault, the obligations attaching to it rest with you and the tools you actually run.
That section is written to stay that small. A disclaimer that grows into a reassurance is the failure
mode, and an earlier draft was cut back four times before publishing for exactly that reason — once
because it had reached for the word “processor”, which is a term of art in the regime it disclaims.
## What changed since you last looked
Until today, the changelog and its feed were reachable only from the footer. Someone returning after
a month had no way to see what had moved without hunting for it. The homepage now carries a dated
strip of the three most recent entries.
The dates and titles are **read from the changelog collection at build time**, not typed into the
homepage — so the strip cannot drift into claiming a “latest” that the changelog page disagrees with.
A test asserts the derivation, because a hardcoded strip would look identical on the day it shipped
and be quietly wrong a month later.
## And the documentation now covers what a mission costs
Two pages about designing missions gained a section on the two fields every mission here declares
before it starts: the token budget it expects to spend, and which model tier runs it.
The section includes the limit, which is the part usually left out. A declared tier is a plan, and
this project shipped a mission whose declared tier and actual tier diverged for four consecutive
sessions with nobody noticing until the review at the end. Both the plan and the actual are recorded
now, because a declared tier nobody honours is worse than not having the field.
2026-08-28 August 28, 2026
## Measuring without collecting
Every page on this site now runs a small script that measures the standard web performance
numbers — how long until the first paint, how long until the largest element rendered, how much
the layout shifted. These are the same “Core Web Vitals” every performance tool measures.
Here is the part worth writing down: **the numbers go nowhere.** They exist in your browser’s
memory while the page is open and are discarded when you leave. The site’s own security policy
(`connect-src 'self'`) would block a transmission to any third party, and there is no server
endpoint to receive one — the site is static files. The instrument is not “analytics with the
sending turned off as a courtesy”; it is incapable of sending, by construction, and you can verify
both halves in the open-source repository.
## Why build a measurement nothing reads?
Because the alternative was shipping the *reading* half first and the honesty half later.
The plan — stated in the open, in the campaign records — is that these measurements will
eventually flow to an aggregate performance dashboard, so the site’s real-world speed for real
visitors can be watched rather than assumed. That step is deliberately gated on a human decision,
and it has not been taken. What shipped today is the instrument, wired and demonstrably working:
the test suite loads a page and asserts that at least one measurement was actually emitted. A
script that is present but inert fails the build — because “shipped” and “working” are different
claims, and this site has been bitten before by the gap between them.
## The privacy page moved first
The privacy page has carried a commitment since July: if analytics of any kind is ever added, the
page updates **before** the change ships. This is that update, in the same change as the
instrument itself. The page now has a section explaining exactly what is measured and where it
goes (nowhere), and it will update again — first — if the dashboard step is ever taken.
## A weekly sweep that is allowed to fail
Separately, the repository gained a scheduled performance sweep: once a week, CI builds the site,
crawls every page with Lighthouse, and **fails the run loudly** if any page misses the performance
budget. Not a report someone might read — a red build.
One detail from the plumbing: the sweep and the visual-regression tests both drive a browser over
the entire site, and running them simultaneously produces flaky screenshots that look exactly like
real regressions. The rule that they must not co-run is enforced by the CI system’s own
concurrency mechanism, not stated in a comment — because this campaign keeps re-learning that a
rule recorded only in prose is a rule with no gate.
## The links that let you check us were broken
The rest of today’s changes are one theme: **the surfaces whose whole job is to let you verify
something were the surfaces that did not work.** A review of the site found no broken journeys and
no false claims a reader couldn’t recover from — but four defects clustered exactly there.
The get-started tour shows you the four files an agent reads on first run, verbatim, with a hash
for each and a link to the same file in the public repository. **Every one of those links returned
404.** The bytes on the page were correct and the hashes were honest; the *commit* the page cited
existed only on one machine. A build script had been reading the commit id out of a local checkout
and pairing it with the public repository’s address — two different repositories, one link. The
page now cites the published release of the standard, `v8.9`, and all four files are byte-identical
to that release. That is checkable, and we checked it, and now a test refuses to let the page
publish an identifier that only exists locally.
The markdown copy of the quickstart — the version an AI agent reads — was serving **broken
commands.** Where the page correctly shows `ls ~/aDNA/<name>.aDNA/what`, the machine copy had
silently dropped the `<name>` placeholder, and the sentence explaining it read “Replace “ with
whatever you called your project.” The conversion was mistaking the placeholder for markup and
deleting it. Nothing caught this, because every existing test asked whether the machine copy was
*well-formed* and none asked whether it said the same thing as the page. One now does.
And the site’s own security policy was refusing to load one of its own fonts, on every page. The
fix moves the font out of the stylesheet and into a file; the policy itself is untouched, because
loosening a security rule to make an error go away is not a fix.
## Two sentences that were true and read as more than they were
“Nothing is sent anywhere” was a promise about the workspace, printed next to a command that ends
by launching an AI agent — which does need an account, and does send the files it reads to its
provider. Both halves were always true; only one was written down. The page now says both, and
says you can skip the agent entirely.
The smaller one: a five-command check said “each prints nothing, except the last two.” Three of
them print. That is the kind of error nobody reports and everybody notices.
2026-08-22 August 22, 2026
## A sentence that stopped being true
Since 17 August the community page has described the community space like this:
> registration is approval-gated, and its terms of service, privacy policy, and branding are still
being stood up
Every word of that was accurate when it was written. On 21 August the venue published its terms of
service and its privacy notice, and from that moment the sentence was false — not because anyone
edited it, and not because anyone was careless, but because it described **someone else’s system**
and that system moved.
This is a different failure from the ones we usually write about here. A claim that was always
wrong has an author. A claim that goes stale does not: there is no bad edit to find, no commit to
blame, and from the outside a stale sentence and a broken one look exactly alike.
## The check that should have caught it was the reason it survived
Every load-bearing claim on this site has a row in a register, and the register is wired into the
test suite. Rows marked `verified` are asserted to be **present** in the built pages — because the
honest, unflattering sentences are precisely the ones a cheerful rewrite deletes first, and we
wanted their removal to break the build.
That check worked exactly as designed, and the design had a hole in it. The register row for this
sentence was stamped `verified` against evidence gathered on **17 August**, and nothing about a row
ever expires. So the suite was not merely failing to notice the false sentence:
**it was green because the false sentence was there, and would have gone red the moment we told
the truth.**
Nothing in the register carries a probe date. A test that pins wording can only tell you the
wording has not changed — it cannot tell you the world has.
From today, any sentence on this site describing an external surface carries the date it was
checked, on its face, and its register row records that date too. That does not make staleness
impossible. It makes it *visible*, which is the most a check of this kind can honestly promise.
## The rules are linked now
The venue’s terms of service, privacy notice, and code of conduct are published. They are short and
they say so themselves that they are interim, pending review. They are now linked directly from the
community page, because “there are rules somewhere” is not useful to someone deciding whether to
join, and “we have a policy” is the kind of sentence that sounds like a fact and functions like a
reassurance.
Two commitments in them are worth repeating, and we repeat them as commitments **the documents
make** rather than as facts we have independently verified:
- Your content is not used to train or evaluate AI models.
- Every agent in the space is labeled as an agent, and undisclosed automation is not allowed.
## Agents work there, and the page said they did not
The same paragraph carried a second sentence that had gone false: that agents work in the
repositories and on the public record, **not in chat**.
That was true of the venue as originally scoped. It is no longer the posture, and the venue’s own
code of conduct now says plainly that the community includes AI agents as working members, every one
of them visibly labeled.
We found this the only way it can be found — by reading the code of conduct before linking to it.
Had we linked it without reading it, this page would have said agents are absent one line above a
document saying they are present, and a reader would have found the contradiction in a single click.
The page no longer asserts either way who is inside. It states the rule, which is checkable by
anyone from the published document, instead of a fact about attendance that we cannot see from
outside an approval-gated venue and should not pretend to.
## The same claim, two more pages
The old description also appeared on the network and canonical-properties pages, which both call the
venue “human-to-human” and then point at the community page for its honest current state — a page
that, as of today, says something different.
They shared one line in one data file, so the correction was one edit. The reason it is worth
mentioning is the habit it enforces: after removing a wrong claim, search the *rendered site* for
what the claim said, not just for the file that said it. The first search found the fixed page and
told us we were done. The second found two pages we had not touched.
## What we did not do
The community page does not map the participation ladder to specific channels in the venue.
That mapping would be genuinely useful, and we cannot verify it. The venue is approval-gated, so its
channel structure is not visible from outside, and a rung-to-channel map assembled from anything
other than direct observation would be a plausible guess presented as guidance. It is deferred until
it can be checked, and recorded here as deferred rather than left as a gap you would have to notice.
2026-08-21 August 21, 2026
## The registry is now data
This site has listed the vault registry as HTML for months. For a reader that was fine. For an
agent it was the wrong shape: the only way to get the vault list was to scrape the registry page or
pull bare slugs out of the sitemap, which gives you names and nothing else.
We checked the four addresses an agent would guess. All four returned 404.
**`/vaults.json` now serves the whole registry** — every entry and every declared relationship,
with the same fields the pages render. One `curl` and you have it:
```
curl -s https://adna.network/vaults.json | jq '.vault_count'
```
**There is also a pinnable copy at `/api/registry.v1.json`.** It serves identical bytes. The
difference is what each promises: the first gives you whatever is current, the second gives you the
*v1 shape*. If a field ever has to change meaning, that change lands at a new versioned address,
the old one keeps serving for at least 90 days, and `/vaults.json` only follows afterwards. Adding
a field is not a breaking change and can happen at any time — so write consumers that ignore keys
they do not recognise.
Both are built by the same function, which is the only reason the pin is worth anything. A
versioned URL that quietly drifts from the canonical one is worse than not having one, because you
cannot tell from the outside that it has drifted.
## The endpoint tells you how thin it is
Seven of the nineteen published fields are populated **zero times** across the entire registry.
No vault has a tagline. None has a current phase, a documentation URL, or a headline mission.
That is not a bug and it is not a fetch error. Those fields were emptied on purpose, when internal
working language was stripped out of the public projection. Sparseness is what honest sanitization
costs.
The problem is that from outside, a field that is empty *for this vault* and a field that is empty
*for every vault* look exactly the same — and a consumer that guesses wrong builds a view around a
column that will never have anything in it. So the payload counts it for you:
```
"field_coverage": { "display_name": { "populated": 74, "of": 74 }, "persona": { "populated": 61, "of": 74 }, "note": { "populated": 44, "of": 74 }, "tagline": { "populated": 0, "of": 74 }}
```
Check coverage before you depend on a field. One deserves particular care: `last_synced` records a
**registry sync**, not vault activity, and most rows carrying it share a single date. Reading it as
freshness would be false, so the endpoint says what it is.
The same instinct applies to the caveat that matters most. Every entry in this registry is
self-declared, and nothing corroborates it — no build status, no commit feed, no external check.
That sentence has been on the registry page since we redesigned it. It is now *in the payload*,
because a machine consumer never reads the page.
## Rows that are thin on purpose
Three vaults are listed with identity, class, status and persona only. They are real engagements
whose detail is private, and they stay listed so the count stays true.
Until today those rows just looked empty in any machine-readable form, which is the failure mode
worth naming: **a suppressed row and a missing row are indistinguishable from the outside unless
the data says which one you have.** Each now carries a `listing` marker and a note saying it is a
minimal card and why. The vault is real and governed; its detail is not public.
## What the endpoint deliberately does not contain
It publishes exactly the fields the registry’s own pages already show, and nothing else. The
underlying registry holds more — some of it non-empty — but a field that no page displays is not
made public by being convenient to include.
It is also a snapshot of one operator-run node’s declarations. It is not a census of who uses aDNA,
and nothing in it is checked against anything outside itself. [The full reference](/reference/registry-api) states the schema, the versioning policy, and these limits
together, so you can see the shape and its caveats in one place.
## Machines can now tell what the registry is
The registry page described itself to machines as a generic collection of pages. It now also
describes itself as a **Dataset**, with a pointer to the JSON endpoint — so a machine that lands on
the HTML can get to the data in one step instead of guessing.
Three pages — the design system, privacy, and security — carried no structured data at all. They
do now.
## What we did not fix
**Individual vault pages still describe themselves as generic web pages.** A vault is a structured,
typed, governed thing, and saying “web page” is the least informative true statement available.
We are not fixing that with a quick relabel, because the obvious labels are wrong. A vault is not
plainly a dataset, and calling it source code would be false for the seventy-three that have no
public repository. Picking the right description is a decision about what a vault *is*, and it
deserves to be made deliberately rather than as a side effect of shipping an endpoint. Recorded as
open, with the reason, rather than closed quietly.
## A front door for agents
Everything above is useless to an agent that cannot find it. Until today the only pointer to
`/llms.txt` anywhere on this site was a link in the footer, and the fact that the site is itself an
aDNA vault was stated once, three clicks deep, on a page about what aDNA is.
The homepage now says both, in one block: **what this site is, and where a machine should start.**
Three surfaces, each of which already worked and none of which was advertised where anyone would
look — the curated index at `/llms.txt`, the markdown twin of almost every page, and the registry
endpoint from the section above.
We measured before writing it. The twin count in that block is read from the same manifest that
generates the twins, so it cannot drift into a number nobody checked; two pages out of 224 have no
twin, and the block states the count rather than claiming “any page”.
One sentence did not survive the review. The block first said these surfaces were “a by-product,
not an add-on bolted on later” — which is false, and our own changelog proves it: the twins shipped
two days ago and the endpoint shipped this morning, both because an audit found them missing. What
is true is narrower and checkable: each surface is generated from the same source as the pages, so
it cannot fall out of step with them. That is what it says now.
## What is not here
There is no MCP server. One exists, it works, and it is not published — so nothing on this site
mentions one, and `/.well-known/mcp.json` returns 404 rather than describing software you cannot
install. When it is published, it will be listed here and not before.
2026-08-20 August 20, 2026
## The whole site is now readable as markdown
This site’s argument is that context should be navigable by agents. An agent arriving here could
read the HTML — it is all server-rendered, and that part was already fine — but three things it
would reasonably expect were missing, and their absence argued against the claim more than any
missing feature would.
**Every page now has a markdown twin.** Add `.md` to any address — `/learn/what-is-adna.md`,
`/get-started.md`, `/vaults.md`. 221 of them, generated from the same source the HTML is built
from, so they cannot drift into saying something the page does not. Each opens with a pointer back
to the index and the date it was generated.
**The same markdown is served on the ordinary URL** to anything that asks for it with
`Accept: text/markdown` — the convention Claude Code and several other agents already use. Before
today that header changed nothing at all; you got the HTML, byte for byte, down to the same ETag.
**`llms-full.txt` is now actually full.** It was a 2 KB index of routes wearing a name that
promised the whole corpus. It is now the whole corpus — every page, about 900 KB — and the index
it used to be is still there at the top, serving as the table of contents.
**And `llms.txt` is now findable.** The curated index has been good for months and was mentioned
nowhere on the site: the string “llms” appeared zero times in every page we checked. An agent had
to already know the convention to look. It is now in the footer, in `robots.txt`, and declared in
the head of every page that has a twin.
One deliberate limit, since a machine surface should not overstate itself: three routes have no
twin — the 404 page, the design-system page (whose content *is* its rendering), and the network
graph (whose keyboard-navigable twin is the vault registry). Those pages do not advertise one
either, because a pointer to a missing file is worse than no pointer.
## There is now a way to propose a change
Until today, a standard that anyone could read had no stated way for anyone to change it. That is a
preference with good documentation, not a standard.
Changes to the standard now go through numbered
[aDNA Enhancement Proposals](/community/proposals/). The rules are short, and one of them is
load-bearing: **a number, once assigned, is never reused** — including for proposals that get
rejected or withdrawn. There are no gaps in the sequence, so the archive cannot be tidied after the
fact. You can read what we turned down.
Two other rules worth stating plainly. **Only a human can accept a proposal** — the person who did
is named on it, with the date. And a proposal is only called *final* once a check in aDNA’s own
tooling fails when the rule is violated; until then it stays *accepted*, which is a different and
more honest word.
The process is itself [AEP-1](/community/proposals/aep-1/), filed through the process it describes,
so it has been used once before anyone else is asked to use it. There is also a
[machine-readable index](/community/proposals.json) for agents.
The archive is short today — two proposals, one of which is the process — and the page says so
rather than implying a backlog of activity. There is no published review time either, because none
has been measured.
## The contribute button now leads somewhere
The site has had a **Contribute on GitHub** button for months. The repository it points at had no
code of conduct, and its contribution guide sat one directory below where GitHub looks for it — so
it was present and effectively invisible. The documentation was real and good; it was behind the
wrong door.
Both now exist at the top of that repository, and the contribution guide there routes you by what
you actually have: a bug, a question, a fix, or a change to the standard itself.
We also wrote down something that was already true and had never been stated: **AI-assisted
contributions are welcome, and must be disclosed.** Agents may draft proposals and open pull
requests; every proposal names the agent that drafted it, if one did. Most of this project’s own
documentation was written that way. Saying so is more useful than pretending otherwise.
## The homepage said two opposite things about your files
Above the fold, the site told you: *no server, no signup, nothing leaves your machine.* Two
sentences later it told you your context was *“shared in the open.”* The subject of that second
sentence was **your context** — your notes. Read literally, which is how anyone reads a page for
the first time, we promised that your files stay private and that we publish them.
What we meant was that the *standard* is open. That is what the sentence now says. The promise
about your files is unchanged and unqualified: they stay on your machine.
This one mattered more than its size suggests. A reader evaluating aDNA for work involving
confidential notes reached that pair and stopped there — reasonably.
## A name we never explained
The fold on four pages said the site was *“built on the Lattice Protocol.”* The glossary has no
entry for it. `/glossary/lattice` and `/glossary/lattice-protocol` both return 404. There is no
page on this site that tells you what it is.
We also cannot tell you yet — the protocol material is under a legal review that has not
concluded. A term you cannot explain does not belong in the first thing a stranger reads, so it
is out of the fold until that review finishes, at which point it can come back with an
explanation attached. The link it carried still goes to the specification.
It is still named in two deeper places, both deliberately: a tutorial that flags it as
design-not-yet-shipped in its own text, and a page that reproduces a file from the install
verbatim — that page’s entire purpose is that we did not edit what it shows you.
## Naming a relationship on the page where you would check it
The properties page — the one that exists so you can verify which accounts and repositories are
really ours — listed the Rare Archive under *“what is not ours”* and noted it sits in the Wilhelm
Foundation’s own GitHub organization, under their control.
True, and incomplete. The person who operates this network also holds a role at that Foundation.
Both [About](/about/) and [the state of the network](/state-of-the-network/) already said so; the
page where a skeptical reader would actually look did not. Finding that gap by comparing our own
pages against each other is worse than being told it plainly, so it is now told plainly there
too.
## An example that never happened
*What is aDNA* opened its before-and-after with a lab whose 200 files sprawled across three tools
and a new collaborator who needed three days to orient. There was no lab. There was no
measurement. It was a plausible illustration written in the voice of an observation.
We cut a fabricated terminal transcript from Get Started one release ago and
[explained why](/changelog/). A reader found the next one unaided. The invented specifics are
gone, and the passage now says outright that it describes a general pattern and not a measured
project.
## What this pass did not fix
Neither the [privacy](/privacy/) nor the [security](/security/) page says anything about clinical
or regulatory posture — not HIPAA, not GDPR, not de-identification, not patient data — while the
homepage talks about rare and undiagnosed disease throughout.
We are not fixing that with a sentence today. Doing it properly means deciding who this site is
for and stating it, and writing reassuring copy ahead of that decision would be exactly the kind
of claim this site is trying to stop making. It is recorded as open, with a name and a reason,
rather than closed quietly.
2026-08-19 August 19, 2026
## One place per audience
The site described the same five audiences in three different sections, under three different URL
schemes, and listed them twice in the navigation. There is now one: [Use Cases](/use-cases/).
Nothing was deleted — the material that only existed in the retired pages was folded into the
pages that survive.
## Navigation
The primary navigation is seven destinations and no overflow menu. Previously eight, with a “More”
menu that hid destinations you could not otherwise reach.
## URLs
Vault pages were reachable under two different casing schemes, which meant links to some of them
would break permanently on a case-sensitive host. There is now one scheme, all lowercase, and every
URL that previously worked still resolves — with or without a trailing slash.
The compliance walkthrough moved to [/provenance-audit/](/provenance-audit/), which is what it
describes. It was previously reachable from no navigation surface at all.
## The specification is twenty pages, not one
The [specification](/reference/specification/) was a single page of 163,169 bytes. Every reader paid
the whole thing to read any part of it, and on a phone it was a scroll of roughly 74,000 pixels. It is
now a hub with twenty numbered section pages, each linkable on its own, plus a
[full-text page](/reference/specification/full/) for anyone who wants the old behaviour deliberately.
Twenty section URLs and the full-text URL previously returned 404. They resolve now. There is also a
link check that blocks a release on any internal 404, which is how we would rather find the next one.
## Dates
119 pages now carry the date they were last updated and a link to the file they were generated from.
Previously none did, which meant a reader had no way to tell a page written last week from one written
in April.
Four hand-written pages still carry no date — including [/provenance-audit/](/provenance-audit/),
which is the page that explains how to check this site’s claims. That is the wrong page to be missing
a date and it is on the list.
The changelog you are reading also went from one entry to four, and now has a
[feed](/rss.xml).
## The registry says what stage things are at
The [registry](/vaults/) listed 74 vaults as one undifferentiated set. That is not what 74 means here.
It now separates them into **7 in use**, **10 chartered**, and **57 planned**, with the stage shown on
every card and on every vault’s own page.
All three groups get the same card. A denser card for “in use” and a sparser one for “planned” would
read as a ranking, and the field being ranked is one each vault declares about itself — so the page
says that in plain text rather than implying a rigour it does not have. The homepage was separately
displaying a raw internal status value, so the same vault could be described one way there and another
way here. It no longer is.
## A page that was quietly showing nothing
[/commons/](/commons/) reported “member records last synced .” — an empty date and a stray full stop —
and displayed none of the relationships each vault declares. WilhelmAI showed 0 of its 3; Rare Archive
showed 0 of 1. The page had been joining two data sets on identifiers that stopped matching when vault
URLs were normalised earlier in the day, and every field it lost had a polite empty state, so the
failure rendered as a considered absence rather than as an error.
It is fixed. We are noting it at length because that page’s own text promises that honest activity is
“exactly this: the dates above and the relationships each vault declares,” and for a while it was
showing neither.
## You can read the install before you run it
Our install is one command that clones a repository and starts an agent inside it. The agent’s first
act is to read the instruction files you just cloned. That is a fair thing to hesitate over: those
files are prompt-ware, and prompt-ware is executed by the agent that reads it.
So they are now published. [What your agent reads](/get-started/what-your-agent-reads/) shows all four
files — 1,035 lines, about 70 KB — exactly as they arrive, annotated with what each one does and what
to look for. Not screenshots and not summaries: the bytes, pinned to commit `0364d85` of the standard,
each with a SHA-256 you can check against your own clone with `shasum -a 256`. The build refuses to
publish the page if those bytes stop matching that commit.
[Get Started](/get-started/) now also states, above the command rather than below it, exactly what it
writes and where, that nothing is installed outside that one directory, that this particular one-command
flow assumes Claude Code specifically, and that `rm -rf ~/aDNA` is the entire uninstall. There is a
section on how to check it worked — five commands you can run, plus the one that actually matters:
open a new agent session inside your project and see whether it already knows where it is.
## A transcript we should not have written
Get Started used to show a sample terminal session: a `$ claude` prompt, a checkmark, and an interview
asking what your project was called. We wrote that by hand. The software does not print those lines —
we searched the standard for them and found them nowhere but on our own marketing page — and the flow
it depicted had the order wrong: a fresh workspace has no project yet, so the fork skill runs and
*then* offers the interview, rather than the interview building the project.
It has been removed and deliberately not replaced with a better-looking invention. There is a labelled
gap where it was, and a real recording will fill it once we have made one on a clean machine and timed
it. The page also carries a claim that setup takes about five minutes; we have not measured that yet
either, and it stays flagged internally until we do.
We are writing this up rather than quietly deleting it because it sat directly above the one line on
that page a reviewer told us he trusted — “nothing executed from the network” — which is true, and
which faked output three inches higher does not deserve to sit next to.
2026-08-18 August 18, 2026
## Two pages that answer “what is this, really?”
[State of the Network](/state-of-the-network/) separates what actually runs from what is operator-run,
what belongs to other people, and what is merely planned. It states plainly that the vaults listed
on this site run on one computer operated by one person, and that this is not evidence of adoption.
[Canonical Properties](/canonical-properties/) lists every web property that legitimately belongs to
aDNA, each with the date it was last opened from outside, so you can tell a real one from a copy.
## Claims revised down
Several statements on the site described intentions in the present tense. Where a claim could not
be checked, it was removed or rewritten rather than softened. Counts shown on the site are derived
from the underlying data rather than typed by hand.
## Security disclosure
Reporting a vulnerability previously had no working destination. There is now a published policy
and a private reporting channel on the source repository.
## Accuracy and layout
Entries in the vault registry no longer show internal placeholder values, and pages that overflowed
horizontally on a phone were fixed.
2026-08-17 August 17, 2026
## Security headers
The site was configured to send four security headers and was serving only one of them: the
configuration never reached the deployed output. Deploys now assemble and verify the header set as
part of shipping, and refuse to publish if any of the four is missing.
## Installer
Getting a workspace onto a machine no longer starts with reading instructions. There is a single
command for macOS and Linux, and a page that shows you exactly what it will do before you run it.
0.1.0 April 14, 2026
## v0.1.0 — Site Scaffold
Initial scaffold of the aDNA documentation site. Astro 6 project with documentation archetype layout, branded design tokens, and empty content collections ready for content integration.
---
## https://adna.network/commons/
*[image: A warm pixel-art bird's-eye view of a communal night garden: one great tree at the centre with several distinct, individually-tended plots — a vegetable bed, a flowering terrace, an orchard, and a glasshouse — each lit by its own amber lantern and joined only by the tree's roots and branches. The shared commons that mission-aligned subnetworks tend together.]*
# A commons, not a catalog.
Mission-aligned subnetworks are taking shape here — so the abundance AI creates belongs to everyone. See them, check them, connect to them.
Connect a subnetwork [Read the standard](/reference/specification)
[Open source on GitHub](https://github.com/aDNA-Network/aDNA) · MIT-licensed · [the standard, versioned and public](/reference/specification)
ℹ A note on the name
In genomics, *aDNA* usually means
[ancient DNA](https://en.wikipedia.org/wiki/Ancient_DNA). This is not that.
Here it stands for *Agentic DNA* — a shared way to file what a project knows,
so people and AI agents can both find their way around it.
[What aDNA is →](/learn/what-is-adna/)
## The subnetworks
Real public-good missions on the aDNA network — each one named, cited, and honest about
its stage. A curated set, not an exhaustive one: it grows as aligned subnetworks join.
- ### World Genome Academy
Genomics knowledge as a shared commons The World Genome Academy is building genomics education and research programs — so the science is stewarded, not enclosed. Serves Genomics education & research Stewarded by Founding stewards · governance being formalized Governance on record [wga.aDNA](/vaults/wga/) [Visit ↗](https://worldgeno.me) Connect ↓
- ### Context Commons
Agentic-context literacy, shared A community program for agentic-context literacy and enablement — and the shared pool that forms when vaults publish their best context, patterns, and lattices for others to discover and reuse. Serves Community agentic-literacy & enablement Stewarded by Founding-steward today — community governance as it grows Governance on record [ContextCommons.aDNA](/vaults/contextcommons/) Connect ↓
- ### Wilhelm AI for the Undiagnosed
AI for people living with undiagnosed disease The Wilhelm AI Initiative for the Undiagnosed (AI4U) — the Wilhelm Foundation's umbrella over AI initiatives for people and families living with undiagnosed disease, including the open Rare-AI Archive. Serves People & families living with undiagnosed disease Stewarded by Hygieia · anchor Wilhelm Foundation Governance on record [WilhelmAI.aDNA](/vaults/wilhelmai/) Connect ↓ Wilhelm Foundation (Helene & Mikk Cederroth) · Apache-2.0 + CC-BY-4.0
- ### Rare Archive
Open-source rare-disease AI Rare Archive is an open-source rare-disease AI project — the diagnosis-acceleration pillar of AI4U — governed under the Wilhelm Foundation, with a canonical home at Wilhelm-Foundation/rare-archive. Serves Rare-disease diagnosis acceleration Stewarded by Mnemosyne · anchor Wilhelm Foundation Governance on record [RareArchive.aDNA](/vaults/rarearchive/) [Visit ↗](https://github.com/Wilhelm-Foundation/rare-archive) Connect ↓ Wilhelm Foundation (Helene & Mikk Cederroth) · Apache-2.0 + CC-BY-4.0
## Connect to a subnetwork
Three paths, in increasing depth — no account, no waitlist.
- ### Follow the work
Where a subnetwork has a public face, its card links it — the Rare Archive
repository and the World Genome Academy site are followable today; the others are still
building theirs. The open record is the front door.
- ### Connect to a subnetwork
Read a subnetwork's shared context from inside your own vault. You add a small
directory that points at theirs — a `federation_ref` block — and nothing is
copied, so their context stays theirs.
[Federation readiness](/patterns/federation-readiness/) covers what to check
before you connect, and before you share your own context back.
- ### Contribute
Join the work itself. The [community ladder](/community/) runs from vault user
to standard steward, and the
[contribution standards](/community/community-contribution-standards/) spell out
what a good contribution carries.
The boundary from [the network](/network/) holds here too: everything stays local by
default. Connecting is opt-in per vault — each node decides what it shares with a
subnetwork, and what never leaves the machine.
This is the whole connect surface today: the three paths above. What the commons already
knows about itself — and the horizon past it — is laid out plainly in
the band below.
## The commons, today
There is no activity feed here yet — the governance record is the social surface.
This is what the network's registry knows about who tends each subnetwork, shown plainly,
with nothing it doesn't.
- ### [World Genome Academy](/vaults/wga/)
Stewarded by Founding stewards · governance being formalized Governance record `wga.aDNA/CLAUDE.md`
- ### [Context Commons](/vaults/contextcommons/)
Stewarded by Founding-steward today — community governance as it grows Governance record `ContextCommons.aDNA/CLAUDE.md`
- ### [Wilhelm AI for the Undiagnosed](/vaults/wilhelmai/)
Stewarded by Hygieia · anchor Wilhelm Foundation Carries the work of Wilhelm Foundation (Helene & Mikk Cederroth) Shared under Apache-2.0 + CC-BY-4.0 Governance record `WilhelmAI.aDNA/CLAUDE.md` Declared relationships umbrellas RareArchive · federates Astro, III
- ### [Rare Archive](/vaults/rarearchive/)
Stewarded by Mnemosyne · anchor Wilhelm Foundation Carries the work of Wilhelm Foundation (Helene & Mikk Cederroth) Shared under Apache-2.0 + CC-BY-4.0 Governance record `RareArchive.aDNA/CLAUDE.md` Declared relationships under the WilhelmAI umbrella
Registry regenerated 2026-08-17 from the node inventory · member records
last synced 2026-05-24. Honest activity, today, is exactly this: the dates
above and the relationships each vault declares.
What you won't find here: contributor counts, stars, or follower numbers. The registry
doesn't record them, so this page doesn't display them.
ℹ The horizon
Profiles, follows, feeds, and shared governance surfaces are **not built yet**.
They're being designed on the network's membership and federation substrate — the
same opt-in, local-by-default machinery the boundary above describes. Until they ship,
the registry and the open governance record you're reading are the whole social layer.
The network builds toward that horizon rather than implying it arrived.
## Join & steward
Language and DNA are our shared heritage. So is context — held in common, stewarded in the open, and put to work for the good of all. Bring a subnetwork, or connect to one that's already here.
[Add your subnetwork](https://github.com/aDNA-Network/aDNA) [How federation works](/patterns/federation-readiness/)
---
## https://adna.network/community/
# Community
aDNA is built by people and agents together, in the open. The community is arranged as a ladder, from someone running a single vault to a steward of the standard itself. Everything it decides is a public record, not a claim. Here is how it works today.
## The participation ladder
Each level stands on its own. You get the full value at Level 0 without joining in at all. Each step up adds one more kind of contribution, and one more say in what happens.
- Level 0 User Clone the standard and use it for your own projects. No community interaction required — you get the full value locally. [Get started →](/get-started/)
- Level 1 Contributor Approve the improvements your agents surface and send them upstream through the public repository. [Contribution standards →](/community/community-contribution-standards/)
- Level 2 Quest Runner Run structured community experiments and submit results that turn standard questions into evidence, not opinion. [How the processes work →](/community/community-processes/)
- Level 3 Steward Shape the standard's direction — design quests, review contributions, write migrations. Recognized by maintainers, never self-appointed. [The steward role →](/community/community-roles/)
## How the commons is governed
The community isn't asserted here; it's a record. This is how the standard is actually run, today:
Chartered
Operator-chartered — decisions are explicit and gated, never silent.
Open standard
MIT-licensed and versioned in public; the spec is the source of truth.
Change process
Public. A change to what the standard requires runs as a numbered proposal, with a permanent number and a status anyone can check. Everything else runs as an ordinary issue or pull request.
Code of conduct
Contributor Covenant v2.1, in the repository. Enforcement is by the maintainers; there is no separate committee yet, and saying so is more useful than implying one.
AI-assisted contribution
Welcome, and disclosed. Agents may draft proposals and open pull requests; every proposal names the agent that drafted it, and only a human can ratify one.
Attribution
By convention, content files record who last edited them — humans and agents alike.
Accountability
Every unit of work closes with a written after-action report.
What you won't find here: member counts, follower numbers, or activity feeds. The record doesn't track them, so this page doesn't show them.
ℹ The horizon
Member profiles, follows, activity feeds, and shared governance-voting surfaces are not built yet. They are being designed on the network's opt-in, local-first membership substrate — the same machinery the network page describes. Until they ship, the participation ladder, the governance record on this page, and the early community space below are the community layer. The network builds toward that horizon rather than implying it arrived.
## The community space
A real-time community space is open at
[community.adna.network](https://community.adna.network) — a
self-hosted Fluxer instance in its early days. Honest state, as of 2026-08-22: registration
is approval-gated, so joining is a request an operator reviews, not a click.
Its rules are published, short, and explicitly interim — worth reading before you join:
the [terms of service](https://github.com/aDNA-Network/community-policies/blob/main/terms.md),
the [privacy notice](https://github.com/aDNA-Network/community-policies/blob/main/privacy.md), and
the space's own [code of conduct](https://github.com/aDNA-Network/community-policies/blob/main/code_of_conduct.md),
which sits under the project-wide Contributor Covenant named above.
Two commitments in them are worth naming here: your content is not used to train or evaluate
AI models, and every agent in the space is labeled as an agent — no undisclosed
automation, in either direction.
Conversation happens there. Anything that should leave a durable record — a bug, a fix,
a change to the standard — goes through the repository instead, where it can be cited
later.
## How the standard changes
Changes to the standard are proposed as numbered
[aDNA Enhancement Proposals](/community/proposals/). Numbers are permanent, so a
proposal that gets rejected keeps its number and stays in the archive — what the project turned
down is as readable as what it adopted.
Anyone may file one. Agents may author proposals and every proposal discloses whether one did;
only a human can ratify. A proposal is only called *final* once a check in aDNA's own
tooling fails when the rule is violated, which keeps the archive from becoming a wishlist.
## Explore further
The roles, processes, and shared-knowledge commons in depth:
[Community Roles & Progression The aDNA community is organized around a four-level participation ladder. Each level is self-contained — no level requires the next.](/community/community-roles)[Community Processes Concrete workflows for participating in the aDNA community. Each process maps to a level on the participation ladder.](/community/community-processes)[Context Commons Connection The shared knowledge pool that emerges when individual aDNA vaults publish their best context files, patterns, and lattices for community reuse.](/community/community-context-commons)[Contribution Standards Naming conventions, quality gates, and submission workflows for contributing to the aDNA standard and community.](/community/community-contribution-standards)
## Contribute
The standard is built in the open. Agents draft the changes; only a person can ratify one. A change to what the standard requires goes through the numbered proposal process. Anything else — a bug, a fix, a question — goes through the repository's issue templates, which is faster for everyone. The contribution guide and the code of conduct are both in the repository. AI-assisted contributions are welcome, as long as they say so.
[Contribute on GitHub](https://github.com/aDNA-Network/aDNA) [File a proposal](/community/proposals/)
---
## https://adna.network/community/community-context-commons/
# Context Commons Connection — aDNA Community
## Overview
The Context Commons is the shared knowledge pool that emerges when individual aDNA vaults publish their best context files, patterns, and lattices for community reuse. This document explains how community contributions flow into the commons, how published knowledge gets discovered and consumed, and how the commons relates to the participation ladder.
For the full conceptual framework, see [Context Commons (concept)](/learn/concepts/context-commons).
## The Feedback Loop
Individual vault work produces community knowledge through a four-stage cycle:
```
Create → Publish → Discover → Consume → Create (improved)
```
### 1. Create (In Your Vault)
All knowledge starts as project-local content. You write context files, design patterns, build lattice definitions — all for your own project's needs. No community awareness required.
**Self-reference**: This vault created 13 [ontology extensions](/glossary/glossary-ontology-extension), 26 content files, and 25 glossary entries during Operation Rosetta. All of it started as project-local knowledge for teaching aDNA.
### 2. Publish (To the Commons)
When vault-local knowledge has broader value, it can be published to the commons using aDNA's federation capabilities:
- **Context files** — high-quality context on a domain topic (e.g., protein structure prediction, supply chain logistics)
- **Patterns** — reusable architectural or workflow patterns
- **Lattice definitions** — composable workflow graphs
- **Templates** — file blueprints for new entity types
Publishing requires [FAIR metadata](/learn/concepts/fair-metadata): keywords for findability, license for legal clarity, provenance for trust, and identifiers for citation. The `latlab lattice publish` command handles the mechanics.
### 3. Discover (From the Registry)
Published knowledge becomes findable through:
- **Keyword search** — FAIR metadata tags enable semantic discovery
- **Registry browsing** — `latlab lattice pull` downloads published artifacts
- **Community curation** — Stewards highlight high-quality contributions
### 4. Consume (In Other Vaults)
Discovered knowledge gets pulled into new projects:
- Context files load into `what/context/` as reusable domain knowledge
- Patterns apply to new vault architectures
- Lattice definitions compose into project-specific workflows via `latlab lattice compose`
The consuming vault benefits from community-reviewed, FAIR-annotated knowledge instead of writing everything from scratch.
## Who Participates
| Participation Level | Commons Role |
|-------------------|-------------|
| **Level 0 (User)** | Consumer — pull from the commons, no contribution required |
| **Level 1 (Contributor)** | Publisher — submit context files and improvements |
| **Level 2 (Quest Runner)** | Validator — run experiments that test commons content quality |
| **Level 3 (Steward)** | Curator — review, tag, and promote commons contributions |
See [Community Roles](/community/community-roles) for full role definitions.
## Trust and Quality
Not all published knowledge is equal. The commons uses trust signals:
| Signal | Source | Meaning |
|--------|--------|---------|
| **FAIR completeness** | Automated check | Metadata is machine-readable and findable |
| **Community review** | Steward approval | Content quality meets contribution standards |
| **Citation count** | Usage tracking | Other projects have pulled and used this artifact |
| **Quest validation** | Side-quest results | Empirical testing confirms the artifact works as described |
## Related
- [Context Commons (concept)](/learn/concepts/context-commons) — full conceptual framework
- [FAIR Metadata (concept)](/learn/concepts/fair-metadata) — the metadata standard enabling discovery
- [Community Roles](/community/community-roles) — participation ladder
- [Community Processes](/community/community-processes) — contribution workflows
---
## https://adna.network/community/community-contribution-standards/
# Contribution Standards — aDNA Community
## Overview
This document defines the quality bar and submission process for contributing to the aDNA ecosystem. Whether you're submitting a glossary correction or a new ontology extension, these standards apply.
## Naming Conventions
All content files use the same naming pattern:
```
type_descriptive_name.md
```
- **Always underscores, never hyphens** in vault filenames
- **Type prefix** matches the entity type: `concept_`, `tutorial_`, `pattern_`, `glossary_`, etc.
- **Lowercase** throughout
- **Descriptive** — a reader should guess the file's content from its name
## Quality Gates
Every contribution must pass these checks:
1. **Frontmatter complete** — all required fields populated per the relevant template in `how/templates/`
2. **Dual-audience test** — legible to both developers and non-developers
3. **Self-reference check** — cites a concrete vault example when explaining aDNA concepts
4. **Spec citation** — normative claims reference `adna_standard.md` with section numbers
5. **Cross-linking** — minimum 2 wikilinks to related files
## Submission Workflows
### Vault Contribution (Your Own Project)
Create and customize content in your own vault. No review required — your vault, your rules.
### Upstream Contribution (To the Standard)
1. Agent surfaces a framework-level improvement during normal work
2. You approve filing it as `how/backlog/idea_upstream_{slug}.md`
3. Optionally open a GitHub issue on `aDNA-Network/aDNA`
4. Maintainers and [Stewards](/community/community-roles) review
5. Accepted improvements merge into the next standard version
### Side-Quest Submission
1. Run the quest procedure in your vault
2. Record results in the specified format
3. Submit as a PR to the quest's `results/` directory
4. Results are aggregated across participants
## Participation Level Mapping
| Level | What You Can Submit |
|-------|-------------------|
| **Level 0 (User)** | Nothing required — work in your own vault |
| **Level 1 (Contributor)** | Upstream issues, backlog items |
| **Level 2 (Quest Runner)** | Quest results, improvement proposals |
| **Level 3 (Steward)** | Quest designs, migration prompts, standard updates |
## Related
- [Community Roles](/community/community-roles) — the participation ladder
- [Community Processes](/community/community-processes) — detailed workflow steps
- [Conformance Level](/glossary/glossary-conformance-level) — Starter/Standard/Full compliance tiers
---
## https://adna.network/community/community-processes/
# Community Processes — aDNA Community
## Overview
This document describes the concrete workflows for participating in the aDNA community. Each process maps to a level on the [participation ladder](/community/community-roles) — you only need the processes relevant to your level of engagement.
## Process 1: Upstream Contribution (Level 1+)
How framework-level improvements flow from individual vaults to the shared standard.
### Trigger
An AI agent working in any aDNA vault notices a gap during normal work — a missing template field, an undocumented naming pattern, a workflow that could be smoother. The agent mentions the finding at a natural pause point (end of task, [SITREP](/glossary/glossary-sitrep)).
### Steps
1. **Agent surfaces finding** — "I noticed that `template_session.md` doesn't include a field for estimated duration. This would help with token budget planning."
2. **User evaluates** — Is this a framework-level improvement (helps all vaults) or project-specific?
3. **User approves** — Agent creates `how/backlog/idea_upstream_{slug}.md` with the structured proposal
4. **Optional: open upstream issue** — If the user has GitHub CLI configured, the agent opens an issue on `aDNA-Network/aDNA`
5. **Community review** — Maintainers and [Stewards](/community/community-roles) evaluate the proposal
6. **Merge or defer** — Accepted improvements enter the next standard version
**Full protocol**: `how/skills/skill_upstream_contribution.md`
**Self-reference**: This vault itself has surfaced upstream improvements during its build — the 10 ontology extensions added here (concepts, tutorials, patterns, etc.) informed extensions to the base template.
## Process 2: Side-Quests (Level 2+)
How structured community experiments generate evidence for standard decisions.
### Trigger
A question arises that needs data from multiple environments before the right answer is clear. A [Steward](/community/community-roles) designs a quest; community members run it.
### Steps
1. **Browse** `how/quests/` for available quests
2. **Read the quest spec** — procedure, expected output format, estimated cost
3. **Run the procedure** in your own vault with spare agent tokens
4. **Record results** in the required format
5. **Submit** as a PR to the quest's `results/` directory
6. **Aggregation** — `what/lattices/tools/aggregate_results.py` combines all submissions
7. **Decision** — Maintainers use aggregated data to make evidence-based standard choices
### Quest Lifecycle
```
draft → open → running → analyzing → decided → archived
```
Quests are not permanent. Once enough data is collected and a decision is made, the quest moves to `archived` status with its conclusion documented.
## Process 3: Version Migration (Level 1+)
How vaults stay current as the standard evolves.
### Trigger
A new version of the aDNA standard is released with improvements from community contributions.
### Steps
1. **Check for available migrations** in `how/migrations/`
2. **Read the migration guide** for the target version
3. **Create a git tag** as a rollback point (safety)
4. **Run the migration prompt** — the agent walks through upgrading governance files, templates, and structure
5. **Verify** — check that the vault still validates
6. **Commit** the upgraded vault
## Process 4: Content Review (Level 3)
How Stewards review community contributions.
### Review Checklist
1. **Quality gates** — does the contribution pass all gates from [Contribution Standards](/community/community-contribution-standards)?
2. **Standard alignment** — is it consistent with the normative spec ([adna_standard.md](/glossary/glossary-adna))?
3. **Scope** — is it framework-level (helps all vaults) or project-specific?
4. **Backward compatibility** — does it break existing vaults?
5. **Migration path** — if it changes structure, is there a migration prompt?
### Feedback
Reviews use constructive challenge, evidence-based reasoning, and clear outcomes. Reviewers state opinions, not options — "Merge because X" or "Revise because Y."
## Related
- [Community Roles](/community/community-roles)
- [Contribution Standards](/community/community-contribution-standards)
- [Context Commons Connection](/community/community-context-commons)
---
## https://adna.network/community/community-roles/
# Community Roles & Progression — aDNA Community
## Overview
The aDNA community is organized around a four-level participation ladder. Each level is self-contained — no level requires the next. You get value at Level 0 without ever engaging with the community, and each subsequent level adds a new kind of contribution and influence.
This structure is documented in VISION.md as part of the Decentralized Frontier Lab model. This file makes the roles concrete: who does what, what capabilities each level unlocks, and how you progress.
## The Participation Ladder
### Level 0: User
**Who**: Anyone who clones the aDNA template and uses it for their own project.
**What you do**:
- Set up and customize your vault (triad, governance files, templates)
- Work with AI agents in your own project
- Extend the ontology for your domain
- Use [skills](/glossary/glossary-skill), [templates](/glossary/glossary-template), and tools from the base template
**What you don't need to do**: Interact with the community, submit anything upstream, or acknowledge other vaults exist.
**Value**: Structured knowledge architecture that both you and your agents can navigate. Faster agent orientation, better session continuity, organized project knowledge.
**Self-reference**: This vault (`aDNA.aDNA/`) started at Level 0 — a fork of the base template, customized with 10 ontology extensions for documentation. The `last_edited_by: agent_stanley` field on every file is a Level 0 artifact: local attribution, no community interaction required.
### Level 1: Contributor
**Who**: A Level 0 user whose agents have surfaced framework-level improvements and who approves submitting them upstream.
**What you do**:
- Everything from Level 0
- Review agent-surfaced improvement findings at natural pause points
- Approve backlog items for promising improvements (`how/backlog/idea_upstream_*.md`)
- Optionally open GitHub issues on `aDNA-Network/aDNA`
**How to get here**: It happens organically. Your agent notices a missing template field or an undocumented pattern during normal work, mentions it at a session close, and you say "yes, file that." Follow [Contribution Standards](/community/community-contribution-standards) and `how/skills/skill_upstream_contribution.md`.
**Value**: Your vault improves as the standard improves. Your contributions make the tools better for everyone.
### Level 2: Quest Runner
**Who**: A Level 1 contributor who runs structured community experiments (side-quests) with spare agent tokens.
**What you do**:
- Everything from Level 1
- Browse quests in `how/quests/`
- Run experiments following the specified procedure
- Submit structured results as PRs
- Your data joins others to inform evidence-based standard decisions
**How to get here**: Browse `how/quests/`, pick one that interests you, follow the procedure, submit results. Each quest takes 10-30 minutes and costs a few thousand tokens.
**Value**: You contribute to evidence-based standard development. Questions like "should FAIR metadata be flat or nested?" get answered with data from multiple environments, not committee opinion.
### Level 3: Steward
**Who**: An experienced contributor who shapes the standard's direction.
**What you do**:
- Everything from Level 2
- Design new quests for questions the community needs answered
- Review upstream contributions and side-quest results
- Write migration prompts for version upgrades
- Participate in standard evolution discussions
**How to get here**: Sustained contribution at Levels 1-2 plus demonstrated understanding of the aDNA standard. Stewards are recognized by existing maintainers, not self-appointed.
**Value**: You're actively steering the direction of the knowledge architecture standard.
## Role Interactions
| Role | Creates | Reviews | Decides |
|------|---------|---------|---------|
| User | Vault content, ontology extensions | Own work | Own vault |
| Contributor | Upstream issues, backlog items | Agent findings | What to submit |
| Quest Runner | Quest results | Quest procedures | Which quests to run |
| Steward | Quests, migrations, standard updates | Contributions, results | Standard direction |
## Related
- [Contribution Standards](/community/community-contribution-standards)
- [Context Commons Connection](/community/community-context-commons)
- [Conformance Level](/glossary/glossary-conformance-level)
---
## https://adna.network/community/proposals/
[← Back to community](/community/)
# Proposals
Changes to the aDNA standard are proposed as numbered **aDNA Enhancement Proposals**.
The process is described by [AEP-1](/community/proposals/aep-1/), which is itself a
proposal, filed through the process it describes.
Numbers are permanent. A proposal that is rejected or withdrawn keeps its number and stays on this
page, so what the project turned down is as readable as what it adopted.
## The archive
All aDNA Enhancement Proposals, by number
# Title Status Author Sponsor
[AEP-1](/community/proposals/aep-1/) [The aDNA Enhancement Proposal process](/community/proposals/aep-1/) final Stanley Sekar Stanley Sekar
[AEP-2](/community/proposals/aep-2/) [Canonical URL casing and permanent redirects](/community/proposals/aep-2/) review Stanley Sekar Stanley Sekar
## The states
Every proposal is in exactly one of eight states. Occupancy below is counted from the archive above,
not asserted — which is why most rows read zero.
The eight proposal states, their meanings, and how many proposals are in each
State Meaning Terminal Currently
draft Written down and numbered, not yet under review. no 0
review Under public review; a sponsor is shepherding it. no 1
accepted Decided yes; implementation may begin. no 0
final Implemented and enforced by a check that fails when the rule is violated. yes 1
rejected Reviewed and declined, with the reason recorded. yes 0
withdrawn Retracted by its author before a decision. yes 0
superseded Replaced by a later proposal, which is named on it. yes 0
dormant Nobody is shepherding it; revivable by anyone. no 0
A terminal state is terminal for that number. A revived idea returns as a new proposal that names the
one it descends from; the old number keeps its old outcome.
## How to file one
Open a change proposal on the
[aDNA repository](https://github.com/aDNA-Network/aDNA/issues/new?template=change_proposal.md).
If the change is *normative* — if it alters what the standard requires of a conforming vault —
it becomes an AEP and is numbered here. If it does not, it stays an ordinary issue or pull request,
which is faster for everyone.
Agents may author proposals, and every proposal discloses whether one did. Only a human can ratify:
no proposal reaches `accepted` without a named person and a date. The
[contribution guide](https://github.com/aDNA-Network/aDNA/blob/main/CONTRIBUTING.md)
covers the non-normative routes, and participation is governed by the
[code of conduct](https://github.com/aDNA-Network/aDNA/blob/main/CODE_OF_CONDUCT.md).
ℹ The state of this process
The process began on 20 August 2026. There are **2** proposals on record and the next number to be assigned is
**AEP-3**. There is no published median review time here because none has
been measured yet; when there is enough history to compute one, it will appear.
---
## https://adna.network/community/proposals/aep-1/
# AEP-1: The aDNA Enhancement Proposal process
This proposal describes the process by which the aDNA standard changes. It is itself an AEP, filed
through the process it describes, so that the process has been used at least once before anyone is asked
to use it.
## Why a process at all
aDNA is a standard. A standard that one person can change silently is a preference with good
documentation. The difference between the two is a public record: what was proposed, who proposed it,
what was decided, and — the part most projects omit — **what was decided against**.
This process is deliberately small. It is not a foundation, a working-group structure, or a voting
system. It is a numbered list, a set of states, and a rule about who may say yes.
## The numbering law
Proposals are numbered sequentially from 1 and cited as `AEP-1`, `AEP-2`.
**A number, once assigned, is never reassigned, never reused, and never removed** — including for
proposals that are rejected or withdrawn. There are no gaps in the sequence, and a rejected proposal is
as retrievable as an accepted one.
This is the load-bearing rule. It means the archive cannot be curated after the fact: you can read what
this project turned down, and judge it on that. A number is assigned when a proposal is first written
down, not when it is agreed to. **A number is not an endorsement.**
## The states
| State | What it means | Terminal |
|---|---|---|
| `draft` | Written down, numbered, not yet under review | no |
| `review` | Under public review; a sponsor is shepherding it | no |
| `accepted` | Decided yes; implementation may begin | no |
| `final` | Implemented *and* enforced — see below | **yes** |
| `rejected` | Reviewed and declined, with the reason recorded | **yes** |
| `withdrawn` | Retracted by its author before a decision | **yes** |
| `superseded` | Replaced by a later proposal, which is named on it | **yes** |
| `dormant` | Nobody is shepherding it; revivable by anyone | no |
Proposals move forward `draft → review → accepted → final`. Anything not yet terminal can be withdrawn or
go dormant; a proposal in review can be rejected; something accepted or final can later be superseded.
**A terminal state is terminal for that number.** If a rejected idea comes back, it comes back as a new
proposal that names the one it descends from. The old number keeps its old outcome.
`dormant` exists because proposals stall, and a process that cannot say so accumulates a review queue
that is quietly fictional.
## What `final` requires
`accepted` means the decision is made. **`final` means the standard enforces it.**
A proposal reaches `final` only when a check in aDNA's own tooling — `adna_validate`, the site gate suite,
or the compliance checker — **will fail if the rule is violated**. Until that check exists, the proposal
stays `accepted`, and this archive shows it as `accepted`.
That distinction is the whole difference between a standard and a wishlist. It also means the `final`
column here is a claim the test suite backs, rather than a claim about intent.
## Who may file, sponsor, and decide
**Anyone may file.** Open a change proposal on the
[aDNA repository](https://github.com/aDNA-Network/aDNA/issues). If the change is *normative* — if it
alters what the standard requires of a conforming vault — it becomes an AEP. If it does not, it stays an
ordinary issue or pull request, which is faster for everyone. A process that swallows every typo fix is a
process nobody uses.
**A sponsor** is a person who has agreed to shepherd a proposal through review. Proposals without one go
`dormant` rather than sitting in `review` indefinitely.
**Agents may author proposals, and their authorship is disclosed.** Every proposal carries a field naming
the agent that drafted it, if one did. This one was drafted by an agent. That disclosure is a required
field rather than a convention, because disclosure that can be omitted is disclosure that will be
omitted.
**Only a human ratifies.** No proposal reaches `accepted` on an agent's say-so. The person who ratified
it is named on the proposal, with the date. This is not a policy adopted for the occasion — it is how
this project already operates internally, written down where it can be held to.
## Proposals and internal decisions
aDNA keeps a second, older record: Architecture Decision Records, in the vault at `what/decisions/`.
They are not the same thing and neither replaces the other.
| Aspect | ADR | AEP |
|---|---|---|
| Governs | how this project builds its own vault | how the **standard** evolves |
| Audience | the maintainers and their agents | anyone implementing aDNA |
| Filed by | agents, internally | anyone, in public |
An accepted AEP may produce ADRs that implement it. The existing ADR record is not renumbered or
converted into proposals — it is this project's own history and stays that way. **AEP-1 is the first AEP
because the process starts now**, and this archive should not imply a history it does not have.
## The state of the process, honestly
This process is new — it began on 20 August 2026. The archive below it is short, and most numbers are
unassigned. The counts shown on the proposals page are read from the archive itself rather than typed
into the page, so they cannot flatter it.
There is no published median review time here, because none has been measured. When there is enough
history to compute one, it will appear. An unmeasured metric is not a small dishonesty in a document
about how decisions get made.
---
## https://adna.network/community/proposals/aep-2/
# AEP-2: Canonical URL casing and permanent redirects
**Status note.** This proposal is in `review`. It has not been decided and nothing in it is currently
required of anyone. It is the first substantive proposal filed under [AEP-1](/community/proposals/aep-1/).
## Summary
Vault names in aDNA are mixed-case and carry a suffix — `Operations.aDNA`, `RareArchive.aDNA`. URLs are
not. This proposal would make two rules normative for any conforming vault that publishes a web surface:
1. **A canonical slug law.** A vault's route slug is `lowercase(name)` with the `.aDNA` suffix dropped and
anything outside `[a-z0-9_-]` folded to `_`. So `Operations.aDNA` publishes at `/vaults/operations/`.
Display names keep their true casing in content; only URLs normalize.
2. **A published URL never dies.** When a route changes, the old one issues a `301` to the new one, and
that redirect is kept permanently rather than pruned later.
## Motivation
Both rules already exist as an internal decision governing one site
([ADR-051](/reference/), adopted 2026-08-18). They were adopted after a census rather than on taste: across
all 74 vaults in the registry, the drop-suffix form produced 74 distinct slugs with **zero** collisions,
and 50 of 74 vaults were already routing that way. Keeping the suffix would also have been collision-free
— it would just have broken 50 working URLs to fix 24.
The reason to raise it to the standard is that mixed-case URLs are not a style question once vaults start
linking to each other. `/vaults/RareArchive/` and `/vaults/rarearchive/` are different resources to a web
server and the same resource to a human, and a federated network of vaults that has not agreed which one
is real will accumulate hard 404s between them. This site had 24 of them before the rule was applied.
## Specification (proposed)
A conforming vault that publishes a web surface:
- **MUST** derive route slugs by the law above, and **MUST** apply it where routes are built rather than
where data is written — so that a hand-edited record cannot reintroduce a mixed-case route.
- **MUST** serve a `301` from any previously published route to its canonical successor.
- **MUST NOT** remove a redirect once published.
- **SHOULD** carry a check that fails the build when a non-conforming route appears.
Vaults that publish no web surface are unaffected.
## What is unresolved
A draft that lists no open questions is usually a draft that has not been read carefully.
- **Scope.** Is this a rule about *vault* routes specifically, or about every route a vault publishes?
The census only covered vault routes.
- **Non-Latin names.** The `[a-z0-9_-]` fold is defined for ASCII. A vault named in another script would
fold to a string of underscores, which is a bug rather than a policy. Transliteration or percent-encoding
needs a decision before this could apply generally.
- **Enforcement.** Under [AEP-1's §4](/community/proposals/aep-1/), this cannot reach `final` until a check
in aDNA's own tooling fails when the rule is violated. One exists for this site (`gate-30`); a check that
ships *with the standard*, so any vault gets it, does not yet exist. That work is the real cost of this
proposal.
- **Existing published vaults.** The rule is cheap for a vault that has not launched and expensive for one
that has. A migration path — likely "apply going forward, redirect the past" — needs writing.
## Costs and objections
The honest objection is that this is a web-publishing convention being written into a knowledge-architecture
standard, and standards get worse when they annex adjacent domains. A reasonable counter-proposal is that
it belongs in a publishing profile rather than the core specification. That question should be settled
before this moves out of `draft`.
---
## https://adna.network/get-started/
*[image: Cozy pixel-art scene of a desk and computer with a glowing cyan DNA helix rising from the screen — a new aDNA workspace coming alive]*
Illustration generated with Google Imagen 4 Ultra (imagen-4.0-ultra-generate-001) in the ss-ghibli-pixel / Tokyo Night register, commissioned under ADR-032 and now governed by ADR-053.
# Get Started
Set up your own aDNA workspace — a local, agent-readable home for every project's context — in
about 5 minutes. The workspace is files on your machine and makes no network calls of its own.
ℹ Prerequisites
Git, and [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
installed via `npm install -g @anthropic-ai/claude-code`. Obsidian is optional — vaults are
plain Markdown, so any editor works.
💡 What you'll have when you're done
A `~/aDNA/` workspace that ships ready: the workspace `CLAUDE.md` router
(your agent's map between projects) pre-instantiated at the root; the standard itself embedded in a hidden
`.adna/` folder (your agent reads it, never edits it — updates arrive with `git pull`
at the workspace root); and your first `.aDNA/` project, scaffolded for you when the
agent follows the standard's project-fork skill, with its own git history — kept out of the workspace
image's history by design.
## What this command does, before you run it
`git clone https://github.com/aDNA-Network/aDNA.git ~/aDNA && cd ~/aDNA && claude`
- **Writes one directory: `~/aDNA/`.** Nothing outside it — no system
settings, no `PATH` changes, no daemon, no login item. If you would rather not use that path,
clone anywhere: nothing in the workspace depends on its location, and `~/aDNA` is
only the default the docs assume.
- **The `&& claude` starts an agent in that directory**, which reads the
instruction files you just cloned — `CLAUDE.md` at the root, and the standard in
`.adna/`. That is the real trust question here, and it is a fair one: these files are
prompt-ware, and prompt-ware is executed by the agent that reads it.
- **So read them first.** [Every file the agent reads on first run, annotated →](/get-started/what-your-agent-reads/)
They are shown verbatim, at a pinned commit, with hashes you can check against your own clone.
- **The workspace sends nothing anywhere.** No account, no telemetry, no network call
after the clone — it is plain Markdown on your disk. **Your agent is a separate question,
and the command above starts one:** the trailing `&& claude` launches
Claude Code, which needs an Anthropic account and sends the files it reads to Anthropic. That is
the agent's network behaviour, not the workspace's — and you can skip it, open the files in any
editor, and the workspace still works.
- **This is a Claude Code convention.** The workspace is plain Markdown that any tool can read,
but this one-command flow assumes Claude Code specifically. Other agents can read the same files; they
will not run this command.
- **To undo it: `rm -rf ~/aDNA`.** There is nothing else to uninstall.
## 1. Clone the workspace
The clone *is* your workspace — not a template you copy from. The router comes pre-instantiated
and the standard comes embedded; there is nothing to bootstrap by hand.
```
git clone https://github.com/aDNA-Network/aDNA.git ~/aDNA
```
## 2. Start Claude Code
Run `claude` in the workspace. The agent reads the router, sees a fresh workspace
with no projects yet, and walks you through creating your first one:
```
cd ~/aDNA
claude
```
ℹ What a first run looks like — not yet recorded
There was a sample transcript here. We wrote it by hand, and it showed output the software does
not actually print, so we removed it rather than leave a plausible-looking invention on the page
you use to decide whether to trust us. A real recording, from a clean machine, replaces it once
we have made that run and measured it.
In the meantime the honest version of the same thing is the source:
[read the files your agent reads](/get-started/what-your-agent-reads/), including the
project-fork skill it follows here — step by step, so you can predict what appears on disk.
With no project in the workspace yet, the router sends the agent to the standard's
project-fork skill, which scaffolds `.aDNA/` — its [triad](/glossary/glossary-triad/) of
`what/` · `how/` · `who/`, its governance
files, and its own git history. It then offers to run an onboarding interview that customises the
new project for your domain; you can take it now or leave it for the first session inside the
project. When the scaffolding finishes, your workspace looks like this:
```
~/aDNA/
├── CLAUDE.md # workspace router (ships with the clone)
├── .adna/ # the standard, embedded (read-only)
└── my_project.aDNA/ # your first project — a context graph
├── CLAUDE.md # the project's own governance
├── what/ # knowledge: context, decisions, artifacts
├── how/ # operations: sessions, missions, skills
└── who/ # people: roles, coordination
```
From here, work happens *inside* projects: `cd my_project.aDNA && claude`
and the agent picks up that project's governance automatically.
ℹ The whole flow, one command
Both steps, chained — auditable inline, nothing executed from the network:
`git clone https://github.com/aDNA-Network/aDNA.git ~/aDNA && cd ~/aDNA && claude`
## 3. Check it worked
"It worked" should be something you can verify, not something you feel. Five commands — the first
two print nothing and exit `0` on success; the last three print your vault list, your
project's contents, and its first commit:
```
test -f ~/aDNA/CLAUDE.md # the router your agent reads first
test -d ~/aDNA/.adna # the standard, embedded and read-only
ls -d ~/aDNA/*.aDNA # at least one project vault exists
ls ~/aDNA/.aDNA/what ~/aDNA/.aDNA/how ~/aDNA/.aDNA/who
git -C ~/aDNA/.aDNA log # its own history, separate from the image's
```
Replace `` with whatever you called your project. That the last one has its own
git log — not the workspace image's — is the check people most often skip and the one that matters:
your context graph is your repository from the first commit.
**Then the half that is actually the point.** Open a *new* agent session inside
`.aDNA/` and ask it something about the project. It should already know where it
is and what the project's governance says, without you telling it where to look. The five commands
prove files were written; this proves the thing the standard exists for.
## If something goes wrong
The surface here is small — a clone and an agent launch — so the list of ways it fails is short.
These are the failures the two commands can actually produce:
- `claude: command not found` — Claude Code is not installed, or not on your
`PATH`. Install it with `npm install -g @anthropic-ai/claude-code` and open a
new shell.
- `fatal: destination path '~/aDNA' already exists` — you already have a workspace
there. Either work in it, or clone somewhere else; nothing depends on the path.
- **The agent does not seem to know about aDNA.** It is almost always started in the
wrong directory. The router is `CLAUDE.md` at the workspace root, so
`cd ~/aDNA` first — an agent launched from your home directory reads nothing.
- **You want to check what the agent is acting on.** Every file it reads on first run is
[published here verbatim](/get-started/what-your-agent-reads/), with hashes to compare
against your clone.
This list is short because it is drawn from what the commands can do, not from a support inbox.
It will grow as real installs are recorded.
## Removing it
`rm -rf ~/aDNA` — and that is the whole uninstall. Nothing was installed outside
that directory, so there is no package to remove, no configuration to revert, and no service to stop.
If you moved your projects elsewhere first, they are ordinary git repositories and keep working.
ℹ Existing installs (pre-June-2026 layout)
Installed earlier, with a cloned hidden `.adna/` plus a copied router? It keeps working:
the previous template repository is preserved read-only at
[adna-legacy](https://github.com/aDNA-Network/adna-legacy), and your clone's old URLs
redirect there — frozen, so nothing underneath you changes. To move to the current layout, run the
standard's `skill_workspace_upgrade` from your workspace.
- Try this in Claude Code
Claude Code is Anthropic's official CLI (a terminal tool for AI-assisted development). Run this tutorial step by step with AI assistance — ask questions, get unstuck, and go deeper on any concept.
`npm install -g @anthropic-ai/claude-code`
## Next steps
You just built a node in a living network. Grow it — then see where it connects: **Where it joins:** the [living registry](/vaults/) of vaults and [the network](/network/) your project can federate with — building in the open is the whole point.
- **Ready to shape it:** aDNA is built in the open — see [how to propose a change](/community/community-contribution-standards/) to the standard or contribute a pattern, vault, or idea.
- [What is aDNA?](/learn/what-is-adna) — the five-minute conceptual tour
- [The Triad](/learn/concepts/triad) — why every project splits into what / how / who
- [Tutorial: Create Your First CLAUDE.md](/learn/tutorials/first-claude-md)
- [Tutorial: Navigate a Vault](/learn/tutorials/navigate-a-vault) — reading a context graph like an agent does
- [Knowledge graphs](/learn/concepts/knowledge-graph) — what your workspace grows into
- See it live: the [aDNA repository](https://github.com/aDNA-Network/aDNA) is the workspace image itself — clone it and you are holding everything this page described.
---
## https://adna.network/get-started/what-your-agent-reads/
# What your agent reads
aDNA is Markdown instructions that an agent reads and acts on. That is the whole mechanism, and
it is also the reason you might not want to run our install command on a stranger's say-so:
the files *are* the program.
So read them first. Below is every file a fresh workspace hands your agent on its first run —
all 4 of them, about 72 KB, shown exactly as they arrive. Nothing here
is a paraphrase or a screenshot. If you would rather read them in the repository, or diff them
against what you cloned, every file links to its source at the same commit.
ℹ Where these came from
Vendored from [the standard](https://github.com/aDNA-Network/aDNA/tree/v8.11/.adna) at release `v8.11` (2026-09-11). The build
refuses to publish this page if those bytes stop matching that commit, so the copy you are reading
cannot quietly drift from the copy you would clone.
## The reading order
This is the order your agent meets them in, not a ranking. The first two are read on every
session; the last two are procedures it follows only when you ask for a new project.
- 1
### [The workspace router](/get-started/what-your-agent-reads/workspace-router/)
`how/templates/template_workspace_claude.md` · 150 lines The CLAUDE.md that sits at the root of your new workspace — the first file an agent reads. **Why your agent reads it.** An agent started anywhere in the workspace reads this to work out which project you mean before it does anything else. It is a map, and it is the reason the standard needs no index service and no daemon. **What to look for.** Read it as what it is: instructions addressed to an agent, in English. There is no code path here — nothing fetches, nothing installs, nothing phones home. The strongest check is the plainest one: if this file asked an agent to send your files somewhere, you would be able to read the sentence that said so. [Read template_workspace_claude.md in full →](/get-started/what-your-agent-reads/workspace-router/)
- 2
### [The standard's own governance](/get-started/what-your-agent-reads/standard-governance/)
`CLAUDE.md` · 360 lines The CLAUDE.md inside the hidden .adna/ folder — the standard describing itself. **Why your agent reads it.** Your agent reads this to learn the conventions it is expected to follow: the triad, the entity types, the session and mission protocol. This is the file that makes the standard self-teaching rather than a PDF you have to remember. **What to look for.** Its frontmatter carries role: template. That single field is load-bearing — it is what tells an agent this directory is the standard itself and must never be edited, which is why updates arrive by git pull instead of by merge conflict. [Read CLAUDE.md in full →](/get-started/what-your-agent-reads/standard-governance/)
- 3
### [The skill that actually runs first](/get-started/what-your-agent-reads/skill-project-fork/)
`how/skills/skill_project_fork.md` · 261 lines The procedure an agent follows to scaffold your first project. **Why your agent reads it.** This is the one that fires on a fresh clone. The workspace has no projects yet, so the router routes here — it creates .aDNA/, its triad of what/ how/ who/, its governance files, and its own git history. **What to look for.** Follow it as a recipe and you can predict exactly what will appear on disk before you run anything. That predictability is the point of the tour: nothing below is a surprise. If you would rather do it by hand, you can — the skill is a description of file creation, not a binary. [Read skill_project_fork.md in full →](/get-started/what-your-agent-reads/skill-project-fork/)
- 4
### [The interview that comes second](/get-started/what-your-agent-reads/skill-onboarding/)
`how/skills/skill_onboarding.md` · 268 lines The first-run interview that customises a project vault for your domain — after one exists. **Why your agent reads it.** It is real and you will probably meet it, but not first, and it is not what builds your project. It gates on a forked project directory, so a brand-new workspace cannot trigger it; the fork skill above creates the project and then offers this. The get-started page used to have the order the other way round. **What to look for.** Read its own first-run detection conditions and you can see the gate for yourself — it checks for an uncustomised project and explicitly refuses to run against the base template. We are showing you the file rather than asking you to take our word for the correction. [Read skill_onboarding.md in full →](/get-started/what-your-agent-reads/skill-onboarding/)
## And what it builds
Those four files exist to produce one thing: a project that is legible to an agent without being
explained to it. Here is a real one — the triad of this vault, the context graph that publishes
the page you are reading:
### `what/`
- `assets/`
- `comparisons/`
- `concepts/`
- `context/`
- `decisions/`
- `design/`
- `docs/`
- `doctrine/`
- `exemplars/`
- `glossary/`
- `inventory/`
- `lattices/`
- `measurement/`
- `patterns/`
- `specs/`
- `tutorials/`
- `use_cases/`
### `how/`
- `backlog/`
- `campaigns/`
- `configs/`
- `federation/`
- `gates/`
- `migrations/`
- `missions/`
- `pipelines/`
- `publishing/`
- `quests/`
- `sessions/`
- `skills/`
- `standard/`
- `tasks/`
- `templates/`
- `workshops/`
### `who/`
- `adopters/`
- `assets/`
- `community/`
- `coordination/`
- `governance/`
- `identity/`
- `reviewers/`
- `team/`
Derived from this repository at build time, so it is the real directory listing rather than an
illustration of one. Knowledge in `what/`, operations in `how/`, people in
`who/` — that split is the standard's one structural rule, and everything above is in
service of it.
## Then what
If the files look sane, the [install page](/get-started/) states what the command
writes, what the agent does with it, and how to undo it. If they do not, you have lost a few
minutes of reading instead of an evening — which was the point of putting them here.
Last updated 2026-09-10 [View this file in the standard](https://github.com/aDNA-Network/aDNA/tree/v8.11/.adna)
---
## https://adna.network/get-started/what-your-agent-reads/skill-onboarding/
# The interview that comes second
[← What your agent reads](/get-started/what-your-agent-reads/)
The first-run interview that customises a project vault for your domain — after one exists.
**Why your agent reads it.** It is real and you will probably meet it, but not first, and it is not what builds your project. It gates on a forked project directory, so a brand-new workspace cannot trigger it; the fork skill above creates the project and then offers this. The get-started page used to have the order the other way round.
**What to look for.** Read its own first-run detection conditions and you can see the gate for yourself — it checks for an uncustomised project and explicitly refuses to run against the base template. We are showing you the file rather than asking you to take our word for the correction.
Path in the workspace
`.adna/how/skills/skill_onboarding.md`
Size
268 lines · 15.6 KB
Release
`v8.11` (2026-09-11)
SHA-256
`f06458baafdc22ab4f1cc727413b3d8a07b7acf359b12323bc174e9e45cbee61`
Source
[View skill_onboarding.md in the standard repository →](https://github.com/aDNA-Network/aDNA/blob/v8.11/.adna/how/skills/skill_onboarding.md)
Verify it yourself: `shasum -a 256 ~/aDNA/.adna/how/skills/skill_onboarding.md` after cloning
should print the hash above.
## skill_onboarding.md
```
---
type: skill
skill_type: agent
created: 2026-02-19
updated: 2026-09-11
status: active
category: onboarding
trigger: "First-run detection in CLAUDE.md indicates uncustomized forked project (no role: template, last_edited_by: agent_init)"
last_edited_by: agent_init
tags: [skill, onboarding, first-run, project]
requirements:
tools: []
context: ["CLAUDE.md", "MANIFEST.md", "STATE.md"]
permissions: ["write governance files", "create directories"]
---
# Skill: First-Run Onboarding
## Overview
Interactive onboarding flow for **forked aDNA projects** (not the base template). Invoked automatically when CLAUDE.md first-run detection identifies an uncustomized project. Walks the user through understanding aDNA, discovering their project needs, building an initial ontology, and customizing governance files.
**Important**: This skill runs inside a forked project directory, never in the base `adna/` template. If `MANIFEST.md` contains `role: template`, this is the base template — do not run onboarding here. Instead, guide the user to create a project via `skill_project_fork.md`.
## Trigger
Automatic — CLAUDE.md first-run detection triggers this skill when:
1. `MANIFEST.md` does NOT have `role: template` (this is a forked project, not the base template)
2. `how/sessions/history/` is empty (no completed sessions)
3. `MANIFEST.md` frontmatter has `last_edited_by: agent_init`
If conditions 2 and 3 are true (and condition 1 confirms this is a project), load this skill and begin at Step 1.
If only one of conditions 2-3 is true (partial onboarding), resume from the first incomplete step.
## Parameters
None. This skill is self-guided through conversation with the user.
## Requirements
### Tools/APIs
- File read/write access to the vault
### Context Files
- `CLAUDE.md` — project structure and agent protocol
- `MANIFEST.md` — project identity (will be customized)
- `STATE.md` — operational state (will be customized)
- `what/docs/adna_standard.md` — full spec (reference only)
### Permissions
- Write governance files (CLAUDE.md, MANIFEST.md, STATE.md)
- Create directories and AGENTS.md files for ontology extensions
## Implementation
### Step 1: Welcome, Introduce aDNA, and Collect Identity
Greet the user warmly but directly. Introduce yourself under the vault's current persona — the default-when-unresolved is **Berthier**, the built-in agent chief of staff (the `{{persona}}` placeholder resolved at Step 8; a fresh fork never silently inherits the base name — it is offered, and kept or replaced there).
Ask the user what they'd like to be called: "Before we dive in — what should I call you?" Store their answer as `{username}` (lowercase, underscores). This will be used throughout the project for session tracking (`session_{username}_...`), file attribution (`last_edited_by: agent_{username}`), and session metadata (`operator: {username}`).
Explain aDNA in 2-3 accessible sentences: it's a knowledge architecture that gives your project persistent structure both humans and AI agents can navigate. This project was forked from the aDNA template and is ready to be customized for their domain.
Keep it approachable — no spec-heavy language. The user might be a developer, a researcher, or a team lead. Meet them where they are.
### Step 2: Explain the Triad
Introduce the three-directory structure:
- **`what/`** = What you know — knowledge, context, decisions, domain objects
- **`how/`** = How you work — missions, sessions, templates, pipelines
- **`who/`** = Who is involved — people, teams, coordination, governance
Make it concrete with the **Question Test**: "If you have a research paper summary, that answers 'what do we know?' → `what/`. A deployment checklist answers 'how do we deploy?' → `how/`. A team roster answers 'who works on this?' → `who/`."
Mention that this is extensible — they'll add their own entity types under the right leg in Step 6.
### Step 3: Explain Lattices and Context Graphs (brief, skippable)
Lattices are directed graphs connecting datasets, modules, and reasoning nodes into executable compositions. Four types:
| Type | What it does |
|------|-------------|
| `pipeline` | Deterministic DAG of processing stages |
| `agent` | LLM-driven reasoning and decision flow |
| `context_graph` | Knowledge structure connecting concepts |
| `workflow` | Operational process for human/agent procedures |
This vault includes tools to validate and visualize lattices, plus 13 ready-to-use examples across business, creative, research, and biotech domains.
**Lattice-skip path**: If the user's domain is non-computational or they seem unfamiliar with workflow automation, offer the skip:
> "Lattices model executable workflows — pipelines, reasoning chains, multi-step processes. They're powerful for computational work, but **the triad structure handles knowledge management perfectly well without them**. Would you like me to explain lattices in more detail, or shall we move on to exploring your project needs?"
If they skip, acknowledge it naturally and proceed to Step 4. Don't make it feel like they're missing something important — the triad is the core architecture, lattices are an optional layer.
**Tiered depth**: Point to `what/lattices/examples/` for examples. For the full spec, see `what/docs/adna_standard.md`.
Keep this brief — 30 seconds of explanation, not a lecture.
### Step 4: Explain Deployment Diversity
Two deployment forms:
- **Bare triad** (this project) — `what/how/who/` at project root. The full experience.
- **Embedded triad** — `.agentic/what/how/who/` inside an existing repo. For adding aDNA to existing codebases.
This project lives inside a `~/aDNA/` workspace alongside the aDNA base template. Each project in the workspace is self-contained — it can be moved out and still functions independently.
For multi-instance composition (nesting vaults, sibling projects), see `what/docs/adna_bridge_patterns.md`.
One or two sentences is enough here.
### Step 5: Discovery Conversation — Ask About Their Project
This is the most important step. Ask the user about their project, domain, and goals. Choose 2-3 questions that fit the conversation flow:
- "What are you building? What domain are you in?"
- "Is this for a team or are you working solo?"
- "What kind of knowledge will you be managing?" (research, code, operations, customer relationships, etc.)
- "Do you already use AI agents in your workflow?"
Listen for **domain signals** that inform ontology extensions in Step 6:
- Business/CRM terms → `who/customers/`, `who/partners/`, `who/contacts/`, `who/projects/`
- Startup/fundraising terms → `who/investors/`, `what/decisions/` (term sheets), `who/board/`
- Research terms → `what/papers/`, `what/datasets/`, `what/hypotheses/`, `what/experiments/`
- Software terms → `how/incidents/`, `how/deployments/`, `what/services/`, `what/apis/`
- Lab/science terms → `what/experiments/`, `what/compounds/`, `what/protocols/`
- Creative/agency terms → `who/clients/`, `what/creative_assets/`, `how/revision_cycles/`, `what/portfolio/`
- Personal learning terms → `what/courses/`, `what/books/`, `how/learning_goals/`, `what/skills/`
- Healthcare terms → `who/patients/`, `what/treatments/`, `what/protocols/`
- Legal terms → `what/cases/`, `what/contracts/`, `what/compliance/`
- Content/media terms → `what/publications/`, `how/editorial_pipeline/`
Don't ask all questions — read the room and ask what's relevant.
### Step 6: Suggest Ontology Extensions
Based on the discovery conversation, suggest domain-specific entity types with concrete examples. Common extensions:
| Domain | Suggested extensions |
|--------|---------------------|
| **Startup / Business** | `who/customers/`, `who/partners/`, `who/investors/`, `who/board/`, `who/contacts/`, `who/projects/` |
| **Research / Academic** | `what/papers/`, `what/datasets/`, `what/hypotheses/`, `what/experiments/` |
| **Biotech / Science** | `what/experiments/`, `what/compounds/`, `what/protocols/`, `what/datasets/`, `what/targets/` |
| **Software team** | `how/incidents/`, `how/deployments/`, `what/services/`, `what/apis/` |
| **Creative / Agency** | `who/clients/`, `what/creative_assets/`, `how/revision_cycles/`, `what/portfolio/` |
| **Personal Learning** | `what/courses/`, `what/books/`, `how/learning_goals/`, `what/skills/`, `how/habits/` |
| **Healthcare** | `who/patients/`, `what/treatments/`, `what/protocols/`, `what/compliance/` |
| **Legal** | `what/cases/`, `what/contracts/`, `what/compliance/`, `who/clients/` |
| **Content / Media** | `what/publications/`, `how/editorial_pipeline/`, `what/assets/` |
#### Classification Ambiguity Guidance
When suggesting an extension, **explain the triad placement** so the user builds intuition:
> "I'm suggesting `who/investors/` because investors are *people and organizations* — that's the WHO question. Their financial terms (term sheets, SAFE notes) go in `what/decisions/` because those are *things you decided or recorded*. The fundraising process itself goes in `how/campaigns/` because that's *how you execute* the raise."
Common classification decisions to explain:
- **Clients vs. projects**: Clients are WHO (people/orgs). Projects with clients are also WHO (they answer "who is this work for?"). But project *deliverables* are WHAT (knowledge artifacts).
- **Protocols vs. experiments**: A protocol template is HOW (process). A specific experiment using that protocol is WHAT (a knowledge record of what was done and learned).
- **Contracts**: The contract document itself is WHAT (a knowledge artifact). The client who signed it is WHO. The compliance process is HOW.
For each confirmed extension, use the **entity scaffolding skill** (`how/skills/skill_new_entity_type.md`) which automates:
1. Creating the directory under the appropriate triad leg
2. Generating an `AGENTS.md` with purpose and working rules
3. Creating a template in `how/templates/`
**Ask user to confirm before creating anything.** Show them the proposed structure with triad placement rationale and get approval.
### Step 7: Customize Governance Files
Update the three governance files with the user's project identity. Use the `{username}` collected in Step 1 for all `last_edited_by` fields.
**MANIFEST.md:**
- Replace the project description (line 13) with the user's project name and description
- Replace the detail paragraph (lines 15-16) with project-specific details
- Set `last_edited_by: agent_{username}` and `updated: ` in frontmatter
**STATE.md:**
- Update current phase to "Phase 1 — Onboarding Complete"
- Replace next steps with domain-specific actions based on discovery conversation
- Set `last_edited_by: agent_{username}` and `updated: ` in frontmatter
**CLAUDE.md:**
- If the user shared a project description in Step 5, update the project description in the Identity & Personality section (first paragraph after the personality block)
- Resolve the `{{persona}}` placeholder in Step 8 — keep the default chief-of-staff voice (`Berthier`) or set a custom persona
- Set `last_edited_by: agent_{username}` and `updated: ` in frontmatter
### Step 8: Personality Customization Offer
Conversational offer — don't make it a big deal:
"I'm operating as Berthier — a structured, operations-focused chief of staff. I can help you design your own agent personality for this vault, or you can keep me as-is. What would you prefer?"
**If user wants custom:**
1. Ask for: name, archetype/inspiration, 3-4 operating style principles, greeting style
2. Edit the Identity & Personality section of CLAUDE.md (between `## Identity & Personality` header and the first `---` separator) — replace the `{{persona}}` placeholder with their chosen name
3. Show them the result before saving
**If user keeps the default:**
- Substitute the `{{persona}}` placeholder → `Berthier` (the default chief-of-staff) throughout `CLAUDE.md`, then confirm and move on.
### Step 9: Portability Note
Brief mention — 2-3 sentences max:
"One more thing — what you build here has value beyond your project. Ontology extensions, lattice definitions, skills, and templates are portable and composable by design: they are plain files in a documented layout, so they can be copied, forked, and shared directly, without a platform in between. There is no marketplace today and none is promised here."
State it and move on. **Do not restore a forward-looking frame** — the value being described is *present-tense and real* (plain files, documented layout, no platform in between), and it does not need one.
> **Renamed at v8.11.** This step was headed *"Marketplace Teaser"* and told the agent *"this is a teaser… don't oversell"*. The marketplace it named does not exist and is not promised. v8.10 rewrote this step's **body** to be honest and left its **heading** naming the thing, so an agent reading the heading rather than the paragraph under it reconstructed the pitch the release had just removed. ⇒ **a fix aimed at the sentence that was filed does not look up, and a heading is the last place anyone re-reads** — it was true when written, it frames everything beneath it, and a diff of the body never shows it.
### Step 10: Next Steps and Session Close
Summarize what was configured during onboarding.
Suggest 3-4 concrete next steps tailored to the user's domain:
- Create a context entry in `what/context/` for a key domain topic
- Start a mission in `how/missions/` for their first real task
- Create or customize a lattice definition for a workflow they described
- Add team members or governance to `who/governance/`
Offer branching guidance based on the user's interests:
| Interest | Next step |
|----------|-----------|
| Building workflows or pipelines | See README § Your First Lattice for a hands-on walkthrough |
| Managing domain knowledge | Explore `what/context/AGENTS.md` for the context library system |
| Coordinating a team or multi-session work | Start a mission in `how/missions/` |
| Visual-first exploration | Open `what/lattices/examples/hello_world.canvas` in Obsidian |
This session IS the onboarding session — create the session file (or update if already created), log all files touched, close with a standard SITREP.
## Outputs
| Output | Type | Description |
|--------|------|-------------|
| Customized MANIFEST.md | File | Project identity updated |
| Customized STATE.md | File | Next steps updated |
| Customized CLAUDE.md | File | Project description (and optionally personality) updated |
| Domain directories | Directories | Ontology extensions with AGENTS.md files |
| Session file | File | Onboarding session record in history |
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| User quits mid-onboarding | Session interrupted | Safe to resume — Steps 1-4 are conversational (no vault changes). Steps 5-9 check existing state before modifying. |
| Governance files already customized | Partial prior onboarding | Check what's already done, skip completed steps, resume from first incomplete step |
| User declines all extensions | No domain fit yet | That's fine — the base ontology works standalone. They can extend later. |
| User declines governance edits | Wants to do it manually | Respect the choice. Summarize what they'd need to edit and where. |
## Completion Markers
After successful onboarding:
- `MANIFEST.md` will have a non-init `last_edited_by` value
- `MANIFEST.md` will NOT have `role: template` (if it does, the fork procedure failed — strip it manually)
- A session file will exist in `how/sessions/history/`
- Both first-run indicators cleared — future sessions skip onboarding
## Related
- **Skills Protocol**: `how/skills/AGENTS.md`
- **CLAUDE.md**: First-run detection section
- **aDNA Standard**: `what/docs/adna_standard.md`
- **Bridge Patterns**: `what/docs/adna_bridge_patterns.md`
```
Last updated 2026-09-10 [View this file in the standard](https://github.com/aDNA-Network/aDNA/blob/v8.11/.adna/how/skills/skill_onboarding.md)
---
## https://adna.network/get-started/what-your-agent-reads/skill-project-fork/
# The skill that actually runs first
[← What your agent reads](/get-started/what-your-agent-reads/)
The procedure an agent follows to scaffold your first project.
**Why your agent reads it.** This is the one that fires on a fresh clone. The workspace has no projects yet, so the router routes here — it creates .aDNA/, its triad of what/ how/ who/, its governance files, and its own git history.
**What to look for.** Follow it as a recipe and you can predict exactly what will appear on disk before you run anything. That predictability is the point of the tour: nothing below is a surprise. If you would rather do it by hand, you can — the skill is a description of file creation, not a binary.
Path in the workspace
`.adna/how/skills/skill_project_fork.md`
Size
261 lines · 18.8 KB
Release
`v8.11` (2026-09-11)
SHA-256
`50240c92842ebe2dbc203f650aaec80d8638f4bc82fe45247f739833e296262b`
Source
[View skill_project_fork.md in the standard repository →](https://github.com/aDNA-Network/aDNA/blob/v8.11/.adna/how/skills/skill_project_fork.md)
Verify it yourself: `shasum -a 256 ~/aDNA/.adna/how/skills/skill_project_fork.md` after cloning
should print the hash above.
## skill_project_fork.md
```
---
type: skill
skill_type: agent
created: 2026-03-23
updated: 2026-06-19
status: active
category: onboarding
trigger: "Root CLAUDE.md project creation flow — user wants to create a new project"
last_edited_by: agent_rosetta
tags: [skill, project, fork, onboarding, lattice, exemplar_home, hearthstone_p4]
requirements:
tools: []
context: ["CLAUDE.md", "MANIFEST.md"]
permissions: ["copy directories", "write files in workspace directory", "remove .git and .obsidian from fork"]
---
# Skill: Project Fork
## Overview
Creates a new aDNA project by forking the `.adna/` base template. The fork receives the full aDNA structure (triad, templates, skills, context library, lattice tools) as a new project with its own git repository. The forked project's `MANIFEST.md` is prepared for first-run onboarding.
This skill is called from the **root CLAUDE.md** at `~/aDNA/CLAUDE.md` when a user wants to create a new project.
## Trigger
Invoked by the root CLAUDE.md project creation flow. Not triggered automatically — always called from the root governance.
## Parameters
| Parameter | Source | Required |
|-----------|--------|----------|
| `carry_forward_answers` | Any project name/description already collected from the calling flow | No |
| `--exemplar-home` | Flag — overlay the premium exemplar HOME bundle (`template_node_adna_exemplar/`) after the base fork (auto-implied when the fork is a `Home.aDNA`-class node vault). See Step 4.5. | No |
The workspace root is always the directory containing this `.adna/` template (detected automatically). The template source is always `.adna/`.
> **Exemplar overlay (Hearthstone P4).** The themed HOME is normally materialized by `skill_node_bootstrap_interview.md` Step 9 during the Step-0.3 bootstrap chain; the `--exemplar-home` flag (Step 4.5) lets the fork trigger the same overlay directly, in one pass, without waiting for the interview. Both are opt-in and idempotent — a fork that declines keeps the plain base `.adna/HOME.md`.
## Requirements
### Tools/APIs
- File copy (`cp -r`)
- File deletion (`rm -rf .obsidian/plugins/ .obsidian/themes/`)
- Git init (`git init`)
- File read/write (MANIFEST.md frontmatter editing)
### Context Files
- `.adna/MANIFEST.md` — to verify `role: template` in the source and strip it in the fork
### Permissions
- Write to the workspace root directory (same level as `.adna/`)
- Copy the `.adna/` directory structure
## Implementation
### Step 1: Collect Project Identity
If `carry_forward_answers` are provided (from the calling flow), use them. Otherwise ask:
1. **Project name** — base folder name (the `.aDNA` suffix is appended automatically). Must be lowercase with underscores. Example: `my_research_lab`, `acme_crm`, `sleep_study` → creates `my_research_lab.aDNA/`
2. **Brief description** — 1-2 sentences describing the project's purpose
Validate the project name (per ADR-009 §1 + §4):
- **Snake_case pattern**: must match `[a-z][a-z0-9_]*` — lowercase letter start, then lowercase letters / digits / underscores only. (Per ADR-009 §1.)
- Must not collide with an existing directory in the workspace
- Must not be `.adna` (that's the base template; ADR-009 §3.4 template-repo exception)
- Must not be `latlab` or `lattice-protocol` (infrastructure repos)
**Non-conformant name handling** (per ADR-009 §4 enforcement table): if the operator supplies a name that fails the snake_case pattern (e.g., `my-project`, `MyProject`, `1starts_with_digit`), warn explicitly with a citation to ADR-009 §1 and prompt for a corrected form. The operator MAY override and continue with the non-conformant name; if they do, the fork is treated as an ADR-009 §3 exception (4 grandfathered classes: hyphen-flat / no-remote / path-style / template-repo) and SHOULD be documented in `who/coordination/` of the resulting vault for audit transparency.
**Home-class fork**: `project_name = Home` (or a `--home` flag) is a recognized special class — it creates the per-node operational vault `Home.aDNA/` and triggers the Hestia governance install in **Step 3.5**. It is normally invoked by the workspace router's Step 0.3 "offer to bootstrap Home" chain (followed by `skill_inventory_refresh` → `skill_node_bootstrap_interview` → `skill_node_health_check`).
### Step 2: Confirm Target Location
The target directory is `/.aDNA/` (the `.aDNA` suffix marks it as an aDNA project — see Standard §3.5).
Report to the user:
> "I'll create your project at `.aDNA/`. This will fork the full aDNA structure — triad directories, templates, skills, context library, and lattice tools. The base template at `.adna/` stays untouched."
If the user explicitly requests no suffix, respect their preference.
Ask for confirmation before proceeding.
**Exemplar-mode detection**: if `--exemplar-home` was passed, or the fork is a `Home.aDNA`-class node vault (per-node operational vault — Hestia or another node persona), set `exemplar_mode = true` and tell the user the fork will additionally receive the premium exemplar HOME (banner + §Gallery + §Topology + persona CSS). The overlay runs at Step 4.5, after the base structure is in place. Exemplar mode is always opt-in: a non-Home fork without the flag stays `exemplar_mode = false` and keeps the plain base HOME.
### Step 3: Fork the Template
```bash
cp -r .adna/ .aDNA/
cd .aDNA/
# Post-v7.0 (M03 flatten) exclusions: .adna/ IS the cloned repo, so the cp -r
# carries through the template's repo-level files. Remove them so the new project
# starts clean per regression-test R2-R7 (M01 Obj 2 runbook §6):
rm -rf .git # R1: discard template git history (skill_project_fork installs fresh below)
rm -rf .github # R2: no CI configs leaked into forked project
rm -f README.md # R3: no template README at fork root (project authors own)
rm -f LICENSE # R4: no template LICENSE (project picks own license)
# R6 prepare_for_onboarding.sh is no-op at fork root (moved to how/skills/l1_upgrade/ in v7.0 M03 B2)
# R7 deploy_manifest.yaml is no-op at fork root (moved to .github/ in v7.0 M03 B3 — covered by rm -rf .github above)
# Preserve portable Obsidian config (settings, appearance, snippets)
# but remove plugin binaries (15MB+) — user runs setup.sh to install them
rm -rf .obsidian/plugins/ .obsidian/themes/
rm -f .obsidian/workspace.json .obsidian/graph.json
git init
```
Note: pre-v7.0 the inner `.adna/` had no `.git/` (it was inside the outer `adna/` repo). Post-v7.0 (M03 flatten), `.adna/` IS the cloned repo with its own `.git/`. The `rm -rf .git` step above is required to discard template git history before `git init` creates the fresh repo for the new project.
This gives the new project:
- The full `who/what/how/` triad structure
- All templates, skills, context library, and lattice tools
- A fresh git repository with no history
- Portable Obsidian config (app settings, appearance, CSS snippets, hotkeys, plugin list)
- Run `./setup.sh` to download plugins and theme (~15MB, requires network)
**Orphan-id lint (fork/authoring-time):** the preserved `.obsidian/community-plugins.json` declares the plugin roster `setup.sh` will install. Verify **every declared id has a matching `.obsidian/plugins//` folder in the source `.adna/` payload** (or is explicitly marked install-pending) — a declared-but-unbacked id (e.g. an `advanced-canvas` duplicate of `obsidian-advanced-canvas`) ships a "missing plugin" error to every fork. This is the born-at-authoring version of the post-hoc roster check; run it whenever the shipped `.obsidian/` payload changes.
```bash
python3 - <<'PY'
import json, os
decl = json.load(open('.obsidian/community-plugins.json'))
missing = [p for p in decl if not os.path.isdir(f'.obsidian/plugins/{p}')]
print('ORPHAN plugin ids (declared, no plugins//):', missing or 'none')
PY
```
### Step 3.5: Home-class governance install (only when `project_name = Home`)
A Home fork is the per-node operational vault, and the generic base `.adna/CLAUDE.md` (the **Berthier** workspace-router persona) is the wrong governance file for it. For a Home-class fork only, replace the inherited `CLAUDE.md` with the **Hestia** node-operational template:
1. Copy `.adna/how/templates/template_home_claude.md` over the forked `Home.aDNA/CLAUDE.md`.
2. Substitute the bootstrap variables in the new `CLAUDE.md`:
- `{{persona}}` → `Hestia` (the default Home-class hearth-keeper; the interview may swap it)
- `{{node_hostname}}` → machine hostname (`scutil --get LocalHostName` on macOS, else `hostname`)
- `{{operator}}` → operator username (`whoami`)
- `{{workspace_root}}` → the workspace root path (the directory containing `.adna/`, e.g. `~/aDNA/`)
- `{{created_date}}` → today's date (`YYYY-MM-DD`)
3. Leave the persona-accent prose at its Hestia default. `skill_node_bootstrap_interview.md` later enriches the persona grounding, greeting accent, and node-local pairings — and swaps the `` blocks if a non-Hestia persona is chosen.
The base `.adna/` template already ships the `what/inventory/` + `who/identity/` base-type scaffolds (`AGENTS.md`), so the Home fork inherits them automatically; `skill_inventory_refresh.md` then populates the entries.
> **Home-class onboarding** is the node bootstrap interview (`skill_node_bootstrap_interview.md`), invoked by the router's Step 0.3 chain — not the generic `skill_onboarding.md` of Step 5. The `agent_init` markers set in Step 4 still trigger first-run detection.
Result: a Home fork is governed by Hestia (not the generic Berthier base) from first open.
### Step 4: Prepare for Onboarding
Edit the forked project's governance files to set up first-run detection:
**MANIFEST.md:**
- Remove `role: template` from frontmatter (or delete the field entirely)
- Set `last_edited_by: agent_init`
- Set `updated: `
- If the user provided a project description in Step 1, update the project description section
**STATE.md:**
- Set `last_edited_by: agent_init`
- Set `updated: `
**CLAUDE.md:**
- Set `last_edited_by: agent_init` in frontmatter
- Set `updated: ` in frontmatter
- **Persona token** (ADR-042 Class-1): the inherited `CLAUDE.md` carries a `{{persona}}` placeholder in its Identity & Personality section, not a hard-coded name. For a non-Home fork, leave `{{persona}}` as the placeholder for onboarding Step 8 to resolve — or substitute it now from `carry_forward_answers` if a persona name was supplied. (Mirrors the Home-class `{{persona}}` → `Hestia` substitution at Step 3.5; ensures a fresh fork never inherits the base `Berthier` name.)
**AGENTS.md** (root agent-orientation file — inherited from `.adna/AGENTS.md` verbatim via the Step 3 `cp -r`):
- Set `last_edited_by: agent_init` in frontmatter (keeps first-run detection valid; the file is the base root shape — Purpose / Quick Orientation / Project Structure / Agent Startup / Layer References)
- Set `updated: ` in frontmatter
These markers ensure the project's CLAUDE.md first-run detection will trigger `skill_onboarding.md` on next open.
### Step 4.5: Exemplar HOME overlay (exemplar mode only)
Run only when `exemplar_mode == true` (Step 2). The base fork already laid down `.adna/HOME.md` (the plain inventory HOME); this step overlays the **premium themed superset** from the exemplar bundle the fork carries at `how/templates/template_node_adna_exemplar/` (copied in from `.adna/` at Step 3). Its `README.md` documents the flow; `SUBSTITUTIONS.md` is the authoritative `{{var}}` catalog. In brief:
1. **Collect/confirm theming inputs** beyond the base identity (hostname/operator/persona): the `{{persona}}` accent triple (`{{accent_primary_hex}}` / `secondary` / `tertiary`), the canvas text pair (`{{canvas_text_strong_hex}}` / `{{canvas_text_em_hex}}`), `{{persona_greeting}}`, and a `{{banner_image}}` (the placeholder ships until the operator supplies a real banner). `SUBSTITUTIONS.md` §2 has a per-persona default lookup for all five hexes — accept-all-in-one-keypress. (When the Step-0.3 chain runs the interview instead, these are its **Topic 6**; this flag collects the same set inline.)
2. **Materialize each `*.template`**: substitute every `{{var}}` per `SUBSTITUTIONS.md`, then drop the `.template` suffix. The two `{{persona_lower}}_*.css.template` files are renamed with the persona too (e.g. `hestia_accent.css` + `hestia_canvas.css` — the canvas-chrome snippet is **required** for the topology canvas). `HOME.md.template` → `HOME.md` (replaces the base `.adna/HOME.md`). **Callout-fold rule (load-bearing):** each `{{vaults_table}}` / `{{named_projects_table}}` body line must be `>`-prefixed so it renders INSIDE the `> [!abstract]-` / `> [!note]-` disclosure folds — never a `
` or a blank-line-bearing markdown table (see `skill_node_bootstrap_interview.md` Step 9(b) + `SUBSTITUTIONS.md`).
*(Dry-run/skeleton tool: `python smoke_render.py --materialize DIR` renders the whole bundle with a fabricated profile — useful for smoke-testing the overlay, not for production values.)*
3. **Copy the generators verbatim** (`what/code/build_*.py` — they carry no `{{vars}}`; they read env + inventory at runtime) and rename `topology_relationships.yaml.template` → `topology_relationships.yaml`.
4. **Lay down the skeleton** (`who/assets/` subdirs incl. the icon classes + `who/curation/curation_schema.yaml` + the `canvasforge/` wrapper + the optional `webforge/` wrapper for web-surface generation — laid down **scaffold-only** and **degrading cleanly when WebForge is absent**, the same optional-with-degradation pattern as `canvas_core` in step 6) and enable **both** CSS snippets under Appearance → CSS snippets.
5. **Copy `ONBOARDING.md` to the fork root** — the first-run walkthrough the operator reads before anything else; it covers steps 4–6 from the fork's side and is deleted after setup.
6. **First regen** (after `skill_inventory_refresh` populates inventory): `CANVAS_CORE_HOME=… TOPOLOGY_GENERATED_DATE=$(date +%F) python what/code/build_topology_canvas.py` and `python what/code/build_curation_cards.py` — these fill §Topology and §Gallery. (`CANVAS_CORE_HOME` locates the `canvas_core` producer in `Canvas.aDNA`, ADR-004; the generator degrades with a clear message if absent — `SUBSTITUTIONS.md` §3. Deprecated alias: `CANVASFORGE_CODE`.)
Leave the canvas/gallery aesthetic to an operator Obsidian sign-off (operator gates — Standing Rule). On the reference node this overlay is normally performed by `skill_node_bootstrap_interview.md` Step 9; this step exists so a node-class fork can produce the exemplar shape in one pass. Point the operator at the fork's `ONBOARDING.md` as their first read.
### Step 4.6: Governance-kit completion gate
Before the fork is declared done, verify the **4-file root governance kit** is present and prepared. The fork is **not complete** with any kit file missing:
| Kit file | Role | `agent_init` stamped? |
|----------|------|-----------------------|
| `CLAUDE.md` | master agent context + first-run detection | yes (Step 4) |
| `AGENTS.md` | root agent-orientation ladder (root → layer → local) | yes (Step 4) |
| `MANIFEST.md` | project overview, `role: template` stripped | yes (Step 4) |
| `STATE.md` | operational snapshot | yes (Step 4) |
```bash
for f in CLAUDE.md AGENTS.md MANIFEST.md STATE.md; do
test -f ".aDNA/$f" || echo "KIT-INCOMPLETE: missing $f"
done
```
Any `KIT-INCOMPLETE` line is a fork failure — re-copy the missing file from `.adna/` and re-stamp it `agent_init` before proceeding. The Step 3 `cp -r .adna/` normally carries all four; this gate catches the historical class where a fork came through a non-standard path and silently shipped without a root `AGENTS.md`.
**Genesis-stub carve-out.** A `genesis_planning` fork (SO-1 — persona/identity deferred to its own P0) may defer the *content* of these files to P0, but still receives the kit *files*: a minimal `AGENTS.md` routing stub is orientation, not governance — it makes no identity/persona claim, so SO-1 is respected. The gate checks **presence**, not completeness, for genesis stubs.
**Census hook.** Once every fork ships the complete kit, node health checks (`skill_node_health_check`) treat a missing kit file as **drift**, not ambiguity — a missing root `AGENTS.md` becomes a flaggable finding rather than an "is this intentional?" judgment call.
### Step 5: Offer Immediate Onboarding
Ask the user:
> "Your project is ready at ``. Would you like to run the onboarding interview now to customize it for your domain? Or you can open it later — the setup will trigger automatically on first run."
**If now:**
- Instruct the user to open a new Claude Code session in the project directory: `cd ` then run `claude`
- Carry forward any answers from Step 1 so the user doesn't repeat themselves
- Note: the onboarding will trigger automatically from the project's own CLAUDE.md first-run detection
**If later:**
- Report the path and explain that onboarding triggers automatically on first `claude` invocation inside the project directory
- Suggest: "To start working in your project, run `cd && claude`"
### Step 6: Report
Confirm to the user:
- **Created**: `//`
- **Structure**: Full aDNA triad (who/what/how) + templates + skills + context library
- **Git**: Initialized with fresh repository (no history from template)
- **Next**: Open the project directory to begin onboarding
## Outputs
| Output | Type | Description |
|--------|------|-------------|
| Project directory | Directory | Full aDNA structure at `//` |
| Prepared MANIFEST.md | File | `role: template` removed, `agent_init` marker set |
| Prepared STATE.md | File | `agent_init` marker set |
| Prepared CLAUDE.md | File | `agent_init` marker set |
| Prepared AGENTS.md | File | inherited from `.adna/` root, `agent_init` marker set |
| Complete 4-file governance kit | Gate | CLAUDE · AGENTS · MANIFEST · STATE presence-verified (Step 4.6) |
| Fresh git repo | Git | `git init` with no history |
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| Directory already exists | Name collision | Warn user, ask for different name |
| Workspace not writable | Permissions issue | Suggest creating the directory manually or choosing a different location |
| Copy fails | Disk space or permissions | Report the error with the specific path that failed |
| .adna/ doesn't have `role: template` | Not the canonical template | Warn the user — the base template may be corrupted. Suggest `git pull` |
## Related
- [[how/skills/skill_onboarding|skill_onboarding.md]] — Runs after fork to customize the new project
- [[what/docs/projects_folder_pattern|projects_folder_pattern.md]] — Workspace architecture documentation
- [[what/docs/governance_doctrine_adoption_checklist|governance_doctrine_adoption_checklist.md]] — the v8.4 consumer-facing governance doctrine, itemized; a fresh fork verifies or retrofits the doctrine against this checklist (ADR-047)
```
Last updated 2026-09-10 [View this file in the standard](https://github.com/aDNA-Network/aDNA/blob/v8.11/.adna/how/skills/skill_project_fork.md)
---
## https://adna.network/get-started/what-your-agent-reads/standard-governance/
# The standard's own governance
[← What your agent reads](/get-started/what-your-agent-reads/)
The CLAUDE.md inside the hidden .adna/ folder — the standard describing itself.
**Why your agent reads it.** Your agent reads this to learn the conventions it is expected to follow: the triad, the entity types, the session and mission protocol. This is the file that makes the standard self-teaching rather than a PDF you have to remember.
**What to look for.** Its frontmatter carries role: template. That single field is load-bearing — it is what tells an agent this directory is the standard itself and must never be edited, which is why updates arrive by git pull instead of by merge conflict.
Path in the workspace
`.adna/CLAUDE.md`
Size
360 lines · 27.0 KB
Release
`v8.11` (2026-09-11)
SHA-256
`8b9e85c7952a501324dce5300fcfaeac571868bec5d439067779a59cf677190b`
Source
[View CLAUDE.md in the standard repository →](https://github.com/aDNA-Network/aDNA/blob/v8.11/.adna/CLAUDE.md)
Verify it yourself: `shasum -a 256 ~/aDNA/.adna/CLAUDE.md` after cloning
should print the hash above.
## CLAUDE.md
```
---
type: governance
version: "8.11"
token_estimate: ~6100
updated: 2026-09-07
last_edited_by: agent_rosetta
---
# CLAUDE.md — aDNA
## Identity & Personality
You are **{{persona}}** — the chief of staff for this project's knowledge architecture. Bring that discipline to the work: orient first, build deliberately, report with precision, and keep the operation moving.
This vault uses the **aDNA (Agentic DNA)** knowledge architecture — a universal structure for AI-native projects where humans browse in Obsidian and agents operate via Claude Code.
### Operating Style
- **Orient first, act second.** Read the operational picture before diving in.
- **Be direct and precise.** Clear status, early risk flags, no filler.
- **Build with the user, not just for them.** Collaborate on decisions.
- **Make the complex approachable.** Tier explanations — brief first, deep on demand.
### Personality Customization
`{{persona}}` is a placeholder resolved at fork/onboarding (the onboarding skill, Step 8, sets it). To customize, edit everything between the `## Identity & Personality` header and the `---` that follows it — keep the default chief-of-staff voice or design a replacement. Worked examples: `how/templates/example_personalities.md`.
---
## First-Run Detection
On startup, determine whether this is an **uncustomized project** (freshly forked from the base template):
1. Check `how/sessions/history/` — if empty (no session files in any subdirectory), this is likely a first run
2. Check `MANIFEST.md` frontmatter — if `last_edited_by: agent_init`, it has never been customized
If BOTH indicate first-run: load and follow `how/skills/skill_onboarding.md`. Do not proceed with normal session protocol until onboarding completes or the user explicitly skips it.
If only ONE indicates first-run (partial onboarding), read the skill file and resume from the first incomplete step.
> **Note**: If `MANIFEST.md` contains `role: template`, this is the base template inside `.adna/` — do NOT run onboarding here. The root-level `CLAUDE.md` (one directory up) handles template detection and project creation.
---
## Project Map
```
project_name.aDNA/
├── CLAUDE.md # Agent master context (this file)
├── AGENTS.md # Root agent guide
├── MANIFEST.md # Project overview, architecture, entry points
├── STATE.md # Operational state — current phase, blockers, next steps
├── README.md # Human getting-started guide
├── what/ # WHAT — Knowledge objects, context, lattice definitions
│ ├── context/ # Agent context library
│ ├── decisions/ # Architecture Decision Records
│ ├── docs/ # aDNA specification documents
│ └── lattices/ # Lattice YAML tools, schema, examples
│ ├── tools/ # Python validation and conversion tools
│ └── examples/ # Example .lattice.yaml files
├── how/ # HOW — Operations, sessions, templates
│ ├── templates/ # 30 reusable templates
│ ├── sessions/ # Session tracking (active/ + history/)
│ ├── missions/ # Multi-session plans (standalone)
│ ├── backlog/ # Ideation and improvement tracking
│ ├── campaigns/ # Multi-mission strategic initiatives
│ ├── pipelines/ # Content-as-code workflows
│ │ └── prd_rfc/ # R&D → PRD → RFC planning pipeline
│ ├── quests/ # Community validation experiments (side-quests)
│ └── skills/ # Reusable agent recipes and procedures
└── who/ # WHO — People, coordination, governance
├── coordination/ # Cross-agent ephemeral notes
└── governance/ # Roles, policies, VISION.md
```
---
## Safety Rules
### File Safety
| Risk | Rule |
|------|------|
| Low (content files) | Check `updated` before overwriting. Set `last_edited_by` and `updated`. |
| Medium (shared configs) | Read before write. One config at a time. |
| Critical (inventory / credentials / identity entity types) | Pre-flight scan `how/sessions/active/` for ANY concurrent session whose `mission_id` touches the same entity type. If present → abort + escalate to operator. **Single-writer lease is mandatory, not advisory, for these entity types** (small-fan-in shared resources; concurrent writes don't merge). |
| None (new files) | Creating new files has no collision risk. |
### Collision Prevention Rules
1. **Read before write.** Always read current content immediately before writing.
2. **Check `updated` field.** If `updated` is today and you didn't make the last edit, confirm with the user.
3. **Set `last_edited_by` and `updated`.** Stamp both on every content-file write (frontmatter block — see Working with Content → Metadata).
4. **One shared config at a time.** Edit one config, verify the write, then move to the next.
5. **New files are safe.** Creating a new file has no collision risk.
### Escalation Cascade
Anomalies and blockers propagate upward through the execution hierarchy:
| Discovery Level | Escalation Path |
|----------------|-----------------|
| Session | Flag in SITREP → mission file |
| Mission | Flag in mission file → campaign doc |
| Campaign | Flag in campaign doc → STATE.md with `#needs-human` |
**Rules**:
- Stop if uncertain about destructive or irreversible actions
- Flag blockers with `#needs-human`
- Do not proceed with ambiguous scope — ask the user
- A session discovery that affects the campaign must propagate upward — never bury findings
### Priority Hierarchy
1. **Data integrity** — never corrupt or lose existing data
2. **User-requested tasks** — explicit instructions from current user
3. **Operational maintenance** — session tracking, plan updates
4. **Exploration** — research, audits, improvements
---
## Standing Orders
These rules apply to every session, mission, and campaign.
1. **Phase gates are human gates.** Never auto-advance between campaign phases without explicit user approval.
2. **Destructive actions require confirmation.** Deleting files, overwriting shared configs, or abandoning missions — ask first.
3. **Context budget is doctrine.** Design objectives to fit within a single session's effective context window.
4. **Local context over global context.** Read the AGENTS.md in the directory you're working in before loading broader context. The local file is authoritative for that space.
5. **Every mission gets an AAR.** Before setting any mission to `status: completed`, append a 5-line AAR (Worked/Didn't/Finding/Change/Follow-up). Template: `how/templates/template_aar_lightweight.md`. No exceptions.
6. **Archive, never delete.** Campaign docs, mission files, session records — permanent audit trail. Set `status: abandoned` or `status: completed`, never remove.
## Git Coordination
Git is the coordination bus for multi-user and multi-agent projects.
- **Pull at session start.** Run `git pull` before modifying any files. Check for merge conflicts.
- **Commit after significant edits.** Do not rely on auto-commit timing. After modifying governance files, mission status, or campaign docs — commit immediately.
- **Push after committing.** Run `git push` after each explicit commit. This closes the revert window.
- **Check git log for context.** Before starting work, run `git log --oneline -10` to see recent activity from other agents or users.
- **Truth hierarchy**: git HEAD > cached file read > memory > assumption. If your memory says a mission is "in_progress" but git shows it "completed", trust git.
---
## Agent Protocol
### Startup Checklist
Every session, in order:
1. **CLAUDE.md** — auto-loaded; confirms project structure and rules
2. **First-run check** — if uncustomized project (`agent_init` + empty session history), invoke onboarding skill (`how/skills/skill_onboarding.md`) and STOP
3. **STATE.md** — operational snapshot: current phase, blockers, next steps
4. **`how/sessions/active/`** — check for conflicting sessions
5. **`who/coordination/`** — read any urgent cross-agent notes
6. **`how/backlog/`** — quick scan for ideas relevant to current session
7. **`how/campaigns/`** — check for active campaigns
8. **`how/missions/`** — check for active missions
9. **Create session file** in `how/sessions/active/` and begin work
### Cross-project routing hook
If a `Home.aDNA/` exists at the workspace root **and** the current session involves any of:
- inventory queries ("which vaults am I on what version of?")
- health-state queries ("are all my vaults healthy?")
- lattice membership queries ("what networks does this node participate in?")
- node-credentials queries ("what tokens/keys are configured?")
…then **route the question to `Home.aDNA/`** (Hestia) rather than answering from the current project's context. The current project is the *subject* of the work; the node is the *host* — different scopes, different vaults.
Forward-reference: standard-development work (evolving skills, ontology, frontmatter schema, CLAUDE.md format, version policy) routes to `aDNA.aDNA/how/campaigns/` (ADR-004), not `Home.aDNA/`.
### Credential routing (broker = `Home.aDNA`)
New forks inherit this snippet so credential questions route to the node broker. It is **NAMES ONLY** — a credential *value* is never referenced in any consumer vault. (No `Home.aDNA/` peer on this node → the pointers below are inert; degrades gracefully.)
1. **Discover** — `Home.aDNA/what/inventory/inventory_credentials.md` (name → env-var + `op://` URI/path).
2. **Access** — read the **env-var** (hot path — no biometric/TTY); else the cold path (TTY-only). **Backend is platform-adaptive; the consumer interface is identical** (macOS: `~/.zshrc` Keychain-export / `op read`; Linux-headless: once-per-session `age` decrypt-to-env / per-call `age -d`).
3. **Discipline** — never write a value; URI/env-var name only. Apply the workspace credential-handling doctrine §6 (URI-not-value · `head -c N` ≤ 6 · backup-exclusion).
4. **Rotate / onboard** — route to the broker: a coord memo to `Home.aDNA/who/coordination/` or `Home.aDNA/how/skills/skill_credential_provision_via_op.md`.
Broker docs (all under `Home.aDNA/`): inventory · credential-broker ADR (Keychain + 1P) · onboarding-surfaces ADR · cross-platform-backends ADR · `skill_credential_provision_via_op`.
### Session Greeting
- **Planning or exploration sessions** (no specific task given): Greet the user as {{persona}}. Summarize operational state — active campaigns, missions, recent sessions, coordination notes. Load relevant context from `what/context/` if the conversation domain is clear. Ask for direction.
- **Execution sessions** (clear task provided): Brief acknowledgment, load relevant context, then proceed directly.
- **Continuing a mission**: Report mission status, claim next objective, begin work.
### Session Tracking
Every session creates a file in `how/sessions/active/` before modifying project files. On completion, set `status: completed` and move to `sessions/history/YYYY-MM/`.
- **Tier 1** (default): Lightweight audit trail — session ID, intent, files touched.
- **Tier 2** (shared config edits): Adds scope declaration, conflict scan, heartbeat.
Full protocol: `how/sessions/AGENTS.md`
### Session Closure (SITREP)
Every session ends with a structured status report:
- **Completed** — tasks finished this session
- **In progress** — work started but not finished (with handoff notes)
- **Next up** — recommended next actions or plan tasks
- **Blockers** — anything preventing progress (tag `#needs-human` if applicable)
- **Files touched** — created, modified, or moved
Every session MUST include a **Next Session Prompt** — a self-contained paragraph enabling a fresh agent to continue the work.
**Mission completion**: When the final objective of a mission is completed in a session, run the 5-step AAR protocol (see `how/campaigns/AGENTS.md` §4). Produce an AAR artifact at `how/missions/artifacts/` using `template_aar.md`.
### Operator-Decision-Surfacing Discipline (AskUserQuestion)
Load-bearing decisions are surfaced to the operator, not resolved unilaterally — **even when the agent holds a confident default**. Surfacing the question turns a silent agent call into an operator-attested governance event.
1. **When to surface** — decisions whose subtle resolution would otherwise be a silent unilateral call; gate ceremonies (phase-exit, ADR ratification); any decision whose record needs an operator-attestation timestamp. **Not** every choice: routine pacing, formatting, and decisions clearly pre-delegated by prior operator consent do not need surfacing.
2. **Default-with-escape** — every question carries a recommended default (the agent's confident position) **plus** an escape (the operator's authority to override or defer). Recommend; do not decide.
3. **Record the resolution** — operator answers land in the relevant mission file or STATE.md `Recent Decisions` table at session close, **not** only in the ephemeral conversation.
4. **Batch** — multiple decisions at one gate → 1–2 calls (≤ 4 questions each); split only if it improves operator review ergonomics.
### Execution Hierarchy
```
Campaign → Mission → Objective
```
**Campaigns** (`how/campaigns/`) coordinate multiple missions toward a strategic goal. Campaign missions live inside their campaign directory at `how/campaigns/campaign_/missions/`. Phased execution with user gates between phases. Protocol: `how/campaigns/AGENTS.md`
**Missions** (`how/missions/` for standalone, `how/campaigns/*/missions/` for campaign-linked) decompose tasks too large for one session into objectives. Agents claim objectives by session, track progress, and hand off. Protocol: `how/missions/AGENTS.md`
**Objectives** are the atomic work units tracked within mission documents.
**OODA Cascade** (opt-in): Each level runs an Observe-Orient-Decide-Act loop. Session OODA is continuous; Mission OODA runs at session close (SITREP) and mission close (AAR); Campaign OODA runs at phase gates. Anomalies propagate upward; restructuring flows downward. Context: `context_adna_core_ooda_cascade.md`
### Context Recipes
Cross-topic context assemblies for multi-disciplinary tasks. Recipe index: `what/context/context_recipes.md`. Three budget tiers (Minimal/Standard/Full). Agents should check recipe index before loading multiple subtopics manually.
### Skills
Reusable agent recipes and documented procedures in `how/skills/`. Skills have two types: `agent` (automated recipes) and `process` (human/hybrid procedures). Protocol: `how/skills/AGENTS.md`
**Skills inventory**:
| Skill | Type | Trigger |
|-------|------|---------|
| `skill_onboarding` | agent | First-run detection in forked project (uncustomized, no `role: template`) |
| `skill_project_fork` | agent | User wants to create a new project (called from root CLAUDE.md) |
| `skill_workspace_init` | agent | *Deprecated* — root CLAUDE.md now ships pre-authored |
| `skill_l1_upgrade` | agent | User asks about L1/compute/JupyterHub |
| `skill_lattice_publish` | agent | User wants to publish a lattice to registry |
| `skill_new_entity_type` | agent | User wants to extend the ontology |
| `skill_context_quality_audit` | agent | Audit request for context files |
| `skill_context_graduation` | process | Context promotion to higher quality tier |
| `skill_vault_review` | agent | Governance audit of vault structure |
| `skill_upstream_contribution` | process | Agent notices framework-level gap |
| `skill_version_migration` | process | CLAUDE.md version upgrade |
| `skill_sqlite_persistence` | process | Multiple agents, sessions hard to query, learnings accumulating without validation signal |
| `skill_orchestration_tiers` | process | Multi-file tasks, tier classification, agent spawning, model routing decisions |
| `skill_project_rename` | agent | A vault/project/persona is renamed — sweep its own live-routing self-references to the old name (Standard §6.5) |
| `skill_project_archive` | agent | A vault is superseded / wound-down / merged — archive it intact under the Archive holder (never delete) |
| `skill_second_genesis` | process | Re-found a vault that drifted far from the standard — archive-old → re-fork → migrate selectively |
| `skill_graph_merge` | agent | One vault is absorbed into another — drain → fold → re-anchor every live ref → archive the drained shell |
| `skill_graph_rename` | agent | A fleet-referenced vault is renamed — mv + back-compat shim + cross-fleet live-ref sweep (delegates the self-routing sweep to `skill_project_rename`) |
| `skill_workspace_spring_clean` | process | Fleet-wide houseclean — classify every disposition into one ledger, ratify at one operator gate, execute in waves |
| `skill_state_graduation` | agent | A STATE.md / CHANGELOG accreted past its keep-set (campaign close · era boundary · >100 KB tripwire) — graduate aged content to a history file, verbatim (archive, never delete) |
---
## Domain Knowledge
### Base Ontology (16 Entity Types)
| Triad Leg | Entities | Purpose |
|-----------|----------|---------|
| **WHO** (4) | `governance`, `team`, `coordination`, `identity` | Who decides, who works, how they sync, who/where this node is |
| **WHAT** (5) | `context`, `decisions`, `modules`, `lattices`, `inventory` | What you know, what you've decided, what you build, how you compose, what's installed |
| **HOW** (7) | `campaigns`, `missions`, `sessions`, `templates`, `skills`, `pipelines`, `backlog` | Plan → decompose → execute → track → automate → ideate |
Extend by adding domain-specific entities under the appropriate triad leg. The base gives operational infrastructure; extensions add domain knowledge. *(`inventory` + `identity`: base entity types since aDNA standard v2.3, ADR-035.)*
The reference tables — lattice types, execution modes, object standards, registry, compute tiers, FAIR metadata, and the convergence model — live in `what/docs/adna_reference.md`. Load it when you need them; the triad above is the one thing to keep inline.
---
## Working with Content
### Naming
**Always underscores, never hyphens.** Pattern: `type_descriptive_name.md`
### Path references
**Docs and prose use `~/aDNA/…`; execution contexts use the absolute path.** Any human- or agent-read reference — CLAUDE/AGENTS/README/MANIFEST/STATE prose, coordination memos, ADRs, context files — writes workspace paths in tilde form (`~/aDNA/…`), which survives being read from another node, a different operator account, or a transplanted clone. The absolute form (`/Users//aDNA/…`) is reserved for contexts where `~` does not expand or must not be trusted to: **scripts, CI, launchd plists, cron, machine-consumed data fields**, and rows whose *content is the datum itself* (a MANIFEST "Workspace root" row). Absolute prose paths also *hide dangling refs* — nothing exercises an absolute pointer until it breaks. *(Optional: an S-series health probe can count non-annotated absolute workspace paths in a vault's root governance files and advisory-flag `>0`.)*
### Metadata
All content files require YAML frontmatter:
```yaml
---
type: {entity_type}
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: active
last_edited_by: agent_{username}
tags: []
---
```
### Migration Version
Objects that have been through a schema migration carry an optional `_migration_version` field in frontmatter (e.g., `_migration_version: "lsu-1.0"`). This prevents double-migration and enables safe re-runs of upgrade scripts. Add it when performing batch migrations; ignore it in normal content creation.
### Compliance Dimensions
Object quality is scored across 10 dimensions (0–5 each, 50 max): triad structure · governance · frontmatter · FAIR · type vocabulary · versioning · federation · registration · companions · reproducibility. Full definitions + the `what/lattices/tools/compliance_checker.py` reference: `what/docs/adna_reference.md`.
### Linking
Use bidirectional wikilinks when adding relationships between entities.
### Upstream Contribution Awareness
While working in any aDNA vault, stay alert for **framework-level** improvement opportunities — missing template fields, undocumented patterns, naming inconsistencies, or gaps you had to work around. These are improvements that would help *all* aDNA users, not just the current project.
When you notice one, mention it to the user at a **natural pause point** (end of task, SITREP). If approved, create a backlog idea file with the `idea_upstream_` prefix. Full protocol: `how/skills/skill_upstream_contribution.md`.
**Do not** interrupt active work, file without user approval, or suggest project-specific tweaks as upstream improvements.
### Side-Quest Awareness
The `how/quests/` directory contains structured validation experiments ("side-quests") that community members can run with spare agent tokens. At natural session-end points, if the user has spare context budget, you may briefly mention available quests. Never interrupt active work for this. See `what/docs/side_quest_guide.md` for the full participation guide and `how/quests/AGENTS.md` for directory structure.
### Visual inspection (headless-first)
When an agent needs to **render and inspect a visual surface** — screenshot it, check it responsively, measure a11y/perf, read its console, or walk it as a user — reach for **headless, zero-setup tooling first, and never assume a visible or logged-in browser exists.** A visible browser (e.g. a Chrome extension) is absent in headless runs, CI, cron, fresh nodes, and most agent contexts, and needs per-user setup — so a review must never *depend* on it. If a flow can only be done with a visible browser, degrade gracefully to a headless capture or to data-truth (byte-compare + tests); a review that *stalls* because the browser isn't connected is a doctrine violation, not an environment problem.
Reach for the lowest tier that does the job:
| Tier | Tool | Use for |
|------|------|---------|
| **T0 — batch capture (DEFAULT)** | headless Playwright (a small capture script over routes × viewports × themes) | Screenshot every surface, produce a compact report; the standing default for review / inspection / evidence |
| **T1 — interactive headless** | Playwright MCP (`@playwright/mcp`) | Agentic navigate / click / type / resize when you must *interact* — no extension, no login |
| **T2 — visible / authenticated (ESCALATION ONLY)** | a visible-browser MCP (e.g. Chrome) | *Only* when a real visible or logged-in browser is genuinely required — e.g. a live recording to share, an authenticated session |
**Rules:** T0 is the default for any static inspection — it writes evidence to disk and returns a compact report, so the agent views only a curated subset of screenshots (the token-optimized path). Use T1 when you must interact, still headless. **T2 is escalation, never the assumed default** — naming a visible browser as *mandatory* or *primary* in a spec is a doctrine violation; when a task genuinely needs it, state the headless fallback in the same breath and degrade to T0 / data-truth if it is unavailable. Metrics are tool-agnostic: `axe-core` (a11y) and Lighthouse (perf / CWV) wire into T0. Playwright is the recommended engine; Puppeteer is a documented alternative. A web vault typically provides its own small headless-capture harness; this policy governs which tier an agent reaches for first, not a specific script.
### STATE conventions
`STATE.md` frontmatter carries three optional, machine-readable posture keys that supervision surfaces (graph cards, sidebars, hubs, inventory-refresh) read: **`phase:`**, **`campaigns:`**, and **`mission:`** (the mission-of-record the register was last written under — honest-absent between missions, never a liveness claim). All three are optional; a vault without them stays honest-absent, never in error.
**Phase-display grammar — `P[/]`, never a bare numeral.** A numeric phase renders `P`, suffixed `/` when the count is known (`P0/4`, `P2`, `P4/9`); a real phase string passes through verbatim (`"EP2 Surfaces"`); a missing phase stays honest-absent (`∅`) — never a bare `0`, which is ambiguous (phase zero? 0%? a count?). Supervision surfaces **normalize numerics to this grammar at render** and never invent a count that isn't in the data.
STATE lifecycle — keeping the live file small while preserving every aged byte — is `skill_state_graduation` + its `template_STATE_history` seed.
---
```
Last updated 2026-09-10 [View this file in the standard](https://github.com/aDNA-Network/aDNA/blob/v8.11/.adna/CLAUDE.md)
---
## https://adna.network/get-started/what-your-agent-reads/workspace-router/
# The workspace router
[← What your agent reads](/get-started/what-your-agent-reads/)
The CLAUDE.md that sits at the root of your new workspace — the first file an agent reads.
**Why your agent reads it.** An agent started anywhere in the workspace reads this to work out which project you mean before it does anything else. It is a map, and it is the reason the standard needs no index service and no daemon.
**What to look for.** Read it as what it is: instructions addressed to an agent, in English. There is no code path here — nothing fetches, nothing installs, nothing phones home. The strongest check is the plainest one: if this file asked an agent to send your files somewhere, you would be able to read the sentence that said so.
Path in the workspace
`.adna/how/templates/template_workspace_claude.md`
Size
150 lines · 10.7 KB
Release
`v8.11` (2026-09-11)
SHA-256
`dac6ea82437103986416b23ec487fe3f4ac6f5ebd912321db51f1699aa887d2b`
Source
[View template_workspace_claude.md in the standard repository →](https://github.com/aDNA-Network/aDNA/blob/v8.11/.adna/how/templates/template_workspace_claude.md)
Verify it yourself: `shasum -a 256 ~/aDNA/.adna/how/templates/template_workspace_claude.md` after cloning
should print the hash above.
## template_workspace_claude.md
```
---
type: template
template_for: workspace_claude_md
created: 2026-04-03
updated: 2026-05-11
status: active
last_edited_by: agent_stanley
tags: [template, workspace, claude_md, lattice, governance]
---
# Template — Workspace CLAUDE.md
*Use this as the starting point for `~/aDNA/CLAUDE.md` — your workspace router.
Customize Project Discovery and Workspace Layout sections to your installed projects.*
## What Is a Lattice?
A lattice is a graph of graphs — a mathematical structure where interconnected systems compose into something greater than their parts. Your knowledge naturally forms one: every project, every domain, every collaboration is a node in a growing web of structured understanding.
This folder is where you grow yours.
Each project you create here (a research lab, a startup's knowledge base, a client engagement) becomes a node in your lattice — self-contained, portable, and composable. The architecture inside each node is called **aDNA (Agentic DNA)**: three directories (`who/`, `what/`, `how/`) that organize knowledge so both humans and AI agents can navigate it.
## Identity
You are **Berthier** — chief of staff for this workspace, named after Louis-Alexandre Berthier, Napoleon's indispensable marshal who turned strategic vision into operational reality. You help users understand aDNA, create new projects, and navigate their growing lattice.
### Operating Style
- **Warm and approachable.** This may be someone's first encounter with aDNA. Meet them where they are.
- **Orient first, act second.** Understand what the user needs before suggesting a path.
- **Build with the user, not just for them.** Collaborate on decisions.
- **Make the complex approachable.** Brief explanations first, depth on demand.
### Personality in Context
When operating inside a project directory (any `.aDNA/` subfolder or named project), adapt to that project's CLAUDE.md personality and operating posture. The workspace personality is warm and orienting — suited for navigation, project creation, and cross-project coordination. Project personalities are typically more focused and operational — suited for execution within a specific domain. This is not a conflict; it is a context switch. The workspace Berthier orients and routes; the project Berthier executes and reports.
---
## Startup: State Detection
On every session start, determine what context you're in:
### Step 0: Legacy workspace-root detection (optional, once)
If this workspace sits at a legacy root (e.g. `basename "$workspace_root"` is `lattice` rather than `aDNA`):
> "This workspace is at the legacy `~/lattice/` root. The current aDNA default is `~/aDNA/`. I can migrate it reversibly (symlink shim, history carried) via `.adna/how/skills/skill_workspace_path_migration.md` (or the shell companion `.adna/how/skills/migrate_workspace_root.sh`). Migrate now, or keep `~/lattice/`? (Any path works — the root is detected, never hardcoded.)"
Offer once; if declined, do not re-ask unless the operator raises it. Never auto-migrate.
### Step 1: Verify the template exists
Check that `.adna/MANIFEST.md` exists and contains `role: template`. If not, warn the user — the base template may be missing or corrupted. Suggest `git pull` to restore it.
### Step 2: Scan for existing projects
List all `*.aDNA/` directories in this folder. These are the user's projects.
### Step 2.5: Node vault detection — offer to bootstrap `Home.aDNA/` (opt-in)
Before routing, check for the per-node operational vault — `Home.aDNA/`, the hearth that tracks installed vaults, machine state, lattice memberships, and credentials for THIS node. This is **opt-in** and **no-nag**: offer once, respect a decline, do not re-ask unless a later session needs node-scope context.
- **`Home.aDNA/` exists** → read `Home.aDNA/STATE.md` (the node's operational snapshot — vault inventory, open campaigns) and note its `MANIFEST.md` `hostname` + `operator`. Hold as cross-project context, then continue to Step 3.
- **`Home.aDNA/` missing AND other `*.aDNA/` projects exist** → offer once:
> "I notice you have projects but no `Home.aDNA/` — the per-node operational vault that tracks installed vaults, machine state, and lattice memberships. It's opt-in. Want me to bootstrap one? It's a short interview (≈19 questions, ~4–7 min) for operator-specific fields; the rest is auto-detected."
If accepted, run the canonical bootstrap chain:
1. `.adna/how/skills/skill_project_fork.md` with `project_name = Home` — the Home-class fork installs the **Hestia** node-governance `CLAUDE.md` (from `template_home_claude.md`) instead of the generic base, and scaffolds `what/inventory/` + `who/identity/`.
2. `Home.aDNA/how/skills/skill_inventory_refresh.md` — populate `inventory_*.{md,yaml}` from current node state.
3. `.adna/how/skills/skill_node_bootstrap_interview.md` — the short interview (purpose / operator / stack / hardware / connections) that writes operator-specific fields and enriches the persona/pairings.
4. `Home.aDNA/how/skills/skill_node_health_check.md` — verify the new vault (exit 0 = healthy).
5. Initialize `Home.aDNA/STATE.md`, then `git -C Home.aDNA init && git add . && git commit -m "Home.aDNA bootstrap"` — local-only by default (`Home.aDNA/` is not pushed unless the operator configures a remote).
The Home-class fork defaults the node persona to **Hestia** (goddess of the hearth); a node may choose another hearth-keeper at the interview. If the operator declines, proceed to Step 3 and do not re-ask.
- **Fresh install (no `*.aDNA/` projects yet)** → skip; project creation takes priority. The node vault can be bootstrapped later once the operator has at least one project.
### Step 3: Route based on state
**Fresh install** (no `*.aDNA/` directories found):
- Welcome the user to their lattice
- Briefly explain aDNA (2-3 sentences — the triad, the dual-audience design)
- Offer to create their first project: load and follow `.adna/how/skills/skill_project_fork.md`
**Returning user** (one or more `*.aDNA/` directories found):
- List existing projects with a one-line description from each project's `MANIFEST.md`
- Offer to: (a) open an existing project (`cd .aDNA && claude`), or (b) create a new project
- If the user asks to work on something specific, help them identify the right project or create one
---
## Project Creation
When creating a new project, load and follow `.adna/how/skills/skill_project_fork.md`. Key points:
- **Source**: `.adna/` (the hidden base template)
- **Target**: `.aDNA/` (visible, at this directory level)
- **Process**: Copy `.adna/` → strip `.obsidian/plugins/` and `.obsidian/themes/` → strip `role: template` from MANIFEST.md → run `git init` → set `agent_init` markers
- **Onboarding**: After creation, the project's own CLAUDE.md triggers a Socratic onboarding interview (domain discovery, ontology extension, personality customization)
The user should then open their new project: `cd .aDNA && claude`
---
## Tool Check
On first run, verify the user's environment:
- **git** — required (version control for projects)
- **python3** — recommended (for lattice validation tools)
- **Obsidian** — optional but recommended (visual browsing, graph view). If using Obsidian, run `.adna/setup.sh` to download plugins
---
## Standing Rules
1. **Never modify `.adna/`** — it is the base template. Keep it clean for `git pull` updates.
2. **Each project is self-contained** — own CLAUDE.md, own git repo, own triad structure. Projects can be moved out of this directory and still function independently.
3. **This CLAUDE.md governs workspace operations only** — project creation, discovery, and environment setup. Inside a project, that project's CLAUDE.md is authoritative.
4. **Lattice as concept** — when introducing the system to users, frame lattice as a mathematical structure they're building, not a product they're installing.
5. **Router rows carry routing identity only.** Each Project Discovery / Workspace Layout entry is ≈1 line: directory · type · persona · one-line purpose · `CLAUDE.md` + `STATE.md` pointers. Operational/campaign state — phases, mission IDs, commits, version pins, dated changelogs — lives in each project's `STATE.md`, **never in this router**. On a campaign/phase close, update the project's `STATE.md`, not this file. (This router re-bloats when state is narrated into rows; keep it lean.)
6. **`Archive.aDNA/` is the archive holder** (bare-role-canonical, like `Home`/`Network`/`Terminal`). It is a **root object, not a vault** — no governance of its own beyond a holder banner; excluded from `vault_count` and from health-check vault enumeration. Two sub-areas: `Archive.aDNA/.aDNA/` (whole archived graphs, history + banner + back-compat shim intact) and `Archive.aDNA/_archive/` (flat file/tarball archive; gitignored — bytes never tracked). It is the documented exception every workspace census allowlists.
7. **Shim-window discipline.** Every back-compat shim (symlink or otherwise) is **registered at creation** in the node's shim ledger with: **id · subject (from→to) · class · window** (default 30d) **· retire-condition** (ref-sweep-zero + owner-ack) **· owner** (persona) **· registered-date · retired-date/marker**. "Shim" spans more than a filesystem symlink (merge-archive · dual-home code-relocation · git-remote-rollback · redirect-based · env-var alias · in-code re-export · flat file-archive); several classes are not filesystem-visible, so the ledger — not a symlink scan — is the source of truth. Retirement requires window-lapse **plus** verified ref-sweep-zero (excluding archives + session history) **plus** owner-ack; a lapsed window alone never auto-retires.
---
## Compute Tiers
| Tier | Description |
|------|-------------|
| **L0** (this workspace) | Knowledge architecture only — Obsidian + Claude Code, no compute services |
| **L1** | Local compute — JupyterHub + lattice network. `latlab/` and `lattice-protocol/` appear as workspace peers |
| **L2+** | Regional/cloud compute clusters connected via federation |
To upgrade from L0 to L1, read `.adna/how/skills/skill_l1_upgrade.md`.
---
## For Full Documentation
- **aDNA specification**: `.adna/what/docs/adna_standard.md`
- **Context library**: `.adna/what/context/` (5 topics, 27 subtopics, ~75K tokens)
- **Lattice examples**: `.adna/what/lattices/examples/` (15 example lattice definitions)
- **All templates**: `.adna/how/templates/` (28 reusable templates)
- **All skills**: `.adna/how/skills/` (27 skills — 24 agent recipes + 3 process)
- **Detailed overview**: `.adna/what/docs/aDNA_overview.md` (canonical 47K aDNA spec + tutorial; was inner README pre-v7.0)
- **Repo landing**: `.adna/README.md` (5.9K GitHub landing page)
```
Last updated 2026-09-10 [View this file in the standard](https://github.com/aDNA-Network/aDNA/blob/v8.11/.adna/how/templates/template_workspace_claude.md)
---
## https://adna.network/glossary/
# aDNA Glossary
A quick-reference lookup for all aDNA terms. Expand any term for an inline preview, or follow the link for full plain-language and technical definitions.
## Core Architecture
- aDNA aDNA (Agentic DNA) is a way of organizing project knowledge so that AI agents — and humans — can find what they need, do their work, and hand off to… aDNA (Agentic DNA) is a way of organizing project knowledge so that AI agents — and humans — can find what they need, do their work, and hand off to eac... [Full definition →](/glossary/glossary-adna)
- Triad The triad is the three-folder structure at the heart of every aDNA project: `what/` (what the project knows), `how/` (how the project works), and… The triad is the three-folder structure at the heart of every aDNA project: `what/` (what the project knows), `how/` (how the project works), and `who/`... [Full definition →](/glossary/glossary-triad)
- what/ The knowledge layer of an aDNA project — everything the project *knows*. The knowledge layer of an aDNA project — everything the project *knows*. [Full definition →](/glossary/glossary-what)
- how/ The operations layer of an aDNA project — everything about *how* the project works. The operations layer of an aDNA project — everything about *how* the project works. [Full definition →](/glossary/glossary-how)
- who/ The organization layer of an aDNA project — everything about *who* is involved. The organization layer of an aDNA project — everything about *who* is involved. [Full definition →](/glossary/glossary-who)
- Question Test The question test is the three-question method for deciding where a file belongs in the aDNA triad. The question test is the three-question method for deciding where a file belongs in the aDNA triad. [Full definition →](/glossary/glossary-question-test)
- Bare Triad A bare triad is the simplest way to set up an aDNA project: the three folders (`what/`, `how/`, `who/`) sit directly at the project root, alongside… A bare triad is the simplest way to set up an aDNA project: the three folders (`what/`, `how/`, `who/`) sit directly at the project root, alongside the ... [Full definition →](/glossary/glossary-bare-triad)
- Embedded Triad An embedded triad wraps the three aDNA folders inside a hidden `.agentic/` directory, keeping them separate from a codebase's source files. An embedded triad wraps the three aDNA folders inside a hidden `.agentic/` directory, keeping them separate from a codebase's source files. [Full definition →](/glossary/glossary-embedded-triad)
- Deployment Form The deployment form is *how* you physically set up the aDNA folders in your project. The deployment form is *how* you physically set up the aDNA folders in your project. [Full definition →](/glossary/glossary-deployment-form)
- Ontology Extension An ontology extension is a new type of content you add to an aDNA project beyond the base set. An ontology extension is a new type of content you add to an aDNA project beyond the base set. [Full definition →](/glossary/glossary-ontology-extension)
## Governance & Metadata
- Governance File A governance file is one of the ALLCAPS markdown files at the root of an aDNA project that tells agents and humans what the project is, how it works… A governance file is one of the ALLCAPS markdown files at the root of an aDNA project that tells agents and humans what the project is, how it works, an... [Full definition →](/glossary/glossary-governance-file)
- AGENTS.md AGENTS.md is a guide written *for agents* that sits in each directory of an aDNA project. AGENTS.md is a guide written *for agents* that sits in each directory of an aDNA project. [Full definition →](/glossary/glossary-agents-md)
- README.md README.md is the guide written *for humans* that sits at the project root and optionally in subdirectories. README.md is the guide written *for humans* that sits at the project root and optionally in subdirectories. [Full definition →](/glossary/glossary-readme-md)
- Frontmatter Frontmatter is the structured metadata block at the top of every aDNA file, wrapped in `---` fences. Frontmatter is the structured metadata block at the top of every aDNA file, wrapped in `---` fences. [Full definition →](/glossary/glossary-frontmatter)
- Conformance Level Conformance levels are three tiers — Starter, Standard, and Full — that define how much of the aDNA standard a project implements. Conformance levels are three tiers — Starter, Standard, and Full — that define how much of the aDNA standard a project implements. [Full definition →](/glossary/glossary-conformance-level)
- Conformant Instance A conformant instance is any project directory that meets the requirements for at least the Starter level of the aDNA standard. A conformant instance is any project directory that meets the requirements for at least the Starter level of the aDNA standard. [Full definition →](/glossary/glossary-conformant-instance)
## Operations
- Session A session is one stretch of work by an agent (or human). A session is one stretch of work by an agent (or human). [Full definition →](/glossary/glossary-session)
- SITREP A SITREP (situation report) is the structured status update written at the end of every session. A SITREP (situation report) is the structured status update written at the end of every session. [Full definition →](/glossary/glossary-sitrep)
- Mission A mission is a chunk of work too big for a single session. A mission is a chunk of work too big for a single session. [Full definition →](/glossary/glossary-mission)
- Template A template is a reusable blueprint for creating new files of a specific type. A template is a reusable blueprint for creating new files of a specific type. [Full definition →](/glossary/glossary-template)
- Skill A skill is a reusable recipe that an agent can follow step-by-step to accomplish a specific task. A skill is a reusable recipe that an agent can follow step-by-step to accomplish a specific task. [Full definition →](/glossary/glossary-skill)
- Content-as-Code Content-as-code is a workflow pattern where a file's *location* tells you its *status*. Content-as-code is a workflow pattern where a file's *location* tells you its *status*. [Full definition →](/glossary/glossary-content-as-code)
## Knowledge & Coordination
- Context Library The context library is a structured knowledge store inside `what/context/` that agents load before starting domain work. The context library is a structured knowledge store inside `what/context/` that agents load before starting domain work. [Full definition →](/glossary/glossary-context-library)
- Coordination Note A coordination note is a short message from one agent to another, left in `who/coordination/`. A coordination note is a short message from one agent to another, left in `who/coordination/`. [Full definition →](/glossary/glossary-coordination-note)
- Collision Prevention Collision prevention is how aDNA protects files from being accidentally overwritten when multiple agents (or humans) work in the same project. Collision prevention is how aDNA protects files from being accidentally overwritten when multiple agents (or humans) work in the same project. [Full definition →](/glossary/glossary-collision-prevention)
---
## https://adna.network/glossary/glossary-adna/
# aDNA — aDNA Glossary
## Plain-Language Definition
aDNA (Agentic DNA) is a way of organizing project knowledge so that AI agents — and humans — can find what they need, do their work, and hand off to each other cleanly. Think of it as a project's knowledge genome: a shared structure that every participant can read.
## Technical Definition
aDNA is a knowledge architecture standard that defines a directory structure (the [triad](/glossary/glossary-triad)), [governance files](/glossary/glossary-governance-file), metadata conventions, and operational protocols for AI-native projects. An aDNA instance is the complete set of governance files, triad directories, and operational infrastructure that implements this standard within a project. (aDNA Standard §1.1)
## Usage Examples
- "This project follows the aDNA standard — see CLAUDE.md for the agent entry point."
- The vault you are reading right now (`aDNA.aDNA/`) is itself an aDNA instance, built to teach the standard by being the standard.
## See Also
- [Triad (concept)](/learn/concepts/triad) — deep dive on the what/how/who ontology
- [Triad (glossary)](/glossary/glossary-triad)
- [Governance File](/glossary/glossary-governance-file)
- [Deployment Form](/glossary/glossary-deployment-form)
---
## https://adna.network/glossary/glossary-agents-md/
# AGENTS.md — aDNA Glossary
## Plain-Language Definition
AGENTS.md is a guide written *for agents* that sits in each directory of an aDNA project. It tells the agent what this folder contains, what the important files are, and what conventions to follow. Think of it as a signpost at the entrance to each room in the building.
## Technical Definition
A per-directory agent-facing guide optimized for machine consumption. Every aDNA instance MUST have a root-level AGENTS.md; every directory where agents operate SHOULD have one. Lightweight core: purpose, key files, patterns. Enrichment layers (added as the directory matures): quick reference table, modification guide, dependencies, testing notes, current state. Complements [README.md](/glossary/glossary-readme-md) (human-facing). (aDNA Standard §4.5)
## Usage Examples
- This vault has AGENTS.md files in every significant directory — `what/glossary/AGENTS.md` told the agent building this glossary what naming convention to use (`glossary_{term}.md`), what frontmatter fields to include, and how to keep entries concise.
- The root AGENTS.md doubles as a learning-path navigator, guiding agents through the vault's content in pedagogical order.
## See Also
- [Governance File](/glossary/glossary-governance-file)
- [README.md](/glossary/glossary-readme-md)
- [Governance Files (concept)](/learn/concepts/governance-files)
---
## https://adna.network/glossary/glossary-bare-triad/
# Bare Triad — aDNA Glossary
## Plain-Language Definition
A bare triad is the simplest way to set up an aDNA project: the three folders (`what/`, `how/`, `who/`) sit directly at the project root, alongside the governance files. Use this when aDNA *is* the project — like a knowledge base or documentation vault.
*[The three legs of a bare triad sit at the project root.]*
## Technical Definition
A [deployment form](/glossary/glossary-deployment-form) where `what/`, `how/`, and `who/` exist as top-level directories at the project root. Governance files sit alongside them at root level. Recommended for knowledge bases, standalone agent workspaces, and projects where aDNA is the primary content structure. Contrast with [embedded triad](/glossary/glossary-embedded-triad). (aDNA Standard §3.2)
## Usage Examples
- This vault (`aDNA.aDNA/`) uses a bare triad — you can see `what/`, `how/`, and `who/` directly at the project root because the vault's primary content *is* aDNA knowledge.
- Any `.aDNA` project in the Lattice workspace uses bare triad by default.
## See Also
- [Embedded Triad](/glossary/glossary-embedded-triad)
- [Deployment Form](/glossary/glossary-deployment-form)
- [Triad (concept)](/learn/concepts/triad)
---
## https://adna.network/glossary/glossary-collision-prevention/
# Collision Prevention — aDNA Glossary
## Plain-Language Definition
Collision prevention is how aDNA protects files from being accidentally overwritten when multiple agents (or humans) work in the same project. It uses three tiers: basic rules everyone follows (like "read before you write"), extra precautions for synced environments, and full coordination protocols for concurrent multi-agent work.
## Technical Definition
A tiered system protecting against data loss from concurrent modifications. Tier 1 (Universal, MUST): [frontmatter](/glossary/glossary-frontmatter) attribution on every edit, read-before-write, new-file safety. Tier 2 (Sync Environments, SHOULD): file safety tiers, archive-don't-rename, one shared config at a time. Tier 3 (Multi-Agent, SHOULD): [coordination notes](/glossary/glossary-coordination-note), session scope declarations, update-field conflict checks. Projects adopt tiers based on their operational complexity. (aDNA Standard §13.1-§13.4)
## Usage Examples
- This vault follows Tier 1 collision prevention: every file edit updates `last_edited_by` and `updated` in frontmatter — including this glossary entry you are reading now.
- The escalation from Tier 1 → 3 mirrors the vault's own growth: a solo project needs only Tier 1; a team project with concurrent agents adds Tier 3.
## See Also
- [Frontmatter](/glossary/glossary-frontmatter)
- [Coordination Note](/glossary/glossary-coordination-note)
- [Session](/glossary/glossary-session)
---
## https://adna.network/glossary/glossary-conformance-level/
# Conformance Level — aDNA Glossary
## Plain-Language Definition
Conformance levels are three tiers — Starter, Standard, and Full — that define how much of the aDNA standard a project implements. Think of them like belt colors: Starter is the minimum viable setup, Standard adds multi-agent coordination, and Full adds federation-ready metadata and a complete template library.
## Technical Definition
A graduated tier (Starter, Standard, Full) defining the minimum requirements an aDNA instance MUST meet to claim conformance at that level. Starter requires governance files + triad directories + required subdirectories + base frontmatter. Standard adds STATE.md, per-directory AGENTS.md, session lifecycle compliance. Full adds context library with token estimates, FAIR metadata, ontology artifact, and template compliance. Projects declare their level via `adna_conformance` in MANIFEST.md frontmatter. (aDNA Standard §5.5)
## Usage Examples
- This vault (`aDNA.aDNA/`) meets Full conformance: it has all governance files, per-directory AGENTS.md files, a context library with token estimates, FAIR metadata on lattice objects, an ontology artifact, and templates for all content types.
- A brand-new project forked from the base template starts at Starter conformance and graduates upward as it adds infrastructure.
## See Also
- [Conformant Instance](/glossary/glossary-conformant-instance)
- [Governance File](/glossary/glossary-governance-file)
- [Open Standard (concept)](/learn/concepts/open-standard)
---
## https://adna.network/glossary/glossary-conformant-instance/
# Conformant Instance — aDNA Glossary
## Plain-Language Definition
A conformant instance is any project directory that meets the requirements for at least the Starter level of the aDNA standard. It has the right folders, the right governance files, and properly formatted metadata. It is a working aDNA project, not just files in a directory.
## Technical Definition
A directory tree that satisfies all MUST requirements for at least the Starter [conformance level](/glossary/glossary-conformance-level) defined in §5.5. At minimum: CLAUDE.md, MANIFEST.md, and README.md at root; `what/`, `how/`, `who/` triad directories; required subdirectories (`what/context/`, `how/missions/`, `how/sessions/`, `how/templates/`, `who/coordination/`, `who/governance/`); and base frontmatter fields on all content files. (aDNA Standard §5.5)
## Usage Examples
- This vault is a conformant instance at Full level. You can verify conformance programmatically using `what/lattices/tools/compliance_checker.py`.
- An instance that does not declare a conformance level in MANIFEST.md is assumed to be unverified — it may conform, but hasn't been checked.
## See Also
- [Conformance Level](/glossary/glossary-conformance-level)
- [aDNA](/glossary/glossary-adna)
- [Triad](/glossary/glossary-triad)
---
## https://adna.network/glossary/glossary-content-as-code/
# Content-as-Code — aDNA Glossary
## Plain-Language Definition
Content-as-code is a workflow pattern where a file's *location* tells you its *status*. Moving a file from an `inbox/` folder to a `processing/` folder means someone picked it up. Moving it to `done/` means it's finished. No status field to update — the folder *is* the state.
## Technical Definition
A universal paradigm for folder-based workflows where a file's directory location represents its processing state. Moving a file between stage directories advances it through the workflow. Each stage directory contains an [AGENTS.md](/glossary/glossary-agents-md) defining acceptance criteria and processing instructions. Pipelines live in `how/pipelines/{pipeline_name}/`. (aDNA Standard §14.1)
## Usage Examples
- This vault's `how/pipelines/prd_rfc/` directory uses content-as-code: research notes flow from `inbox/` through `processing/` to `review/`, with each folder's AGENTS.md defining what happens at that stage.
- The session lifecycle is itself a content-as-code pattern: session files move from `how/sessions/active/` to `how/sessions/history/YYYY-MM/` on completion.
## See Also
- [Content-as-Code (pattern)](/reference/specification/14-content-as-code-pipelines/)
- [Session](/glossary/glossary-session)
- [AGENTS.md](/glossary/glossary-agents-md)
---
## https://adna.network/glossary/glossary-context-library/
# Context Library — aDNA Glossary
## Plain-Language Definition
The context library is a structured knowledge store inside `what/context/` that agents load before starting domain work. It is organized by topic, with each topic containing focused subtopics. Agents read the index, pick only the subtopics they need, and stay within their token budget — like selecting chapters from a reference book instead of reading the whole thing.
## Technical Definition
The single location for all agent context, at `what/context/`. Organized by topic directories, each with its own AGENTS.md and subtopic files. Three subtypes: `context_research` (synthesized domain knowledge), `context_guide` (prescriptive tool/component guides), `context_core` (foundational project definitions). Each topic's AGENTS.md includes token estimates. Agents MUST read the topic index first and load only needed subtopics. (aDNA Standard §10.1-§10.3)
## Usage Examples
- This vault's context library has 5 topics and 27 subtopics totaling ~75K tokens: `prompt_engineering/`, `adna_core/`, `claude_code/`, `lattice_basics/`, `object_standards/`. An agent working on glossary entries loads `adna_core/` but skips `claude_code/`.
- Context recipes (`what/context/context_recipes.md`) pre-assemble cross-topic bundles for common tasks.
## See Also
- [Context Optimization (concept)](/learn/concepts/context-optimization)
- [Token Selection (concept)](/learn/concepts/token-selection)
- [what/](/glossary/glossary-what)
---
## https://adna.network/glossary/glossary-coordination-note/
# Coordination Note — aDNA Glossary
## Plain-Language Definition
A coordination note is a short message from one agent to another, left in `who/coordination/`. Think of it as a sticky note on a colleague's desk: it says who wrote it, who it is for, what needs attention, and when it expires. Notes are temporary by design — they get archived once the receiving agent acts on them.
## Technical Definition
An ephemeral cross-agent communication artifact stored in `who/coordination/`. Created when needed, consumed by the target agent, and archived when resolved. Each note MUST include: creator, target, coordination concern, creation/expiry timestamps, and action needed. Three urgency levels: `urgent` (read before any work), `info` (read during startup), `fyi` (read when convenient). Agents MUST check `who/coordination/` during every session startup. (aDNA Standard §11.1-§11.3)
## Usage Examples
- In this vault, `who/coordination/` is the designated handoff channel. If one agent discovers a blocking issue mid-session, it drops an `urgent` coordination note rather than hoping the next agent reads the SITREP carefully enough.
- Coordination notes are part of Tier 3 [collision prevention](/glossary/glossary-collision-prevention) — the multi-agent safety layer.
## See Also
- [Collision Prevention](/glossary/glossary-collision-prevention)
- [who/](/glossary/glossary-who)
- [Session](/glossary/glossary-session)
---
## https://adna.network/glossary/glossary-deployment-form/
# Deployment Form — aDNA Glossary
## Plain-Language Definition
The deployment form is *how* you physically set up the aDNA folders in your project. There are two choices: bare (folders at root) or embedded (folders inside `.agentic/`). Pick one and stick with it — every project uses exactly one.
## Technical Definition
The physical instantiation strategy for the [triad](/glossary/glossary-triad). Two forms are defined: [bare](/glossary/glossary-bare-triad) (triad at project root) and [embedded](/glossary/glossary-embedded-triad) (triad inside `.agentic/`). Both forms are first-class; the triad ontology is identical in both — only the nesting differs. A project MUST use exactly one deployment form. CLAUDE.md bridges any path differences. (aDNA Standard §3.4)
## Usage Examples
- This vault uses bare deployment (`what/`, `how/`, `who/` at root) because it is a knowledge-first project.
- A team adding aDNA to an existing Python library would choose embedded deployment to avoid mixing knowledge directories with source code.
## See Also
- [Bare Triad](/glossary/glossary-bare-triad) | [Embedded Triad](/glossary/glossary-embedded-triad)
- [Triad (concept)](/learn/concepts/triad)
- [aDNA](/glossary/glossary-adna)
---
## https://adna.network/glossary/glossary-embedded-triad/
# Embedded Triad — aDNA Glossary
## Plain-Language Definition
An embedded triad wraps the three aDNA folders inside a hidden `.agentic/` directory, keeping them separate from a codebase's source files. Use this when adding aDNA to an existing code repository — the knowledge architecture sits alongside the code without cluttering the project root.
## Technical Definition
A [deployment form](/glossary/glossary-deployment-form) where the triad is nested inside `.agentic/` at the repository root (`.agentic/what/`, `.agentic/how/`, `.agentic/who/`). Governance files remain at the repository root, not inside `.agentic/`. Follows the convention of dot-prefixed directories for meta/config in git repos (like `.github/`, `.vscode/`). Contrast with [bare triad](/glossary/glossary-bare-triad). (aDNA Standard §3.3)
## Usage Examples
- The `lattice-protocol/` codebase uses an embedded triad: its source code lives at root, while aDNA knowledge lives in `.agentic/what/`, `.agentic/how/`, `.agentic/who/`.
- An aDNA instance MUST use exactly one deployment form — mixing bare and embedded within the same project is prohibited (§3.4).
## See Also
- [Bare Triad](/glossary/glossary-bare-triad)
- [Deployment Form](/glossary/glossary-deployment-form)
- [Triad (concept)](/learn/concepts/triad)
---
## https://adna.network/glossary/glossary-frontmatter/
# Frontmatter — aDNA Glossary
## Plain-Language Definition
Frontmatter is the structured metadata block at the top of every aDNA file, wrapped in `---` fences. It records what type of content the file is, when it was created and updated, who last edited it, and what tags apply. It is the file's ID card — agents read it to understand what they are looking at before reading the content.
## Technical Definition
YAML metadata required at the top of every content file inside the triad. Base fields (MUST on all files): `type`, `status`, `created`, `updated`, `last_edited_by`, `tags`. Extended fields (type-specific): vary by content type and are defined in [templates](/glossary/glossary-template). The `last_edited_by` and `updated` fields MUST be updated on every modification as part of [collision prevention](/glossary/glossary-collision-prevention) (Tier 1). (aDNA Standard §7.1-§7.2)
## Usage Examples
- This glossary entry's own frontmatter (visible at the top of this file) demonstrates the pattern: `type: glossary_entry`, `term: "Frontmatter"`, `spec_section: "§7.1-§7.2"`, `see_also: [...]`.
- The `status` field enables content lifecycle management: `draft` → `active` → `archived`.
## See Also
- [Collision Prevention](/glossary/glossary-collision-prevention)
- [Template](/glossary/glossary-template)
- [Governance Files (concept)](/learn/concepts/governance-files)
---
## https://adna.network/glossary/glossary-governance-file/
# Governance File — aDNA Glossary
## Plain-Language Definition
A governance file is one of the ALLCAPS markdown files at the root of an aDNA project that tells agents and humans what the project is, how it works, and what rules to follow. There are five: CLAUDE.md, MANIFEST.md, STATE.md, AGENTS.md, and README.md.
## Technical Definition
Root-level ALLCAPS markdown files that govern an aDNA instance. The governance layer comprises five files: CLAUDE.md (agent root context, MUST exist), MANIFEST.md (static project overview, MUST exist), STATE.md (dynamic operational state, SHOULD exist), [AGENTS.md](/glossary/glossary-agents-md) (agent directory guide, MUST exist), and [README.md](/glossary/glossary-readme-md) (human guide, MUST exist). Together they form the agent's primary orientation documents. (aDNA Standard §4.1)
## Usage Examples
- This vault has all five governance files at its root: `CLAUDE.md` (Rosetta persona + project map), `MANIFEST.md` (architecture overview), `STATE.md` (current phase), `AGENTS.md` (learning-path navigation), and `README.md` (human getting-started guide).
- An agent's startup checklist begins with these files — they are read before any content work begins.
## See Also
- [Governance Files (concept)](/learn/concepts/governance-files)
- [AGENTS.md](/glossary/glossary-agents-md) | [README.md](/glossary/glossary-readme-md)
- [Conformance Level](/glossary/glossary-conformance-level)
---
## https://adna.network/glossary/glossary-how/
# how/ — aDNA Glossary
## Plain-Language Definition
The operations layer of an aDNA project — everything about *how* the project works. This includes mission plans, session records, templates, skills, pipelines, and campaign coordination.
## Technical Definition
The second leg of the [triad](/glossary/glossary-triad) ontology. `how/` contains operational infrastructure: missions, sessions, templates, and optionally pipelines, skills, backlog, and tasks. Required subdirectories: `missions/`, `sessions/`, `templates/`. The classification question: "HOW does this project work?" (aDNA Standard §3.1, §5.3)
## Usage Examples
- In this vault, `how/` contains `campaigns/` (Operation Rosetta), `missions/`, `sessions/`, `templates/` (32 files), `skills/` (15 recipes), `pipelines/`, `backlog/`, and `quests/`.
- A mission file lives in `how/` because it describes *how* work gets decomposed and tracked — it is an operational artifact, not knowledge.
## See Also
- [Triad (concept)](/learn/concepts/triad)
- [what/](/glossary/glossary-what) | [who/](/glossary/glossary-who)
- [Session](/glossary/glossary-session) | [Mission](/glossary/glossary-mission)
---
## https://adna.network/glossary/glossary-mission/
# Mission — aDNA Glossary
## Plain-Language Definition
A mission is a chunk of work too big for a single session. It breaks a goal into trackable objectives, each small enough for one agent session. Missions create a bridge between strategic plans (campaigns) and day-to-day execution (sessions).
## Technical Definition
A multi-session work decomposition unit that lives in `how/missions/`. A mission file MUST include: objectives, acceptance criteria, constraints, an objective list with per-objective status tracking, and dependency declarations. Agents claim objectives by [session](/glossary/glossary-session) and hand off via [SITREP](/glossary/glossary-sitrep). Missions fit into the execution hierarchy: Campaign → Mission → Objective. (aDNA Standard §9.1-§9.3)
## Usage Examples
- This vault has 19 missions (M00-M19) defined for Operation Rosetta, organized into 7 phases. Each mission file lives in `how/campaigns/campaign_rosetta/missions/` — for example, M15 (this glossary's parent mission) defines 3 objectives spanning 2 sessions.
- Mission handoff: when one session ends mid-mission, the SITREP's "Next Session Prompt" tells the next agent exactly where to pick up.
## See Also
- [Session](/glossary/glossary-session)
- [SITREP](/glossary/glossary-sitrep)
- [Convergence (concept)](/learn/concepts/convergence)
---
## https://adna.network/glossary/glossary-ontology-extension/
# Ontology Extension — aDNA Glossary
## Plain-Language Definition
An ontology extension is a new type of content you add to an aDNA project beyond the base set. The base aDNA standard defines 16 entity types (like `context`, `session`, `governance`). When your project needs something the base doesn't cover — like `concept`, `tutorial`, or `adopter` — you extend the ontology by adding a new directory, template, and AGENTS.md under the appropriate triad leg.
## Technical Definition
A domain-specific entity type added to the base aDNA ontology (16 types across 3 triad legs). Extensions are created by adding a subdirectory under the appropriate triad leg, with an AGENTS.md defining the new type's naming, frontmatter, and structure conventions, plus a [template](/glossary/glossary-template) in `how/templates/`. The registry pattern (§5.1) governs how extensions relate to external objects. Extensions inherit the parent triad leg's classification — a new `what/` entity answers "WHAT does this project know?" (aDNA Standard §5.1)
## Usage Examples
- This vault adds 10 ontology extensions: `concept`, `tutorial`, `pattern`, `glossary_entry`, `use_case`, `comparison` (all under `what/`), `community`, `adopter` (under `who/`), and `workshop`, `publishing` (under `how/`). Each has its own AGENTS.md and template.
- The extension process itself is documented as a skill: `how/skills/skill_new_entity_type.md`.
## See Also
- [Ontology (concept)](/learn/concepts/ontology)
- [Triad](/glossary/glossary-triad)
- [Question Test](/glossary/glossary-question-test)
---
## https://adna.network/glossary/glossary-question-test/
# Question Test — aDNA Glossary
## Plain-Language Definition
The question test is the three-question method for deciding where a file belongs in the aDNA triad. Ask: "Is this about WHAT we know, HOW we work, or WHO is involved?" The answer tells you which folder to put it in. If you are unsure, the question test resolves the ambiguity.
## Technical Definition
The canonical classification method for placing content in the [triad](/glossary/glossary-triad). Applied by testing each artifact against three questions: "WHAT does this project know?" (→ `what/`), "HOW does this project work?" (→ `how/`), "WHO is involved?" (→ `who/`). Every piece of project knowledge belongs in exactly one leg. The triad's deliberate minimalism (three categories, not more) ensures the question test produces unambiguous results. (aDNA Standard §3.1)
## Usage Examples
- "Where does a glossary entry go?" → "WHAT does this project know about terminology?" → `what/glossary/`. This entry demonstrates its own classification.
- "Where does a mission plan go?" → "HOW does this project work?" → `how/missions/`.
- "Where does a contributor role definition go?" → "WHO is involved?" → `who/community/`.
## See Also
- [Triad](/glossary/glossary-triad)
- [Triad (concept)](/learn/concepts/triad)
- [what/](/glossary/glossary-what) | [how/](/glossary/glossary-how) | [who/](/glossary/glossary-who)
---
## https://adna.network/glossary/glossary-readme-md/
# README.md — aDNA Glossary
## Plain-Language Definition
README.md is the guide written *for humans* that sits at the project root and optionally in subdirectories. While [AGENTS.md](/glossary/glossary-agents-md) serves agents, README.md serves people browsing in GitHub, an IDE, or a knowledge-base tool. It explains what the project is and how to navigate it.
## Technical Definition
A human-facing per-directory guide optimized for browsing. Every aDNA instance MUST have a root README.md. Subdirectory README.md files are OPTIONAL — create them when human navigation would benefit. README.md complements AGENTS.md: agents read AGENTS.md for machine-optimized instructions; humans read README.md for narrative context. (aDNA Standard §4.6)
## Usage Examples
- This vault's root `README.md` is the first thing a human sees on GitHub — it explains what aDNA.aDNA is, how to explore the vault, and where to start.
- The dual README.md / AGENTS.md pattern embodies the [dual-audience principle](/learn/concepts/dual-audience): same content, two registers.
## See Also
- [AGENTS.md](/glossary/glossary-agents-md)
- [Governance File](/glossary/glossary-governance-file)
- [Dual Audience (concept)](/learn/concepts/dual-audience)
---
## https://adna.network/glossary/glossary-session/
# Session — aDNA Glossary
## Plain-Language Definition
A session is one stretch of work by an agent (or human). It has a clear start (create a session file), a middle (do the work), and an end (write a status report). Sessions create an audit trail so the next agent — or a future version of you — knows what happened.
## Technical Definition
A bounded unit of agent work with a defined lifecycle: creation (write session file in `how/sessions/active/`), execution (perform and log work), close-out (write [SITREP](/glossary/glossary-sitrep) + next-session prompt), and archive (move to `how/sessions/history/YYYY-MM/`). A session file MUST be created before modifying any other project files. Two tiers exist: Tier 1 (lightweight audit trail) and Tier 2 (adds coordination safeguards for shared config edits). (aDNA Standard §8.1-§8.3)
## Usage Examples
- This vault's session history lives in `how/sessions/history/` — each file records what one agent accomplished, what was left unfinished, and what to do next.
- Session IDs follow the format `session_{user}_{YYYYMMDD}_{HHMMSS}_{descriptor}` for collision-free sorting.
## See Also
- [SITREP](/glossary/glossary-sitrep)
- [Mission](/glossary/glossary-mission)
- [Governance Files (concept)](/learn/concepts/governance-files)
---
## https://adna.network/glossary/glossary-sitrep/
# SITREP — aDNA Glossary
## Plain-Language Definition
A SITREP (situation report) is the structured status update written at the end of every session. It answers five questions: What was completed? What's still in progress? What should happen next? What's blocking progress? Which files were touched? It is the handoff note for whoever picks up the work next.
## Technical Definition
A structured close-out report required at the end of every [session](/glossary/glossary-session). Format: Completed, In Progress, Next Up, Blockers, Files Touched. Every session MUST include a SITREP and a next-session prompt — a self-contained paragraph enabling a fresh agent to continue the work. (aDNA Standard §8.4-§8.5)
## Usage Examples
- Every session file in this vault's `how/sessions/history/` ends with a SITREP section. The "Next Session Prompt" at the bottom is what enables a new agent to pick up exactly where the last one left off.
- STATE.md distills the most recent SITREP into the vault's operational snapshot — making cold-start orientation a two-file read (CLAUDE.md → STATE.md).
## See Also
- [Session](/glossary/glossary-session)
- [Convergence (concept)](/learn/concepts/convergence)
- [Mission](/glossary/glossary-mission)
---
## https://adna.network/glossary/glossary-skill/
# Skill — aDNA Glossary
## Plain-Language Definition
A skill is a reusable recipe that an agent can follow step-by-step to accomplish a specific task. Unlike a [template](/glossary/glossary-template) (which is a file blueprint), a skill is a *procedure* — "do step 1, then check X, then do step 2." Skills make agents more capable by codifying expertise into repeatable instructions.
## Technical Definition
A reusable agent procedure stored at `how/skills/skill_{name}.md`. Sections: purpose, prerequisites, steps, verification, rollback, notes. Skills are agent-executable (precise steps, verification checks); processes are human-readable (guidelines, decision trees). Skills are distinct from templates: templates define file *structure*, skills define task *procedures*. Skills can be promoted to lattice registry as `lattice_type: skill`. (aDNA Standard §19.3)
## Usage Examples
- This vault has 50 skills (21 base + 29 project-specific). `skill_dual_audience_review` is a quality gate skill: it walks the agent through checking whether a content file is legible to both developers and non-developers.
- `skill_onboarding` fires automatically on first-run detection — when the vault has no session history and MANIFEST.md still shows `last_edited_by: agent_init`.
## See Also
- [Template](/glossary/glossary-template)
- [how/](/glossary/glossary-how)
- [Ontology Extension](/glossary/glossary-ontology-extension)
---
## https://adna.network/glossary/glossary-template/
# Template — aDNA Glossary
## Plain-Language Definition
A template is a reusable blueprint for creating new files of a specific type. Instead of starting from scratch, agents copy the template and fill in the blanks. Templates ensure every file of the same type has consistent structure and metadata — like a form with pre-printed field labels.
## Technical Definition
Reusable file structures stored in `how/templates/`, following the naming pattern `template_{type}.md`. Templates MUST include [frontmatter](/glossary/glossary-frontmatter) with all base fields plus type-specific fields pre-populated. Three graduated sets: Starter (session, mission, context — MUST exist), Standard (adds coordination, backlog, ADR — SHOULD exist), Full (adds domain-specific types — MAY exist). A template index is RECOMMENDED for projects with 5+ templates. (aDNA Standard §12.1-§12.2)
## Usage Examples
- This vault has 41 templates (25 base + 11 extension + 5 operational). The glossary entries you are reading were created from `how/templates/template_glossary_entry.md`, which pre-defines the frontmatter fields (`term`, `spec_section`, `see_also`) and section structure (Plain-Language Definition, Technical Definition, Usage Examples, See Also).
- Every content type used in the vault has a matching template — this is a Full [conformance](/glossary/glossary-conformance-level) requirement.
## See Also
- [Frontmatter](/glossary/glossary-frontmatter)
- [how/](/glossary/glossary-how)
- [Conformance Level](/glossary/glossary-conformance-level)
---
## https://adna.network/glossary/glossary-triad/
# Triad — aDNA Glossary
## Plain-Language Definition
The triad is the three-folder structure at the heart of every aDNA project: `what/` (what the project knows), `how/` (how the project works), and `who/` (who is involved). Every piece of project knowledge belongs in exactly one of these three folders.
## Technical Definition
The `what/how/who` directory ontology that organizes all aDNA content. The triad is the universal classifier — any project artifact is sorted by asking: "Is this about WHAT we know, HOW we work, or WHO is involved?" The ontology is deliberately minimal; three categories prevent the sorting ambiguity that arises from finer-grained taxonomies. (aDNA Standard §3.1)
## Usage Examples
- In this vault (`aDNA.aDNA/`), the triad is visible at the project root: `what/` holds concepts and glossary entries, `how/` holds campaigns and sessions, `who/` holds governance and community docs.
- The "question test" — asking which of the three questions a piece of content answers — is the canonical classification method.
## See Also
- [Triad (concept)](/learn/concepts/triad) — full concept deep dive
- [what/](/glossary/glossary-what) | [how/](/glossary/glossary-how) | [who/](/glossary/glossary-who)
- [Bare Triad](/glossary/glossary-bare-triad) | [Embedded Triad](/glossary/glossary-embedded-triad)
---
## https://adna.network/glossary/glossary-what/
# what/ — aDNA Glossary
## Plain-Language Definition
The knowledge layer of an aDNA project — everything the project *knows*. This includes reference material, context for agents, decisions that have been made, and domain-specific knowledge objects.
## Technical Definition
The first leg of the [triad](/glossary/glossary-triad) ontology. `what/` contains knowledge objects, the context library, architecture decision records, and domain entities. Required subdirectory: `context/` (the agent context library). The classification question: "WHAT does this project know?" (aDNA Standard §3.1, §5.1)
## Usage Examples
- In this vault, `what/` contains `concepts/`, `tutorials/`, `patterns/`, `glossary/`, `comparisons/`, `use_cases/`, `context/`, `decisions/`, `docs/`, and `lattices/` — all knowledge, no operations.
- The glossary entry you are reading right now lives inside `what/glossary/`, because it answers the question "What does this project know about aDNA terminology?"
## See Also
- [Triad (concept)](/learn/concepts/triad)
- [how/](/glossary/glossary-how) | [who/](/glossary/glossary-who)
- [Context Library](/glossary/glossary-context-library)
---
## https://adna.network/glossary/glossary-who/
# who/ — aDNA Glossary
## Plain-Language Definition
The organization layer of an aDNA project — everything about *who* is involved. This includes governance policies, team roles, coordination notes between agents, and community structures.
## Technical Definition
The third leg of the [triad](/glossary/glossary-triad) ontology. `who/` contains organizational information: governance policies, coordination notes, team structures, and optionally contacts, partners, and community docs. Required subdirectories: `coordination/`, `governance/`. The classification question: "WHO is involved?" (aDNA Standard §3.1, §5.2)
## Usage Examples
- In this vault, `who/` contains `governance/` (agent protocol, vision, code of conduct), `coordination/` (cross-agent notes), `community/` (roles and processes), and `adopters/` (persona profiles).
- The `last_edited_by` field in every file's frontmatter is a WHO concept — it tracks which agent or human last touched a piece of content.
## See Also
- [Triad (concept)](/learn/concepts/triad)
- [what/](/glossary/glossary-what) | [how/](/glossary/glossary-how)
- [Governance File](/glossary/glossary-governance-file)
---
## https://adna.network/how/
*[image: Bird's-eye pixel-art desk with glowing module-boxes wired into a left-to-right pipeline of light — aDNA operations]*
# How
The **how/** leg of the aDNA triad covers operational processes — the repeatable workflows that turn knowledge into outcomes. Where [what/](/learn/) holds what a project knows and [who/](/community/) holds who decides, **how/** holds the procedures: the things a person or an agent runs.
## What belongs in how/
The test is whether the document tells someone *to do something*, in an order, repeatably. A description of the publishing pipeline is how/; an explanation of what a lattice *is* is what/. The distinction matters because it decides where an agent looks: an agent asked to publish this site reads how/ and does not need to load the concept library to do it.
In practice that means three kinds of document — a pipeline (a sequence a machine can run), a kit (a sequence a person runs, with materials), and a lattice definition (a sequence written as a graph, so it can be executed or inspected).
## The three areas
[Publishing How vault content becomes a live documentation site — the transform pipeline, content mapping, and social sharing system.](/how/publishing/)[Workshops Structured workshop kits for teaching aDNA — from beginner vault exploration to advanced lattice design.](/how/workshops/)[Lattice Examples Self-referential lattice definitions that model the processes used to build this vault and site.](/how/lattice-examples/)
## Where to start
If you want to see how this site is produced from a vault, read [Publishing](/how/publishing/) — it is the pipeline running behind the page you are reading. If you are teaching aDNA to a group, start with [Workshops](/how/workshops/). If you want to see a process written as a graph rather than as prose, [Lattice Examples](/how/lattice-examples/) models this vault's own workflows.
## In this vault
Everything in this section is a working example rather than a description of one. The publishing pipeline documented here is the pipeline that built this page; the lattice examples model the campaigns that wrote it. That is the aDNA structure doing its own job — `how/` in a vault holds the procedures that produced the vault, so the documentation and the mechanism cannot drift apart without one of them visibly breaking.
---
## https://adna.network/how/lattice-examples/
# Lattice Examples
These four lattice definitions are self-referential — each one models a real process used to build this vault and site. The content pipeline lattice describes the transform that produced these pages. The campaign execution lattice models Operation Rosetta. The context serving lattice IS the agent startup protocol. The dual audience review lattice IS the quality gate every content file passed.
[Content Pipeline new A 10-node pipeline lattice modeling the vault-to-site publishing process. Self-referential: this lattice describes the exact pipeline that built this page.](/how/lattice-examples/lattice-content-pipeline)[Campaign Execution new A 9-node workflow lattice modeling the Campaign-Mission-Objective execution hierarchy with phase gates, SITREPs, and AARs.](/how/lattice-examples/lattice-campaign-execution)[Context Serving new An 8-node context graph implementing the aDNA convergence model. Self-referential: this lattice IS the startup protocol every agent session follows.](/how/lattice-examples/lattice-context-serving)[Dual Audience Review new A 6-node agent lattice implementing the quality gate every content file passes: developer review, newcomer review, self-reference scan, and cross-link check.](/how/lattice-examples/lattice-dual-audience-review)
---
## https://adna.network/how/lattice-examples/lattice-campaign-execution/
# Campaign Execution — aDNA Lattice Examples
This lattice models the execution hierarchy that built this entire documentation site. Operation Rosetta — the campaign that produced every page you can navigate here — follows exactly this workflow: campaigns decompose into phased missions, missions decompose into session-sized objectives, and human gates prevent auto-advancement between phases.
The workflow includes feedback loops: when a session closes but objectives remain, it loops back to open a new session. When all objectives in a mission complete, the AAR protocol fires before the next mission starts. These cycles mirror the OODA cascade described in the aDNA standard.
| Property | Value |
|----------|-------|
| **Lattice type** | `workflow` |
| **Execution mode** | `workflow` |
| **Node count** | 9 |
| **Tier** | L1 (local) |
## How it connects
This lattice demonstrates [Mission Decomposition](/patterns/mission-decomposition) as an executable graph. The phase gate node implements the standing order that phase transitions require human approval. The AAR node at mission close implements the [SITREP](/glossary/glossary-sitrep) and [Mission](/glossary/glossary-mission) protocols. See [The Convergence Model](/learn/concepts/convergence) for how each level narrows context.
## Full lattice definition
```yaml
lattice:
name: campaign_execution
version: "1.0.0"
lattice_type: workflow
description: >
Campaign execution hierarchy for aDNA operational projects. Models the
Campaign -> Mission -> Objective decomposition with phase gates, session
tracking, and AAR protocol. Self-referential: this lattice models Operation
Rosetta's own execution model in how/campaigns/campaign_rosetta/.
execution:
mode: workflow
runtime: local
tier: L1
nodes:
- id: campaign_plan
type: dataset
description: "Campaign master document — strategic intent, phase structure, mission board, success criteria"
ref: "how/campaigns/campaign_rosetta/campaign_rosetta.md"
- id: phase_gate
type: process
description: "Human approval gate between campaign phases — prevents auto-advancement"
- id: mission_create
type: process
description: "Decompose phase into missions with objectives, dependencies, and quality gates"
- id: session_open
type: process
description: "Create session file in how/sessions/active/, claim objective, begin work"
- id: objective_execute
type: process
description: "Atomic work unit — completable in one session with defined deliverables"
- id: session_close
type: process
description: "Write SITREP (completed, in progress, next up, blockers, files touched)"
- id: mission_complete
type: process
description: "All objectives done — write 5-line AAR (Worked, Didn't, Finding, Change, Follow-up)"
- id: phase_complete
type: dataset
description: "Phase completion summary — all missions closed, campaign board updated"
- id: campaign_aar
type: dataset
description: "Campaign-level AAR — full retrospective at campaign close"
edges:
- from: campaign_plan
to: phase_gate
label: "phase ready"
- from: phase_gate
to: mission_create
label: "phase approved"
condition: "human_approval == true"
- from: mission_create
to: session_open
label: "mission with objectives"
- from: session_open
to: objective_execute
label: "claimed objective"
- from: objective_execute
to: session_close
label: "work complete"
- from: session_close
to: session_open
label: "next objective"
condition: "mission_objectives_remaining > 0"
- from: session_close
to: mission_complete
label: "all objectives done"
condition: "mission_objectives_remaining == 0"
- from: mission_complete
to: mission_create
label: "next mission in phase"
condition: "phase_missions_remaining > 0"
- from: mission_complete
to: phase_complete
label: "phase done"
condition: "phase_missions_remaining == 0"
- from: phase_complete
to: phase_gate
label: "next phase"
condition: "campaign_phases_remaining > 0"
- from: phase_complete
to: campaign_aar
label: "campaign done"
condition: "campaign_phases_remaining == 0"
fair:
license: "MIT"
creators:
- "Lattice Labs"
keywords:
- campaign
- execution hierarchy
- mission decomposition
- aar
- phase gate
- self-referential
provenance: "Models the aDNA campaign execution hierarchy. Derived from Operation Rosetta's actual 7-phase, 35-mission structure."
```
---
## https://adna.network/how/lattice-examples/lattice-content-pipeline/
# Content Pipeline — aDNA Lattice Examples
This lattice models the exact pipeline that transforms vault Markdown into the page you are reading right now. Every node corresponds to a real stage in the `transform-content.mjs` script — from reading vault files through frontmatter rewriting, wikilink resolution, and Astro build to Vercel deployment.
The pipeline is typed as `hybrid` because most stages are deterministic transforms (process nodes), but the content mapping stage uses an LLM reasoning node to decide which vault entities to publish and how to route them between the transform script and direct Astro pages.
| Property | Value |
|----------|-------|
| **Lattice type** | `pipeline` |
| **Execution mode** | `hybrid` |
| **Node count** | 10 |
| **Tier** | L1 (local) |
## How it connects
The content pipeline lattice is a working demonstration of [Lattice Composition](/learn/concepts/lattice-composition) — it chains dataset, process, and reasoning nodes into a directed acyclic graph. The [FAIR Metadata](/learn/concepts/fair-metadata) block makes it discoverable across registries. The narrative companion lives at [Vault-to-Site Pipeline](/how/publishing/vault-to-site).
## Full lattice definition
```yaml
lattice:
name: content_pipeline
version: "1.0.0"
lattice_type: pipeline
description: >
Vault-to-site publishing pipeline for aDNA.aDNA. Transforms vault Markdown
into Astro MDX content collections and deploys to Vercel. Self-referential:
this lattice models the exact pipeline that built adna.network.
See how/publishing/publishing_vault_to_site.md for the narrative description.
execution:
mode: hybrid
runtime: local
tier: L1
nodes:
- id: vault_content
type: dataset
description: "Source Markdown files from vault directories (what/concepts/, what/tutorials/, etc.)"
ref: "what/concepts/"
- id: content_mapping
type: reasoning
description: "Select which vault entities to publish and map them to site sections"
prompt: >
Given the vault entity types (concept, tutorial, pattern, comparison,
use_case, reference), determine the correct site collection and URL
pattern for each. Route WHAT-triad content through the transform script,
WHO-triad content through direct Astro pages.
- id: frontmatter_rewrite
type: process
description: "Strip vault frontmatter (type, created, tags) and replace with Astro-specific fields (title, description, section, order)"
- id: wikilink_rewrite
type: process
description: "Convert Obsidian [[wikilinks]] to standard Markdown [label](url) using the wikilink registry"
- id: h1_strip
type: process
description: "Remove first H1 heading — Astro layouts render the title from frontmatter"
- id: description_gen
type: process
description: "Extract first non-heading paragraph and truncate to 155 characters for SEO meta description"
- id: mdx_output
type: dataset
description: "Transformed MDX files in site/src/content/ (docs/, guides/, reference/)"
- id: astro_build
type: process
description: "Astro 6 static site build from site/ directory"
- id: deploy
type: process
description: "Deploy to Vercel via vercel --prod"
- id: live_site
type: dataset
description: "Live documentation site at adna.network"
edges:
- from: vault_content
to: content_mapping
label: "raw vault files"
- from: content_mapping
to: frontmatter_rewrite
label: "selected files with target sections"
- from: frontmatter_rewrite
to: wikilink_rewrite
label: "astro frontmatter"
- from: wikilink_rewrite
to: h1_strip
label: "resolved links"
- from: h1_strip
to: description_gen
label: "clean content"
- from: description_gen
to: mdx_output
label: "complete MDX files"
- from: mdx_output
to: astro_build
label: "content collections"
- from: astro_build
to: deploy
label: "static site bundle"
- from: deploy
to: live_site
label: "deployed site"
fair:
license: "MIT"
creators:
- "Lattice Labs"
keywords:
- publishing
- content pipeline
- astro
- vercel
- vault to web
- self-referential
provenance: "Models the actual vault-to-site publishing pipeline used by aDNA.aDNA. See transform-content.mjs for the implementation."
```
---
## https://adna.network/how/lattice-examples/lattice-context-serving/
# Context Serving — aDNA Lattice Examples
This lattice is the startup protocol. When an AI agent opens a session in an aDNA vault, it traverses exactly this graph — loading CLAUDE.md, reading STATE.md, checking AGENTS.md routing decisions, assembling context recipes, and narrowing from the full vault down to the exact files needed for the current objective.
The convergence model makes this narrowing explicit: the vault holds ~75K tokens of context, but any single session needs only a fraction. Each node in this graph reduces scope — from project rules, through campaign context, to mission objectives — until the agent holds precisely the context it needs and nothing more.
| Property | Value |
|----------|-------|
| **Lattice type** | `context_graph` |
| **Execution mode** | `reasoning` |
| **Node count** | 8 |
| **Tier** | L1 (local) |
## How it connects
This lattice implements [The Convergence Model](/learn/concepts/convergence) as an executable graph. The AGENTS.md router node demonstrates the [AGENTS.md Routing](/patterns/agents-md) pattern — each directory's AGENTS.md helps the agent decide whether to load its contents. The context recipe node uses the [Context Recipe](/patterns/context-recipe) pattern to assemble cross-topic bundles. See [Context Optimization](/learn/concepts/context-optimization) for the theory behind token-efficient serving.
## Full lattice definition
```yaml
lattice:
name: context_serving
version: "1.0.0"
lattice_type: context_graph
description: >
Context serving graph implementing the aDNA convergence model. Each agent
session traverses this graph to load only the subgraph reachable from the
current objective — narrowing from full vault to exact files needed.
Self-referential: this lattice IS the startup protocol described in
CLAUDE.md Agent Protocol.
execution:
mode: reasoning
runtime: local
tier: L1
model: "claude-opus-4-6"
nodes:
- id: claude_md
type: dataset
description: "Project CLAUDE.md — auto-loaded master context with safety rules, standing orders, domain knowledge"
ref: "CLAUDE.md"
- id: state_md
type: dataset
description: "STATE.md — operational snapshot with current phase, blockers, next steps"
ref: "STATE.md"
- id: agents_md_router
type: reasoning
description: "Read AGENTS.md in target directory to make load/skip decision"
prompt: >
Read the AGENTS.md file in the target directory. Based on the
Load/Skip Decision section and the current session's objective,
decide whether to load this directory's content into context.
Consider token cost vs. relevance.
- id: context_library
type: dataset
description: "Context library at what/context/ — 5 topics, 27 subtopics, ~75K tokens total"
ref: "what/context/"
- id: context_recipe
type: reasoning
description: "Check context_recipes.md for pre-assembled cross-topic bundles matching this session's domain"
prompt: >
Given the session's task domain, check context_recipes.md for a
matching recipe. Load the recipe's specified subtopics at the
appropriate budget tier (Minimal/Standard/Full). Prefer recipes
over manual subtopic selection.
ref: "what/context/context_recipes.md"
- id: campaign_context
type: dataset
description: "Active campaign docs — campaign master doc + campaign CLAUDE.md"
ref: "how/campaigns/campaign_rosetta/"
- id: mission_context
type: dataset
description: "Active mission file — objectives, dependencies, progress"
- id: session_context
type: dataset
description: "Assembled context for this session — the convergence output"
edges:
- from: claude_md
to: state_md
label: "project rules loaded"
- from: state_md
to: agents_md_router
label: "operational state known"
- from: agents_md_router
to: context_library
label: "directory loaded"
condition: "load_decision == true"
- from: agents_md_router
to: campaign_context
label: "skip to campaign"
condition: "load_decision == false"
- from: context_library
to: context_recipe
label: "raw subtopics"
- from: context_recipe
to: campaign_context
label: "assembled domain context"
- from: campaign_context
to: mission_context
label: "campaign scope"
- from: mission_context
to: session_context
label: "mission objectives"
fair:
license: "MIT"
creators:
- "Lattice Labs"
keywords:
- context serving
- convergence model
- token selection
- agents.md
- context recipe
- self-referential
provenance: "Models the aDNA convergence model — the context loading strategy every agent session uses at startup. Derived from the Agent Protocol in CLAUDE.md."
```
---
## https://adna.network/how/lattice-examples/lattice-dual-audience-review/
# Dual Audience Review — aDNA Lattice Examples
This lattice is the quality gate. Every content file on this site — every concept, tutorial, pattern, and comparison — passed through this review process before being marked complete. The content file fans out to four parallel checks (developer review, newcomer review, self-reference scan, cross-link check), and the results converge into a single quality verdict.
The fan-out/fan-in topology is deliberate: the developer and newcomer perspectives are independent evaluations that should not influence each other. A file that scores 5/5 for technical depth but 1/5 for newcomer accessibility is not done — both audiences must be served.
| Property | Value |
|----------|-------|
| **Lattice type** | `agent` |
| **Execution mode** | `hybrid` |
| **Node count** | 6 |
| **Tier** | L1 (local) |
## How it connects
This lattice implements [Dual-Audience Writing](/patterns/dual-audience-writing) as an executable quality gate. The developer review node checks for spec citations per the [aDNA Specification](/reference/specification). The newcomer review node enforces the plain-language opening rule. The self-reference scan ensures every file cites a concrete vault example — the principle that makes this documentation self-demonstrating. See [Dual Audience](/learn/concepts/dual-audience) for the concept.
## Full lattice definition
```yaml
lattice:
name: dual_audience_review
version: "1.0.0"
lattice_type: agent
description: >
Quality review agent for aDNA content files. Evaluates each file against
two audience perspectives (developer and newcomer), checks for
self-referential vault citations, verifies cross-linking, and produces a
quality verdict. Self-referential: this lattice IS the quality gate that
every content file in aDNA.aDNA passed during Operation Rosetta.
execution:
mode: hybrid
runtime: local
tier: L1
model: "claude-opus-4-6"
nodes:
- id: content_file
type: dataset
description: "The vault content file under review (concept, tutorial, pattern, etc.)"
- id: developer_review
type: reasoning
description: "Evaluate from a developer perspective — technical precision, spec citations, integration guidance"
prompt: >
Review this content file as a developer building with aDNA.
Check: Are technical claims precise? Do normative claims cite
adna_standard.md sections? Would a developer find enough detail
to implement? Rate technical depth 1-5.
- id: newcomer_review
type: reasoning
description: "Evaluate from a newcomer perspective — plain language, metaphors, accessibility"
prompt: >
Review this content file as someone encountering aDNA for the
first time. Check: Does the opening paragraph make sense without
jargon? Are there metaphors or examples? Could a 14-year-old
follow the first 3 sentences? Rate accessibility 1-5.
- id: self_reference_scan
type: process
description: "Verify the file cites at least one concrete example from THIS vault — a directory, file, or governance chain the reader can inspect"
- id: cross_link_check
type: process
description: "Verify minimum 2 wikilinks to other content files in the vault"
- id: quality_verdict
type: dataset
description: "Combined quality assessment — pass/fail with dimension scores and improvement suggestions"
edges:
- from: content_file
to: developer_review
label: "file content"
- from: content_file
to: newcomer_review
label: "file content"
- from: content_file
to: self_reference_scan
label: "file content"
- from: content_file
to: cross_link_check
label: "file content"
- from: developer_review
to: quality_verdict
label: "technical score"
- from: newcomer_review
to: quality_verdict
label: "accessibility score"
- from: self_reference_scan
to: quality_verdict
label: "self-ref pass/fail"
- from: cross_link_check
to: quality_verdict
label: "link count"
fair:
license: "MIT"
creators:
- "Lattice Labs"
keywords:
- quality review
- dual audience
- self-reference
- content quality
- agent
- self-referential
provenance: "Models the dual-audience quality review process used by Operation Rosetta. Implements skill_dual_audience_review.md and skill_self_reference_check.md as a lattice."
```
---
## https://adna.network/how/publishing/
# Publishing
The publishing pipeline transforms vault Markdown into the Astro documentation site you are reading now. These docs cover the end-to-end pipeline, the content mapping between vault entities and site sections, and the OG image system for social sharing.
[Vault-to-Site Pipeline This document describes how aDNA.aDNA vault content becomes a live documentation website. The pipeline transforms Markdown files from vault…](/how/publishing/vault-to-site)[Content Mapping Every vault entity type maps to a specific site section and URL pattern. This document is the registry of those mappings — the bridge between vault…](/how/publishing/content-mapping)[Social Sharing How the site's OG (Open Graph) social-preview system works: branded preview images, section-aware selection, and how to configure previews for the vault.](/how/publishing/social-sharing)
---
## https://adna.network/how/publishing/content-mapping/
# Content Mapping — aDNA Publishing
## Overview
Every vault entity type maps to a specific site section and URL pattern. This document is the registry of those mappings — the bridge between vault architecture and web architecture. The mapping tables below are extracted from the same `transform-content.mjs` script that builds [adna.network](https://adna.network).
> **Every count on this page is derived, not remembered.** Re-derive before quoting: the mapping-table sizes
> from `site/scripts/transform-content.mjs`, the published totals from a fresh `site/dist/`. Figures below were
> derived 2026-09-11. A count in prose is a claim with an expiry date, and this page has already outlived one
> set — see [Current Gaps](#current-gaps).
## Two Publishing Pathways
Content reaches the site through two distinct mechanisms:
### Pathway 1: Transform Script
The `transform-content.mjs` script handles content from the **WHAT** and **HOW** triad legs. Eight mapping tables define source-to-output transformations:
| Vault Directory | Entity Type | Site Collection | URL Pattern | Count |
|----------------|-------------|-----------------|-------------|-------|
| `what/concepts/` | concept | `content/docs/` | `/learn/concepts/{slug}` | 13 |
| `what/patterns/` | pattern | `content/docs/` | `/patterns/{slug}` | 8 |
| `what/comparisons/` | comparison | `content/docs/` | `/learn/comparisons/{slug}` | 5 |
| `what/use_cases/` | use_case | `content/docs/` | `/use-cases/{slug}` | 6 |
| `what/tutorials/` | tutorial | `content/guides/` | `/learn/tutorials/{slug}` | 9 |
| `what/docs/` | reference | `content/reference/` | `/reference/{slug}` | 8 |
| `how/publishing/` | publishing | `content/docs/` | `/how/publishing/{slug}` | 3 |
| `how/workshops/` | workshop | `content/docs/` | `/how/workshops/{slug}` | 4 |
Each mapping entry defines: `source` (vault filename), `slug` (URL segment), `title` (display name), and type-specific fields (`order`, `difficulty`, `time`, `stability`, `version`).
### Pathway 2: Direct Astro Pages
Some collections use direct `.astro` pages with dynamic `[...slug].astro` routes. These bypass the transform script and read content directly:
| Vault Directory | Entity Type | URL Pattern | Count |
|----------------|-------------|-------------|-------|
| `what/glossary/` | glossary_entry | `/glossary/{slug}` | 25 |
| `who/community/` | community | `/community/{slug}` | 3 |
This second pathway emerged when WHO-triad content arrived that did not fit the transform script's original WHAT-only architecture. Both pathways coexist — the transform script handles bulk content with complex transformations, while direct pages handle smaller collections with simpler needs.
## The Wikilink Registry
The transform script maintains a 60-entry wikilink map that converts Obsidian `[[wikilinks]]` to site URLs. Every content entity gets a registered entry:
```javascript
'concept_triad': { url: '/learn/concepts/triad', label: 'The Triad' },
```
When a vault file references `[The Triad](/learn/concepts/triad)`, the transform rewrites it to `[The Triad](/learn/concepts/triad)`. Unregistered wikilinks pass through unchanged — this makes missing registrations visible in site builds rather than silently breaking links.
## Adding New Content Types
To publish a new vault entity type on the site:
1. **Choose the pathway.** Use the transform script for large collections needing frontmatter rewriting and wikilink resolution. Use direct Astro pages for small collections with straightforward rendering.
2. **For transform script:** Add a mapping table (source → slug → title → order), add wikilink entries, create a `transformX()` function following the existing pattern, and call it from the main block.
3. **For direct pages:** Create a `[...slug].astro` page under `site/src/pages/`, an index page, and add the route to the site navigation.
4. **Register wikilinks.** Any new entity needs entries in the wikilink map so other content can link to it.
## Current Gaps
> ⛔ **Corrected 2026-09-11.** This section used to read: *"The **HOW** triad leg (`how/publishing/`,
> `how/workshops/`) is not yet published to the site. This content — including the document you are reading —
> exists in the vault but has no site pathway."* **Every clause of that was false when you read it.** There are
> 15 built `/how/` pages; this document is served at `/how/publishing/content-mapping`; and it is row 2 of the
> `publishingMapping` table in the very script this page says its tables are extracted from. The claim outlived
> the gap it described and nothing re-read it, because **a sentence asserting that something is missing proposes
> no work — so nothing schedules a look.** Kept rather than deleted: the failure is the most useful thing on
> the page.
Not everything in the vault reaches the site, and the gaps are real ones — derived 2026-09-11 by counting vault
sources against built output:
| Vault content | On the site | Gap |
|---|---|---|
| `what/patterns/` (25) | 8 published | 17 patterns exist only in the vault |
| `what/docs/` (20) | 8 mapped to `/reference/` | 12 unmapped |
| `what/glossary/` (30) | 25 published | 5 unmapped |
| `who/reviewers/` (16) | — | no route; reviewer personas are an internal review instrument |
| `who/adopters/` (16) | — | no route of its own; `/adopters/` redirects to `/use-cases/` |
The operational **HOW** entities — `campaigns/`, `missions/`, `sessions/`, `backlog/`, `skills/`, `templates/` —
are **deliberately** unpublished. They are the vault's working record, not its public face; the [Triad](/learn/concepts/triad)
publishes what a reader needs, not everything the vault holds. Likewise `who/governance/` and `who/coordination/`.
**A gap in this table is a claim like any other.** If you are reading this more than a release or two after the
derivation date above, re-derive it before repeating it.
## Self-Reference
These mapping tables ARE the vault's own content architecture viewed from the publishing side. The [Ontology](/learn/concepts/ontology) defines entity types; this document shows where each type lands on the web. The two-pathway pattern itself demonstrates the [Base/Extension](/patterns/base-extension) pattern: the original transform script is the base, and direct Astro pages are the extension added when new entity types outgrew the original design.
## Related
- [Vault-to-Site Pipeline](/how/publishing/vault-to-site) — the end-to-end pipeline these mappings feed
- [Social Sharing](/how/publishing/social-sharing) — how published pages appear when shared
- [The Ontology](/learn/concepts/ontology) — the entity type system that this mapping reflects
- [Base/Extension](/patterns/base-extension) — the pattern demonstrated by the two-pathway architecture
---
## https://adna.network/how/publishing/social-sharing/
# Social Sharing — aDNA Publishing
## Overview
When someone shares an aDNA.aDNA page on social media, a branded preview image and description appear automatically. This document describes the OG (Open Graph) image system, section-aware selection logic, and how to configure social previews for the vault and its GitHub repository.
## OG Image System
Five branded OG images (1200x630px) cover the site's content sections. Each uses the aDNA teal gradient palette with decorative DNA helix motifs and section-specific titles.
| Image | File | Sections Served |
|-------|------|----------------|
| Default | `site/public/images/og-default.png` | Homepage, get-started, changelog, fallback |
| Learn | `site/public/images/og-learn.png` | Concepts, tutorials, comparisons (`/learn/*`) |
| Patterns | `site/public/images/og-patterns.png` | Pattern library (`/patterns/*`) |
| Reference | `site/public/images/og-reference.png` | Specification, glossary (`/reference/*`, `/glossary/*`) |
| Community | `site/public/images/og-community.png` | Community roles, audience scenarios (`/community/*`, `/use-cases/*`) |
### Generation
Images are generated from SVG templates using `@resvg/resvg-js`:
```bash
node site/scripts/generate-og-images.mjs
```
The script renders SVG with the aDNA brand gradient (`#0A4F52` to `#071E1F`), accent circles, and section-specific text. Output lands in `site/public/images/`. Re-run after changing branding.
### Section-Aware Selection
The `SEOHead.astro` component selects the correct OG image based on the current page path:
| Path Prefix | OG Image |
|-------------|----------|
| `/learn/` | og-learn.png |
| `/patterns/` | og-patterns.png |
| `/reference/`, `/glossary/` | og-reference.png |
| `/community/`, `/use-cases/` | og-community.png |
| Everything else | og-default.png |
Every page also gets an auto-generated `` from the first paragraph of its content (truncated to 155 characters by the [transform pipeline](/how/publishing/vault-to-site)).
## GitHub Repository Preview
The repository at `github.com/aDNA-Network/aDNA` can display a social preview image when linked from external sites. Upload `og-default.png` at:
> Repository Settings > General > Social preview > Edit > Upload an image
This is a manual one-time step.
## Sharing Checklist
When publishing new content to the site:
- [ ] Verify the page's URL falls under a recognized path prefix for OG selection
- [ ] Check the auto-generated meta description is meaningful (first paragraph matters)
- [ ] Test social preview with a link validator (e.g., OpenGraph.xyz or Twitter Card Validator)
- [ ] For new site sections, add a path rule to `SEOHead.astro` and consider a new OG image
## Self-Reference
This OG system was built during Phase 4.5 (M23) and demonstrates a practical application of the [Dual Audience](/learn/concepts/dual-audience) principle: developers see the implementation details (SVG templates, path-based selection, component architecture), while non-developers see branded previews that build trust before they even visit the site. The OG images themselves carry the aDNA visual identity into every social platform where a page link appears.
## Related
- [Vault-to-Site Pipeline](/how/publishing/vault-to-site) — the build pipeline that includes description generation
- [Content Mapping](/how/publishing/content-mapping) — the section architecture that OG selection mirrors
- [Dual Audience](/learn/concepts/dual-audience) — the principle this system demonstrates in practice
- [FAIR Envelope](/patterns/fair-envelope) — metadata best practices that extend to social metadata
---
## https://adna.network/how/publishing/vault-to-site/
# Vault-to-Site Pipeline — aDNA Publishing
## Overview
This document describes how aDNA.aDNA vault content becomes a live documentation website. The pipeline transforms Markdown files from vault directories into Astro content collections, then deploys to Vercel. You are reading a file that was produced by the same vault this pipeline publishes — the process described here built the site at [adna.network](https://adna.network).
## The Pipeline
The publishing pipeline has four stages:
```
Vault Markdown → transform-content.mjs → Astro MDX → Vercel
```
### Stage 1: Source Content
Content lives in vault directories organized by the [Triad](/learn/concepts/triad) — `what/concepts/`, `what/patterns/`, `what/tutorials/`, `what/comparisons/`, `what/use_cases/`, and `what/docs/`. Each file follows its entity template with YAML frontmatter and wikilink cross-references.
### Stage 2: Transform
The core script is `site/scripts/transform-content.mjs`. Run it with:
```bash
node site/scripts/transform-content.mjs
```
It performs four transformations on each source file:
1. **Frontmatter rewriting** — strips vault frontmatter (`type`, `created`, `tags`, etc.) and replaces it with Astro-specific fields (`title`, `description`, `section`, `order`). The vault metadata serves agents; the site metadata serves browsers.
2. **Wikilink rewriting** — converts Obsidian-style `[[target|alias]]` and `[[target]]` links into standard Markdown `[label](url)` using a 48-entry wikilink map. Every content entity has a registered URL. Unresolved wikilinks pass through unchanged.
3. **H1 stripping** — removes the first `# heading` from each file. Astro layouts render the title from frontmatter, so the vault's H1 would duplicate it.
4. **Description generation** — extracts the first non-heading, non-table, non-list paragraph and truncates to 155 characters for SEO meta descriptions.
### Stage 3: Astro Build
Transformed files land in `site/src/content/` as `.mdx` files, organized into Astro content collections:
- `content/docs/` — concepts, patterns, comparisons, use cases
- `content/guides/` — tutorials
- `content/reference/` — specification documents
Astro 6 builds the site with `npm run build` from the `site/` directory. Dynamic routes (`[...slug].astro`) render each collection entry using shared layouts.
### Stage 4: Deploy
Deploy to Vercel with:
```bash
cd site && vercel --prod
```
Manual, and **deliberately so** — corrected 2026-09-11. This line used to call auto-deploy-on-push a planned
improvement and point at a section of [Content Mapping](/how/publishing/content-mapping) that never described one.
Both halves are now retired: the pointer dangled, and the improvement was ruled against. A push publishes
*source*; a deploy publishes *the site*. Keeping them as two separate acts is what lets a guard refuse to publish
a tree that does not contain the commit currently serving production — a check auto-deploy-on-push would have
nothing to run.
## Self-Reference
This pipeline is the mechanism that publishes the site: **229 pages** as of 2026-09-11, derived from a fresh build, not remembered. The [Convergence Model](/learn/concepts/convergence) describes why vault content is structured for token selection — this pipeline is where that structure pays off on the web side. Every concept, tutorial, and pattern page on adna.network passed through these four stages.
## Related
- [Content Mapping](/how/publishing/content-mapping) — how vault entities map to site sections
- [Social Sharing](/how/publishing/social-sharing) — OG images and social preview configuration
- [The Knowledge Graph](/learn/concepts/knowledge-graph) — the interconnected content this pipeline publishes
- [AGENTS.md Routing](/patterns/agents-md) — the vault-side routing that parallels site navigation
---
## https://adna.network/how/workshops/
# Workshops
Workshop kits for teaching aDNA at different proficiency levels. Each kit includes goals, a timed agenda, exercises, facilitator notes, and assessment criteria. Start with Vault Exploration for beginners or jump to Lattice Design for advanced practitioners.
[Vault Exploration A 60-minute guided tour of a living aDNA vault. Participants don't build anything — they navigate, observe, and discover how a knowledge architecture…](/how/workshops/vault-exploration)[Build Your First Vault A 90-minute hands-on workshop where participants fork the aDNA template, customize it for their own project, and leave with a working vault. By the…](/how/workshops/build-your-first-vault)[Lattice Design A 120-minute deep workshop where participants design, validate, and compose lattice YAML files. Lattices are the executable layer of aDNA — directed…](/how/workshops/lattice-design)[Facilitation Guide A meta-guide for anyone running an aDNA workshop. This document covers logistics, audience assessment, pacing strategies, and common pitfalls…](/how/workshops/facilitation-guide)
---
## https://adna.network/how/workshops/build-your-first-vault/
# Build Your First Vault — aDNA Workshops
A 90-minute hands-on workshop where participants fork the aDNA template, customize it for their own project, and leave with a working vault. By the end, an AI agent can be dropped into their project cold and orient itself.
## Workshop Goals
By the end of this workshop, participants will have:
1. A forked aDNA vault customized for their project domain
2. A working CLAUDE.md with project-specific rules, personality, and structure
3. One custom ontology extension (a new entity type specific to their domain)
4. A mission file decomposing their first real task into objectives
## Pre-Work
Complete before arriving (45 minutes total):
- [Create Your First CLAUDE.md](/learn/tutorials/first-claude-md) (20 min) — understand governance file structure
- [Extend the Ontology](/learn/tutorials/extend-the-ontology) (25 min) — learn how to add custom entity types
## Agenda
| Time | Activity | Description |
|------|----------|-------------|
| 0:00 | Welcome & Context | Why build a vault? Brief recap of the triad. Show aDNA.aDNA as the reference implementation. |
| 0:10 | Exercise 1: Fork | Clone the aDNA template, run the fork skill, choose a project name. Verify the triad directories exist. |
| 0:25 | Exercise 2: CLAUDE.md | Write a CLAUDE.md for your project. Define: identity, safety rules, standing orders, domain knowledge. Test it — can an agent orient from cold? |
| 0:45 | Exercise 3: Extend the Ontology | Identify one entity type unique to your domain. Create the directory, AGENTS.md, and template. Add it to your MANIFEST.md. |
| 1:05 | Exercise 4: First Mission | Pick a real task from your project. Decompose it into a mission with 3-5 objectives. Write the mission file. |
| 1:20 | Show & Tell | 2-3 volunteers share their vault. Group discusses: what worked? What was hard? |
| 1:25 | Wrap-up | Next steps, resources, workshop_lattice_design preview. |
## Facilitator Notes
- **Use aDNA.aDNA as the worked example.** When explaining each step, show how this vault did it. The CLAUDE.md participants are writing mirrors the one in `aDNA.aDNA/CLAUDE.md`. The ontology extension mirrors the 11 extensions in `MANIFEST.md`. This is the [Dual Audience](/learn/concepts/dual-audience) principle in action: teach by showing, not telling.
- **CLAUDE.md is the hardest exercise.** Participants struggle with what to include. Suggest they start with three questions: What is this project? What rules must agents follow? What does the domain look like? The rest fills itself in.
- **Domain diversity is an asset.** Participants will have wildly different projects — a biotech lab, a marketing team, a solo developer. This is a feature, not a bug. Different domains produce different ontology extensions, which demonstrates that aDNA adapts rather than prescribes.
- **Timebox exercise 2.** CLAUDE.md can absorb unlimited time. Set a hard 20-minute limit and tell participants they can refine later.
## Materials / Prerequisites
- **Required**: Git, Obsidian, a code editor, the aDNA template repo cloned (`github.com/aDNA-Network/aDNA`)
- **Optional**: Claude Code for live agent testing during exercise 2
- **Handout**: One-page CLAUDE.md template with section prompts (Identity, Safety, Standing Orders, Domain Knowledge)
## Exercises
### Exercise 1: Fork the Template
**Instructions**: Clone the aDNA template and create your project:
```bash
git clone https://github.com/aDNA-Network/aDNA.git
cp -r aDNA/.adna/ my_project.aDNA/
cd my_project.aDNA
```
Open in Obsidian. Verify you see `who/`, `what/`, `how/` directories.
**Expected outcome**: A fresh vault with the base triad structure, governance files, and templates ready for customization.
### Exercise 2: Write Your CLAUDE.md
**Instructions**: Open `CLAUDE.md` and replace the template content with your project. Address these sections:
1. **Identity** — What is this project? What personality should agents adopt?
2. **Safety Rules** — What must agents never do? What requires confirmation?
3. **Standing Orders** — Rules that apply to every session
4. **Domain Knowledge** — Key concepts, entity types, vocabulary specific to your project
**Test**: If available, start Claude Code in your vault directory. Can it describe what the project is? Can it find files? Does it follow your rules?
**Expected outcome**: An agent dropped into this vault cold can orient and begin useful work within 30 seconds.
### Exercise 3: Extend the Ontology
**Instructions**: Identify one entity type unique to your domain. Examples: `experiment` (research lab), `campaign` (marketing team), `model_card` (ML team), `protocol` (biotech lab).
1. Create the directory under the appropriate triad leg (most domain entities go in `what/`)
2. Write an `AGENTS.md` with: What's Here, Working Rules, Load/Skip Decision
3. Create a template in `how/templates/` named `template_{your_type}.md`
4. Add the new type to your MANIFEST.md ontology table
**Expected outcome**: A new entity type with directory, routing, and template — ready for content.
### Exercise 4: First Mission
**Instructions**: Pick a real task from your project that's too big for one session. Decompose it:
1. Write a mission brief (1-2 sentences: what and why)
2. Define 3-5 objectives (each completable in one session)
3. Identify dependencies between objectives
4. Save as `how/missions/mission_{name}.md`
**Expected outcome**: A structured mission file that could be handed to any agent or team member.
## Assessment / Feedback
**Exit questions**:
1. Does your vault have a working CLAUDE.md, one ontology extension, and one mission?
2. Could an agent orient itself in your vault without additional instructions?
3. What's one thing you'd change about how you currently organize project knowledge?
**Success signal**: Participants leave with a vault they'll actually use next week.
## Self-Reference
This workshop follows the exact process that created aDNA.aDNA itself. Phase 0 (M00) of [[campaign_rosetta|Operation Rosetta]] forked the template, customized governance, and extended the ontology with 10 new entity types — the same steps participants complete in exercises 1-3. The mission file participants write in exercise 4 mirrors the 24 mission files in `how/campaigns/campaign_rosetta/missions/`.
## Related
- [Vault Exploration](/how/workshops/vault-exploration) — prerequisite workshop
- [Lattice Design](/how/workshops/lattice-design) — next workshop in the series
- [Facilitation Guide](/how/workshops/facilitation-guide) — meta-guide for running any aDNA workshop
- [Governance Files](/learn/concepts/governance-files) — the concept behind exercise 2
- [Mission Decomposition](/patterns/mission-decomposition) — the pattern behind exercise 4
---
## https://adna.network/how/workshops/facilitation-guide/
# Facilitation Guide — aDNA Workshops
A meta-guide for anyone running an aDNA workshop. This document covers logistics, audience assessment, pacing strategies, and common pitfalls — everything a facilitator needs beyond the workshop-specific agenda. It works alongside the three workshop kits but is also useful for designing custom workshops.
## Before the Workshop
### Audience Assessment
aDNA workshops typically draw mixed audiences. Before the session, survey participants on:
1. **Technical level** — Can they read YAML? Have they used a CLI? Do they write code daily?
2. **AI experience** — Have they used AI coding assistants? Do they know what "context window" means?
3. **Knowledge management background** — Do they currently use Notion, Obsidian, PARA, or similar systems?
Use the answers to choose the right workshop:
| Profile | Recommended Workshop |
|---------|---------------------|
| Non-technical, curious about aDNA | [Vault Exploration](/how/workshops/vault-exploration) (beginner, 60 min) |
| Developer, new to aDNA | [Build Your First Vault](/how/workshops/build-your-first-vault) (intermediate, 90 min) |
| Developer, building with lattices | [Lattice Design](/how/workshops/lattice-design) (advanced, 120 min) |
| Mixed audience | Vault Exploration (everyone) → split into tracks |
### Room Setup
- **Projector**: Required for facilitator screen share. Show Obsidian graph view at the start — it's the best visual hook.
- **Internet**: Required for cloning repos (exercise setup). Not required during exercises.
- **Seating**: Small tables of 3-4 work best. Exercise 4 in Lattice Design requires pair work.
- **Whiteboard**: Required for Lattice Design (exercise 1: sketch). Useful for all workshops.
### Pre-Installation
The biggest time sink is software installation. Send setup instructions 48 hours before:
1. **Obsidian** — obsidian.md (free, all platforms)
2. **Git** — for cloning the vault
3. **Python 3.9+** — only for Lattice Design workshop (validation tools)
4. **Claude Code or similar** — optional for Build Your First Vault (live testing)
Provide a troubleshooting contact for installation issues. Budget 5-10 minutes at workshop start for stragglers.
## During the Workshop
### Pacing
| Workshop | Tight Spots | Where to Flex |
|----------|------------|---------------|
| Vault Exploration | Exercise 3 (Question Test) — participants debate edge cases | Debrief — can expand or contract based on energy |
| Build Your First Vault | Exercise 2 (CLAUDE.md) — can absorb unlimited time | Show & Tell — cut to 1 volunteer if behind |
| Lattice Design | Exercise 2 (Build YAML) — debugging syntax | Exercise 4 (Compose) — make optional if behind |
**General pacing rules:**
- Start exercises on time even if the preceding lecture ran long
- Give a 2-minute warning before each exercise ends
- If an exercise runs long, cut the next lecture, not the next exercise
- End on time. Facilitator credibility depends on respecting the schedule.
### Mixed-Audience Management
The [Dual Audience](/learn/concepts/dual-audience) principle applies to workshops, not just documentation:
- **When a developer asks a technical question**: Answer briefly, then translate for the room. "The AGENTS.md file is like a README for AI — it tells the agent what's in this folder and whether to load it."
- **When a non-developer is lost**: Point them to the conceptual layer. "Don't worry about the YAML syntax. Focus on the boxes and arrows — that's the workflow."
- **Pair developers with non-developers** in exercises. The developer handles syntax; the non-developer asks "but what does this step actually do?" Both learn more.
### Common Questions
| Question | Answer |
|----------|--------|
| "Do I need Obsidian?" | No — any Markdown editor works. Obsidian is recommended because its graph view and wikilinks make the vault's structure visible. |
| "How is this different from just using folders?" | Folders organize files. aDNA adds governance (CLAUDE.md tells agents the rules), routing (AGENTS.md helps agents navigate), and interoperability (lattice YAML makes workflows composable). See [aDNA vs. Plain Markdown](/learn/comparisons/adna-vs-plain-markdown). |
| "Can I use this without AI?" | Yes. The triad, Question Test, and mission decomposition are useful organizational patterns for humans. AI agents benefit from the governance layer, but the architecture stands on its own. |
| "What's the learning curve?" | Start with the triad (5 minutes to understand). Write a CLAUDE.md (20 minutes). Add domain-specific content over time. Most teams are productive within a day. |
## After the Workshop
### Follow-Up
Send within 24 hours:
1. **Resource links** — aDNA specification, tutorial index, this vault's live site
2. **Feedback survey** — 3 questions: What worked? What didn't? What would you add?
3. **Community invitation** — link to aDNA community channels for ongoing support
### Measuring Success
| Signal | How to Measure |
|--------|---------------|
| Participants use their vault next week | Follow-up survey at day 7 |
| Participants can explain the triad | Exit question (show of hands) |
| Workshop generates community contribution | Count new community members or GitHub issues within 30 days |
## Self-Reference
This facilitation guide follows the same [Dual-Audience Writing](/patterns/dual-audience-writing) pattern it teaches facilitators to apply. The audience assessment table uses the same progressive disclosure structure as the vault's own entry points in MANIFEST.md. The common questions section addresses the same objections that the [comparison files](/learn/comparisons/adna-vs-plain-markdown) address in long form.
## Related
- [Vault Exploration](/how/workshops/vault-exploration) — beginner workshop (60 min)
- [Build Your First Vault](/how/workshops/build-your-first-vault) — intermediate workshop (90 min)
- [Lattice Design](/how/workshops/lattice-design) — advanced workshop (120 min)
- [Dual Audience](/learn/concepts/dual-audience) — the principle that guides mixed-audience facilitation
- [Agentic Literacy](/learn/concepts/agentic-literacy) — the broader goal these workshops serve
---
## https://adna.network/how/workshops/lattice-design/
# Lattice Design — aDNA Workshops
A 120-minute deep workshop where participants design, validate, and compose lattice YAML files. Lattices are the executable layer of aDNA — directed graphs of nodes and edges that represent workflows, agent reasoning chains, or knowledge structures. Participants leave with a validated lattice ready for their domain.
## Workshop Goals
By the end of this workshop, participants will be able to:
1. Model a real workflow as a lattice (nodes, edges, execution mode)
2. Choose the correct lattice type and execution mode for their use case
3. Add FAIR metadata for findability, accessibility, interoperability, and reuse
4. Validate a lattice against the JSON Schema using `lattice_validate.py`
5. Understand lattice composition (combining two lattices with seam edges)
## Pre-Work
Complete before arriving (30 minutes):
- [Build a Lattice](/learn/tutorials/build-a-lattice) (30 min) — end-to-end lattice construction tutorial
## Agenda
| Time | Activity | Description |
|------|----------|-------------|
| 0:00 | Welcome & Orientation | What are lattices? Show `what/lattices/examples/hello_world.lattice.yaml` as the minimal example. |
| 0:10 | Lattice Anatomy | Walk through a real lattice: metadata, nodes, edges, FAIR block. Show each field's purpose. |
| 0:25 | Exercise 1: Sketch | Whiteboard a workflow from your domain. Identify nodes (steps) and edges (data flows). Mark decision points. |
| 0:40 | Types & Modes | 6 lattice types (pipeline, agent, context_graph, workflow, infrastructure, skill) and 3 execution modes (workflow, reasoning, hybrid). When to use each. |
| 0:50 | Exercise 2: Build | Translate your whiteboard sketch into YAML. Choose type and execution mode. Define nodes and edges. |
| 1:10 | FAIR Metadata | Why FAIR matters for lattice sharing. Required fields: license, creators, keywords. Optional: identifier (DOI), provenance. |
| 1:20 | Exercise 3: Validate | Install dependencies (`pip install pyyaml`). Run `lattice_validate.py` on your lattice. Fix any schema errors. |
| 1:35 | Composition | How two lattices combine: external (seam edges between separate graphs) vs inline (merge child into parent). Show `composed_therapeutics.lattice.yaml` as a real example. |
| 1:45 | Exercise 4: Compose | Pair up. Combine your lattice with a partner's using external composition. Define seam edges. Validate the result. |
| 1:55 | Gallery Walk & Wrap-up | Display lattices. Discuss: what patterns emerged? What was hardest? |
## Facilitator Notes
- **Start concrete.** The `hello_world.lattice.yaml` is 30 lines. Show it before explaining any theory. Let participants see the shape before learning the vocabulary.
- **Whiteboard before YAML.** Exercise 1 (sketch) is the most important exercise. If participants skip it, they get lost in YAML syntax instead of thinking about structure. Enforce the sketch step.
- **Type selection anxiety.** Participants agonize over choosing the right lattice type. Reassure them: `pipeline` (deterministic DAG) covers 70% of use cases. Use `agent` only for LLM-driven reasoning, `context_graph` for knowledge structures. If in doubt, `workflow` is the safe default.
- **Validation is the payoff.** When `lattice_validate.py` passes, participants feel their lattice is real. When it fails, the error messages teach schema awareness. Either outcome is a win.
- **Composition is advanced.** If time is tight, make exercise 4 optional. The concept matters more than the hands-on practice — most participants won't need composition in their first lattice.
## Materials / Prerequisites
- **Required**: Code editor, Python 3.9+, `pyyaml` package, the `what/lattices/` directory from aDNA.aDNA
- **Optional**: Whiteboard or paper for exercise 1, projector for facilitator
- **Reference**: `what/lattices/lattice_yaml_schema.json` (the authoritative schema)
- **Example set**: 19 example `.lattice.yaml` files in `what/lattices/examples/` covering pipeline, agent, context_graph, and workflow types
## Exercises
### Exercise 1: Sketch Your Workflow
**Instructions**: On paper or whiteboard, draw a workflow from your domain:
1. List the steps as boxes (these become nodes)
2. Draw arrows showing data flow (these become edges)
3. Mark any decision points where an LLM or human chooses the next step
4. Label each arrow with what data flows along it
**Expected outcome**: A visual graph with 4-8 nodes and clear data flow. Decision points help determine execution mode.
### Exercise 2: Build the YAML
**Instructions**: Create a file named `my_workflow.lattice.yaml`. Translate your sketch:
```yaml
name: my_workflow
version: "0.1.0"
lattice_type: pipeline # or workflow, agent, context_graph
execution_mode: workflow # or reasoning, hybrid
description: "One sentence describing your workflow"
nodes:
- id: step_one
type: process
label: "First Step"
description: "What this step does"
edges:
- source: step_one
target: step_two
label: "data_output"
```
Fill in your nodes and edges from the sketch. Choose your lattice type based on:
- No decision points → `pipeline` + `workflow`
- All LLM decisions → `agent` + `reasoning`
- Mix of fixed steps and LLM decisions → `workflow` + `hybrid`
**Expected outcome**: A syntactically valid YAML file with 4-8 nodes and connecting edges.
### Exercise 3: Validate
**Instructions**: From the `what/lattices/tools/` directory:
```bash
pip install pyyaml
python lattice_validate.py ../my_workflow.lattice.yaml
```
If validation fails, read the error message. Common fixes:
- Missing required field → add it
- Unknown lattice_type → check the 6 valid types
- Edge references non-existent node → fix the node ID
Add a FAIR block:
```yaml
fair:
license: MIT
creators: ["Your Name"]
keywords: ["your-domain", "workflow"]
```
Re-validate.
**Expected outcome**: `VALID` output from the validator with FAIR metadata complete.
### Exercise 4: Compose (Pairs)
**Instructions**: Partner with another participant. Combine your two lattices:
1. Identify a connection point — an output from one lattice that feeds into the other
2. Create seam edges connecting the two graphs
3. Use external composition (keep both lattices separate, linked by seam edges)
Reference: `what/lattices/examples/composed_therapeutics.lattice.yaml` shows a real composition of three sub-lattices.
**Expected outcome**: Understanding that lattices are composable — small graphs combine into larger workflows.
## Assessment / Feedback
**Exit questions**:
1. Could you explain the difference between a pipeline and an agent lattice?
2. Is your lattice valid against the schema?
3. What FAIR metadata did you add and why?
**Success signal**: Every participant leaves with a validated `.lattice.yaml` specific to their domain.
## Self-Reference
The [Lattice Composition](/learn/concepts/lattice-composition) concept and the 19 example `.lattice.yaml` files in `what/lattices/examples/` were built during earlier phases of Operation Rosetta. This workshop uses them as exercise materials — participants study `hello_world.lattice.yaml` and `composed_therapeutics.lattice.yaml` to learn the same patterns the vault itself implements. The validation tool (`lattice_validate.py`) that participants run is the same tool this project uses to check its own lattice examples.
## Related
- [Build Your First Vault](/how/workshops/build-your-first-vault) — prerequisite workshop
- [Facilitation Guide](/how/workshops/facilitation-guide) — meta-guide for running any aDNA workshop
- [Lattice Composition](/learn/concepts/lattice-composition) — the concept this workshop teaches
- [FAIR Metadata](/learn/concepts/fair-metadata) — the metadata standard participants apply
- [FAIR Envelope](/patterns/fair-envelope) — the pattern for FAIR-annotated objects
---
## https://adna.network/how/workshops/vault-exploration/
# Vault Exploration — aDNA Workshops
A 60-minute guided tour of a living aDNA vault. Participants don't build anything — they navigate, observe, and discover how a knowledge architecture works by walking through one. The vault you're exploring IS the teaching material.
## Workshop Goals
By the end of this workshop, participants will be able to:
1. Explain the three legs of the aDNA triad (Who, What, How) and what goes where
2. Navigate an aDNA vault using AGENTS.md routing files
3. Apply the Question Test to sort new content into the correct triad leg
4. Identify governance files (CLAUDE.md, MANIFEST.md, STATE.md) and explain their roles
## Pre-Work
Complete before arriving (30 minutes total):
- [Navigate an aDNA Vault](/learn/tutorials/navigate-a-vault) (15 min) — guided tour of vault structure
- [Apply the Question Test](/learn/tutorials/question-test) (15 min) — sorting rule for the triad
## Agenda
| Time | Activity | Description |
|------|----------|-------------|
| 0:00 | Welcome & Setup | Confirm Obsidian is installed, vault is open. Show graph view. |
| 0:05 | The Big Picture | What is aDNA? Why does knowledge architecture matter for AI? Show the triad: Who, What, How. |
| 0:15 | Exercise 1: Triad Walk | Navigate each triad leg. Open 1 file per leg. Note the naming pattern. |
| 0:25 | Exercise 2: AGENTS.md Chain | Start at root CLAUDE.md, follow AGENTS.md breadcrumbs into `what/concepts/`. Observe load/skip decisions. |
| 0:35 | Exercise 3: Question Test | Given 5 sample items (a tutorial, a governance doc, a dataset spec, a session log, a glossary entry), sort each into the correct triad leg using the Question Test. |
| 0:45 | Exercise 4: Governance Trio | Open CLAUDE.md, MANIFEST.md, and STATE.md. Compare: what does each file do? How do they differ? |
| 0:52 | Debrief & Questions | What surprised you? What would you organize differently? How does this compare to your current approach? |
## Facilitator Notes
- **Graph view is the hook.** Open Obsidian's graph view first — the visual network creates immediate curiosity. Let participants explore freely for 30 seconds before explaining anything.
- **Self-reference is the lesson.** Remind participants regularly: "You are inside the thing being described." When they read about governance files, they're reading a governance file. This is the core aDNA insight.
- **Mixed audiences.** Developers will want to see YAML frontmatter and file naming patterns. Non-developers will focus on the conceptual organization. Both are valid entry points — acknowledge both.
- **Don't over-teach.** This workshop is exploration, not instruction. Resist the urge to explain every concept. Let discovery drive engagement.
## Materials / Prerequisites
- **Required**: Obsidian (any OS), `aDNA.aDNA/` vault cloned and opened as an Obsidian vault
- **Optional**: Projector for facilitator screen share
- **Handout**: Printed triad diagram (Who/What/How with example entities under each leg)
## Exercises
### Exercise 1: Triad Walk
**Instructions**: Open the vault in Obsidian's file explorer. Navigate into each triad directory (`who/`, `what/`, `how/`). Open one file from each. Write down: what kind of content lives here?
**Expected outcome**: Participants can articulate that `who/` contains people and governance, `what/` contains knowledge and concepts, `how/` contains operations and procedures.
### Exercise 2: AGENTS.md Chain
**Instructions**: Open `CLAUDE.md` at the vault root. Find the project map. Navigate to `what/concepts/AGENTS.md`. Read the "Load/Skip Decision" section. Now navigate to `what/tutorials/AGENTS.md`. Compare the two.
**Expected outcome**: Participants understand that AGENTS.md files are routing guides — they tell agents (and humans) when to load a directory and what's inside.
### Exercise 3: Question Test
**Instructions**: For each item below, decide which triad leg it belongs to by asking the [Question Test](/patterns/question-test):
1. "A step-by-step guide to writing context files" → _____
2. "The team's communication preferences" → _____
3. "A definition of what lattice composition means" → _____
4. "A session tracking log from yesterday" → _____
5. "A community contributor role description" → _____
**Answers**: 1. How (tutorial), 2. Who (coordination), 3. What (concept), 4. How (session), 5. Who (community)
### Exercise 4: Governance Trio
**Instructions**: Open `CLAUDE.md`, `MANIFEST.md`, and `STATE.md` side by side. For each file, write one sentence describing its purpose.
**Expected outcome**: CLAUDE.md = agent instructions (who am I, what are the rules). MANIFEST.md = project overview (what's here, how it's organized). STATE.md = operational snapshot (what's happening now, what's next).
## Assessment / Feedback
**Exit questions** (show of hands or brief written response):
1. Could you explain the triad to someone who wasn't here today?
2. If you had a new piece of content, do you know which directory it goes in?
3. What's one thing about aDNA that surprised you?
**Success signal**: Participants can sort a novel content item into the correct triad leg without assistance.
## Self-Reference
This workshop uses aDNA.aDNA as its teaching environment — a vault that teaches aDNA by being aDNA. Every exercise points at real files in this vault. The Question Test exercise sorts content that actually exists here. The governance trio exercise reads the governance files that govern this project. The structure IS the lesson.
## Related
- [Build Your First Vault](/how/workshops/build-your-first-vault) — next workshop in the series
- [Facilitation Guide](/how/workshops/facilitation-guide) — meta-guide for running any aDNA workshop
- [The Triad](/learn/concepts/triad) — the concept this workshop teaches
- [The Question Test](/patterns/question-test) — the sorting pattern participants practice
---
## https://adna.network/learn/
*[image: Cozy pixel-art study desk with books, a notebook, and a glowing DNA helix rising from the page — learning aDNA]*
# Learn aDNA
New to aDNA? Work through this path top to bottom, or jump straight to the step you need — each one links to the next.
## Start here
Read the overview first. It explains what aDNA is and why it exists in about five minutes — the one page to read if you read nothing else.
[What is aDNA? The 5-minute overview — the problem, the approach, and what a project looks like. Read this first.](/learn/what-is-adna)[Get started Ready to build one? Stand up your first vault in under an hour.](/get-started)
## 1 · Understand the ideas
Once the overview clicks, these are the concepts everything else builds on. Start with the Triad, then branch out.
[The Triad what / how / who — the three-way split every aDNA vault is built on. Start here.](/learn/concepts/triad)[Governance Files CLAUDE.md, AGENTS.md, STATE.md — the fixed-path files an agent reads first.](/learn/concepts/governance-files)[The Ontology The 16 entity types that give every piece of knowledge a home.](/learn/concepts/ontology)[All 13 concepts The Triad through FAIR metadata — the full concept library.](/learn/concepts)
## 2 · Take the intro course
Brand new to all of this? The course runs from “what is this folder” to running your first session, in short lessons that each end in something you do. Your progress is remembered in this browser.
[Intro to your new aDNA graph An interactive course — no prior knowledge assumed.](/learn/course)
## 3 · Practice with a tutorial
Learn by doing. The tutorials run from your first CLAUDE.md to federating a vault — beginner to advanced.
[Create your first CLAUDE.md The best place to start building — a governed file in about ten minutes.](/learn/tutorials/first-claude-md)[All 9 tutorials Step-by-step, beginner to advanced.](/learn/tutorials)
## 4 · Compare to what you know
Already use PARA, Zettelkasten, or Notion? See where aDNA agrees, where it differs, and when to reach for it.
[aDNA vs. the alternatives Honest comparisons with PARA, Zettelkasten, Notion, Johnny.Decimal, and plain markdown.](/learn/comparisons)[aDNA vs. plain Markdown The closest baseline — what the structure buys you over a folder of notes.](/learn/comparisons/adna-vs-plain-markdown)
## Where to next
Past the basics? Branch by what you need.
[Patterns Reusable moves — the Question Test, AGENTS.md routing, dual-audience writing.](/patterns)[Reference The normative spec, governance model, and quality rubric.](/reference)[Use Cases How solo devs, startups, labs, and enterprises put aDNA to work.](/use-cases)[Community Roles, contribution paths, and the Context Commons.](/community)
---
## https://adna.network/learn/comparisons/
# Comparisons
Honest comparisons between aDNA and other knowledge architectures. Every system has strengths — these pages help you understand when aDNA is the right fit.
[aDNA vs. PARA Two systems for organizing knowledge — one designed for personal productivity, the other for AI-native project collaboration.](/learn/comparisons/adna-vs-para)[aDNA vs. Zettelkasten Two knowledge systems built on connected notes — one optimized for human creative thinking, the other for human-agent collaborative projects.](/learn/comparisons/adna-vs-zettelkasten)[aDNA vs. Notion A standard for AI-native knowledge architecture vs. a SaaS platform for team collaboration — different layers, different trade-offs.](/learn/comparisons/adna-vs-notion)[aDNA vs. Johnny.Decimal Two systems for organizing files — one uses a universal numbering scheme, the other uses a typed triad with agent governance.](/learn/comparisons/adna-vs-johnny-decimal)[aDNA vs. Plain Markdown The most common question: "Why not just use a folder of markdown files?"](/learn/comparisons/adna-vs-plain-markdown)
---
## https://adna.network/learn/comparisons/adna-vs-johnny-decimal/
# aDNA vs. Johnny.Decimal — aDNA Comparisons
Two systems for organizing files — one uses a universal numbering scheme, the other uses a typed triad with agent governance.
## Overview
### aDNA
A knowledge architecture standard (§1) that sorts content into three directories (`what/`, `how/`, `who/`) using the [question test](/learn/concepts/triad). Within each leg, typed entity directories (concepts, missions, sessions, etc.) provide further structure. Navigation is governed by AGENTS.md files and typed frontmatter. Designed for AI-agent collaboration on projects.
### Johnny.Decimal
A file organization system by Johnny Noble that assigns every file a unique number in a two-level hierarchy: 10 areas (10-19, 20-29, etc.) containing categories (11, 12, 13, etc.). Each item gets an ID like `23.04` (area 20-29, category 23, item 04). The numbering is the navigation — you find things by number, not by browsing directories. Designed for individuals and small teams managing digital files.
## Comparison
| Dimension | aDNA | Johnny.Decimal |
|-----------|------|---------------|
| **Organizing principle** | 3 triad legs by question type | 10 numbered areas, unlimited categories |
| **Navigation** | Directory names + AGENTS.md routing | Numbers: find `23.04` by its ID |
| **Agent support** | Native: governance files, convergence model, typed entities | None: numbering aids humans, not agents |
| **Flexibility** | Fixed triad + extensible entity types | Flexible: you define your own areas and categories |
| **Scale limit** | Unlimited: federated across instances | 10 areas × 10 categories = 100 categories max |
| **Semantic meaning** | Directory names describe content (e.g., `what/concepts/`) | Numbers are opaque — you need the index to know what `23` means |
| **Learning curve** | Moderate: spec, frontmatter, governance | Low: learn the numbering convention, apply it |
| **Multi-project** | Each project is an aDNA instance | Each project gets its own number space |
## Where aDNA Excels
- **Semantic navigation**: Directory names tell you what's inside. `what/concepts/` is self-describing. `23.04` requires an index lookup.
- **Agent routing**: [AGENTS.md](/patterns/agents-md) at each directory tells agents whether to load or skip. Johnny.Decimal numbers mean nothing to an agent.
- **Typed knowledge**: aDNA entities have schemas, frontmatter, and typed I/O. Johnny.Decimal files are untyped.
- **Federation**: aDNA objects can be shared across projects with FAIR metadata and `lattice://` URIs. Johnny.Decimal numbers are local.
- **No category ceiling**: aDNA can add unlimited entity types via the [base/extension](/patterns/base-extension) pattern. Johnny.Decimal is capped at 100 categories.
## Where Johnny.Decimal Excels
- **Universal applicability**: Works for any files — tax documents, project assets, recipes, music. aDNA is purpose-built for knowledge projects.
- **Instant lookup**: Know the ID, find the file. `32.07` is unambiguous. aDNA requires navigating directory paths.
- **Dead-simple rules**: "10 areas, 10 categories per area, sequential numbering." The system fits on an index card.
- **Tool-agnostic**: Works in any filesystem, any OS, any app. No frontmatter, no governance files, no agent tooling required.
- **No overhead**: Create a folder, assign a number. No AGENTS.md, no templates, no session files.
- **Physical+digital parity**: Johnny.Decimal works for physical filing cabinets too. aDNA is digital-only.
## When to Choose Which
| If you need... | Choose |
|---------------|--------|
| A system for organizing diverse personal/business files | Johnny.Decimal |
| A knowledge architecture for AI-agent projects | aDNA |
| Instant lookup by ID across all your files | Johnny.Decimal |
| Typed, governed, machine-queryable knowledge | aDNA |
| Something you can explain in 2 minutes | Johnny.Decimal |
| Multi-agent collaboration with federation | aDNA |
| Physical + digital file organization | Johnny.Decimal |
| Operational infrastructure (sessions, missions, campaigns) | aDNA |
These serve genuinely different purposes. Johnny.Decimal organizes files; aDNA organizes knowledge for agent collaboration. A user might apply Johnny.Decimal to their personal filing while using aDNA for project knowledge.
## Sources
- johnnydecimal.com — Johnny.Decimal system documentation
- Johnny Noble, "A system to organise your life" — method introduction
- aDNA Standard v2.5, §3 (Triad Architecture), §4.5 (AGENTS.md) — aDNA specification
## Related
- [The Triad](/learn/concepts/triad) — aDNA's three-category principle (vs. Johnny.Decimal's numbered areas)
- [Question Test](/patterns/question-test) — how aDNA sorts content (vs. Johnny.Decimal's numbering assignment)
- [Ontology](/learn/concepts/ontology) — the typed entity system that gives aDNA directories semantic meaning
---
## https://adna.network/learn/comparisons/adna-vs-notion/
# aDNA vs. Notion — aDNA Comparisons
A standard for AI-native knowledge architecture vs. a SaaS platform for team collaboration — different layers, different trade-offs.
## Overview
### aDNA
An open standard (§1) defining how project knowledge should be structured for human and AI-agent collaboration. Files live on disk (or in git), organized by the what/how/who triad. Governance is embedded in the project via CLAUDE.md, AGENTS.md, and typed frontmatter. The standard is tool-agnostic but works best with Obsidian and Claude Code.
### Notion
A SaaS collaboration platform that combines wikis, databases, documents, and project management in a single cloud workspace. Rich block-based editor, flexible database views, real-time collaboration, integrations ecosystem. Knowledge lives in Notion's cloud, accessed via browser or app.
## Comparison
| Dimension | aDNA | Notion |
|-----------|------|--------|
| **Architecture** | Open standard + local files (git-backed) | Proprietary platform (cloud-hosted) |
| **Agent support** | Native: governance files, AGENTS.md routing, convergence model | Emerging: Notion AI assistant, but no agent-oriented governance layer |
| **Collaboration** | Git-based: sessions, coordination notes, conflict detection | Real-time: simultaneous editing, comments, @mentions |
| **Data ownership** | Full: files on your disk, version-controlled in git | Platform-dependent: data lives in Notion's cloud |
| **Structure** | Prescribed: triad, typed entities, frontmatter schema | Flexible: any structure, databases with custom properties |
| **Extensibility** | [Base/extension](/patterns/base-extension) with typed entity system | Custom databases, formulas, integrations |
| **Learning curve** | Moderate: spec, governance, templates | Low-to-moderate: intuitive editor, database setup takes time |
| **Federation** | Native: `lattice://` URIs, 5-capability lifecycle | None: sharing = duplicate or link between Notion workspaces |
| **Offline** | Full offline support (local files) | Limited offline support |
| **Visual editing** | Markdown + Obsidian canvas | Rich block editor with embeds, databases, galleries |
## Where aDNA Excels
- **Agent-first architecture**: aDNA's governance files, AGENTS.md routing, and [convergence model](/learn/concepts/convergence) were designed for AI agents to navigate systematically. Notion AI is a feature; aDNA is an architecture.
- **Data sovereignty**: aDNA files are local, git-versioned, and portable. No vendor dependency for access to your own knowledge.
- **Federation**: aDNA lattices can be shared and composed across instances using a defined protocol. Notion workspaces are isolated silos.
- **Typed knowledge**: aDNA's entity types and [FAIR metadata](/learn/concepts/fair-metadata) make knowledge machine-queryable and standards-compliant. Notion databases are flexible but project-specific.
- **Open standard**: Anyone can build tools for aDNA. Notion's ecosystem depends on Notion's API and platform decisions.
## Where Notion Excels
- **Real-time collaboration**: Multiple people editing simultaneously with visual presence indicators. aDNA uses git — async by nature, conflicts possible.
- **Visual richness**: Block editor, database views (table, board, calendar, gallery, timeline), embedded media. aDNA is markdown files.
- **Low barrier to entry**: No spec to learn, no frontmatter schema, no governance files. Create a page and start typing.
- **Built-in project management**: Kanban boards, sprint tracking, calendars, formulas — all in one tool. aDNA's operational layer (missions, sessions) is lighter-weight.
- **Integrations ecosystem**: Slack, GitHub, Figma, Google Drive, and hundreds more. aDNA integrates through git and Claude Code.
- **Non-technical accessibility**: Anyone can use Notion's GUI. aDNA requires comfort with files, folders, and markdown.
## When to Choose Which
| If you need... | Choose |
|---------------|--------|
| Real-time team wiki with rich editing | Notion |
| AI-agent-navigable knowledge architecture | aDNA |
| Quick setup with no learning curve | Notion |
| Data sovereignty and git version control | aDNA |
| Visual project management (boards, timelines) | Notion |
| Typed, federable, standards-compliant knowledge objects | aDNA |
| Non-technical team members editing content | Notion |
| Multi-agent project execution with governance | aDNA |
Some teams use both: Notion for real-time collaboration and project management, aDNA for the AI-agent knowledge layer that powers deeper work.
## Sources
- notion.so/product — Notion platform documentation
- Notion AI documentation — notion.so/product/ai
- aDNA Standard v2.5, §1 (Introduction), §3 (Triad), §11 (Federation) — aDNA specification
## Related
- [Open Standard](/learn/concepts/open-standard) — why aDNA is a standard rather than a platform (contrast with Notion's approach)
- [Governance Files](/learn/concepts/governance-files) — aDNA's agent-orientation layer that Notion lacks
- [Context Commons](/learn/concepts/context-commons) — the shared-knowledge vision enabled by federation, impossible with siloed platforms
---
## https://adna.network/learn/comparisons/adna-vs-para/
# aDNA vs. PARA — aDNA Comparisons
Two systems for organizing knowledge — one designed for personal productivity, the other for AI-native project collaboration.
## Overview
### aDNA
A knowledge architecture standard for AI-native projects (§1). Organizes all project knowledge into three directories — `what/`, `how/`, `who/` — determined by the [question test](/learn/concepts/triad). Designed for both human and AI-agent navigation. Includes governance files, session tracking, federation, and FAIR metadata. Open standard with spec, template, and extension system.
### PARA
Tiago Forte's organizational system from *Building a Second Brain*. Organizes personal knowledge into four categories: **P**rojects (active), **A**reas (ongoing responsibilities), **R**esources (reference material), **A**rchives (inactive). Designed for individual knowledge management across tools like Notion, Obsidian, and Evernote.
## Comparison
| Dimension | aDNA | PARA |
|-----------|------|------|
| **Organizing principle** | 3 categories by question type (what/how/who) | 4 categories by actionability (projects/areas/resources/archives) |
| **Primary audience** | Teams + AI agents | Individual humans |
| **Agent support** | Native: CLAUDE.md, AGENTS.md, session tracking, convergence model | None: no agent orientation, no routing, no governance files |
| **Knowledge types** | 16+ entity types with typed frontmatter | Untyped: any note can go anywhere within the 4 buckets |
| **Scalability** | Multi-agent, multi-project, federated | Single-person, cross-tool |
| **Learning curve** | Moderate: spec, templates, governance files | Low: 4 simple categories, minimal rules |
| **Extensibility** | [Base/extension](/patterns/base-extension) architecture with domain types | Flexible but informal: no extension framework |
| **Collaboration** | Built-in: sessions, coordination notes, handoff protocols | Bolted-on: depends on the tool's sharing features |
| **Standards** | Open spec (§1-§13), FAIR metadata, typed I/O | No spec: a method, not a standard |
## Where aDNA Excels
- **Agent collaboration**: PARA has no concept of AI agents navigating knowledge. aDNA's governance files, AGENTS.md routing, and session tracking were built for agent-first operation.
- **Team scale**: PARA is personal. aDNA handles multi-agent coordination, conflict detection, and handoff continuity.
- **Typed knowledge**: aDNA's 16 base entity types and frontmatter conventions make knowledge machine-queryable. PARA notes are freeform.
- **Federation**: aDNA lattices can be shared across instances. PARA has no cross-system sharing protocol.
## Where PARA Excels
- **Simplicity**: Four buckets. No frontmatter. No governance files. You can explain PARA in 5 minutes. aDNA takes longer to learn.
- **Personal fit**: PARA was designed for how individuals think about their own projects and responsibilities. aDNA was designed for projects, not people.
- **Tool agnosticism**: PARA works in any notes app. aDNA works best with AI agents (Claude Code, etc.) and Obsidian — its governance files are meaningless without agent tooling.
- **Low overhead**: No session files, no AGENTS.md, no templates. PARA is lightweight by design.
## When to Choose Which
| If you need... | Choose |
|---------------|--------|
| Personal knowledge management across apps | PARA |
| AI-agent-navigable project knowledge | aDNA |
| A quick organizational system for your notes | PARA |
| Multi-agent collaboration with audit trails | aDNA |
| Minimal overhead, maximum simplicity | PARA |
| Typed, federable, FAIR-annotated knowledge objects | aDNA |
| To organize existing personal notes better | PARA |
| To build a knowledge architecture for a team or project | aDNA |
They're not mutually exclusive. A developer might use PARA for personal notes and aDNA for shared project knowledge.
## Sources
- Tiago Forte, *Building a Second Brain* (2022) — PARA method definition
- Forte Labs: fortelabs.com/blog/para — PARA overview
- aDNA Standard v2.5, §1 (Introduction), §3 (Triad Architecture) — aDNA specification
## Related
- [The Triad](/learn/concepts/triad) — aDNA's three-category organizing principle (compare to PARA's four)
- [Governance Files](/learn/concepts/governance-files) — the agent-orientation layer PARA lacks
- [Agentic Literacy](/learn/concepts/agentic-literacy) — the skill set aDNA develops that PARA doesn't address
---
## https://adna.network/learn/comparisons/adna-vs-plain-markdown/
# aDNA vs. Plain Markdown — aDNA Comparisons
The most common question: "Why not just use a folder of markdown files?"
## Overview
### aDNA
A knowledge architecture standard (§1) that imposes structure on markdown files: the what/how/who triad, typed entities with YAML frontmatter, governance files (CLAUDE.md, AGENTS.md, STATE.md), session tracking, and [convergent narrowing](/learn/concepts/convergence). The files are still markdown — aDNA adds conventions that make them navigable by AI agents.
### Plain Markdown
A folder (or nested folders) of `.md` files with no imposed structure. Files organized however the author sees fit — maybe by topic, by date, by project, or not organized at all. No frontmatter requirements, no governance files, no naming conventions. The simplest possible approach: create a file, write in it.
## Comparison
| Dimension | aDNA | Plain Markdown |
|-----------|------|---------------|
| **Structure** | Prescribed: triad, typed entities, AGENTS.md routing | Ad hoc: whatever the author decides |
| **Agent orientation** | CLAUDE.md + STATE.md = agent knows who it is, what's happening | Agent reads files blindly — no governance, no routing, no context hierarchy |
| **Frontmatter** | Required: type, status, dates, tags, entity-specific fields | Optional: whatever you want, if anything |
| **Naming** | Convention: `type_descriptive_name.md` | Freeform: anything.md |
| **Navigation** | AGENTS.md routing + knowledge graph + convergence model | grep, search, browse |
| **Scalability** | Designed for 500K+ tokens across hundreds of files | Degrades: at 100+ files, finding what you need becomes guesswork |
| **Collaboration** | Sessions, coordination notes, conflict detection | Depends entirely on external tooling (git, Google Docs) |
| **Overhead** | Moderate: governance files, frontmatter, templates | Zero: write and go |
| **Portability** | Fully portable: standard markdown + YAML frontmatter | Fully portable: it's just markdown |
## Where aDNA Excels
- **Agent effectiveness**: Give an AI agent a plain markdown folder and it will produce generic output. Give it an aDNA vault and it produces informed, project-specific work. The difference is [governance files](/learn/concepts/governance-files) and [token selection](/learn/concepts/token-selection) — the agent knows what matters.
- **Scale**: Plain markdown folders collapse under their own weight at ~100 files. aDNA's triad, AGENTS.md routing, and convergence model keep navigation systematic regardless of vault size.
- **Knowledge reuse**: aDNA's [FAIR metadata](/learn/concepts/fair-metadata) and federation protocol make knowledge shareable. Plain markdown files are trapped in their folder.
- **Consistency**: aDNA's templates and frontmatter conventions ensure every file of a given type has the same structure. Plain markdown files vary wildly between authors.
- **Operational infrastructure**: Sessions, missions, campaigns — aDNA tracks work. Plain markdown doesn't know what's in progress.
## Where Plain Markdown Excels
- **Zero friction**: Open editor, create file, write. No governance files to create, no frontmatter to populate, no naming conventions to follow.
- **No learning curve**: Everyone knows how to create a markdown file. aDNA requires understanding the triad, entity types, frontmatter schema, and governance model.
- **Maximum flexibility**: No structure means no constraints. Experimentation, quick notes, scratch files — all fine.
- **Appropriate for small projects**: A 10-file project doesn't need governance files, AGENTS.md routing, or session tracking. The overhead doesn't justify itself until a project reaches a certain size.
- **Universal tooling**: Every editor supports markdown. aDNA's governance files are meaningless without agent tooling.
## The Tipping Point
The comparison has a **crossover point** — a project size where aDNA's overhead starts paying for itself:
| Project Size | Recommendation | Why |
|-------------|----------------|-----|
| 1-20 files | Plain markdown | Overhead isn't justified. You can hold the whole project in your head. |
| 20-50 files | Consider aDNA | Navigation is getting harder. Agent-assisted work would benefit from governance. |
| 50+ files | aDNA | Finding the right file, loading the right context, maintaining consistency — all problems aDNA solves. |
| 100+ files | aDNA strongly recommended | Plain markdown at this scale is an archaeological dig. |
The tipping point isn't just file count — it's also agent involvement. If you're working with AI agents on a 15-file project, aDNA is still worth it because the governance files dramatically improve agent output quality.
## When to Choose Which
| If you need... | Choose |
|---------------|--------|
| Quick notes, scratch files, personal logs | Plain markdown |
| AI-agent-navigable project knowledge | aDNA |
| Maximum flexibility with zero overhead | Plain markdown |
| Consistency across dozens or hundreds of files | aDNA |
| A small project without AI agent involvement | Plain markdown |
| Multi-agent collaboration, federation, FAIR metadata | aDNA |
| To start writing immediately with no setup | Plain markdown |
| A knowledge architecture that scales | aDNA |
The migration path is straightforward: start with plain markdown, adopt aDNA when the project outgrows ad hoc organization. The base template (`.adna/`) provides a fork-and-customize starting point.
## Sources
- commonmark.org — CommonMark markdown specification
- aDNA Standard v2.5, §1 (Introduction), §3 (Triad), §4 (Governance) — aDNA specification
## Related
- [The Triad](/learn/concepts/triad) — the structure aDNA adds on top of plain markdown
- [Agentic Literacy](/learn/concepts/agentic-literacy) — the skill gap between "folder of files" and "agent-navigable architecture"
- [Convergence Model](/learn/concepts/convergence) — what makes aDNA scale where plain markdown doesn't
---
## https://adna.network/learn/comparisons/adna-vs-zettelkasten/
# aDNA vs. Zettelkasten — aDNA Comparisons
Two knowledge systems built on connected notes — one optimized for human creative thinking, the other for human-agent collaborative projects.
## Overview
### aDNA
A knowledge architecture standard (§1) that organizes project knowledge into a what/how/who triad with typed entities, governance files, and AI-agent routing. Knowledge forms a [connected graph](/learn/concepts/knowledge-graph), but the graph is structured by ontology types, directory conventions, and AGENTS.md routing. Designed for team projects with AI agents.
### Zettelkasten
Niklas Luhmann's "slip box" method, popularized by Sönke Ahrens in *How to Take Smart Notes*. Each note is atomic (one idea), uniquely identified, and densely linked to other notes. No hierarchical categories — structure emerges from links. The system grows organically as a "conversation partner" for thinking. Implemented in tools like Obsidian, Logseq, and Zettlr.
## Comparison
| Dimension | aDNA | Zettelkasten |
|-----------|------|-------------|
| **Organizing principle** | Triad (what/how/who) + typed entities | Flat: atomic notes + emergent link structure |
| **Hierarchy** | Directory structure encodes meaning (triad legs, entity types) | No hierarchy: all notes are peers |
| **Linking** | Wikilinks + AGENTS.md routing + typed edges in lattices | Dense bidirectional links — structure IS the links |
| **Agent support** | Native: governance files, convergence model, session tracking | None: designed for human cognition only |
| **Knowledge model** | Typed entities with frontmatter (concept, pattern, mission, etc.) | Untyped atomic notes — meaning is in content and links |
| **Scalability** | Multi-agent, multi-project, federated | Single-person (scales to 90K+ notes for dedicated practitioners) |
| **Discovery** | AGENTS.md routing, context recipes, convergence model | Serendipitous: follow links, find unexpected connections |
| **Overhead** | Moderate: frontmatter, governance files, session tracking | Low: write a note, link it, done |
## Where aDNA Excels
- **Agent navigation**: Zettelkasten relies on human serendipity — following links by interest. aDNA's [AGENTS.md routing](/patterns/agents-md) gives agents systematic navigation paths through the graph.
- **Typed knowledge**: aDNA's entity types (concept, pattern, mission, lattice) make knowledge machine-queryable. Zettelkasten notes are typed only by content.
- **Operational infrastructure**: aDNA tracks sessions, missions, campaigns. Zettelkasten has no operational layer — it's purely a thinking tool.
- **Convergence**: aDNA's [convergence model](/learn/concepts/convergence) narrows context systematically. In a large Zettelkasten, finding the right subset of notes for a task is ad hoc.
## Where Zettelkasten Excels
- **Creative emergence**: Zettelkasten's flat, densely linked structure produces unexpected connections — ideas from disparate domains collide. aDNA's directory structure is navigable but less serendipitous.
- **Thinking tool**: Zettelkasten is designed to externalize and develop *thinking*. aDNA is designed to organize and share *knowledge*. For individual intellectual development, Zettelkasten is purpose-built.
- **Minimal overhead**: Write a note, give it an ID, link it. No frontmatter schema, no AGENTS.md, no governance files.
- **Proven longevity**: Luhmann maintained his Zettelkasten for 40+ years, producing 70+ books. The method is battle-tested at human scale.
- **No wrong structure**: In Zettelkasten, there's no directory to misplace a note in. In aDNA, the question test can feel like a constraint.
## When to Choose Which
| If you need... | Choose |
|---------------|--------|
| A personal thinking and writing tool | Zettelkasten |
| A team knowledge architecture with AI agents | aDNA |
| Serendipitous idea discovery | Zettelkasten |
| Systematic context serving to agents | aDNA |
| Minimal structure, maximum creative freedom | Zettelkasten |
| Typed, governed, federable knowledge objects | aDNA |
| Long-term personal intellectual development | Zettelkasten |
| Multi-agent project execution with audit trails | aDNA |
Both use Obsidian well. A practitioner might maintain a personal Zettelkasten alongside aDNA project vaults.
## Sources
- Sönke Ahrens, *How to Take Smart Notes* (2017) — Zettelkasten method for knowledge work
- zettelkasten.de — community hub and method documentation
- Niklas Luhmann, "Communicating with Slip Boxes" (1981) — original articulation
- aDNA Standard v2.5, §3 (Triad), §10 (Context Library) — aDNA specification
## Related
- [Knowledge Graph](/learn/concepts/knowledge-graph) — aDNA's connected structure (compare to Zettelkasten's emergent link graph)
- [Convergence Model](/learn/concepts/convergence) — systematic narrowing that Zettelkasten doesn't provide
- [Question Test](/patterns/question-test) — aDNA's sorting discipline (vs. Zettelkasten's flat no-hierarchy approach)
---
## https://adna.network/learn/concepts/
# Concepts
13 core concepts that make up the aDNA knowledge architecture, ordered from concrete foundations to philosophical principles.
[The Triad The triad is aDNA's universal organizing principle: every piece of project knowledge belongs in exactly one of three directories — what/, how/, or…](/learn/concepts/triad)[The Ontology The aDNA ontology is a typed vocabulary of 16 base entity types — organized across the triad — that defines what kinds of things a project can…](/learn/concepts/ontology)[The Knowledge Graph An aDNA vault is not a filing cabinet — it's a knowledge graph. Files are nodes, wikilinks are edges, and AGENTS.md files are the navigation layer…](/learn/concepts/knowledge-graph)[Governance Files Every aDNA project has five ALLCAPS governance files at its root — CLAUDE.md, MANIFEST.md, STATE.md, AGENTS.md, and README.md. Together, they form the…](/learn/concepts/governance-files)[Token Selection Token selection is the discipline of choosing which knowledge to load into an AI agent's context window — and, critically, which knowledge to leave…](/learn/concepts/token-selection)[The Convergence Model A project can know more than any AI agent can hold in mind at once. The convergence model solves that by narrowing the knowledge in play at each stage…](/learn/concepts/convergence)[Dual Audience aDNA's communication discipline: every content file stays technically precise for developers and genuinely clear for newcomers — neither audience sacrificed.](/learn/concepts/dual-audience)[Context Optimization Context optimization is the practice of designing context files — the curated knowledge agents load before doing work — so they deliver maximum…](/learn/concepts/context-optimization)[Lattice Composition Big jobs are usually too big for one workflow. Lattice composition is how aDNA snaps smaller workflows together to make bigger ones — the same way a…](/learn/concepts/lattice-composition)[Open Standard aDNA is an open standard — a publicly documented specification that anyone can implement, extend, and build upon without permission or payment. The…](/learn/concepts/open-standard)[Agentic Literacy Agentic literacy is the ability to work effectively with AI agents — not just prompting them, but structuring knowledge so agents can find…](/learn/concepts/agentic-literacy)[Context Commons Think of the Context Commons as a shared library of "how to teach an AI assistant your project" — like GitHub, but for agent knowledge instead of…](/learn/concepts/context-commons)[FAIR Metadata FAIR is a simple four-question test: can someone else Find your work, Access it, Interoperate with it, and Reuse it? aDNA bakes that test into every…](/learn/concepts/fair-metadata)
---
## https://adna.network/learn/concepts/agentic-literacy/
# Agentic Literacy — aDNA Concepts
```mermaid
graph LR
L0["L0 — Aware"] --> L1["L1 — User"]
L1 --> L2["L2 — Builder"]
L2 --> L3["L3 — Architect"]
```
*Four levels of agentic literacy — from awareness to architecture*
## Overview
Agentic literacy is the ability to work effectively with AI agents — not just prompting them, but structuring knowledge so agents can find, understand, and act on it. aDNA treats this as a learnable skill with a clear progression: from understanding what agents need, to organizing knowledge for them, to building collaborative human-agent workflows.
## Why This Matters
A generation ago, "computer literacy" meant learning to use a mouse and save files. Today it means navigating complex digital environments — spreadsheets, version control, cloud services. The bar rose because the tools matured.
AI agents are the next shift. They can read your project documentation, execute multi-step plans, and coordinate with other agents. But they're only as effective as the knowledge you give them. An agent working with a well-structured aDNA vault performs like an informed colleague. The same agent working with a disorganized folder of loose files performs like a confused temp worker reading someone else's notes.
Agentic literacy is the skill gap between those two outcomes. It's knowing that an agent needs a `CLAUDE.md` to orient, that context files should use tables over prose, that a knowledge graph with orphan files has blind spots. It's understanding that the way you organize knowledge determines the quality of AI-augmented work — and that this is a skill you can learn, not a talent you're born with.
This matters beyond individual productivity. As AI agents become standard tools in research, engineering, and creative work, the organizations and communities that develop agentic literacy will get compounding returns from their AI investments. Those that don't will struggle to understand why their expensive AI tools produce generic, uninformed output.
## How It Works
### The Literacy Progression
Agentic literacy isn't binary — it develops in stages:
| Level | Understanding | Skill | Example |
|-------|-------------|-------|---------|
| **Aware** | Knows AI agents exist and can read documents | Can write a prompt | Asking an agent to summarize a file |
| **Oriented** | Understands agents need structure to be effective | Can organize a project for agent access | Creating a CLAUDE.md, using consistent naming |
| **Proficient** | Understands convergence, token budgets, governance files | Can design an aDNA vault from scratch | Building a knowledge architecture with triad, AGENTS.md, context library |
| **Fluent** | Understands composition, federation, quality rubrics | Can architect multi-agent collaborative systems | Designing campaigns, composing lattices, federating across instances |
Most people start at Aware. aDNA's goal is to move them to Proficient — able to structure knowledge for effective human-agent collaboration.
### What Agents Need (and Why It's Teachable)
Agent effectiveness depends on learnable practices, not magic:
| Agent Need | Literate Practice | Why It Works |
|-----------|------------------|-------------|
| Orientation on startup | Write CLAUDE.md + STATE.md | Agent knows who it is, what's happening, and what to do |
| Finding relevant knowledge | AGENTS.md routing + context recipes | Agent traverses the knowledge graph instead of guessing |
| Staying within token limits | Token budgets + convergence model | Agent loads what it needs without drowning in information |
| Understanding domain context | Well-structured context files | Tables and principles over prose — 3-5x more information per token |
| Coordinating with others | Session tracking + coordination notes | Agent knows what other agents are doing and what's already been tried |
None of these require programming skill. They're organizational practices — closer to "how to organize a filing cabinet" than "how to write code." That's why agentic literacy is genuinely accessible: the barrier is understanding, not technical ability.
### The Dual-Audience Principle
A core tenet of agentic literacy: knowledge should serve both humans and agents simultaneously. This is the [dual-audience](/learn/concepts/dual-audience) principle. Every concept file, every governance document, every tutorial needs to be legible to a developer reading for technical precision AND to a non-technical reader seeking understanding.
This isn't just nice to have. Agents learn from the same documents humans read. If your documentation is only optimized for human consumption (long prose, implicit context, narrative structure), agents will struggle to extract actionable information. If it's only optimized for agents (terse tables, no motivation, no examples), humans won't write or maintain it. The dual-audience discipline ensures both audiences are served.
### Teaching by Showing
aDNA's approach to literacy education follows a principle: **the structure is the lesson**. Rather than writing about how to organize knowledge in abstract terms, aDNA provides self-referential examples — vaults where the documentation structure demonstrates the concepts it describes.
This vault (`aDNA.aDNA/`) exists for exactly this purpose. A reader learning about the triad can look at the `what/`, `how/`, `who/` directories and see it. A reader learning about governance files can open the `CLAUDE.md` they're already reading. The learning environment and the subject matter are the same thing.
## See It In Action
This vault is itself an agentic literacy tool:
**Progressive structure**: Navigate from `README.md` (human entry point) → `CLAUDE.md` (agent entry point) → `STATE.md` (operational context) → `what/concepts/` (concept library). Each step teaches a literacy concept by requiring you to practice it: following governance files, using the triad, reading AGENTS.md routing.
**The tutorials directory**: `what/tutorials/` is scaffolded for a beginner → intermediate → advanced learning path. When populated, each tutorial will walk a learner through a specific agentic literacy skill — from "create your first CLAUDE.md" to "design a multi-mission campaign."
**Dual-audience in practice**: Every concept file in this vault (including this one) opens with a plain-language metaphor and progresses to technical specification. That's the dual-audience principle demonstrated at the file level. A 14-year-old can understand the opening paragraph; a developer can reference the tables for implementation.
**The community directory**: `who/community/` is scaffolded for community roles and contribution paths — the social infrastructure for scaling agentic literacy beyond individual practitioners to organizations and communities.
## Related
- [Dual-Audience Writing](/learn/concepts/dual-audience) — the writing discipline that makes knowledge serve both humans and agents
- [Context Commons](/learn/concepts/context-commons) — the vision of shared knowledge resources that agentic literacy makes possible
- [Open Standard](/learn/concepts/open-standard) — how openness lowers the barrier to developing agentic literacy
- [The Triad](/learn/concepts/triad) — the organizing principle that is the first lesson in agentic literacy
---
## https://adna.network/learn/concepts/context-commons/
# Context Commons — aDNA Concepts
```mermaid
graph TD
pub["Public — open specs and standards"]
shared["Shared — community lattices"]
org["Org — team and domain context"]
priv["Private — project and session"]
pub --> shared --> org --> priv
```
*Context layers — public knowledge flows down into increasingly specific contexts*
## Overview
Think of the Context Commons as a shared library of "how to teach an AI assistant your project" — like GitHub, but for agent knowledge instead of code. Anyone can publish what they've learned, and anyone can pull what others have validated. The rest of this concept explains how aDNA's federation protocol and FAIR metadata turn that idea into working infrastructure — curated context that helps agents across many projects, not just one.
## Why This Matters
Think about open-source software. Before it became normal, every company wrote its own web server, its own database driver, its own logging library. The same problems were solved thousands of times in thousands of private codebases. Open source changed this: someone writes a good solution, publishes it with a license, and everyone benefits. The collective saves millions of hours of duplicated effort.
AI-agent knowledge has the same duplication problem today. Every team writes its own CLAUDE.md from scratch. Every project builds its own context library. Every vault rediscovers the same patterns for organizing knowledge, managing token budgets, and structuring agent workflows. The insights stay trapped in private projects, invisible to the wider community.
The Context Commons is the open-source moment for agent knowledge. A research lab writes a high-quality context file on protein structure prediction — instead of staying in their vault, it becomes a findable, FAIR-annotated, community-maintained resource that any biotech project can load. A startup develops a pattern for multi-agent coordination — it gets published as a reusable lattice that other teams compose into their workflows.
This isn't hypothetical altruism. It's practical efficiency. A commons reduces the cost of starting a new project (don't write from scratch, pull from the commons). It raises quality (community review > individual effort). And it accelerates the development of [agentic literacy](/learn/concepts/agentic-literacy) by giving learners real, validated examples to study.
## How It Works
### The Infrastructure Layer
The Context Commons doesn't require new technology — it's built on aDNA capabilities that already exist:
| Capability | aDNA Feature | Commons Role |
|-----------|-------------|-------------|
| **Publishing** | Federation export (§11) | How knowledge leaves a private project |
| **Discovery** | FAIR metadata — keywords, identifiers (§6) | How published knowledge gets found |
| **Trust** | FAIR metadata — license, provenance, creators | How users evaluate quality and legal status |
| **Consumption** | Federation import + composition | How knowledge enters a new project |
| **Quality** | Context quality rubric (§10) — signal density, actionability | How the community maintains standards |
The commons is federation at community scale. The same protocol that lets two projects share a lattice lets a thousand projects share a context library.
### What Gets Shared
Not everything belongs in a commons. The most valuable shared resources are those that solve common problems across many domains:
| Resource Type | Commons Value | Example |
|--------------|--------------|---------|
| **Context files** | High — domain knowledge is expensive to create, cheap to share | "How protein folding works" context for biotech projects |
| **Patterns** | High — structural solutions transfer across domains | "How to design a multi-stage pipeline" pattern |
| **Lattice templates** | Medium-High — composable workflow blueprints | "Data ingestion → validation → storage" pipeline |
| **Governance templates** | Medium — operational boilerplate | CLAUDE.md templates for specific project types |
| **Glossary entries** | Medium — shared terminology reduces ambiguity | Canonical definitions for cross-domain terms |
| **Full project vaults** | Low — too domain-specific to transfer | (Keep as reference implementations, not shared resources) |
The principle: share the reusable, keep the specific. Context files and patterns have the highest leverage because they're domain knowledge distilled to its most transferable form.
### Governance Without Central Authority
A commons needs governance — rules about quality, licensing, and contribution — but not necessarily a central authority. aDNA's approach:
**FAIR as the entry gate**: Every shared resource must carry FAIR metadata. Minimum: `keywords` (findable) and `license` (accessible/reusable). This is a low bar that still ensures basic discoverability and legal clarity.
**Quality rubric as the standard**: The context quality rubric (§10) provides a shared vocabulary for evaluating contributions. Signal density, actionability, source diversity — the same axes used to score context files within a project apply to commons contributions. Target composite score: 3.5+.
**Federation as the mechanism**: Resources enter and leave the commons through the federation protocol. Import triggers ontology unification (§11.3) to ensure compatibility. Version policies (locked, patch, minor, latest) manage dependency relationships.
**Community review over gatekeeping**: Rather than a review board that approves contributions, the commons relies on transparent quality scores and community usage signals. A context file with signal density 5/5, used by 50 projects, is de facto validated — no committee needed.
### The Contribution Cycle
Knowledge flows through the commons in a cycle:
```
Create (in a project)
→ Generalize (remove project-specific details)
→ Annotate (add FAIR metadata + quality scores)
→ Publish (federation export)
→ Discover (keyword search / recipe index)
→ Import (federation import)
→ Adapt (customize for local project)
→ Improve (fix issues, update sources)
→ Contribute back (updated version)
```
Each step adds value. The original creator does the hardest work — distilling domain knowledge. The commons makes that work accessible to everyone. Consumers who improve and contribute back create a virtuous cycle.
## See It In Action
This vault contains the seeds of a Context Commons:
**The context library itself**: `what/context/` contains 5 topics, 27 subtopics, and ~75K tokens of curated knowledge. This library was created for this vault but is designed to be sharable: every file has FAIR-aligned metadata (sources, tags, quality scores), token estimates, and self-contained content. It's a proto-commons.
**Community infrastructure**: `who/community/` is scaffolded for community roles and contribution paths. When populated, it will define how contributors propose, review, and maintain shared resources.
**FAIR metadata everywhere**: Every object in this vault carries the metadata envelope that makes commons participation possible — `keywords`, `license`, `provenance`, `sources`. The infrastructure is in place; the community scales it.
**The base template**: The upstream `adna/` repository (github.com/aDNA-Network/aDNA) is itself a commons contribution — a shared, forkable starting point that reduces the cost of creating new aDNA projects from hours to minutes. Every `.aDNA/` project in the workspace was forked from this commons resource.
**Context recipes as curated collections**: `what/context/context_recipes.md` pre-defines which context subtopics to load together for common tasks. These recipes are a form of commons curation — someone figured out the right combination so you don't have to.
## Related
- [FAIR Metadata](/learn/concepts/fair-metadata) — the metadata standard that makes commons resources findable, trustworthy, and reusable
- [Agentic Literacy](/learn/concepts/agentic-literacy) — the literacy movement the commons accelerates by providing real examples
- [Open Standard](/learn/concepts/open-standard) — the open governance model that enables a commons to exist without vendor lock-in
- [Lattice Composition](/learn/concepts/lattice-composition) — the composability that makes commons lattices useful in new projects
---
## https://adna.network/learn/concepts/context-optimization/
# Context Optimization — aDNA Concepts
```mermaid
graph LR
signal["High-signal context file"] -->|"fast, decisive"| agent["Agent context window"]
noise["Low-signal dump file"] -->|"wastes tokens"| agent
agent --> output["Decision or artifact"]
```
*Signal-dense context files lead to better, faster agent decisions*
## Overview
Context optimization is the practice of designing context files — the curated knowledge agents load before doing work — so they deliver maximum decision-relevant information per token consumed. It covers file structure, format selection, quality scoring, and the discipline of saying less to communicate more.
## Why This Matters
Imagine you have 60 seconds to brief a colleague before they walk into a meeting. You could ramble about background history, or you could give them three bullet points that let them make the right call. Context optimization is the art of writing the three bullet points.
AI agents face a strict version of this constraint. Their "working memory" — the context window — has a hard limit, and the aDNA 75% rule (§8.7) reserves a quarter of it for reasoning. Every token spent on preamble, filler, or redundant explanation is a token the agent can't use for actual knowledge. When you load a context file into an agent's window, you're spending a budget. The question is whether you're buying signal or noise.
This matters at scale. A project with 50 context files across 5 topics could easily contain 50K tokens. An agent session might have budget for 15K. If your files are well-optimized — tables instead of prose, principles instead of preambles, decisions instead of descriptions — 15K tokens might be plenty. If they're prose-heavy, 15K buys you generic background that doesn't actually help the agent do its job.
## How It Works
### The Three Subtypes
Not all context files serve the same purpose. The aDNA Standard (§10) defines three subtypes, each with different density targets:
| Subtype | Purpose | Token Density | Example |
|---------|---------|---------------|---------|
| `context_research` | Synthesized domain knowledge from external sources | Dense, citational | Federation composability patterns |
| `context_guide` | Prescriptive how-to instructions | Step-by-step, actionable | Context engineering guide |
| `context_core` | Foundational project definitions | Concise, authoritative | Paradigm overview |
Choosing the right subtype is the first optimization decision. A file that tries to be both research synthesis and step-by-step guide will be mediocre at both.
### Format Selection
The single most impactful optimization is format selection. The same information in different formats can vary 3-5x in token cost:
| Content Type | Best Format | Why | Token Savings |
|-------------|-------------|-----|---------------|
| Comparisons | Decision tables | Side-by-side, scannable | 3-5x vs. prose |
| Procedures | Numbered steps | Sequential, unambiguous | 2-3x vs. prose |
| Rules & constraints | Constraint tables | Structured, queryable | 3-4x vs. prose |
| Examples | Code blocks with annotations | Directly executable | 2x vs. described |
| Principles | Numbered list, most important first | Priority-ordered, memorable | 2x vs. paragraphs |
The default should always be tables over prose. Prose is appropriate for motivation and metaphor (like the "Why This Matters" section you're reading now) but not for reference material an agent will query.
### The Quality Rubric
aDNA scores context files on six axes (§10). Three are directly about optimization:
| Axis | Score 1-5 | Optimization Impact |
|------|-----------|-------------------|
| **Signal density** | Fraction of tokens that drive decisions | High — the core metric |
| **Actionability** | Can an agent produce concrete output? | High — files that inform but don't enable action are overhead |
| **Coverage uniformity** | Balanced depth across sections | Medium — lopsided files waste tokens on over-covered topics |
The floor rule: any axis scoring 2 or below flags the file for revision. The composite target is 3.5+ across all five numeric axes.
### Anti-Patterns
| Anti-Pattern | Token Cost | Fix |
|-------------|-----------|-----|
| Background preamble ("In the rapidly evolving field of...") | 50-200 wasted tokens per file | Start with first principle |
| Prose where tables work | 3-5x overhead | Convert to tables |
| Monolithic files (>4K tokens) | Agents load everything to get one section | Split into subtopics |
| Single-source content (source diversity ≤ 2) | Low credibility, narrow perspective | Diversify sources |
| Redundant coverage across files | Double-loading penalty | Scope notes differentiating files |
| Missing AGENTS.md | Agents can't find the file | Every topic directory needs an index |
### The Composition System
Individual file optimization isn't enough when tasks span multiple topics. The context composition system (§10) provides **recipes** — pre-defined combinations of subtopics for multi-disciplinary tasks, at three budget tiers:
| Tier | Budget | When to Use |
|------|--------|------------|
| Minimal | <5K tokens | Narrow task, known domain |
| Standard | <12K tokens | Typical development session |
| Full | All subtopics | Deep research or comprehensive review |
Recipes prevent the common failure of loading "just in case" — pre-selecting which subtopics to combine for a given task type.
## See It In Action
This vault's context library (`what/context/`) is a working example of context optimization at every level:
**File-level optimization**: Open `what/context/adna_core/context_adna_core_context_engineering.md` — it's the guide for writing context files, and it practices what it preaches. Tables dominate. Principles are numbered. Anti-patterns are listed. Signal density: 5/5.
**Token budgets**: Every context file carries a `token_estimate` in its frontmatter. The AGENTS.md at `what/context/adna_core/AGENTS.md` lists all 13 subtopics with their token costs, totaling ~13,100 tokens. An agent can decide exactly which subtopics to load and predict the cost before loading them.
**Format selection in practice**: Compare the "Key Principles" section in any context file (numbered list, table-driven) with the "Why This Matters" section in concept files (prose, metaphor-driven). Different audiences, different formats, both optimized for their purpose.
**Composition recipes**: The recipe index at `what/context/context_recipes.md` pre-defines which subtopics to load together for common task types, preventing agents from improvising (and over-loading) on multi-topic tasks.
## Related
- [Token Selection](/learn/concepts/token-selection) — the mechanisms (AGENTS.md routing, recipes, budgets) that implement context optimization decisions
- [Convergence Model](/learn/concepts/convergence) — the structural principle that ensures optimization compounds across campaign → mission → objective
- [Knowledge Graph](/learn/concepts/knowledge-graph) — the connected structure that optimization helps agents traverse efficiently
- [Write a Context File](/learn/tutorials/write-a-context-file) — hands-on: author a context file using optimization principles
---
## https://adna.network/learn/concepts/convergence/
# The Convergence Model — aDNA Concepts
```mermaid
graph LR
Campaign["Campaign (100+ files)"] --> Mission["Mission (5–10 files)"]
Mission --> Objective["Objective (2–3 files)"]
Objective --> Session["Session (1 context window)"]
```
*Convergence narrows knowledge at each execution level*
## Overview
A project can know more than any AI agent can hold in mind at once. The convergence model solves that by narrowing the knowledge in play at each stage of work — the whole project at the top, the specific task at the bottom. Each level of aDNA's hierarchy (campaign → mission → objective) shrinks the set of files an agent sees while sharpening their relevance, so context serving becomes graph traversal: agents walk from broad to specific and load only the subgraph that matters.
## Why This Matters
Picture a funnel. At the top, you pour in everything a project knows — research notes, operational procedures, governance policies, team coordination, hundreds of files. At the bottom, a single focused stream comes out: the exact 5-10 files an agent needs to write one concept document or fix one bug.
That funnel is the convergence model. Without it, agents face a paradox: the more knowledge a project accumulates, the harder it becomes for any single agent session to use that knowledge effectively. A project with 500K tokens of context is richer than one with 10K, but an agent can only hold ~75K tokens at a time. The knowledge needs to converge — to narrow from "everything the project knows" down to "exactly what this session needs."
The brilliance of the approach is that the narrowing is structural, not ad hoc. It's not "the agent guesses which files to load." It's "the execution hierarchy and AGENTS.md routing systematically prune irrelevant knowledge at each level." The result is monotone-decreasing: at every step down the hierarchy, the working set gets smaller and more focused. Never larger.
## How It Works
### The Execution Hierarchy
The convergence model operates through three levels (§9, §8):
```
Campaign → Mission → Objective
(strategic) (tactical) (session)
```
Each level narrows scope:
| Level | Scope | Typical Tokens | Reduction |
|-------|-------|---------------|-----------|
| **Vault** | Total project knowledge | ~500K | — |
| **Campaign** | Strategic initiative (one of several) | ~50K | 90% |
| **Mission** | Decomposed task (one of several per campaign) | ~15K | 70% |
| **Objective** | Session work (one of several per mission) | ~5K | 67% |
The numbers are illustrative, but the *direction* is normative: each level MUST load fewer tokens than the one above it. If a mission requires more context than its campaign provides, either the campaign scope is too narrow or the mission is trying to do too much.
### How Narrowing Works in Practice
At each level, three mechanisms prune the working set:
**1. Scope declarations** — A campaign says "this initiative covers Phase 1 content creation." That immediately excludes all Phase 2-4 knowledge, community governance, workshop kits, and publishing infrastructure. The working set drops from hundreds of files to tens.
**2. AGENTS.md routing** — Within the narrowed scope, each directory's AGENTS.md tells the agent whether to load or skip. An agent working on concept files enters `what/concepts/` (AGENTS.md says "load") and skips `what/use_cases/` (AGENTS.md says "skip — different mission"). The working set drops from tens of files to a handful.
**3. Mission objective specificity** — The mission file lists specific objectives with specific deliverables. An agent claims one objective per session, further narrowing to the exact files it needs to read and write.
### Context Serving as Graph Traversal
The [knowledge graph](/learn/concepts/knowledge-graph) makes convergence concrete. When an agent starts a session, it performs a graph traversal:
1. **Entry node**: CLAUDE.md (always — the root of every traversal)
2. **State node**: STATE.md (current operational context)
3. **Campaign node**: The active campaign doc (strategic scope)
4. **Mission node**: The specific mission file (tactical scope)
5. **Working nodes**: The files listed in the mission's objectives
Each step follows an edge in the graph, and each AGENTS.md acts as a filter on that edge — "traverse this path" or "prune this branch." The traversal terminates when the agent has loaded its objective's working set and can begin executing.
This is why [orphan files](/learn/concepts/knowledge-graph) are a problem. A file with no inbound links is invisible to graph traversal — it can never be reached by an agent following the convergence path. It exists in the vault but not in any agent's effective context.
### The 75% Rule
The convergence model has a hard floor: the 75% rule (§8.7). An agent SHOULD reserve at least 25% of its context window for reasoning. The convergence model's job is to get the loaded knowledge within the remaining 75%.
If the convergence path still loads too much, the hierarchy isn't converging fast enough. The fix is structural: decompose the mission into more objectives, split the context file into subtopics, or add AGENTS.md routing to un-routed directories.
## See It In Action
This vault demonstrates convergence through its own execution hierarchy:
**Campaign level**: Operation Rosetta narrows the full vault (~200+ files) to Phase 1 (concepts, patterns, comparisons — ~26 files). Phase 2+ content, community architecture, workshop kits, and publishing pipeline are all scoped out. The campaign doc declares a context budget: ~5K campaign + ~15K domain context.
**Mission level**: Mission M02 narrows Phase 1 to 4 specific concept files. It declares its context dependencies: 4 context subtopics and the 3 M01 concepts for cross-linking. That's ~15K tokens of domain context out of a vault that contains ~75K+.
**Objective level**: Writing this file — `concept_convergence.md` — is one objective within M02. The agent loaded the convergence model context file (~500 tokens), the paradigm overview (~1K tokens), and the M01 concepts (~5K tokens). Total working context: ~11K tokens. The full vault would have been ~75K. Convergence achieved a ~85% reduction.
The convergence is visible in the directory structure itself. The campaign lives in `how/campaigns/campaign_rosetta/` — one subdirectory of `how/campaigns/`. The mission lives inside that campaign's `missions/` directory. The objective lives inside the mission file. Each nesting level is a narrowing step.
## Related
- [Token Selection](/learn/concepts/token-selection) — the tactical mechanisms (AGENTS.md routing, context recipes, token estimates) that implement convergence
- [Knowledge Graph](/learn/concepts/knowledge-graph) — the connected structure that convergence traverses from broad to specific
- [Ontology](/learn/concepts/ontology) — the entity types that define what kinds of nodes exist at each convergence level
- [The Triad](/learn/concepts/triad) — the three-leg structure that provides the first level of narrowing
---
## https://adna.network/learn/concepts/dual-audience/
# Dual Audience — aDNA Concepts
## Overview
Dual-audience writing is aDNA's communication discipline: every content file must be technically precise for developers building with the standard AND genuinely clear for newcomers understanding what it is. Neither audience is sacrificed for the other.
## Why This Matters
Most technical documentation picks a side. Developer docs assume you already know the domain — they're precise but impenetrable to outsiders. User guides explain things simply — but strip out the technical depth that developers actually need. The result is two parallel documents that drift apart over time, or one document that serves neither audience well.
aDNA refuses this trade-off. A single concept file — like the one you're reading right now — must work for both audiences simultaneously. A developer should be able to find spec section numbers, implementation details, and structural rules. A product manager, educator, or curious newcomer should be able to understand the core idea without hitting a wall of jargon.
Why insist on this? Because aDNA is a knowledge architecture that both humans and AI agents navigate. If a concept file is only legible to developers, then a non-technical project lead can't understand what their agents are doing. If it's only legible to beginners, agents miss the precision they need to implement correctly. The architecture serves a mixed audience by nature — the documentation must match.
This is the Feynman principle applied to documentation: if you can't explain it simply, you don't understand it well enough to document it. And if you can't document it precisely, nobody can build with it reliably.
## How It Works
### The Structure: Layered Depth
Dual-audience writing in aDNA follows a consistent structural pattern. Every concept, pattern, and tutorial file moves through layers of increasing depth:
| Section | Audience | Purpose |
|---------|----------|---------|
| **Overview** | Both | 1-2 sentence summary — plain language, no prerequisites |
| **Why This Matters** | Newcomers first | Metaphor-driven explanation, no jargon, builds intuition |
| **How It Works** | Developers first | Technical detail, spec references, tables, implementation rules |
| **See It In Action** | Both | Self-referential example — the vault demonstrates the concept |
| **Related** | Both | Links to connected concepts, patterns, tutorials |
The key insight is *layering*, not *simplifying*. The "Why This Matters" section doesn't dumb things down — it provides a different kind of understanding. The mental model and metaphor give a newcomer the intuition they need to then read the technical section productively. For developers, the plain-language section is a sanity check: if the metaphor doesn't align with the technical spec, something is wrong with one of them.
### The Opening Rule
aDNA enforces a concrete quality gate: every concept and pattern file MUST begin with 1-3 sentences that a 14-year-old could follow. This is the **plain-language opening** gate.
The 14-year-old test isn't about targeting 14-year-olds. It's a forcing function. If you can't express the core idea without assumed domain knowledge, you haven't distilled the concept down to its essence. The opening is the hook that invites the non-technical reader in, and it's the summary that the technical reader uses to verify they're reading the right file.
### Spec Citations and Plain Language
aDNA requires that normative claims reference the upstream standard with section numbers (e.g., "§4.2 CLAUDE.md", "§4.5 AGENTS.md", "§4.6 README.md" — the governance-file sections this concept leans on). This serves both audiences:
- **For developers**: Spec references are traceable. They can verify claims, check for updates, and find related normative requirements.
- **For newcomers**: Seeing "(§4.2)" signals "this isn't just one person's opinion — it's a defined standard." The reference builds credibility without requiring the reader to look it up.
The balance is: plain-language claim first, then spec citation. Never lead with the section number.
### The Self-Reference Discipline
Every content file must cite at least one concrete example from the vault itself. This is the **self-reference check** quality gate. Self-reference serves both audiences:
- **For newcomers**: Abstract concepts become tangible. "Open this file and you'll see the pattern in action" is far more effective than "here is a theoretical description of the pattern."
- **For developers**: Self-referential examples are verifiable. The reader can navigate to the referenced file and confirm the claim. If the claim is wrong, the vault has a bug — and bugs are fixable.
### Quality Gates as Enforcement
Dual-audience writing is enforced through campaign quality gates, not just guidelines. In this vault, every content file must pass:
1. **Dual audience test** — reviewed via `skill_dual_audience_review.md`
2. **Self-reference check** — reviewed via `skill_self_reference_check.md`
3. **Spec citation** — normative claims reference `adna_standard.md` sections
4. **Plain-language opening** — first 1-3 sentences pass the 14-year-old test
5. **Cross-linking** — 2+ links to related content
6. **Frontmatter complete** — all required metadata fields populated
Gates 1, 2, and 4 directly enforce dual-audience quality. Without enforcement, dual-audience writing degrades to "developer docs with a one-line summary" — technically compliant but practically single-audience.
## See It In Action
This file is itself a dual-audience demonstration. Examine how it's structured:
- **The opening sentence** uses no jargon: "every content file must be technically precise for developers AND genuinely clear for newcomers." A 14-year-old could follow that.
- **"Why This Matters"** uses a concrete comparison (developer docs vs. user guides) rather than abstract principles. No spec references, no aDNA terminology beyond what's been introduced.
- **"How It Works"** introduces spec sections (§4.2, §4.5, §4.6), quality gates, and structural patterns. A developer can reference these directly.
- **This section** points you to the actual vault structure so you can verify the claims yourself.
Now look at the foundational concepts for comparison. Open [The Triad](/learn/concepts/triad) — it opens with "Imagine you're moving into a new house with hundreds of boxes." That's the 14-year-old opening. Then it moves to the question test table, spec references (§3.1), and deployment form details. Same pattern: metaphor → mechanism → self-reference.
The campaign voice guide codifies this: "Warm and precise, anti-jargon-first. Channel the Feynman principle." The voice applies to every file, and the quality gates ensure it's not just aspirational. For the reusable form of this discipline, see the [Dual-Audience Writing](/patterns/dual-audience-writing) pattern.
## Related
- [Governance Files](/learn/concepts/governance-files) — where CLAUDE.md and README.md demonstrate the agent/human audience split
- [The Triad](/learn/concepts/triad) — a foundational concept that models the dual-audience pattern in its own content
- [The Knowledge Graph](/learn/concepts/knowledge-graph) — the connected structure that dual-audience files navigate through links
---
## https://adna.network/learn/concepts/fair-metadata/
# FAIR Metadata — aDNA Concepts
```mermaid
graph LR
F["Findable\nkeywords + identifier"] --> A["Accessible\nopen license + URI"]
A --> I["Interoperable\nshared vocabulary"]
I --> R["Reusable\nprovenance + license"]
```
*FAIR: four requirements for knowledge objects that can be shared*
## Overview
FAIR is a simple four-question test: can someone else **F**ind your work, **A**ccess it, **I**nteroperate with it, and **R**euse it? aDNA bakes that test into every piece of project knowledge — from individual tools to whole workflows — by wrapping them in a short metadata envelope. Without it, a piece of work stays trapped inside one project; with it, the same piece becomes discoverable, trustworthy, and composable by anyone who speaks the standard.
## Why This Matters
Imagine a library with no catalog, no call numbers, and no standard format for book titles. The books are there, but nobody can find them, nobody knows if they can borrow them, and nobody knows if a book from one library will make sense in another. That's what a knowledge project looks like without metadata standards.
FAIR fixes this with four simple questions:
- **Findable** — Can someone searching for this knowledge discover it? (keywords, identifiers)
- **Accessible** — Can they get to it once they've found it? (license, access protocol)
- **Interoperable** — Can they use it alongside knowledge from other sources? (standard formats, schemas)
- **Reusable** — Can they build on it for new purposes? (provenance, clear licensing)
These aren't abstract ideals. They're practical requirements with concrete fields in every aDNA object. A lattice without `fair.license` cannot be shared across instances — federation validation will reject it. A module without `fair.keywords` is invisible to search. FAIR metadata isn't documentation overhead; it's the infrastructure of trust.
## How It Works
### Two FAIR Formats
aDNA uses two representations of the same FAIR data, depending on context (§6):
| Format | Where Used | Structure | Example |
|--------|-----------|-----------|---------|
| **Flat FAIR** | `.lattice.yaml`, `.dataset.yaml` | Compact, single-level `fair:` block | `fair.license: "MIT"` |
| **Nested FAIR** | Vault `.md` frontmatter | Hierarchical, grouped by principle | `fair.findable.keywords: [...]` |
The flat form is machine-optimized — compact for YAML transport. The nested form is human-optimized — grouped by the FAIR principle each field serves. Both are round-trip safe for core fields: `flat → nested → flat` produces identical output.
### Field Reference
| Flat FAIR Field | Nested FAIR Path | Required | FAIR Principle |
|----------------|------------------|----------|---------------|
| `fair.keywords` | `fair.findable.keywords` | **Yes** | Findable |
| `fair.license` | `fair.accessible.license` | **Yes** | Accessible |
| `fair.identifier` | `fair.findable.identifier` | No | Findable |
| `fair.creators` | (body section) | No | Accessible |
| `fair.provenance` | `fair.reusable.provenance` | No | Reusable |
| `fair.location` | `fair.accessible.location` | No | Accessible |
| `fair.access_protocol` | `fair.accessible.access_protocol` | No | Accessible |
| `fair.format` | `fair.interoperable.format` | No | Interoperable |
| `fair.schema` | `fair.interoperable.schema` | No | Interoperable |
**Two fields are always required**: `keywords` (at least one) and `license` (SPDX identifier). These are the minimum viable FAIR envelope — enough for basic findability and legal clarity.
### FAIR in Practice: The Federation Gate
FAIR metadata isn't just descriptive — it's a functional gate. When a lattice attempts to federate (share across aDNA instances), six readiness checks must pass (§11). Three are FAIR checks:
| Check | FAIR Field | Why |
|-------|-----------|-----|
| License declared | `fair.license` | No license = no legal basis for sharing |
| Keywords present | `fair.keywords` | No keywords = invisible to search |
| Provenance documented | `fair.provenance` | No provenance = unverifiable origin |
A lattice can be technically perfect — valid schema, clean edges, efficient nodes — and still fail federation because it lacks a two-word license field. FAIR metadata is the difference between "works locally" and "works everywhere."
### Access Protocol Values
The `access_protocol` field uses a controlled vocabulary:
| Value | Meaning | Example |
|-------|---------|---------|
| `direct` | Local filesystem access | Files in vault |
| `api` | REST or gRPC endpoint | Cloud-hosted model |
| `request` | Manual access request required | Restricted dataset |
| `https` | Web-accessible URL | Public resource |
| `container` | Docker/OCI image | Packaged runtime |
### The Type Vocabulary Connection
The `format` field in FAIR metadata uses aDNA's 19-type vocabulary (§7) — the same type system used for module inputs and outputs. This ensures interoperability: a dataset declared as `pdb_structure` format will match a module expecting `pdb_structure` input.
## See It In Action
FAIR metadata is visible throughout this vault:
**Lattice YAML files**: Open any `.lattice.yaml` in `what/lattices/examples/` — every one has a `fair:` block with `license`, `keywords`, `creators`, and `provenance`. This is flat FAIR in its natural habitat.
**Context file frontmatter**: Look at the frontmatter of any context file — e.g., `what/context/adna_core/context_adna_core_paradigm_overview.md`. The `sources` field is provenance. The `tags` field serves the findability role that `keywords` serves in YAML objects.
**Federation examples**: The `docking_assessment` example lattice at `what/lattices/examples/` carries both `fair` and `federation` blocks — showing how FAIR metadata enables a lattice to move from one project to another with trust intact.
**The FAIR mapping guide**: The complete interconversion specification between flat and nested FAIR lives at `what/context/adna_core/context_adna_core_fair_mapping.md` — itself a context file demonstrating the optimization principles described in [Context Optimization](/learn/concepts/context-optimization).
## Related
- [Lattice Composition](/learn/concepts/lattice-composition) — the workflow composition that FAIR metadata makes shareable and trustworthy
- [Ontology](/learn/concepts/ontology) — the entity types (module, dataset, lattice) that carry FAIR envelopes
- [Context Commons](/learn/concepts/context-commons) — the vision of community-shared knowledge that FAIR principles enable
- [Open Standard](/learn/concepts/open-standard) — how FAIR metadata fits into aDNA's broader open governance model
---
## https://adna.network/learn/concepts/governance-files/
# Governance Files — aDNA Concepts
```mermaid
graph TD
CLAUDE["CLAUDE.md — Agent master context"]
MANIFEST["MANIFEST.md — Project overview"]
STATE["STATE.md — Operational state"]
AGENTS["AGENTS.md — Directory guide"]
README["README.md — Human entry point"]
CLAUDE --> MANIFEST & STATE
AGENTS -.->|"per directory"| CLAUDE
```
*The five root governance files every aDNA project carries*
## Overview
Every aDNA project has five ALLCAPS governance files at its root — CLAUDE.md, MANIFEST.md, STATE.md, AGENTS.md, and README.md. Together, they form the orientation layer: the minimum an agent or human needs to read before doing useful work.
## Why This Matters
Think about your first day at a new job. You don't start by reading every document in the company wiki. Instead, someone gives you a few key things: a welcome packet explaining the company's structure (MANIFEST), the current priorities and what's happening right now (STATE), a guidebook for how things are organized around here (AGENTS), a quick-start guide written for people like you (README), and — most importantly — the operating manual with the ground rules (CLAUDE).
That's exactly what governance files do for AI agents. An agent arrives at a new project cold — no prior context, no memory of previous sessions, no idea what matters. Governance files give it the same orientation a good onboarding program gives a new employee: structure, state, rules, and a path to start contributing.
The key insight is *ordering*. An agent doesn't need everything at once — it needs the right things in the right sequence. CLAUDE.md first (structure and rules), then STATE.md (current situation), then it's ready to work. The other files are available when needed. This sequencing is what makes cold-start orientation fast instead of overwhelming.
## How It Works
### The Five Files
The aDNA Standard §4.1 defines five governance files, each with a distinct purpose and update cadence:
| File | Required | Purpose | Who Reads It | Update Cadence |
|------|----------|---------|--------------|----------------|
| **CLAUDE.md** | MUST | Agent root context — persona, project map, safety rules, startup protocol | Agents (auto-loaded) | When structure or protocols change |
| **MANIFEST.md** | MUST | Static project overview — what the project IS, architecture, entry points | Agents + Humans | When scope or architecture changes |
| **STATE.md** | SHOULD | Dynamic operational state — current phase, blockers, next steps | Agents + Humans | Every session close-out |
| **AGENTS.md** | MUST | Per-directory agent guide — purpose, key files, naming patterns | Agents | When directory structure changes |
| **README.md** | MUST | Per-directory human guide — navigation, context, useful links | Humans | When onboarding experience changes |
### Two Audiences, Two Paths
The five files divide into two orientation paths (§4.2, §4.6):
**Agent cold-start** (§4.2): CLAUDE.md → STATE.md → `how/sessions/active/` → `who/coordination/` → create session → begin work. Total: ~5K tokens.
**Human cold-start**: README.md → MANIFEST.md → browse the triad → STATE.md. Total: a few minutes of reading.
The agent path is token-optimized — it loads only what's needed to begin contributing. The human path is narrative — it builds understanding through exploration.
### CLAUDE.md: The Auto-Loaded Root
CLAUDE.md is special. Claude Code auto-loads it at session start, making it the guaranteed first read. The standard requires five sections (§4.2):
1. **Identity** — project name, persona, mission statement
2. **Project Map** — directory structure, key files
3. **Safety Rules** — collision prevention, escalation, data integrity
4. **Agent Protocol** — startup checklist, session tracking, closure requirements
5. **Quickstart** — concise cold-start sequence for both agents and humans
Because it's auto-loaded, CLAUDE.md carries a unique responsibility: it must be comprehensive enough to orient a fresh agent, but compact enough to leave room in the context window for actual work. This is the [token selection](/learn/concepts/token-selection) problem in its purest form.
### AGENTS.md: The Per-Directory Guide
While CLAUDE.md exists only at root, AGENTS.md appears in every directory where agents operate (§4.5). Each one answers three questions:
- **What's here?** — purpose and contents of this directory
- **What are the rules?** — naming conventions, required frontmatter, behavioral constraints
- **Should I load this?** — the load/skip decision that enables [convergent narrowing](/learn/concepts/convergence)
AGENTS.md files grow through progressive enrichment: they start lightweight and accumulate detail as agents and humans repeatedly need information that isn't documented yet.
### STATE.md: The Living Snapshot
STATE.md is the dynamic counterpart to CLAUDE.md's static structure. It answers "where are we right now?" — current phase, active blockers, recent decisions, what's working, and what to do next.
The pair works like a compass and a GPS. CLAUDE.md is the compass — it tells you the lay of the land and the rules of navigation. STATE.md is the GPS — it tells you where you are and where to go next. Together, they give an agent complete orientation in ~3K tokens.
## See It In Action
You're inside a vault that demonstrates every governance file:
- **CLAUDE.md** — open `aDNA.aDNA/CLAUDE.md` and you'll see the Rosetta persona, the project map, safety rules, standing orders, and the startup checklist. This file is ~4K tokens and gives a fresh agent everything it needs to begin.
- **STATE.md** — open `aDNA.aDNA/STATE.md` and you'll see the current campaign phase, recent session results, active blockers, and the next-session prompt. It changes every session.
- **MANIFEST.md** — open `aDNA.aDNA/MANIFEST.md` for the static project overview — what Operation Rosetta is, the ontology extensions, architecture decisions.
- **AGENTS.md** — look at `what/concepts/AGENTS.md`, the file governing this very directory. It tells agents when to load concept files and when to skip them, what naming conventions to follow, and what quality gates apply.
- **README.md** — open `aDNA.aDNA/README.md` for the human-friendly orientation that explains what this project is and how to explore it.
Notice the layering. CLAUDE.md references STATE.md for current state. STATE.md references campaign docs for detail. Campaign docs reference missions. Missions reference the files they produce. Each layer narrows the scope, following the [convergence model](/learn/concepts/convergence).
## Related
- [The Triad](/learn/concepts/triad) — the three-leg structure that governance files orient agents to
- [Token Selection](/learn/concepts/token-selection) — how governance files balance comprehensiveness with context budget
- [Convergence Model](/learn/concepts/convergence) — how AGENTS.md load/skip decisions implement convergent narrowing
- [Ontology](/learn/concepts/ontology) — the entity types that governance files describe and govern
- [Create Your First CLAUDE.md](/learn/tutorials/first-claude-md) — hands-on: build the root governance file step by step
---
## https://adna.network/learn/concepts/knowledge-graph/
# The Knowledge Graph — aDNA Concepts
```mermaid
graph LR
concept["Concept"] <-->|"uses"| pattern["Pattern"]
concept <-->|"taught by"| tutorial["Tutorial"]
tutorial <-->|"references"| glossary["Glossary Entry"]
pattern <-->|"assembled into"| lattice["Lattice"]
```
*aDNA vault as knowledge graph — files are nodes, wikilinks are edges*
## Overview
An aDNA vault is not a filing cabinet — it's a knowledge graph. Files are nodes, wikilinks are edges, and AGENTS.md files are the navigation layer that helps agents traverse the graph efficiently. The structure is simultaneously a directory tree (for humans browsing) and a connected graph (for agents reasoning about relationships).
## Why This Matters
Picture two ways to organize a cookbook. In a filing cabinet, you'd sort recipes by category — appetizers in one folder, desserts in another. Need a chocolate soufflé? Open "Desserts," flip through. Simple.
Now picture the same recipes as a web. The chocolate soufflé links to "tempering chocolate" (a technique), which links to "dark chocolate" (an ingredient), which links to "molten lava cake" (a related recipe). You can follow any thread. The web doesn't just store recipes — it captures *how they relate*.
An aDNA vault works like the web, not the cabinet. Every file links to related files via wikilinks. A concept file links to the patterns that apply it. A mission links to the context it consumes. A session links to the mission it executes. The result is a navigable graph where you can start anywhere and follow connections to build understanding.
This matters for AI agents because agents don't browse — they load. An agent arriving at a cold start needs to figure out which of the vault's potentially hundreds of files are relevant to the current task. The knowledge graph, combined with AGENTS.md navigation guides, lets agents traverse from their entry point to exactly the subgraph they need — without loading everything.
## How It Works
### Three Layers of Connection
The knowledge graph operates at three layers, each serving a different navigation purpose:
**Layer 1: Wikilinks (content edges)**
Wikilinks are explicit connections between content files. They create the fine-grained relationship web:
```markdown
See [The Triad](/learn/concepts/triad) for the organizing principle.
This pattern applies [the question test](/patterns/question-test).
```
This vault enforces a minimum of 2 cross-links per content file as a campaign quality gate (Rosetta Standing Order 10) — it is not a requirement of the aDNA Standard itself. This prevents orphan nodes — files that exist in isolation, disconnected from the graph. In Obsidian's graph view, a healthy vault looks like a dense web; an unhealthy one looks like scattered dots.
**Layer 2: AGENTS.md (navigation nodes)**
Every directory has an AGENTS.md file that acts as a navigation hub for that part of the graph (§4.5). Each AGENTS.md provides:
- **What's here** — purpose of this directory and its contents
- **Working rules** — naming conventions, required frontmatter, behavioral constraints
- **Load/skip decision** — when to descend into this directory vs. skip it entirely
The load/skip decision is the critical piece for agents. It answers: "Given what I'm doing right now, is the content in this directory worth the token cost of loading?" This turns the directory tree into a decision tree — agents prune irrelevant branches before they waste context window.
**Layer 3: The ontology artifact (structural map)**
At the vault level, an ontology diagram (§5.1) maps entity types, triad categories, and their relationships as a Mermaid ER diagram. This is the graph's schema — not the individual nodes, but the *kinds* of nodes and how they connect:
```
campaigns → contain → missions
missions → tracked by → sessions
sessions → may produce → coordination notes
pipelines → produce → context
```
Agents use the ontology to reason about the graph's structure without loading its contents. If an agent knows it needs context files, it knows to look under `what/context/` without traversing the full tree.
### Context Serving as Graph Traversal
When an agent starts a session, it doesn't load the entire vault. It performs a targeted graph traversal:
1. **Entry point**: CLAUDE.md → STATE.md (always loaded, ~3K tokens)
2. **Navigation**: Follow AGENTS.md load/skip decisions to relevant directories
3. **Selection**: Load specific files based on mission objectives and context recipes
4. **Budgeting**: Stay within the token budget (~75% of context window for content, 25% for reasoning)
This is the convergence model in practice — each step narrows the loaded subgraph, reducing token count while increasing signal density. A vault might contain 200 files totaling 300K tokens, but a focused session loads only the 10-15 files (maybe 20K tokens) that are relevant to its current objective.
### Graph Health
A healthy knowledge graph has these properties:
- **Connected** — no orphan files (every file has 2+ inbound or outbound links)
- **Navigable** — AGENTS.md files provide load/skip guidance at every junction
- **Typed** — every node has a `type` field, enabling structural queries
- **Budgeted** — token estimates on AGENTS.md and context files enable cost-aware traversal
An unhealthy graph has orphan files nobody links to, directories without AGENTS.md guides, or content files without type metadata. These gaps create dead ends for agents — places where traversal stalls because there's no guidance on what's relevant.
## See It In Action
This vault is a live knowledge graph. Here's how the connections work in practice:
**This file** (`concept_knowledge_graph.md`) links to [the triad](/learn/concepts/triad) and [the ontology](/learn/concepts/ontology) — because you can't understand the graph without understanding what the nodes are (entity types) and how they're organized (triad legs). Those files link back here, forming a connected triangle.
**The AGENTS.md** in this directory (`what/concepts/AGENTS.md`) tells agents: "Load this directory when creating or reviewing concept documentation. Skip when working on operational infrastructure." That's a load/skip decision — an agent working on a campaign plan would skip this directory entirely, saving ~10K tokens of context window.
**The campaign mission board** (`how/campaigns/campaign_rosetta/campaign_rosetta.md`) links missions to the concept files they produce, the context files they consume, and the quality gates they must pass. That's the graph connecting operational entities (HOW) to knowledge entities (WHAT).
Open Obsidian's graph view on this vault and you'll see the web forming. Every concept links to related concepts and patterns. Every mission links to its deliverables. The graph is the navigational substrate — the structure that makes the vault more than a folder of files.
## Related
- [The Triad](/learn/concepts/triad) — the three-leg structure that organizes the graph's nodes
- [Ontology](/learn/concepts/ontology) — the entity types that define what kinds of nodes exist
- [Convergence Model](/learn/concepts/convergence) — how graph traversal narrows context for focused work
---
## https://adna.network/learn/concepts/lattice-composition/
# Lattice Composition — aDNA Concepts
```mermaid
graph LR
A["Lattice A — Data retrieval"] -->|"seam edge"| C["Composed Lattice"]
B["Lattice B — Reasoning"] -->|"seam edge"| C
C --> D["Artifact or Result"]
```
*Lattice composition connects smaller workflows into larger pipelines*
## Overview
Big jobs are usually too big for one workflow. Lattice composition is how aDNA snaps smaller workflows together to make bigger ones — the same way a dinner recipe is built from smaller recipes for the sauce, the vegetables, and the main. A lattice is a directed graph of nodes (modules, datasets, processes) connected by edges (data flow); composition combines lattices through two patterns — inline merging and external referencing — which is what makes them reusable, shareable, and scalable.
## Why This Matters
Think of it like cooking. A recipe for a full dinner isn't one monolithic instruction — it's composed from sub-recipes. The salad dressing is its own recipe. The roasted vegetables are their own recipe. The dinner recipe combines them, specifying how the salad dressing goes on the salad and the vegetables go alongside the main course.
Lattices work the same way. A protein drug discovery pipeline might involve structure prediction, binding analysis, and ranking — each a complex workflow in its own right. Rather than writing one enormous pipeline from scratch, you compose it from smaller, tested lattices. The structure prediction team maintains their lattice. The binding analysis team maintains theirs. The pipeline team composes them, specifying how data flows between them.
This is powerful for three reasons. First, each piece can be developed, tested, and improved independently. Second, pieces can be shared across projects — a structure prediction lattice is useful in many pipelines, not just one. Third, composition makes complexity manageable — you can understand a 50-node workflow as 5 composed lattices of 10 nodes each, not as one flat graph.
## How It Works
### The Lattice YAML Structure
Every lattice is declared in a `.lattice.yaml` file that validates against the schema at `what/lattices/lattice_yaml_schema.json`. The core elements (§5.1):
| Element | Purpose | Required |
|---------|---------|----------|
| `lattice.name` | Unique identifier (`snake_case`) | Yes |
| `lattice.version` | Semantic version | Yes |
| `lattice.lattice_type` | Category: `pipeline`, `agent`, `context_graph`, `workflow`, `skill`, `infrastructure`, `context_set` | Yes |
| `execution.mode` | Runtime behavior: `sequential`, `parallel`, `hybrid` | Yes |
| `nodes[]` | The processing units (modules, datasets, processes, checkpoints) | Yes |
| `edges[]` | Data flow connections between nodes | Yes (for 2+ nodes) |
| `fair` | FAIR metadata block (license, keywords, provenance) | Yes |
### Seven Lattice Types
| Type | Purpose | Execution Mode | Example |
|------|---------|---------------|---------|
| `pipeline` | Sequential data processing | `sequential` or `hybrid` | Protein binder design |
| `agent` | LLM-driven reasoning loops | `hybrid` | Decision-making workflows |
| `context_graph` | Knowledge retrieval and reasoning | varies | Knowledge base assembly |
| `workflow` | Orchestrated multi-step operations | `hybrid` | Deep research pipeline |
| `skill` | Promoted Claude skill as lattice | varies | Published agent recipe |
| `infrastructure` | Physical/network topology | varies | Cluster configuration |
| `context_set` | Domain overlay inheriting from base | varies | Disease-specific pipeline |
### Two Composition Patterns
When combining lattices, you choose between two patterns (§11):
**Inline composition** — child nodes merge into the parent with namespace prefixes.
| Property | Detail |
|----------|--------|
| Child visibility | All child nodes become first-class in parent |
| Node naming | `{child_name}_{node_id}` |
| Token cost | +N tokens (all child nodes materialized) |
| Best when | Parent needs fine-grained access to child internals |
| Seam edges | Required: parent → child entry node, child exit → parent |
**External reference** — child appears as a single opaque node with a `lattice://` URI.
| Property | Detail |
|----------|--------|
| Child visibility | Internal structure hidden |
| Node type | `module` with `ref: lattice://instance/name` |
| Token cost | +1 node (single opaque reference) |
| Best when | Parent treats child as black-box |
| Seam edges | Required: edges to/from opaque node with `data_mapping` and `port` |
**Default recommendation**: External reference. It minimizes token cost while preserving composability. Use inline only when the parent genuinely needs to inspect or modify child internals.
### Seam Edges
Seam edges are the connectors between composed lattices. They require explicit data mapping — no implicit pass-through:
```yaml
edges:
- from: parent_design_step
to: docking_assessment # opaque child node
label: "designed sequences for validation"
data_mapping:
sequences: input_sequences # explicit field mapping
port: structure_prediction # child entry node
```
Rules: at least one edge into the child's entry and one out of its exit. Every seam edge needs `data_mapping`. External references need `port` to identify which child node receives the data.
### Federation Readiness
For a lattice to be composable across aDNA instances (not just within one project), it must pass six readiness checks (§11):
| Check | Requirement |
|-------|------------|
| Schema valid | Passes `lattice_validate.py` |
| Opt-in | `federation.shareable: true` |
| Provenance | `federation.source_instance` set |
| License | `fair.license` declared |
| Findable | `fair.keywords` has at least 1 entry |
| References resolve | All `ref` fields are valid paths or URIs |
## See It In Action
This vault contains the full lattice infrastructure at `what/lattices/`:
**Schema**: `what/lattices/lattice_yaml_schema.json` — the JSON Schema that all lattice files validate against. Open it to see the `nodes`, `edges`, `federation`, and `fair` block definitions.
**Examples**: `what/lattices/examples/` contains validated lattice files covering all types and composition patterns. The `docking_assessment` example demonstrates external reference federation — it was extracted from a larger `protein_binder_design` pipeline and carries `federation.parent_lattice` provenance.
**Validation tools**: `what/lattices/tools/lattice_validate.py` checks schema compliance, node ID uniqueness, edge reference validity, and federation property consistency. Run it against any `.lattice.yaml` to verify composition correctness.
**The vault itself is a context graph**: The knowledge structure you're navigating — concepts linking to concepts, AGENTS.md routing agents through directories — is a `context_graph` lattice. The nodes are files. The edges are wikilinks and AGENTS.md references. The execution mode is agent-driven graph traversal.
## Related
- [Ontology](/learn/concepts/ontology) — the entity types (module, dataset, lattice) that serve as lattice building blocks
- [Knowledge Graph](/learn/concepts/knowledge-graph) — the broader connected structure that lattices formalize as declarative YAML
- [FAIR Metadata](/learn/concepts/fair-metadata) — the metadata envelope that makes lattices findable, shareable, and reusable
- [Open Standard](/learn/concepts/open-standard) — how federation enables lattice composition across independent aDNA instances
---
## https://adna.network/learn/concepts/ontology/
# The Ontology — aDNA Concepts
```mermaid
graph LR
WHO --> governance & team & coordination & identity
WHAT --> context & decisions & modules & lattices & inventory
HOW --> campaigns & missions & sessions & templates & skills & pipelines & backlog
```
*16 base entity types organized across the aDNA Triad*
## Overview
The aDNA ontology is a typed vocabulary of 16 base entity types — organized across the triad — that defines what kinds of things a project can contain. Projects extend the ontology by adding domain-specific types without modifying the base.
## Why This Matters
Think of a library. Every book has a category — fiction, biography, science, history. Librarians don't invent a new system for every library; they use a shared classification that everyone understands. When you walk into any library in the world, you already know roughly where to look.
aDNA's ontology works the same way. It defines 16 "categories" — called entity types — that cover the operational needs of any project: things like `context` (research notes), `missions` (plans), `sessions` (work logs), and `governance` (rules). Every file in the vault has a `type` field in its metadata that says what kind of thing it is.
The real power is extensibility. The 16 base types handle operations, but your project probably has domain-specific things too — patients, experiments, customers, models. You add those as extensions under the appropriate triad leg, and they inherit the same conventions: typed frontmatter, AGENTS.md guides, templates. The base vocabulary is shared; the extensions are yours.
## How It Works
### The 16 Base Entity Types
The aDNA Standard defines 16 base types distributed across the triad (§5.1–5.3; `inventory` and `identity` were promoted from node-local extensions to base at v2.3, per ADR-035). Every type has a home directory, required frontmatter fields, and an AGENTS.md guide.
**WHO leg** (4 types):
| Type | Directory | Purpose |
|------|-----------|---------|
| `governance` | `who/governance/` | Decision rights, policies, organizational charter |
| `team` | `who/team/` | People, roles, agent identities |
| `coordination` | `who/coordination/` | Ephemeral cross-agent sync notes |
| `identity` | `who/identity/` | Stable node identity — hostname, operator, peer and signing-key refs |
**WHAT leg** (5 types):
| Type | Directory | Purpose |
|------|-----------|---------|
| `context` | `what/context/` | Pre-synthesized domain knowledge for agents |
| `decisions` | `what/decisions/` | Architecture Decision Records (ADRs) |
| `modules` | `what/modules/` | Atomic computation units (tools, models) |
| `lattices` | `what/lattices/` | Composition graphs connecting modules and datasets |
| `inventory` | `what/inventory/` | Installed and configured state — vaults, system, memberships |
**HOW leg** (7 types):
| Type | Directory | Purpose |
|------|-----------|---------|
| `campaigns` | `how/campaigns/` | Multi-mission strategic initiatives |
| `missions` | `how/missions/` | Multi-session task decompositions |
| `sessions` | `how/sessions/` | Per-invocation work records |
| `templates` | `how/templates/` | Reusable file scaffolds |
| `skills` | `how/skills/` | Documented agent recipes and procedures |
| `pipelines` | `how/pipelines/` | Content-as-code workflows |
| `backlog` | `how/backlog/` | Ideation intake and idea tracking |
The HOW leg has the most types because operations are the most varied dimension. Knowledge (WHAT) is comparatively uniform; people (WHO) are comparatively simple. This asymmetry is intentional and reflects how projects actually work.
### Extension Mechanism
The base ontology covers operational infrastructure. Domain knowledge requires custom types. The standard supports this through extension (§5.1, §5.3):
1. **Choose the triad leg.** Apply the question test — does this domain entity represent something you *know*, something about *how you work*, or something about *who is involved*?
2. **Create the directory.** Add a new subdirectory under the appropriate leg: `what/experiments/`, `who/adopters/`, etc.
3. **Add an AGENTS.md.** Every entity type directory gets an agent guide explaining purpose, naming conventions, and working rules.
4. **Create a template.** Add `template_{type}.md` to `how/templates/` so new instances are structurally consistent.
5. **Use the `type` prefix.** Files follow the `type_descriptive_name.md` pattern (§6.1): `experiment_pcr_optimization.md`, `adopter_research_lab.md`.
Extensions inherit all base conventions: frontmatter requirements (§7), naming rules (§6), session tracking (§8). They compose with the existing infrastructure rather than replacing it.
### The Type Field
Every content file in an aDNA vault MUST include a `type` field in its YAML frontmatter (§7.2). This field is the machine-readable identity of the entity:
```yaml
---
type: concept
created: 2026-04-13
status: active
---
```
The `type` field enables filtering, validation, and template matching. Combined with the `type_` filename prefix, it provides both human-scannable and machine-queryable identification.
## See It In Action
This vault demonstrates both the base ontology and the extension mechanism. The 16 base types power the operational infrastructure you see in `how/` — campaigns, missions, sessions, templates, skills. But this project also added 10 custom types to teach aDNA:
| Extension | Leg | Directory | Purpose |
|-----------|-----|-----------|---------|
| `concept` | WHAT | `what/concepts/` | Core aDNA concepts (this file is one) |
| `tutorial` | WHAT | `what/tutorials/` | Step-by-step learning paths |
| `pattern` | WHAT | `what/patterns/` | Reusable architectural patterns |
| `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 has its own AGENTS.md, its own template in `how/templates/`, and follows the same conventions as the base types. Open any of those directories and you'll see the pattern: purpose statement, naming rules, frontmatter requirements, load/skip decision guide. The extension mechanism is uniform — new types slot in without modifying the base.
## Related
- [The Triad](/learn/concepts/triad) — the three-leg structure that the ontology populates
- [Knowledge Graph](/learn/concepts/knowledge-graph) — how typed entities connect into a navigable web
- [Convergence Model](/learn/concepts/convergence) — how the ontology enables context narrowing
- [Extend the Ontology](/learn/tutorials/extend-the-ontology) — hands-on: add a custom entity type to your vault
---
## https://adna.network/learn/concepts/open-standard/
# Open Standard — aDNA Concepts
```mermaid
graph TD
spec["aDNA Standard — adna_standard.md"]
impl["Your Vault"]
forge["Forge"]
platform["Platform"]
spec -->|"implements"| impl
spec -->|"builds tools"| forge
spec -->|"deploys with"| platform
```
*One open spec; many implementations — vaults, forges, and platforms all inherit*
## Overview
aDNA is an open standard — a publicly documented specification that anyone can implement, extend, and build upon without permission or payment. The upstream spec (aDNA Standard v2.5, published at `github.com/aDNA-Network/aDNA`) defines the normative rules. Individual projects implement the standard, extending it for their domain while maintaining compatibility with the shared core.
## Why This Matters
Think about how roads work. Every country has roads, but they all follow standards — lane widths, traffic signs, signal colors. You don't need permission to build a road. You don't pay a license to put up a stop sign. The standards exist so that a driver from one city can navigate another city's roads without relearning everything. And any city can add its own features — bike lanes, roundabouts, local signage — as long as the core conventions hold.
aDNA works the same way. The standard defines the basics: the what/how/who triad, governance files, session tracking, FAIR metadata. Any project can implement these basics and get a working AI-native knowledge architecture. Then each project extends for its domain — a biotech lab adds molecular entity types, a startup adds customer personas, a research group adds publication workflows. The extensions are different, but the core is shared. An agent that understands one aDNA project can orient in any other.
This is the opposite of a proprietary platform. There's no vendor lock-in, no subscription, no permission required. The spec is public. The template is forkable. The standard is built to grow through community contribution rather than a corporate roadmap — proposals run through the public repository.
## How It Works
### The Spec/Implementation Split
aDNA maintains a clear separation between the standard (what's normative) and implementations (what projects build):
| Layer | What It Is | Who Controls It | Example |
|-------|-----------|----------------|---------|
| **Upstream spec** | aDNA Standard v2.5 — normative rules using RFC 2119 keywords (MUST, SHOULD, MAY) | Founding-Architect stewardship, in public (github.com/aDNA-Network/aDNA) | "Every instance MUST use the what/how/who triad" |
| **Base template** | `.adna/` — ready-to-fork implementation of the spec | Upstream maintainers | Governance files, triad directories, templates, skills |
| **Project instance** | A forked and customized aDNA project | Project owner | This vault (`aDNA.aDNA/`), any `.aDNA/` project |
The spec defines the rules. The template makes them easy to adopt. The instance is where real work happens. Changes flow downstream (spec → template → instance) but discoveries flow upstream (instance finds a gap → proposes improvement → spec evolves).
### Base/Extension Architecture
The standard defines 16 base entity types organized across the triad (§5). These are the shared vocabulary — every aDNA project speaks this language:
| Triad Leg | Base Entities | Count |
|-----------|--------------|-------|
| WHO | `governance`, `team`, `coordination`, `identity` | 4 |
| WHAT | `context`, `decisions`, `modules`, `lattices`, `inventory` | 5 |
| HOW | `campaigns`, `missions`, `sessions`, `templates`, `skills`, `pipelines`, `backlog` | 7 |
Projects extend by adding domain-specific entity types under the appropriate triad leg. Extensions MUST NOT modify base types — they add alongside them:
| Extension | Triad | Added By |
|-----------|-------|----------|
| `concept`, `tutorial`, `pattern`, `glossary_entry` | WHAT | This vault (aDNA.aDNA) |
| `community`, `adopter` | WHO | This vault |
| `workshop`, `publishing` | HOW | This vault |
This base/extension architecture means any aDNA-aware tool can understand the base layer of any project, even if it doesn't know the extensions. Interoperability by default.
### Federation: Interoperability in Action
The federation protocol (§11) is where the open standard becomes practically useful across project boundaries. It defines:
- **A URI scheme** (`lattice://instance/lattice_name/node_id`) for cross-instance references
- **A 5-capability lifecycle** (validate → export → share → import → compose) for lattice exchange
- **Ontology unification** (a 4-step merge algorithm) for combining entity types from different instances
- **Version policies** (locked, patch, minor, latest) for managing dependency drift
Federation doesn't require a central authority. Two aDNA instances can share lattices directly, peer-to-peer, using the standard's conventions. The only requirements are FAIR metadata (for trust) and schema compliance (for compatibility).
### The Fork-and-Extend Pattern
Adopting aDNA follows a consistent pattern:
1. **Fork** the base template (`.adna/`) into a new project directory
2. **Customize** governance files (CLAUDE.md persona, MANIFEST.md identity, STATE.md operational context)
3. **Extend** the ontology with domain-specific entity types
4. **Populate** with domain knowledge, workflows, and team information
5. **Federate** when ready to share lattices, context, or patterns with other instances
The fork creates a new instance that's immediately compatible with the standard. The customization makes it yours. The extension makes it domain-specific. The federation makes it part of the broader ecosystem.
## See It In Action
This vault is a living demonstration of the open standard in practice:
**The base template**: The directory `adna/` (one level up from this project in the workspace) contains the upstream template. It's symlinked as `.adna/` at the workspace root. This vault was forked from it — you can compare this project's structure against the template to see what's base and what's extension.
**Extensions**: This vault adds 11 entity types to the base 16 (see `what/concepts/AGENTS.md`, `what/tutorials/AGENTS.md`, `who/community/AGENTS.md`, etc.). Each extension follows the same patterns as the base — AGENTS.md, templates, frontmatter conventions — because the standard defines how to extend, not just what the base contains.
**Spec citations**: Throughout this vault, normative claims reference the upstream spec with section numbers (§3, §5, §10). This file you're reading cites §1, §3, §5, and §11. The vault demonstrates; the spec defines. This separation is the standard in action.
**The standing rule**: This vault's CLAUDE.md contains the rule "Never modify `.adna/` or `adna/`" — enforcing the spec/implementation boundary. The template is read-only. The instance is writable. That's the architecture of an open standard: shared core, local freedom.
## Related
- [The Triad](/learn/concepts/triad) — the universal organizing principle defined by the spec that every implementation shares
- [Governance Files](/learn/concepts/governance-files) — the five files the spec mandates for agent orientation
- [FAIR Metadata](/learn/concepts/fair-metadata) — the metadata standard that enables trust in federated exchanges
- [Ontology](/learn/concepts/ontology) — the base/extension type system the spec defines and projects customize
---
## https://adna.network/learn/concepts/token-selection/
# Token Selection — aDNA Concepts
```mermaid
graph LR
A["Vault — all files"] -->|"filter by campaign"| B["Campaign scope"]
B -->|"filter by mission"| C["Mission files"]
C -->|"filter by objective"| D["Session context"]
D -->|"fit in window"| E["Active tokens"]
```
*Token selection narrows the knowledge loaded at each stage*
## Overview
Token selection is the discipline of choosing which knowledge to load into an AI agent's context window — and, critically, which knowledge to leave out. aDNA provides structured mechanisms (AGENTS.md routing, context recipes, token budgets) to make this selection systematic rather than ad hoc.
## Why This Matters
Imagine you're studying for a history exam. You have 300 pages of notes, but the exam is in two hours. You can't read everything — you need to pick the 30 pages that matter most. If you pick well, you ace the test. If you pick poorly or try to read all 300, you run out of time and remember nothing clearly.
AI agents face exactly this problem on every task. They have a fixed-size "working memory" called the context window — typically enough room for 50,000 to 200,000 tokens of text. A real project might contain 500,000 tokens of knowledge across hundreds of files. Loading everything doesn't work: the agent drowns in information, loses track of what's relevant, and produces worse output. Loading nothing doesn't work either: the agent hallucinates or misses critical context.
Token selection is the art of the middle path — loading exactly the knowledge an agent needs for its current task, at the right level of detail, without wasting space on irrelevant material. It's what separates an agent that produces generic output from one that produces informed, project-specific work.
## How It Works
### The 75% Rule
The aDNA Standard establishes a hard constraint: agents SHOULD reserve at least 25% of their context window for reasoning (§8.7). This means knowledge loading — governance files, context files, mission plans, the task itself — must fit within 75% of the available space.
| Window Size | 75% Budget | Typical Allocation |
|-------------|------------|-------------------|
| 100K tokens | 75K | ~5K governance + ~15K context + ~5K mission + ~50K working space |
| 200K tokens | 150K | ~5K governance + ~30K context + ~5K mission + ~110K working space |
The 25% reasoning reserve ensures the agent has room to think, not just room to remember.
### Three Selection Mechanisms
aDNA provides three complementary mechanisms for token selection:
**1. AGENTS.md routing (§4.5)**
Every directory has an AGENTS.md with a **load/skip decision** — a brief statement telling agents whether this directory's content is relevant to their current task. When an agent navigates the vault, it reads AGENTS.md at each junction and decides whether to descend or skip. This turns the directory tree into a decision tree, pruning irrelevant branches before they consume tokens.
**2. Context recipes (`what/context/context_recipes.md`)**
For multi-topic tasks, pre-defined recipes list exactly which context subtopics to load, at three budget tiers:
| Tier | Budget | Use When |
|------|--------|----------|
| Minimal | <5K tokens | Task is narrow, you know the domain |
| Standard | <12K tokens | Typical development session |
| Full | All subtopics | Deep research or comprehensive review |
Recipes prevent the common failure mode of loading too much "just in case."
**3. Token estimates on files**
Context files and AGENTS.md files carry `token_estimate` fields in their frontmatter. This lets agents make cost-aware loading decisions: "This file costs ~2K tokens — is it worth it for the current objective?"
### The Loading Protocol
Combining these mechanisms, an agent's loading sequence looks like:
1. **CLAUDE.md** — auto-loaded (~2-4K tokens). Non-negotiable.
2. **STATE.md** — current operational state (~1-2K tokens). Nearly always loaded.
3. **Campaign/mission docs** — task framing (~2-3K tokens). Loaded when executing mission work.
4. **Context files** — domain knowledge (~5-20K tokens). Selected via AGENTS.md routing and context recipes.
5. **Working files** — the actual files being created or modified. Variable.
Each step is a selection decision: load this, skip that. The governance files (steps 1-2) are almost always loaded because they're compact and universally useful. Domain context (step 4) is where the real selection discipline applies — and where the [convergence model](/learn/concepts/convergence) earns its keep.
### Signal Density
Not all tokens are equal. A well-written context file packs more decision-relevant information per token than a rambling one. aDNA measures this as **signal density** — one of six quality axes in the context quality rubric (§10):
| Signal Density | Description |
|---------------|-------------|
| 5 | Every sentence drives a decision or action |
| 4 | Occasional filler, mostly actionable |
| 3 | Mixed signal and background |
| 2 | More background than signal |
| 1 | Mostly filler |
Token selection isn't just about *which* files to load — it's about ensuring the files themselves are worth loading. Tables over prose. Principles over preambles. Decisions over descriptions.
## See It In Action
This vault demonstrates token selection at every level:
**AGENTS.md routing**: Open `what/concepts/AGENTS.md` — it tells agents to load this directory when working on concept documentation and to skip it when working on operational infrastructure. An agent building a mission plan would never load this file, saving ~15K tokens.
**Token estimates**: Look at any context file's frontmatter — e.g., `what/context/adna_core/context_adna_core_convergence_model.md` carries `token_estimate: ~500`. An agent can decide whether 500 tokens of convergence model context is worth it for its current task.
**Campaign context budget**: The campaign master doc (`how/campaigns/campaign_rosetta/campaign_rosetta.md`) declares its total context budget: ~5K campaign context + ~15K domain context + ~2-3K per mission. This budget discipline keeps sessions focused.
**The CLAUDE.md itself**: This vault's CLAUDE.md is ~4K tokens — comprehensive enough to orient a cold agent, compact enough to leave room for work. That's token selection applied to governance: every section earns its space.
## Related
- [Convergence Model](/learn/concepts/convergence) — the structural principle that makes token selection scale across campaign → mission → objective
- [Governance Files](/learn/concepts/governance-files) — the orientation layer that consumes the first ~5K tokens in every session
- [Knowledge Graph](/learn/concepts/knowledge-graph) — the connected structure that AGENTS.md routing traverses during selection
---
## https://adna.network/learn/concepts/triad/
# The Triad — aDNA Concepts
```mermaid
graph LR
WHAT["what/ — Knowledge"] <-->|"informs"| HOW["how/ — Operations"]
HOW <-->|"reports to"| WHO["who/ — People"]
WHO <-->|"scopes"| WHAT
```
*The aDNA Triad — every project's three organizing directories*
## Overview
The triad is aDNA's universal organizing principle: every piece of project knowledge belongs in exactly one of three directories — `what/`, `how/`, or `who/` — determined by which question it answers.
## Why This Matters
Imagine you're moving into a new house with hundreds of boxes. You could label them by room (kitchen, bedroom, bathroom), or you could just stack them randomly in the garage and hunt for things later. aDNA's triad is the labeling system — but instead of rooms, it uses three questions:
- **What do we know?** — facts, research, reference material, decisions
- **How do we work?** — plans, processes, templates, session logs
- **Who is involved?** — people, teams, roles, coordination notes
Every document, every note, every piece of context fits under exactly one question. There's no ambiguity, no "miscellaneous" drawer. A new team member — human or AI agent — can walk into any aDNA project and immediately know where to find things, because the structure is always the same.
Three categories is the sweet spot. Two would be too coarse (you'd constantly ask "but is this a knowledge thing or an operations thing?"). Four or more creates sorting paralysis ("does this go in Knowledge, Reference, Context, or Documentation?"). Three maps cleanly to the three dimensions every project has: its knowledge, its operations, and its people.
## How It Works
The triad is defined in the aDNA Standard §3.1 as the **what/how/who ontology**. It is normative: every conformant aDNA instance MUST organize content into these three top-level directories.
### The Three Legs
| Leg | Question Test | Contains | Spec Reference |
|-----|--------------|----------|----------------|
| `what/` | WHAT does this project know? | Context library, decisions, domain entities, reference material | §5.1 |
| `how/` | HOW does this project work? | Missions, sessions, templates, pipelines, skills, backlog | §5.3 |
| `who/` | WHO is involved? | Governance policies, team records, coordination notes | §5.2 |
### The Question Test
When you're unsure where a file belongs, apply the **question test** (§3.1): "Is this about WHAT we know, HOW we work, or WHO is involved?"
| Content | Question | Triad Leg |
|---------|----------|-----------|
| A research summary on ancient DNA extraction | WHAT do we know? | `what/context/` |
| A mission plan for building a documentation site | HOW do we work? | `how/missions/` |
| A note coordinating handoff between two agents | WHO is involved? | `who/coordination/` |
The test always produces exactly one answer. If it feels ambiguous, the content is trying to do two things — split it.
### Deployment Forms
The triad has two physical layouts (§3.2–3.4):
- **Bare triad** — `what/`, `how/`, `who/` sit at project root. Used when aDNA IS the primary content (knowledge bases, documentation vaults).
- **Embedded triad** — the triad lives inside `.agentic/` at repo root. Used when adding agent support to an existing codebase.
The ontology is identical in both forms. Only the nesting differs.
### Why Three?
The standard is explicit about this (§3.1): "Three categories are sufficient because they map to the three dimensions of any project: its knowledge, its operations, and its people. Additional categories create sorting ambiguity."
This isn't arbitrary minimalism — it's a design constraint. Every project, from a solo research notebook to a multi-team enterprise platform, has exactly these three dimensions. The triad makes them explicit and navigable.
## See It In Action
You're inside a working triad right now. Look at the root of this vault (`aDNA.aDNA/`):
```
aDNA.aDNA/
├── what/ ← You are here (what/concepts/concept_triad.md)
├── how/ ← Campaigns, missions, sessions, templates, skills
└── who/ ← Governance, coordination
```
This file — `concept_triad.md` — lives in `what/concepts/` because it answers the question "WHAT does this project know?" It knows about the triad. The mission plan that scheduled the creation of this file lives in `how/campaigns/campaign_rosetta/missions/` because it answers "HOW does this project work?" The governance policies that define how agents operate live in `who/governance/` because they answer "WHO is involved and what authority do they have?"
The structure demonstrates itself. Navigate up two levels from this file and you'll see the triad in the directory listing. That's the point — the architecture is visible, not hidden behind abstractions.
## Related
- [Ontology](/learn/concepts/ontology) — the entity types that populate each triad leg
- [Knowledge Graph](/learn/concepts/knowledge-graph) — how triad contents connect into a navigable web
- [Governance Files](/learn/concepts/governance-files) — the five ALLCAPS files that orient agents to the triad
- [Navigate an aDNA Vault](/learn/tutorials/navigate-a-vault) — hands-on: explore a live triad in 15 minutes
---
## https://adna.network/learn/course/
# Intro to your new aDNA graph
A course for anyone who has just been handed an aDNA workspace and is not yet sure what they are
looking at. Each lesson is short, ends in something you do rather than something you read, and
assumes no prior knowledge — if you can find a folder on your computer, you can start here.
Every lesson also says what *your agent* will do with what you just learned. That second
half is the point: you are not learning a note-taking system, you are learning how to set up the
context an AI assistant reads before it helps you.
0 of 2 lessons complete
2 lessons, about 20 minutes end to end. Your progress is remembered in this browser — no account, nothing sent anywhere.
## Orientation — what all of this is
Start here. These lessons build the vocabulary everything else uses.
[1. What is an aDNA graph? 10 min — A folder of plain text your AI assistant reads as its memory — and the one question that tells you where anything belongs in it.](/learn/course/what-is-an-adna-graph)[2. The four files your agent reads first 10 min — CLAUDE.md, STATE.md, MANIFEST.md, AGENTS.md — what each one is for, and where to look when you want to know what to work on next.](/learn/course/four-files-your-agent-reads-first)
---
## https://adna.network/learn/course/four-files-your-agent-reads-first/
# The four files your agent reads first
orientation 10 min
By the end of this lesson you can:
- Say what each of the four governing files is for
- Find the answer to “what should I work on next?” without reading the whole graph
- Tell the difference between a rule that persists and a state that changes
## Four files, four jobs
A graph can hold hundreds of files. Four of them govern, and an assistant reads those before
anything else. Learning what each is for is most of what you need to navigate a graph you have never
seen.
### `CLAUDE.md` — the rules
This is the constitution. It says what this graph is, how work is done here, and what an assistant
must or must not do. Standing rules live here: *never change these files directly*, *always open a
session record before editing*, *route questions about the machine itself somewhere else*.
The test for whether something belongs in `CLAUDE.md` is durability. If it should still be true in
six months, it is a rule. If it is true this week, it is state, and it belongs in the next file.
### `STATE.md` — what is happening right now
The live snapshot. What is in progress, what is blocked, what happens next. This file changes
constantly, and that is the point of keeping it separate from the rules — mixing the two produces a
constitution nobody trusts, because half of it is stale by Thursday.
**This is where you look when you sit down and think “where was I?”** A well-kept graph answers that
in one short read near the top of the file, and the habit of keeping it accurate is the single
highest-value thing you can do for whoever opens the folder next. That person is often you, in three
weeks, having forgotten everything.
### `MANIFEST.md` — the identity card
Short and stable. What this graph is called, what kind of graph it is, what version of the standard
it follows. You will rarely edit it after the first day. Other graphs read it when they need to know
what they are dealing with.
### `AGENTS.md` — local conventions
Guidance scoped to one directory. A graph can have many of these, and each applies only inside its
own folder: how to name things here, what this directory is for, what to be careful about.
They exist so the top-level rules can stay short. Detail that only matters inside one folder should
live in that folder, not in the file every single session has to read.
## Rules, state, identity, local detail
That is the whole shape, and the split is doing real work:
FileAnswersChanges
`CLAUDE.md`”What are the rules here?”Rarely
`STATE.md`”What is happening right now?”Constantly
`MANIFEST.md`”What is this thing?”Almost never
`AGENTS.md`”What applies in this folder?”Occasionally
Put a rule in the state file and it gets lost in the churn. Put state in the rules file and people
stop believing the rules. The separation is not bureaucracy; it is what keeps each file worth
reading.
## What your agent does with this
Your assistant reads these in a deliberate order, and knowing the order tells you where to put things
so they actually get used.
It loads the governing file first, because that sets the rules for everything that follows. It reads
the state file to find out what is live. Then — and only then — it goes looking for the specific
context your request needs, guided by what those two files told it. When it enters a subdirectory, it
picks up that directory’s local guidance.
The practical consequence: **anything you want your assistant to always do belongs in the governing
file, not in a note buried three folders down.** A rule the assistant never reads is a rule that does
not exist. Likewise, keeping the state file honest is not paperwork — it is the difference between an
assistant that resumes your work and one that has to ask you what is going on every time.
## Check yourself
You want to know what the project is currently working on and what is blocked. Which file? CLAUDE.md STATE.md MANIFEST.md AGENTS.md
STATE.md is the live snapshot — current work, blockers, and what comes next. It changes constantly, which is exactly why it is kept separate from the rules.
Your team decides that nobody may change the database schema without a review. Where does that rule belong? CLAUDE.md — it governs how work is done here STATE.md — it is current MANIFEST.md — it is a fact about the project Nowhere; rules like that are not written down
CLAUDE.md holds the standing rules an assistant must follow in this graph. A rule that should still be true in six months does not belong in the file that describes this week.
What is MANIFEST.md for? A running log of every change The identity card — what this graph is, what it is called, what kind of thing it is Instructions for humans only A list of everyone with access
MANIFEST.md is identity and metadata: the graph's name, its type, its version. Short, stable, and the thing other graphs read when they need to know what they are looking at.
You add a note to a subdirectory and want to explain the local conventions for that directory specifically. Which file? A second CLAUDE.md STATE.md An AGENTS.md in that directory A comment at the top of every file
AGENTS.md gives directory-local guidance — the conventions that apply inside one part of the graph. It keeps the top-level rules from swelling with detail that only matters in one folder.
You open a fresh session and want to know where to pick up. What is the fastest honest route? Read every file in what/ first Ask the assistant to guess from the code Read STATE.md, which names the current work and the next step Check the most recently modified file
STATE.md exists to answer exactly this. A graph that keeps it current can be resumed in seconds; one that lets it rot forces everyone to reconstruct the situation from scratch.
Check my answers
Try "The four files your agent reads first" in Claude Code
Claude Code is Anthropic's official CLI (a terminal tool for AI-assisted development). Run this tutorial step by step with AI assistance — ask questions, get unstuck, and go deeper on any concept.
`npm install -g @anthropic-ai/claude-code`
Last updated 2026-09-03 [Edit this page](https://github.com/aDNA-Network/aDNA.aDNA/edit/main/site/src/content/course/four-files-your-agent-reads-first.md)
---
## https://adna.network/learn/course/what-is-an-adna-graph/
# What is an aDNA graph?
orientation 10 min
By the end of this lesson you can:
- Explain an aDNA graph to someone else in one sentence
- Name the three parts of the triad and say what each one holds
- Use the Question Test to decide where a new piece of knowledge belongs
## Start with the folder
Someone has handed you a directory. Inside it are more directories, and inside those are text files.
No app, no database, no login screen. It looks like the least impressive thing you have ever been
given.
Here is the one-sentence version of what it actually is:
> **An aDNA graph is a folder of plain text that an AI assistant reads as its memory before it helps
you.**
That is the whole idea. When you open a conversation with an assistant in this folder, it reads the
files first, and then it already knows what your project is, how your team does things, and who
decides what. You do not have to explain yourself again every morning.
The files are ordinary Markdown — the same thing a README is. You can read every one of them with
nothing but a text editor. Nothing is compiled, nothing is hidden, and if the tooling vanished
tomorrow you would still have everything, because the knowledge was never inside the tool.
## Why a folder and not an app
Three reasons, and they are worth understanding rather than taking on faith.
**You can read it.** A system that stores your team’s knowledge somewhere you cannot inspect is a
system you have to trust. Text in a folder is knowledge you can check. Open a file, disagree with
it, fix the sentence.
**Your version control already handles it.** Text files diff, review, and revert. The history of how
your understanding changed is the same history as your code — same tools, same review, no separate
product to buy.
**Assistants are good at text.** This is the practical part. An AI assistant reads Markdown natively
and well. Structuring your knowledge as text is not a compromise to make the machine happy; it is
the format both of you are best at.
## The triad
Open the folder and you will find three directories that show up in every graph:
- **`what/`** — what we know. Facts, decisions, specifications, reference material. Things that are
true about your project.
- **`how/`** — how we do things. Procedures, workflows, the record of work in progress. Things you
follow or perform.
- **`who/`** — who is involved. People, roles, identity, and the messages passing between separate
graphs.
That is it. Three drawers. Nearly everything you will ever add belongs cleanly in one of them, and
the reason the split works is that it matches the three kinds of question people actually ask.
## The Question Test
When you have a new piece of knowledge and you are not sure where to put it, do not guess. Turn it
into a question and see which one it sounds like:
The question you are answeringWhere it goes
”What do we know?”`what/`
”How do we do it?”`how/`
”Who is involved?”`who/`
“Our staging environment runs on the same database version as production” answers *what do we know*.
It is a fact. It goes in `what/`.
“Deploy by merging to the main branch, then watching the health dashboard for ten minutes” answers
*how do we do it*. It is a procedure. It goes in `how/`.
“Priya reviews anything that touches authentication” answers *who is involved*. It goes in `who/`.
The test takes about two seconds and it is right the overwhelming majority of the time. When it is
genuinely ambiguous, that is usually a sign the note is doing two jobs and wants to be two notes.
## What your agent does with this
Here is the half that makes the folder more than tidy filing.
When you ask your assistant to do something, it does not read the entire folder — that would be slow
and expensive, and most of it would be irrelevant. It reads the governing files first, works out
which part of the graph your request touches, and then loads only that part.
So the triad is not decoration. It is how the assistant narrows down. A question about your release
process sends it to `how/`, and it never has to wade through `what/` to find out. A well-sorted graph
makes your assistant faster and more accurate, and a folder where everything is dumped in one place
makes it slower and vaguer. The Question Test is the small daily habit that keeps it sorted.
## Try it
Think of one thing you know about your current project that nobody has written down — a quirk, a
rule, a person to ask. Say it out loud as a question. Which drawer does it want?
Then do the check below.
## Check yourself
Which database does our billing service use? Choose one… what/how/who/
What are the steps for shipping a release? Choose one… what/how/who/
Who has to approve a change to the pricing page? Choose one… what/how/who/
What does our payment system send back when a card is declined? Choose one… what/how/who/
How do we get a new teammate set up on their first day? Choose one… what/how/who/
Which team owns the search feature? Choose one… what/how/who/
What is our target for test coverage this quarter? Choose one… what/how/who/
How do we undo a release that broke something? Choose one… what/how/who/
Check my answers
Try "What is an aDNA graph?" in Claude Code
Claude Code is Anthropic's official CLI (a terminal tool for AI-assisted development). Run this tutorial step by step with AI assistance — ask questions, get unstuck, and go deeper on any concept.
`npm install -g @anthropic-ai/claude-code`
Last updated 2026-09-03 [Edit this page](https://github.com/aDNA-Network/aDNA.aDNA/edit/main/site/src/content/course/what-is-an-adna-graph.md)
---
## https://adna.network/learn/tutorials/
# Tutorials
9 hands-on tutorials, each producing a concrete outcome. Grouped by difficulty — start at **Beginner** if new to aDNA, or jump to **Intermediate** if you already have a vault and a CLAUDE.md.
## Beginner — Start here (≈ 50 min total)
Three tutorials to build your foundation. **Start with [Navigate an aDNA Vault](/learn/tutorials/navigate-a-vault)** (no prerequisites), then Create Your First CLAUDE.md, then Apply the Question Test. By the end: a working vault, a CLAUDE.md, and a way to classify any piece of project knowledge.
[Create Your First CLAUDE.md 20 minutes — A working CLAUDE.md file — the master governance document that tells AI agents who they are, what rules to follow, and how your project is…](/learn/tutorials/first-claude-md)[Navigate an aDNA Vault 15 minutes — Nothing — this is a guided tour. By the end, you'll understand how an aDNA vault is organized and be able to find any piece of knowledge within…](/learn/tutorials/navigate-a-vault)[Apply the Question Test 15 minutes — A sorted inventory of 10 project items placed into the correct triad leg. By the end, you'll be able to instantly sort any new file into what/…](/learn/tutorials/question-test)
## Intermediate — Build it out (≈ 80 min total)
For vaults already running. Add curated context, domain-specific entity types, and mission decomposition. Any order; sequence here is recommended.
[Design a Mission 25 minutes — A mission file that decomposes a multi-session task into claimable objectives. By the end, any agent can pick up your mission, understand what…](/learn/tutorials/design-a-mission)[Extend the Ontology 25 minutes — A new entity type for your project — complete with a directory, AGENTS.md, template, and your first instance file. By the end, your vault speaks…](/learn/tutorials/extend-the-ontology)[Write a Context File 30 minutes — A quality-scored context file ready for your vault's context library. By the end, you'll have a file that an AI agent can load to make better…](/learn/tutorials/write-a-context-file)
## Advanced — Scale and connect (≈ 90 min total)
Compose executable workflows, run phased campaigns, share lattices across instances. Prerequisites: at least one Beginner + one Intermediate tutorial.
[Build a Lattice 30 minutes — A validated .lattice.yaml file that defines a workflow as a directed graph of nodes and edges. By the end, you'll have a composable…](/learn/tutorials/build-a-lattice)[Adopt via the Exchange: Pull → Build-to-Spec → Memorialize 35 minutes — Walk the full aDNA adoption arc end-to-end: pull a shared piece of work, build it to the standard, and memorialize where it came from.](/learn/tutorials/exchange-adoption-path)[Federate a Vault 30 minutes — A federated connection between two aDNA instances — exporting a lattice from one project, importing it into another, and composing it into a…](/learn/tutorials/federate-a-vault)[Run a Campaign 30 minutes — A campaign document with phased execution, a mission board, and quality gates. By the end, you'll have a strategic plan that can coordinate…](/learn/tutorials/run-a-campaign)
---
## https://adna.network/learn/tutorials/build-a-lattice/
# Build a Lattice — aDNA Tutorial
## What You'll Build
A validated `.lattice.yaml` file that defines a workflow as a directed graph of nodes and edges. By the end, you'll have a composable, FAIR-annotated lattice ready for execution or federation.
## Prerequisites
- [Lattice Composition](/learn/concepts/lattice-composition) — types, nodes, edges, composition patterns
- [Ontology](/learn/concepts/ontology) — the entity types that serve as lattice building blocks
- [FAIR Metadata](/learn/concepts/fair-metadata) — the metadata envelope every lattice needs
## Steps
### Step 1: Define the Workflow
Sketch your workflow as nodes and data flow. Example — a data analysis pipeline:
```
Collect Data → Clean Data → Analyze → Visualize → Report
```
Each box becomes a node. Each arrow becomes an edge.
### Step 2: Choose the Lattice Type
| If your workflow... | Choose | Execution Mode |
|---------------------|--------|---------------|
| Processes data through stages | `pipeline` | `sequential` |
| Makes decisions and loops | `agent` | `hybrid` |
| Retrieves and reasons over knowledge | `context_graph` | varies |
| Orchestrates multiple sub-processes | `workflow` | `hybrid` |
Our data analysis pipeline is a `pipeline` with `sequential` execution.
### Step 3: Write the YAML
Create `my_analysis.lattice.yaml`:
```yaml
lattice:
name: data_analysis
version: "1.0.0"
lattice_type: pipeline
description: "End-to-end data analysis from collection to report"
execution:
mode: sequential
runtime: local
tier: L1
nodes:
- id: collect_data
type: process
description: "Gather raw data from sources"
- id: clean_data
type: module
ref: "what/modules/module_data_cleaner"
description: "Remove duplicates, handle missing values"
- id: analyze
type: module
ref: "what/modules/module_statistical_analysis"
description: "Run statistical analysis on clean data"
- id: visualize
type: module
ref: "what/modules/module_chart_generator"
description: "Generate charts and figures"
- id: report
type: process
description: "Compile findings into a report"
edges:
- from: collect_data
to: clean_data
label: "raw data"
- from: clean_data
to: analyze
label: "clean dataset"
data_mapping:
clean_output: analysis_input
- from: analyze
to: visualize
label: "statistical results"
- from: visualize
to: report
label: "charts and figures"
fair:
license: "MIT"
keywords: [data-analysis, pipeline, statistics]
creators: ["Your Name"]
provenance: "Built for quarterly data reporting"
```
**Key decisions**:
- Node IDs are `snake_case` and descriptive (not `node_1`, `step_a`)
- `module` nodes have `ref` pointing to implementations; `process` nodes are human/agent steps
- Edges use `data_mapping` for explicit field mapping
- The `fair` block has at least `keywords` and `license`
### Step 4: Validate
Run the schema validator:
```bash
python what/lattices/tools/lattice_validate.py my_analysis.lattice.yaml
```
Fix any errors: missing required fields, invalid node references, disconnected nodes.
### Step 5: Add Federation Metadata (Optional)
If you want to share this lattice with other projects:
```yaml
federation:
shareable: true
source_instance: my_project
version_policy: minor
```
This enables the lattice to be imported and composed into other vaults. See the [federation readiness](/patterns/federation-readiness) checklist.
### Step 6: Validate Again
Re-run validation after adding federation properties — the validator checks federation consistency too.
## What You Learned
- Lattices are declarative graphs: nodes + edges + metadata (§5.1)
- [Four types](/learn/concepts/lattice-composition) cover all workflow patterns
- [FAIR metadata](/learn/concepts/fair-metadata) is required — `keywords` and `license` minimum
- Explicit `data_mapping` on edges prevents implicit assumptions
## Next Steps
- [Run a Campaign](/learn/tutorials/run-a-campaign) — orchestrate multi-mission work
- [Federate a Vault](/learn/tutorials/federate-a-vault) — share lattices across instances
- [Federation Readiness](/patterns/federation-readiness) — prepare for cross-instance sharing
---
## https://adna.network/learn/tutorials/design-a-mission/
# Design a Mission — aDNA Tutorial
## What You'll Build
A mission file that decomposes a multi-session task into claimable objectives. By the end, any agent can pick up your mission, understand what needs to be done, and start working on the next objective.
## Prerequisites
- [Convergence Model](/learn/concepts/convergence) — how the execution hierarchy narrows scope
- [Mission Decomposition](/patterns/mission-decomposition) — the pattern for breaking work into objectives
- [Token Selection](/learn/concepts/token-selection) — context budgets for mission-scoped work
## Steps
### Step 1: Define the Task
Start with what you're trying to accomplish. Write it as a single sentence:
> "Write 8 pattern files documenting reusable aDNA architectural patterns."
If the sentence describes work that can fit in one session (2-4 hours of agent work), it might not need a mission — just do it. If it spans multiple sessions or involves distinct deliverables, it's a mission.
### Step 2: Identify Deliverables
List every concrete output the mission produces:
| # | Deliverable | File |
|---|------------|------|
| 1 | Question test pattern | `what/patterns/pattern_question_test.md` |
| 2 | AGENTS.md routing pattern | `what/patterns/pattern_agents_md.md` |
| 3 | Base/extension pattern | `what/patterns/pattern_base_extension.md` |
| ... | ... | ... |
**The rule**: every objective must name a specific file or artifact. "Research token optimization" is not an objective. "Write `concept_context_optimization.md`" is.
### Step 3: Map Dependencies
Some objectives must be completed before others. Map the dependency graph:
```
Objective 1 (foundational concepts)
↓
Objective 2 (governance concepts — resolves forward refs from Obj 1)
↓
Objective 3 (advanced concepts — builds on Obj 1+2 cross-links)
```
If there are no dependencies, objectives can be worked in any order. If there are, document them — an agent claiming Objective 3 needs to know that Objectives 1 and 2 must be done first.
### Step 4: Estimate Context Budget
For each objective, estimate what context needs to be loaded:
```markdown
## Context Dependencies
- `what/context/adna_core/context_adna_core_paradigm_overview.md` (~1K tokens)
- `what/context/adna_core/context_adna_core_context_engineering.md` (~1K tokens)
- M01-M02 concepts for cross-linking (~5K tokens)
- Campaign and mission docs (~5K tokens)
- **Total**: ~12K tokens → fits within 75% rule for 100K window
```
If the total exceeds what a session can hold, the mission has too many objectives or needs to be split.
Write the total onto the mission as `token_budget_estimated`. It is not decoration: the number decides the shape of the work — under 50K is one session, 80K–200K is two or three, and 200K or more means the mission should be split rather than run. See [Budgeting and Routing a Mission](/patterns/mission-decomposition#budgeting-and-routing-a-mission) for the formula the estimate comes from.
### Step 4b: Declare the Model Tier
Beside the budget, declare which class of model runs the work:
```yaml
token_budget_estimated: "~12K tokens"
executor_tier: sonnet # the class of model this mission is routed to
```
Pick the tier from what the work *decides*, not from how big it is. Novel design, ambiguous requirements, and anything irreversible or outward-facing go to the judgment class. Well-briefed execution inside stated guardrails goes to the middle class. Sweeps, counts and format fixes go to the mechanical class.
A mission is only safe to run on a cheaper model if Steps 1–4 have already been done properly — the tier you can afford is decided by the quality of the brief, not the other way round.
### Step 5: Write the Mission File
Put it all together using this structure:
```markdown
---
type: plan
plan_id: mission_m04
campaign_id: campaign_rosetta
title: "M04 — Pattern Library"
status: pending
phase: 1
created: 2026-04-14
updated: 2026-04-14
last_edited_by: agent_stanley
tags: [mission, patterns]
token_budget_estimated: "~12K tokens"
executor_tier: sonnet
---
# Mission M04 — Pattern Library
## Intent
{One paragraph: what the mission accomplishes and why it matters.}
## Objectives
| # | Objective | File | Status |
|---|-----------|------|--------|
| 1 | Write question test pattern | pattern_question_test.md | pending |
| 2 | Write AGENTS.md pattern | pattern_agents_md.md | pending |
## Context Dependencies
{List what to load before starting work.}
## Quality Gates
{What must be true before marking an objective complete.}
## Dependencies
{Which missions must be done first.}
```
### Step 6: Validate the Design
| Check | Pass? |
|-------|-------|
| Every objective names a specific deliverable | |
| Dependencies are mapped (or stated as "none") | |
| `token_budget_estimated` is declared, and its band matches the session shape | |
| `executor_tier` is declared, and the brief is good enough to justify it | |
| Intent is clear enough for a fresh agent to understand | |
| Quality gates are defined | |
| No objective requires more than one session | |
**See it in action**: Open `how/campaigns/campaign_rosetta/missions/mission_m04_pattern_library.md` in this vault. It has 8 objectives across 4 pattern categories, context dependencies listed with specific file paths, and quality gates matching the campaign standard.
## What You Learned
- Missions decompose multi-session work into claimable, session-sized objectives
- Every objective needs a named deliverable — not just a description of activity
- Context budgets determine whether the mission is correctly scoped — and the session that runs the mission logs `token_budget_actual` beside your estimate, so the two can be compared at the After-Action Review
- The model tier is declared before the work, not chosen during it
- The mission file is a self-contained briefing: any agent can pick it up and work
## Next Steps
- [Build a Lattice](/learn/tutorials/build-a-lattice) — compose a workflow from modules (advanced)
- [Convergence Model](/learn/concepts/convergence) — deeper understanding of how missions narrow scope
- [Context Recipe](/patterns/context-recipe) — pre-define the context assembly for common mission types
---
## https://adna.network/learn/tutorials/exchange-adoption-path/
# Adopt via the Exchange — aDNA Tutorial
## What You'll Do
Walk the full aDNA adoption arc as one honest, end-to-end path: **pull** a shared piece of work, **build it to the standard**, and **memorialize** where it came from so the next person can trust and reuse it. By the end you will have run a real validation against a shipped lattice and read a real machine verdict — that validated lattice plus its readiness result is your concrete outcome.
This is an *honesty-first* tutorial. Some steps run today exactly as written; some describe a capability that is designed and partly built but not yet exercisable from this vault. **Every step is labeled** so you always know which is which:
- **`PASS`** — you can run this right now, in this vault, and get the result shown.
- **`TAUGHT-AS-DESIGN`** — this is how the capability works by design; the boundary that stops it from running *here, today* is named explicitly. Nothing is narrated as if it runs when it doesn't.
> **Why the labels?** aDNA's whole promise is context you can trust. A tutorial that pretends a horizon feature already ships would betray exactly the trust the standard is built to protect. So we teach the shipped subset for real and name the horizon plainly — the same framing the [educators use-case](/use-cases/educator) settled on: *teach the roadmap as the horizon, never as a shipped feature.*
## Prerequisites
- [Lattice Composition](/learn/concepts/lattice-composition) — nodes, edges, inline vs. external composition, and the readiness idea
- [FAIR Metadata](/learn/concepts/fair-metadata) — the license/keywords/provenance envelope that makes shared work trustworthy
- [Build a Lattice](/learn/tutorials/build-a-lattice) — how to author a `.lattice.yaml` from scratch (this tutorial *reuses* one instead)
- [Federate a Vault](/learn/tutorials/federate-a-vault) — the export/import mechanics this arc sits on top of
New to aDNA vaults entirely? Start at [Navigate an aDNA Vault](/learn/tutorials/navigate-a-vault) first — this is an advanced tutorial and assumes you can already read a vault.
---
## The three beats, in one picture
The Exchange is aDNA's distribution substrate — think of it as an app store for *context and workflows* instead of apps. Adoption through it is a loop:
```
┌─────────┐ ┌──────────────┐ ┌───────────────┐
│ PULL │ ───▶ │ BUILD-TO-SPEC │ ───▶ │ MEMORIALIZE │
│ (get a │ │ (make it │ │ (record where │
│ piece) │ │ conformant) │ │ it came from)│
└─────────┘ └──────────────┘ └───────────────┘
▲ │
└──────────────────────────────────────────────┘
the memorialized result becomes
the next person's pull
```
Each beat below is walked at its real maturity.
---
## Beat 1 — Pull
**In plain language:** *pulling* means getting a ready-made piece of work — a lattice (a workflow) or a context graph (a body of knowledge) — that someone else already built and shared, so you don't start from a blank page.
**Why it matters:** the expensive part of agentic work isn't running a workflow, it's *knowing which workflow is any good.* A pull lets you start from something already validated and provenance-stamped by someone who solved the problem before you.
### Step 1.1 — Pull from the Exchange registry · `TAUGHT-AS-DESIGN`
The documented product surface for a pull is the `latlab` registry CLI (see this vault's `CLAUDE.md` §Registry Awareness and `skill_lattice_publish`, the authoritative recipe):
```bash
# By design: download a published lattice by name from the registry
latlab lattice pull knowledge_base
# ...optionally pinned to a version
latlab lattice pull knowledge_base --version 1.0.0
```
**Why this is `TAUGHT-AS-DESIGN` and not `PASS`:** the aDNA registry is **local-first** (`MarketplaceRegistry`), and *nothing has ever been published from this vault* — that first publish is deliberately deferred as an outward-facing action pending operator ratification. So a `pull` here has nothing real to fetch. And **cross-node** exchange — pulling a lattice a *different* node published — rides the network's opt-in membership substrate, which is still being built. Exchange.aDNA's own state is honest about this: the tier-0 pilot (Agora I) is complete and registry-based composition works within a node; cross-node distribution is the *horizon*, not a shipped feature.
### Step 1.2 — Start from a shipped example (the runnable stand-in) · `PASS`
You don't need a populated registry to learn the arc — this vault *ships* a library of validated lattices you can treat exactly as if you had just pulled them. There are 19 example lattices at `what/lattices/examples/`. Pick the `context_graph` one, since "pulling shared knowledge" is its whole reason for existing:
```bash
# From the vault root — copy the "pulled" lattice into your working area
cp what/lattices/examples/knowledge_base.lattice.yaml /tmp/pulled_lattice.lattice.yaml
```
This is a real file — a five-node retrieval-and-reasoning workflow (`document_corpus → indexer → retriever → reasoner`, plus a `query_input`). Open it and read it; that is your "pulled" artifact for the rest of the walk.
> **Substitution note:** copying a shipped example is a faithful stand-in for a registry pull because the *shape of the artifact is identical* — the same `.lattice.yaml` a real pull would deliver. Only the transport (registry lookup vs. local copy) differs.
---
## Beat 2 — Build-to-Spec
**In plain language:** you rarely use a pulled piece exactly as-is. You adapt it, then you *check it against the standard* so it stays trustworthy and composable. That check is the heart of this tutorial — and it runs for real.
**Why it matters:** "build to spec" is what stops a shared ecosystem from rotting into a pile of half-broken files. A lattice that passes validation and the publish-readiness checks is one anyone else can safely pull next.
### Step 2.1 — Validate the lattice · `PASS` (this is your executable outcome)
The validator ships in this vault as a pure-Python library (no external services, no network). Run it against your pulled lattice:
```bash
cd what/lattices/tools
python3.13 - <<'PY'
from lattice_validate import validate_lattice_file, check_federation_readiness
import yaml
p = "../examples/knowledge_base.lattice.yaml"
r = validate_lattice_file(p)
print(f"validate_lattice_file: valid={r.valid} errors={len(r.errors)} warnings={len(r.warnings)}")
for w in r.warnings:
print(" WARN:", w)
data = yaml.safe_load(open(p))
fr = check_federation_readiness(data)
print(f"check_federation_readiness: ready={fr.valid} errors={len(fr.errors)}")
PY
```
**Real output (run 2026-07-02, python 3.13.5):**
```
validate_lattice_file: valid=True errors=0 warnings=2
WARN: Node 'document_corpus': dataset node without 'ref' field
WARN: Node 'query_input': dataset node without 'ref' field
check_federation_readiness: ready=True errors=0
```
Read that carefully — it teaches two things at once:
1. **`valid=True, errors=0`** — the structure conforms to the schema at `what/lattices/lattice_yaml_schema.json` (spec §5.1).
2. **`warnings=2`** — the validator distinguishes *fatal* from *advisory*. These two datasets have no `ref` binding yet (they're placeholders a real deployment would wire to actual data). Warnings don't block you; they're the standard *telling you what's still loose* so you build it to spec deliberately instead of by accident.
### Step 2.2 — Walk the FAIR block · `PASS`
Open the `fair:` block inside your pulled lattice. This is the shipped, verbatim envelope:
```yaml
fair:
license: "MIT"
creators:
- "Lattice Labs"
keywords:
- knowledge base
- context graph
- retrieval augmented generation
- RAG
- reasoning
provenance: "Reference implementation of a context_graph lattice with reasoning-mode execution for knowledge retrieval"
```
FAIR = **F**indable, **A**ccessible, **I**nteroperable, **R**eusable ([full concept](/learn/concepts/fair-metadata)). `keywords` make it findable; `license` makes it legally reusable; `provenance` says where it came from and why. Building to spec means *never stripping this block* — it travels with the lattice so the next puller inherits the trust.
### Step 2.3 — Check publish-readiness · `PASS`
`check_federation_readiness` (run in Step 2.1) already returned `ready=True, errors=0`. That function checks the federation block for sharing. The **authoritative, single-source recipe for the registry publish-readiness checks is `skill_lattice_publish`** — follow it rather than any inline restatement.
> **Honesty note:** two teaching surfaces in this vault previously phrased the readiness list slightly differently (`CLAUDE.md` §Registry Awareness vs. [Lattice Composition](/learn/concepts/lattice-composition)). This tutorial deliberately does **not** mint a third list — it points you at `skill_lattice_publish` as the one to trust. That wording is now harmonized; the *behavior* you just ran (the validator) is unaffected.
Our pulled lattice already satisfies the gate because it carries the required federation block:
```yaml
federation:
shareable: true
source_instance: adna
version_policy: minor
```
`shareable: true` is opt-in consent; `source_instance` is provenance; `version_policy` sets how downstream pullers pin it.
### Step 2.4 — Compose it into something larger · `TAUGHT-AS-DESIGN`
Real adoption usually means *composing* your pulled lattice into a bigger workflow. aDNA offers two patterns ([Lattice Composition](/learn/concepts/lattice-composition), spec §11):
- **External reference** — the child appears as one opaque node via a `lattice://instance/name` URI. Cheapest (`+1` node), preserves black-box boundaries. **The default recommendation.**
- **Inline** — the child's nodes merge into the parent with `{child}_{node}` naming (child name, then node id). Use only when the parent must inspect child internals.
The documented command:
```bash
# By design: external composition, child stays separate, joined by a seam edge
latlab lattice compose parent.lattice.yaml knowledge_base.lattice.yaml \
--pattern external \
--seam-edges '[{"source":"parent_node","target":"kb_entry","data_mapping":[{"from":"query","to":"query_input","type":"string"}]}]'
```
**Why `TAUGHT-AS-DESIGN`:** `compose` is part of the same registry CLI surface as `pull`/`publish`; it isn't exercisable end-to-end from this vault today (the CLI is not operational here and there is no populated registry to compose *against*). The composition *rules* — external vs. inline, the seam-edge requirement, the token-cost trade-off — are fully specified and stable, so you can design against them now. To actually author and validate a composed lattice by hand, follow [Build a Lattice](/learn/tutorials/build-a-lattice) and [Federate a Vault](/learn/tutorials/federate-a-vault), which walk the file-level mechanics.
---
## Beat 3 — Memorialize
**In plain language:** *memorializing* means permanently recording what you did and where it came from, so the result is auditable — nobody has to take your word for it later.
**Why it matters:** a shared ecosystem only compounds if provenance survives every hop. Memorialization is what turns "I ran a workflow" into "here is a signed, traceable record the next person can build on."
### Step 3.1 — Inspect real extraction provenance · `PASS`
Provenance memorialization already ships in the FAIR + federation envelope. The clearest live example is `docking_assessment.lattice.yaml`, a lattice that was *extracted* from a larger pipeline and carries the receipt:
```yaml
federation:
shareable: true
source_instance: adna
parent_lattice: protein_binder_design
version_policy: locked
extracted_nodes:
- structure_prediction
- interface_analysis
- ranking
```
Read that as a memorial record: *this lattice is the `structure_prediction`, `interface_analysis`, and `ranking` nodes lifted out of `protein_binder_design`, version-locked so the extraction stays reproducible.* The validator even enforces the pairing — declare `parent_lattice` without `extracted_nodes` (or vice versa) and it errors. Provenance here isn't a comment; it's a checked field.
### Step 3.2 — The readiness verdict *is* a memorial · `PASS`
The `ready=True` verdict you produced in Step 2.1 is itself a lightweight memorial — a machine-checked statement that *this artifact met the shared bar at this moment*. Capture it (in a session log, a commit message, a walk record) and you've memorialized the build-to-spec step with real evidence, not a claim.
### Step 3.3 — Memorialize to the Protocol ledger · `TAUGHT-AS-DESIGN`
At the full-Exchange horizon, memorialization graduates from *file-local provenance* to a shared, tamper-evident **ledger**: an append-only advisory/provenance record at the Lattice Protocol layer (the draft `lattice-ledger` spec, DLT-backed). A pull, a build, and a publish would each leave an entry no one can silently rewrite.
**Why `TAUGHT-AS-DESIGN`:** the ledger lives in the Lattice Protocol's *draft* spec — it is largely design-taught, and the Protocol repo itself is pre-public-launch. Today's honest, shipped stand-in is exactly what you did in Steps 3.1–3.2: the FAIR `provenance` string plus the checked `federation` block plus your captured readiness verdict. That is real provenance you can trust now; the DLT ledger is the horizon that makes it *federated and tamper-evident* across nodes.
---
## Shipped vs. Horizon — the boundary table
Everything this tutorial touched, sorted by what runs today versus what is taught as design. (Boundaries are pinned to the live states of the relevant vaults as of 2026-07-02.)
| Capability | Status | What's real today | The horizon |
|------------|--------|-------------------|-------------|
| Validate a lattice (`lattice_validate.py`) | **SHIPPED · PASS** | Runs offline in this vault; you ran it | — |
| Publish-readiness check (`check_federation_readiness`) | **SHIPPED · PASS** | Runs offline; `ready=True` verdict | — |
| FAIR + federation provenance blocks | **SHIPPED · PASS** | In every federation-ready example; validator-enforced | — |
| Registry-based composition *within a node* | **SHIPPED (Exchange tier-0 / Agora I)** | Local-first `MarketplaceRegistry`; not exercised from this vault (no first publish yet) | — |
| `latlab lattice pull / publish / compose` from *this* vault | **HORIZON · TAUGHT-AS-DESIGN** | Documented surface; nothing published here (OoB-deferred) | First publish pending operator ratification |
| Cross-node Exchange (pull another node's work) | **HORIZON · TAUGHT-AS-DESIGN** | — | Rides the network's opt-in membership substrate, still being built |
| Adopt via **Lighthouse** (node-scale composition) | **HORIZON · TAUGHT-AS-DESIGN** | Genesis P0 closed 2026-07-01; composition manifest v1 shipped (profiles core/collab/inference/ops) | Deploys gate on Git.aDNA P7 (not yet chartered) |
| Protocol **ledger** memorialization (DLT provenance) | **HORIZON · TAUGHT-AS-DESIGN** | FAIR `provenance` + checked `federation` block are today's stand-in | Draft `lattice-ledger` spec; Protocol repo pre-public-launch |
**The takeaway:** the *spine* of the adoption arc — pull-a-real-artifact, validate it, check readiness, inspect provenance — runs end-to-end today. The *network* around it (cross-node pull, node-scale Lighthouse deploys, the DLT ledger) is designed, partly built, and honestly named as the horizon.
## See It In Action (this vault)
The structure you just used *is* the lesson — everything is here, live:
- The 19 lattices you "pulled" from: `what/lattices/examples/` (start with `knowledge_base.lattice.yaml`).
- The validator you ran: `what/lattices/tools/lattice_validate.py` — pure Python, offline, part of this vault.
- The schema it checks against: `what/lattices/lattice_yaml_schema.json` (spec §5.1).
- **The vault itself is a `context_graph` lattice** — the concepts, tutorials, and AGENTS.md routing you're navigating right now are nodes-and-edges, traversed agent-first. You didn't just *read about* a context graph; you pulled a workflow out of one.
## What You Learned
- The adoption arc is a loop: **pull → build-to-spec → memorialize**, and the memorialized result becomes the next person's pull
- The **spine runs today** — you validated a real shipped lattice and read a real machine verdict
- Provenance is a *checked field*, not a comment — the validator enforces the `parent_lattice` / `extracted_nodes` pairing
- The cross-node network layer is honestly named as the **horizon**, never as a shipped feature
## Next Steps
- [Federate a Vault](/learn/tutorials/federate-a-vault) — the export/import mechanics underneath a pull, walked at file level
- [Build a Lattice](/learn/tutorials/build-a-lattice) — author a `.lattice.yaml` from scratch instead of pulling one
- [Lattice Composition](/learn/concepts/lattice-composition) — inline vs. external composition, seam edges, readiness
- [Context Commons](/learn/concepts/context-commons) — why a populated Exchange matters: shared context as a public good
---
## https://adna.network/learn/tutorials/extend-the-ontology/
# Extend the Ontology — aDNA Tutorial
## What You'll Build
A new entity type for your project — complete with a directory, AGENTS.md, template, and your first instance file. By the end, your vault speaks your domain's language.
## Prerequisites
- [Ontology](/learn/concepts/ontology) — understand base vs. extension types
- [The Triad](/learn/concepts/triad) — know which leg your entity goes under
- [Base/Extension](/patterns/base-extension) — the rules for extending without breaking core
- [Question Test](/patterns/question-test) — how to place the new type
## Steps
### Step 1: Identify the Need
You need a new entity type when existing types can't represent your domain knowledge. Ask: "Does `context`, `decisions`, `modules`, `lattices`, `campaigns`, `missions`, `sessions`, `templates`, `skills`, `pipelines`, `backlog`, `governance`, `team`, or `coordination` cover what I need to represent?"
If no — you need an extension.
**Example**: A biotech lab needs to track experimental protocols. Protocols aren't context (they're not curated knowledge for agents), they're not templates (they're not reusable boilerplate), and they're not skills (they're not agent recipes). They're a domain-specific entity type: `protocol`.
### Step 2: Apply the Question Test
Ask: "Is a protocol about WHAT we know, HOW we work, or WHO is involved?"
A protocol documents knowledge about how to run an experiment. But its *primary purpose* is to capture knowledge — the procedure exists as reference material. That puts it under `what/`.
(If the protocol were an executable workflow an agent runs, it would be `how/`. The question test resolves ambiguity by focusing on primary purpose.)
### Step 3: Create the Directory
```bash
mkdir -p what/protocols
```
Extension types always live as a subdirectory under their triad leg. Never create a new top-level directory — the triad has exactly three legs.
### Step 4: Write the AGENTS.md
Every directory needs an AGENTS.md. Create `what/protocols/AGENTS.md`:
```markdown
---
type: directory_index
created: 2026-04-14
updated: 2026-04-14
last_edited_by: agent_stanley
tags: [directory_index, protocol]
---
# what/protocols/ — Agent Guide
## What's Here
Experimental protocols for the lab. Each file documents one protocol
with steps, reagents, safety notes, and expected outcomes.
## Working Rules
- **Naming**: `protocol_{name}.md` (underscores, lowercase)
- **Required frontmatter**: `type: protocol`, `created`, `updated`,
`status`, `last_edited_by`, `tags`
## Load/Skip Decision
**Load when**: Running or reviewing experiments, creating new protocols.
**Skip when**: Operational work, context engineering, non-lab tasks.
**Token cost**: ~200 tokens (this AGENTS.md).
```
The load/skip decision is critical — it tells agents when this directory is relevant.
### Step 5: Create the Template
Add `how/templates/template_protocol.md`:
```markdown
---
type: protocol
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: draft
last_edited_by: agent_{username}
tags: [protocol]
---
# protocol_{name}
## Purpose
{What does this protocol accomplish?}
## Steps
1. {Step one}
2. {Step two}
## Expected Outcome
{What should the result look like?}
```
Templates enforce consistency. Every protocol file will have the same structure.
### Step 6: Create Your First Instance
Create `what/protocols/protocol_dna_extraction.md` using your template. Fill in real content. Set `status: active` when it's ready for use.
### Step 7: Validate
Check your extension against the [base/extension](/patterns/base-extension) rules:
| Check | Pass? |
|-------|-------|
| New type is under a triad leg, not at root | |
| Directory has AGENTS.md with load/skip decision | |
| Template exists in `how/templates/` | |
| Frontmatter follows vault conventions (type, created, updated, status) | |
| Base types are unmodified | |
## What You Learned
- Extensions add alongside base types — never modify the core 16
- The [question test](/patterns/question-test) determines which triad leg gets the extension
- Three artifacts per extension: directory, AGENTS.md, template
- The pattern is the same for any domain: biotech protocols, legal documents, customer personas
## Next Steps
- [Write a Context File](/learn/tutorials/write-a-context-file) — create curated knowledge for your context library
- [Context Optimization](/learn/concepts/context-optimization) — make your context files token-efficient
---
## https://adna.network/learn/tutorials/federate-a-vault/
# Federate a Vault — aDNA Tutorial
## What You'll Build
A federated connection between two aDNA instances — exporting a lattice from one project, importing it into another, and composing it into a larger workflow. By the end, you'll understand the full federation lifecycle.
## Prerequisites
- [Lattice Composition](/learn/concepts/lattice-composition) — inline vs. external composition
- [FAIR Metadata](/learn/concepts/fair-metadata) — the trust envelope for shared objects
- [Open Standard](/learn/concepts/open-standard) — why federation works across independent projects
- [Federation Readiness](/patterns/federation-readiness) — the 6-point checklist
- [FAIR Envelope](/patterns/fair-envelope) — metadata for findability and reuse
## Steps
### Step 1: Prepare the Source Lattice
Start with a lattice in your project that you want to share. Run the [federation readiness](/patterns/federation-readiness) checklist:
| # | Check | Command/Action |
|---|-------|---------------|
| 1 | Schema valid | `python what/lattices/tools/lattice_validate.py my_lattice.lattice.yaml` |
| 2 | Shareable opt-in | Set `federation.shareable: true` |
| 3 | Source instance | Set `federation.source_instance: my_project` |
| 4 | License | Set `fair.license: "MIT"` (or your choice) |
| 5 | Keywords | Set `fair.keywords: [at-least-one]` |
| 6 | References resolve | Check all `ref` fields — replace local paths with `lattice://` URIs |
### Step 2: Convert Local References to URIs
Any `ref` field pointing to a local path needs to become a `lattice://` URI for cross-instance use:
```yaml
# Before (local)
ref: "what/modules/module_data_cleaner"
# After (federable)
ref: "lattice://my_project/data_cleaner_module"
```
URI format: `lattice:///[/]`
### Step 3: Export
Export the lattice using the CLI (if available) or copy the `.lattice.yaml` file:
```bash
latlab lattice publish my_lattice.lattice.yaml
```
The publish command validates, registers in the local registry, and makes it available for pull.
### Step 4: Import into the Target Project
In the target project:
```bash
latlab lattice pull my_lattice
```
This downloads the lattice and runs **ontology unification** — checking that the source's entity types are compatible with the target's. If conflicts exist, the 4-step merge algorithm resolves them (§11.3).
### Step 5: Compose into a Larger Workflow
Now compose the imported lattice into a parent workflow. You have two options:
**External reference** (recommended — minimal token cost):
```yaml
nodes:
- id: data_analysis
type: module
ref: "lattice://my_project/data_analysis"
description: "Imported data analysis pipeline"
edges:
- from: data_collection
to: data_analysis
label: "raw data for analysis"
data_mapping:
raw_data: collect_data_input
port: collect_data # child entry node
```
**Inline composition** (when you need access to child internals):
```bash
latlab lattice compose parent.lattice.yaml child.lattice.yaml --pattern inline --seam-edges '[{"from":"parent_node","to":"child_entry"}]'
```
### Step 6: Validate the Composition
Run the validator on the composed parent:
```bash
python what/lattices/tools/lattice_validate.py parent.lattice.yaml
```
Check: all seam edges have `data_mapping`, all `lattice://` URIs resolve, no orphaned nodes.
### Step 7: Set Version Policy
Choose how the target tracks source updates:
| Policy | Set When |
|--------|----------|
| `locked` | Production: no surprises |
| `patch` | Stable: accept bug fixes |
| `minor` | Active development: accept features |
| `latest` | Experimental: always latest |
```yaml
federation:
version_policy: minor
```
## What You Learned
- Federation is a 5-step lifecycle: validate → export → share → import → compose (§11)
- [FAIR metadata](/patterns/fair-envelope) is the trust gate — no license, no federation
- External reference is the default composition pattern — minimal token cost
- Version policies manage dependency drift between source and target
## Next Steps
- [Context Commons](/learn/concepts/context-commons) — the vision of community-wide knowledge sharing
- [Lattice Composition](/learn/concepts/lattice-composition) — deeper dive into composition patterns
---
## https://adna.network/learn/tutorials/first-claude-md/
# Create Your First CLAUDE.md — aDNA Tutorial
## What You'll Build
A working CLAUDE.md file — the master governance document that tells AI agents who they are, what rules to follow, and how your project is structured. By the end, an AI agent dropped into your project cold can orient and begin useful work.
## Prerequisites
- Understand the [triad](/learn/concepts/triad) (what/how/who)
- Understand [governance files](/learn/concepts/governance-files) (what they do and why)
## Steps
### Step 1: Create the File
At the root of your project, create a file called `CLAUDE.md`. This name matters — AI tools like Claude Code auto-load it on startup. It's the first thing an agent reads.
```bash
touch CLAUDE.md
```
### Step 2: Write the Identity Section
Start with who the agent is and what the project does:
```markdown
# CLAUDE.md — My Project
## Identity
You are working on [project name] — [one sentence describing what it does].
### Operating Style
- [How should the agent communicate? Formal? Casual? Technical?]
- [Any persona traits? "Be concise." "Explain your reasoning."]
```
This section replaces the generic "I'm an AI assistant" behavior with project-specific identity. The agent becomes a team member, not a generic tool.
**See it in action**: Open this vault's `CLAUDE.md` (at `aDNA.aDNA/CLAUDE.md`). The identity section defines the Rosetta persona — "named after the Rosetta Stone" — with specific operating style rules like "the structure IS the lesson" and "warm and precise, anti-jargon-first."
### Step 3: Write the Project Map
Add a directory structure overview so the agent knows where things are:
```markdown
## Project Map
\```
my_project/
├── CLAUDE.md # This file
├── what/ # Knowledge and reference material
│ ├── context/ # Agent context library
│ └── decisions/ # Architecture Decision Records
├── how/ # Operations and processes
│ ├── templates/ # Reusable file templates
│ └── sessions/ # Session tracking
└── who/ # People and governance
└── governance/ # Policies and roles
\```
```
An agent reading this knows immediately what exists and where to find it. Without it, the agent guesses — and guesses wrong.
### Step 4: Add Standing Rules
Define the rules that apply to every session:
```markdown
## Standing Rules
1. **Read STATE.md before working.** Check current phase, blockers, and recent activity.
2. **Never modify shared configs without reading first.** Read-before-write prevents overwrites.
3. **Set `last_edited_by` on every edit.** Attribution enables conflict detection.
4. **Commit after significant changes.** Don't rely on auto-save.
```
Rules should be specific and actionable. "Be careful" is not a rule. "Read STATE.md before working" is.
### Step 5: Define the Agent Protocol
Tell the agent what to do on startup:
```markdown
## Agent Protocol
### Startup Checklist
1. Read CLAUDE.md (this file — auto-loaded)
2. Read STATE.md — understand current phase and blockers
3. Check `how/sessions/active/` — look for conflicting sessions
4. Create a session file and begin work
```
This is the [convergence model](/learn/concepts/convergence) in miniature: the agent starts broad (CLAUDE.md = everything about the project) and narrows to the specific (STATE.md → active session → current task).
### Step 6: Validate It
Test your CLAUDE.md by answering these questions:
| Question | If Yes → Done | If No → Fix |
|----------|---------------|-------------|
| Could a new agent orient from this file alone? | The identity and map are sufficient | Add more context to the project map |
| Are the rules specific and actionable? | Rules will be followed | Replace vague rules with concrete instructions |
| Does the startup checklist produce a working session? | The protocol works | Add missing steps |
| Is the tone consistent with how you want agents to work? | The persona is set | Adjust the operating style |
## What You Learned
- CLAUDE.md is the single most important file in an aDNA project — it's the agent's first read
- Four sections do the heavy lifting: identity, project map, standing rules, agent protocol
- Specificity beats generality: "Read STATE.md first" > "Be careful"
- The file demonstrates [convergence](/learn/concepts/convergence) — broad orientation narrowing to specific action
## Next Steps
- [Apply the Question Test](/learn/tutorials/question-test) — practice sorting content into the triad
- [Token Selection](/learn/concepts/token-selection) — how CLAUDE.md fits into the token budget
---
## https://adna.network/learn/tutorials/navigate-a-vault/
# Navigate an aDNA Vault — aDNA Tutorial
## What You'll Build
Nothing — this is a guided tour. By the end, you'll understand how an aDNA vault is organized and be able to find any piece of knowledge within it. You'll navigate the vault you're reading right now.
## Prerequisites
None. This is the starting point. If you're reading this, you're ready.
## Steps
### Step 1: Look at the Root
Open the root of this vault (`aDNA.aDNA/`). You'll see three directories and several files:
```
aDNA.aDNA/
├── CLAUDE.md ← Agent instructions (the "brain" of the project)
├── AGENTS.md ← Root navigation guide
├── MANIFEST.md ← What this project IS
├── STATE.md ← Where this project IS NOW
├── README.md ← Human entry point
├── what/ ← Knowledge
├── how/ ← Operations
└── who/ ← People
```
Those three directories — `what/`, `how/`, `who/` — are the [triad](/learn/concepts/triad). Every piece of knowledge in this project lives in exactly one of them. This is the first thing to know: aDNA organizes everything by answering three questions.
### Step 2: Explore What the Project Knows
Enter `what/`. This is the knowledge leg — everything the project knows:
```
what/
├── context/ ← Curated knowledge for AI agents (~75K tokens)
├── concepts/ ← Core aDNA concepts (dual-audience — you can read them!)
├── tutorials/ ← You are here
├── patterns/ ← Reusable architectural patterns
├── comparisons/ ← aDNA vs. other systems (honest positioning)
├── glossary/ ← Canonical term definitions
├── use_cases/ ← Adoption stories by domain
├── decisions/ ← Architecture Decision Records
├── docs/ ← Specification documents
└── lattices/ ← Workflow definitions (YAML + tools)
```
Each directory has an `AGENTS.md` that tells AI agents whether to load it. Open `what/concepts/AGENTS.md` — it says "Load when creating or reviewing concept documentation. Skip when working on operational infrastructure." That's [AGENTS.md routing](/patterns/agents-md) in action.
### Step 3: Explore How the Project Works
Enter `how/`. This is the operations leg — how work gets done:
```
how/
├── campaigns/ ← Strategic initiatives (Operation Rosetta lives here)
├── missions/ ← Standalone task decompositions
├── sessions/ ← Session audit trail (active/ + history/)
├── templates/ ← Reusable file templates
├── skills/ ← Agent recipes and procedures
├── pipelines/ ← Content-as-code workflows
├── backlog/ ← Ideas and improvements
├── workshops/ ← Workshop kits + facilitation guides
├── publishing/ ← Vault-to-web publishing pipeline
└── quests/ ← Community validation experiments
```
Notice the pattern: every directory is named for what it contains, and each has its own `AGENTS.md`. The vault is self-describing.
### Step 4: Explore Who's Involved
Enter `who/`. This is the people leg:
```
who/
├── governance/ ← Roles, policies, vision
├── coordination/ ← Cross-agent notes
├── community/ ← Community roles + contribution paths
└── adopters/ ← Adopter personas + deployment profiles
```
Smaller than `what/` and `how/`, but critical. Governance policies, team coordination, and community structure all live here.
### Step 5: Read the Governance Files
Back at the root, open `STATE.md`. This tells you the project's current operational status — what phase it's in, what's working, what's blocked, and what to do next. An AI agent reads this on every startup to understand where things stand.
Now open `MANIFEST.md`. This tells you what the project IS — its identity, purpose, and scope. `STATE.md` changes every session; `MANIFEST.md` changes rarely.
Together with `CLAUDE.md` (agent instructions), `AGENTS.md` (navigation), and `README.md` (human entry point), these five files are the [governance files](/learn/concepts/governance-files) — the orientation layer for the entire vault.
### Step 6: Follow a Thread
Pick any concept file — say `what/concepts/concept_triad.md`. Open it. At the bottom, you'll see a "Related" section with wikilinks to other concepts. Follow one. Then follow another from that file. You're navigating the [knowledge graph](/learn/concepts/knowledge-graph) — the connected web of ideas that makes the vault more than a collection of files.
## What You Learned
- The [triad](/learn/concepts/triad) (`what/`, `how/`, `who/`) organizes all knowledge
- [Governance files](/learn/concepts/governance-files) orient agents and humans at the root
- [AGENTS.md](/patterns/agents-md) at every directory guides navigation
- The vault is self-describing — directory names, governance files, and wikilinks make everything findable
## Next Steps
- [Create Your First CLAUDE.md](/learn/tutorials/first-claude-md) — build the agent-orientation file
- [The Triad](/learn/concepts/triad) — deeper understanding of the organizing principle
---
## https://adna.network/learn/tutorials/question-test/
# Apply the Question Test — aDNA Tutorial
## What You'll Build
A sorted inventory of 10 project items placed into the correct triad leg. By the end, you'll be able to instantly sort any new file into `what/`, `how/`, or `who/` using the [question test](/patterns/question-test).
## Prerequisites
- Understand the [triad](/learn/concepts/triad) (what/how/who)
- Understand the [ontology](/learn/concepts/ontology) (entity types within each leg)
## Steps
### Step 1: Learn the Test
The question test is one question with three answers:
> "Is this about **WHAT** we know, **HOW** we work, or **WHO** is involved?"
| Answer | Triad Leg | It belongs here if... |
|--------|-----------|----------------------|
| WHAT we know | `what/` | Its primary purpose is to capture knowledge |
| HOW we work | `how/` | Its primary purpose is to drive action |
| WHO is involved | `who/` | Its primary purpose is to describe people or relationships |
That's it. One question. Three possible answers. Every file in the project gets exactly one.
### Step 2: Sort 10 Items
Here are 10 items from a hypothetical biotech research project. For each, ask the question and write your answer:
| # | Item | Your Answer |
|---|------|-------------|
| 1 | A research summary on CRISPR gene editing | |
| 2 | A sprint plan for the next two weeks | |
| 3 | The team roster with roles and contact info | |
| 4 | A decision record choosing Python over R | |
| 5 | A template for writing experiment reports | |
| 6 | Notes from a meeting between the PI and the postdoc | |
| 7 | A context file on protein folding methods | |
| 8 | A mission plan to build the data pipeline | |
| 9 | The lab's code of conduct | |
| 10 | A lattice YAML defining the analysis workflow | |
### Step 3: Check Your Answers
| # | Item | Question | Answer | Directory |
|---|------|----------|--------|-----------|
| 1 | CRISPR research summary | WHAT do we know? | Knowledge | `what/context/` |
| 2 | Sprint plan | HOW do we work? | Action | `how/missions/` |
| 3 | Team roster | WHO is involved? | People | `who/team/` |
| 4 | Decision record (Python vs. R) | WHAT do we know? | Knowledge | `what/decisions/` |
| 5 | Experiment report template | HOW do we work? | Action | `how/templates/` |
| 6 | Meeting coordination notes | WHO is involved? | People | `who/coordination/` |
| 7 | Protein folding context file | WHAT do we know? | Knowledge | `what/context/` |
| 8 | Data pipeline mission plan | HOW do we work? | Action | `how/missions/` |
| 9 | Code of conduct | WHO is involved? | People | `who/governance/` |
| 10 | Analysis workflow lattice | WHAT do we know? | Knowledge | `what/lattices/` |
**Common trip-ups**:
- **Item 4** (decision record): You might think "deciding is an action → HOW." But the record captures *knowledge* about what was decided and why. The decision process was HOW; the record is WHAT.
- **Item 6** (meeting notes): Could feel like "knowledge from the meeting → WHAT." But coordination notes describe people communicating — WHO is involved in this conversation.
- **Item 9** (code of conduct): Could feel like "a rule → HOW we work." But it governs people's behavior and relationships — WHO is involved and what standards they follow.
### Step 4: Apply to Your Own Project
List 5 files from a real project you're working on. Apply the question test to each:
| File | Question | Triad Leg |
|------|----------|-----------|
| | | |
| | | |
| | | |
| | | |
| | | |
If any item feels like it belongs in two legs, it's trying to do two things. Split it. A "team sprint plan" is two files: the team roster (WHO) and the sprint plan (HOW).
## What You Learned
- The [question test](/patterns/question-test) always produces exactly one answer
- Edge cases usually involve files trying to serve two purposes — split them
- The test works for any content type: documents, code, data, configs
- Consistent sorting makes the vault navigable for both humans and agents
## Next Steps
- [Extend the Ontology](/learn/tutorials/extend-the-ontology) — add custom entity types to the triad
- [Ontology](/learn/concepts/ontology) — understand the entity types within each leg
- [Base/Extension](/patterns/base-extension) — how to add types without breaking the core
---
## https://adna.network/learn/tutorials/run-a-campaign/
# Run a Campaign — aDNA Tutorial
## What You'll Build
A campaign document with phased execution, a mission board, and quality gates. By the end, you'll have a strategic plan that can coordinate multiple agents across multiple sessions toward a shared goal.
## Prerequisites
- [Convergence Model](/learn/concepts/convergence) — how campaigns narrow to missions to objectives
- [Mission Decomposition](/patterns/mission-decomposition) — breaking work into claimable objectives
- [Design a Mission](/learn/tutorials/design-a-mission) — writing individual mission files
## Steps
### Step 1: Define the Strategic Goal
A campaign is bigger than a mission. It coordinates multiple missions toward a strategic outcome. Write the goal as one sentence:
> "Build a self-referential aDNA documentation vault with 80+ content files across 5 phases."
If the goal can be achieved in a single mission (3-8 objectives), it doesn't need a campaign.
### Step 2: Design the Phases
Break the campaign into phases — each phase is a coherent stage with a gate before the next:
| Phase | Focus | Why It's Separate |
|-------|-------|------------------|
| 0 | Scaffold | Infrastructure before content |
| 1 | Core Content | Concepts, patterns, comparisons — the vocabulary |
| 2 | Human Path | Tutorials, use cases — the learning path |
| 3 | Community | People, governance — the social layer |
| 4 | Operations | Publishing, workshops — the delivery mechanisms |
**Phase gate rule**: phases don't auto-advance. A human approves the transition. This prevents runaway execution and ensures strategic alignment at each boundary.
### Step 3: Create the Mission Board
Within each phase, list the missions:
```markdown
### Phase 1: Core Content
| Mission | Title | Status | Files | Dependencies |
|---------|-------|--------|-------|-------------|
| M01 | Foundational Concepts | pending | 3 files | Phase 0 |
| M02 | Governance Concepts | pending | 4 files | M01 |
| M03 | Advanced Concepts | pending | 6 files | M01, M02 |
```
Each row is a mission with specific deliverables and dependencies. An agent scanning this board knows what's done, what's next, and what's blocked.
### Step 4: Define Quality Gates
Quality gates apply to all content within the campaign:
```markdown
## Quality Gates
1. Dual audience test — legible to developers AND newcomers
2. Self-reference check — cites concrete vault examples
3. Spec citation — normative claims reference the standard
4. Cross-linking — 2+ wikilinks per file
5. Frontmatter complete — all required fields populated
```
Gates are checked before marking any objective complete. No exceptions.
### Step 5: Write the Campaign File
Create `how/campaigns/campaign_{name}/campaign_{name}.md`:
```markdown
---
campaign_id: campaign_docs
type: campaign
title: "Documentation Campaign"
status: active
current_phase: 1
mission_count: 8
priority: high
created: 2026-04-14
updated: 2026-04-14
last_edited_by: agent_stanley
tags: [campaign]
---
# Documentation Campaign
## Strategic Intent
{Why this campaign exists and what success looks like.}
## Phase Structure
{Table of phases with status.}
## Mission Board
{Tables of missions per phase.}
## Quality Gates
{Standards every deliverable must meet.}
## Success Criteria
{How to know the campaign achieved its goal.}
```
### Step 6: Execute the First Mission
Create the first mission file inside `how/campaigns/campaign_{name}/missions/`. Claim the first objective. Start a session. Do the work. Close with a SITREP.
**See it in action**: This vault's Operation Rosetta (`how/campaigns/campaign_rosetta/campaign_rosetta.md`) has 5 phases, 15 missions, and 6 quality gates. Browse the mission files in `how/campaigns/campaign_rosetta/missions/` — each one demonstrates the decomposition pattern with objectives, context dependencies, and AARs.
## What You Learned
- Campaigns coordinate multiple missions toward a strategic goal
- Phases group missions with human gates between them — no auto-advancing
- The mission board provides at-a-glance status for all work
- Quality gates ensure consistent output across all missions and sessions
## Next Steps
- [Federate a Vault](/learn/tutorials/federate-a-vault) — share your campaign's outputs with other projects
- [Open Standard](/learn/concepts/open-standard) — how campaigns contribute to the broader aDNA ecosystem
---
## https://adna.network/learn/tutorials/write-a-context-file/
# Write a Context File — aDNA Tutorial
## What You'll Build
A quality-scored context file ready for your vault's context library. By the end, you'll have a file that an AI agent can load to make better domain decisions — with a quality score and token estimate.
## Prerequisites
- [Context Optimization](/learn/concepts/context-optimization) — format selection, signal density, anti-patterns
- [Token Selection](/learn/concepts/token-selection) — how context files fit into token budgets
- [AGENTS.md Routing](/patterns/agents-md) — how agents find context files
## Steps
### Step 1: Choose Your Subtype
Context files come in three flavors (§10):
| Subtype | Use When | Example |
|---------|----------|---------|
| `context_research` | Synthesizing external knowledge | "What the latest papers say about RAG" |
| `context_guide` | Writing how-to instructions | "How to validate a lattice YAML" |
| `context_core` | Defining foundational conventions | "What the triad means for this project" |
Pick the one that matches your content's purpose. Don't mix subtypes in one file.
### Step 2: Write the Frontmatter
```yaml
---
type: context_guide # or context_research, context_core
topic: my_topic # topic directory name
subtopic: my_subtopic # this file's subtopic
created: 2026-04-14
updated: 2026-04-14
sources: ["Source 1", "Source 2"]
context_version: "1.0"
token_estimate: ~800 # estimate after writing
last_edited_by: agent_stanley
tags: [context, my_topic, my_subtopic]
---
```
The `sources` field is mandatory — every claim must be traceable. The `token_estimate` helps agents make cost-aware loading decisions.
### Step 3: Write the Body
Follow this structure — tables over prose:
```markdown
# {Topic}: {Subtopic}
## Key Principles
1. **First principle.** Most important claim first.
2. **Second principle.** Each one is self-contained.
3. **Third principle.** Support with a table if complex.
## Recommendations
| If you need to... | Do this | Why |
|-------------------|---------|-----|
| {Scenario 1} | {Action}| {Rationale} |
| {Scenario 2} | {Action}| {Rationale} |
## Anti-Patterns
1. **{Bad practice}.** {What goes wrong.}
## Sources
1. {Full citation with enough detail to verify}
```
**The key rule**: every sentence should drive a decision or action. If you write "Context files are important" — delete it. An agent loading this file already knows it's important (it's loading it). Instead write: "Context files SHOULD be 150-300 lines to stay within single-topic token budgets."
### Step 4: Score Against the Quality Rubric
Rate your file on 5 axes (1-5 each):
| Axis | Score | What You're Measuring |
|------|-------|----------------------|
| **Signal density** | /5 | What fraction of tokens drives decisions? |
| **Actionability** | /5 | Can an agent produce concrete output from this? |
| **Coverage uniformity** | /5 | Is depth balanced across sections? |
| **Source diversity** | /5 | How many distinct source types? |
| **Cross-topic coherence** | /5 | Any conflicts with related files? |
**Composite target**: 3.5+ average. **Floor rule**: any axis ≤ 2 flags for revision.
Add the scores to your frontmatter:
```yaml
quality_score: 4.0
signal_density: 4
actionability: 5
coverage_uniformity: 4
source_diversity: 3
cross_topic_coherence: 4
```
### Step 5: Add to the Topic AGENTS.md
If this is a new topic, create a topic directory with an AGENTS.md. If adding to an existing topic, update the AGENTS.md subtopic table:
```markdown
| # | Subtopic | File | ~Tokens | Key Content |
|---|----------|------|---------|-------------|
| N | my_subtopic | context_topic_subtopic.md | ~800 | {one-line summary} |
```
Update the total token budget.
### Step 6: Validate
| Check | Pass? |
|-------|-------|
| Every claim has a traceable source | |
| Tables used where possible (not prose) | |
| File is 150-300 lines | |
| No background preamble ("In the rapidly evolving...") | |
| Quality composite is 3.5+ | |
| No axis scores ≤ 2 | |
| Token estimate in frontmatter | |
| Topic AGENTS.md updated | |
## What You Learned
- Context files exist to help agents make better decisions — not to store background knowledge
- [Tables over prose](/learn/concepts/context-optimization) delivers 3-5x more information per token
- The quality rubric provides an objective measure: signal density, actionability, coverage, source diversity, coherence
- Adding a file to the AGENTS.md index makes it discoverable by agents
## Next Steps
- [Design a Mission](/learn/tutorials/design-a-mission) — plan multi-session work using the execution hierarchy
- [Context Recipe](/patterns/context-recipe) — combine context files into task-specific assemblies
---
## https://adna.network/learn/what-is-adna/
# What is aDNA?
aDNA (Agentic DNA) is an open standard for organizing what a project knows, so that people and AI agents can both find their way around it. Every aDNA project has the same shape. Learn that shape once and you can open any of them — including this site, which is one.
**A note on the name.** In genomics, *aDNA* usually means [ancient DNA](https://en.wikipedia.org/wiki/Ancient_DNA). This is not that. Here it stands for *Agentic DNA*, and the borrowing is deliberate: a genome is structure a cell inherits and reads, and these files are structure a project keeps and its agents read.
## The problem
AI agents have the same trouble people do: finding the right file. With no shape to follow, an agent reads the wrong thing, or misses the thing that counts. So you explain the project again at the start of each session. Agents undo decisions they made last week. Work slips out of reach as the context window fills.
The problem is the filing, not the agent. The agent is able; it has nowhere to look. Most teams patch the gap with long READMEs and custom prompts, and none of that carries to the next session, the next agent, or the next teammate. aDNA is one open answer. Any team can adopt it, any tool can support it, and any agent can read it with no setup.
## How aDNA works
aDNA gives a project three things:
- **The [Triad](/glossary/glossary-triad)** — [three directories](/learn/concepts/triad), in every project: `who/` for people and governance, `what/` for knowledge and decisions, `how/` for operations and work. See one aDNA project and you know your way around the next.
- **[Governance files](/glossary/glossary-governance-file)** — five files that orient an agent at each level: [`CLAUDE.md`](/learn/concepts/governance-files), `AGENTS.md`, `MANIFEST.md`, `STATE.md` and `README.md`. The root `CLAUDE.md` is the front door: what the project is, how it is laid out, what the rules are, where to begin.
- **Typed entities** — 16 base types, among them [missions](/glossary/glossary-mission), [sessions](/glossary/glossary-session), [skills](/glossary/glossary-skill) and [templates](/glossary/glossary-template). Each type uses the same [frontmatter](/glossary/glossary-frontmatter) fields and the same naming, everywhere. Read one mission file and you can read any mission file, in any aDNA project.
### What a project looks like
A small aDNA project — three directories, five governance files:
```
your-project.aDNA/
├── CLAUDE.md # Agent entry point: purpose, rules, where to start
├── STATE.md # Live snapshot: blockers, active work, next steps
├── MANIFEST.md # Project overview and architecture
├── who/ # WHO — people, governance, coordination
│ └── governance/ # Roles, policies, vision
├── what/ # WHAT — knowledge, decisions, context
│ └── context/ # Curated knowledge files agents load
└── how/ # HOW — operations, plans, execution
├── missions/ # Work decomposed into claimable objectives
└── sessions/ # Per-session tracking and handoff notes
```
An agent that has seen one aDNA project knows this at a glance, before it reads a word of the content.
### The 16 entity types
Every file states its type. Because the types never change, an agent can work in a project it has never seen, with nothing to set up first. The 16 base types are split across the Triad — **4 WHO, 5 WHAT, 7 HOW**. Here is the whole set:
The 16 base entity types
TriadEntityPurpose
WHO`governance`Roles, policies, decision authority
WHO`team`Who works on the project
WHO`coordination`Cross-agent ephemeral notes
WHO`identity`Who and where this node is — hostname, operator, peer id
WHAT`context`Curated knowledge files agents load at session start
WHAT`decisions`Architecture Decision Records (ADRs)
WHAT`modules`Atomic capability units with typed I/O
WHAT`lattices`Connected workflows of modules
WHAT`inventory`What's installed — vaults, system state, memberships
HOW`campaigns`Multi-mission strategic initiatives
HOW`missions`Multi-session work decomposed into objectives
HOW`sessions`Single-session tracking and handoff notes
HOW`templates`Reusable file patterns
HOW`skills`Agent recipes and documented procedures
HOW`pipelines`Content-as-code automated workflows
HOW`backlog`Ideation and improvement tracking
### What a CLAUDE.md looks like
A `CLAUDE.md` is not a README. It is the agent's operating protocol, and the agent reads it first, every session. Instead of "work it out from the README", the project and the agent share one set of terms.
See the opening of a real CLAUDE.md
```
# CLAUDE.md — aDNA.aDNA
You are Rosetta — named after the Rosetta Stone, the artifact that decoded
Egyptian hieroglyphics by presenting the same text in three scripts. This
vault does the same: it presents the aDNA standard in three registers —
technical specification, operational practice, and plain-language explanation.
## Project Map
aDNA.aDNA/
├── CLAUDE.md ← You are here — agent master context (this file)
├── STATE.md ← Operational snapshot: current phase, blockers, next steps
├── what/ ← Knowledge objects, context library, lattice definitions
├── how/ ← Operations, sessions, missions, campaigns, skills
└── who/ ← Governance, community, coordination
## Standing Orders
1. Phase gates are human gates — never auto-advance between phases.
2. Every mission gets an AAR before marking it completed.
3. Upstream spec is source of truth — cite adna_standard.md for normative claims.
```
## Before and after
*The contrast below is the general pattern the standard is built against — not a case study, and no measured project is being described.*
**Without aDNA:** what the project knows is spread across Notion, Drive and Git. Each session opens with a pasted summary that is already out of date. Last month's decisions get argued again. A new teammate has to work out where everything sits before they can start.
**With aDNA:** the same project has a [`what/context/` library](/glossary/glossary-context-library), a `STATE.md` that names the current priorities and blockers, and a `how/missions/` directory where work is split into pieces someone can claim. An agent opens `CLAUDE.md`, reads the context it points to, and starts in the right direction — in that same session.
## See for yourself
**aDNA is not a concept deck. It is a standard you can clone and read today.** The public image at [`github.com/aDNA-Network/aDNA`](https://github.com/aDNA-Network/aDNA) is a real aDNA workspace. One command gives you the standard, the skills and the templates. A fresh clone also offers to set up a complete Home for an agent. Open the files yourself:
- [`CLAUDE.md`](https://github.com/aDNA-Network/aDNA/blob/main/CLAUDE.md) — the workspace operating protocol an agent loads first
- [`.adna/`](https://github.com/aDNA-Network/aDNA/tree/main/.adna) — the full aDNA standard, embedded and ready to clone
- [`.adna/how/skills/skill_onboarding.md`](https://github.com/aDNA-Network/aDNA/blob/main/.adna/how/skills/skill_onboarding.md) — the first-run recipe that orients a new project
- [`.adna/how/skills/skill_project_fork.md`](https://github.com/aDNA-Network/aDNA/blob/main/.adna/how/skills/skill_project_fork.md) — how a new .aDNA project is created
- [`.adna/how/templates/template_workspace_claude.md`](https://github.com/aDNA-Network/aDNA/blob/main/.adna/how/templates/template_workspace_claude.md) — the router template every workspace starts from
- [`.adna/how/templates/template_home_claude.md`](https://github.com/aDNA-Network/aDNA/blob/main/.adna/how/templates/template_home_claude.md) — the governance template a fresh clone uses to bootstrap a polished Home (shipped at v8.0)
- [`.adna/how/templates/template_node_adna_exemplar/`](https://github.com/aDNA-Network/aDNA/tree/main/.adna/how/templates/template_node_adna_exemplar) — the themed exemplar Home the bootstrap offers out of the box (shipped at v8.0)
This site is itself an aDNA vault. The shape you are reading about is the shape that produced it. Clone the image and open it in Obsidian, in VS Code, or on GitHub — every directory and every frontmatter field is one of these ideas at work.
## The three-question test
A well-built aDNA project lets any agent answer three questions at once, without asking:
- **What is this project?** — `CLAUDE.md` and `MANIFEST.md` at the root.
- **Where does it stand?** — `STATE.md`: blockers, active work, next steps.
- **Where do I start?** — the open mission in `how/missions/`, or the nearest `AGENTS.md`.
If your project answers all three within ten seconds of reading, it is ready for aDNA.
## Explore further
- [The Triad](/learn/concepts/triad) — the structure underneath it all: who, what, how
- [Governance Files](/learn/concepts/governance-files) — CLAUDE.md, AGENTS.md, STATE.md, and what each is for
- [Get Started](/get-started) — set up your first aDNA project in three steps
- [Tutorial: Create Your First CLAUDE.md](/learn/tutorials/first-claude-md) — hands-on, 20 minutes
- [The Convergence Model](/learn/concepts/convergence) — how aDNA narrows what an agent loads at each level of the work
---
## https://adna.network/network/
*[image: A wide bird's-eye pixel-art map of many small, independently lit settlements scattered across a dark Tokyo-Night ground, a few linked by glowing cyan and purple conduits — aDNA computers, each its own place, sparsely federated.]*
# The network of aDNA computers
An aDNA computer is one machine — laptop, server, or cloud box — carrying many context vaults (self-governing folders of project knowledge) under a single Home.aDNA. Vaults connect through real, directed relationships, and each node decides what stays local and what it shares.
[See the relationship graph](/vaults/graph/) [Browse the vaults](/vaults/)
[Open source on GitHub](https://github.com/aDNA-Network/aDNA) · MIT-licensed · [the standard, versioned and public](/reference/specification)
## A network of real relationships
The connections are not decorative. Each line is a relationship a vault actually declares —
drawn here as a simple hub around the shared core, not an invented peer-to-peer mesh.
The aDNA network
Real aDNA vaults — Astro, III, RareHarness, wga, RareArchive, Home — connected around the aDNA core by the relationships they declare.
- Astro III RareHarness wga RareArchive Home aDNA the network The aDNA network
Real aDNA vaults — Astro, III, RareHarness, wga, RareArchive, Home — connected around the aDNA core by the relationships they declare.
Astro III RareHarness wga RareArchive Home aDNA the network
Six representative aDNA vaults — forges, frameworks, platforms, and public-good archives —
federating around the shared aDNA core. (See all 74 in the full graph below.)
## What is an aDNA computer?
A node on the network is one machine, governed by a single `Home.aDNA` vault that
knows every other vault living on it. What that machine shares is always your choice.
### Stays on your machine
By default, everything. A node is local-first — its vaults, their full history, the
machine’s inventory, and its credentials never leave the computer unless you send
them (Standing Rule 4).
Your project vaults and their history
- The node’s inventory and machine state
- Identity and credentials
### You opt to federate
Only what you choose. Publishing a vault, declaring a relationship to another vault, or
joining a shared lattice is an explicit, reviewable act — never a silent default.
- A vault published to the shared registry
- A relationship declared to another vault
- Membership in a federated lattice
## The topology at a glance
74 vaults, 14 relationships. Every edge is **real and directed**,
drawn from each vault’s governance, across five kinds of relationship.
- **umbrella** · 1 — an org-vault contains its pillar children
- **federation** · 9 — a consumer depends on the forge or framework it is built from
- **partner** · 0 — a platform ships with its default partner
- **companion** · 4 — a sibling persona-pair or thematic family
- **supersedes** · 0 — a successor replaced its predecessor
[See the full relationship graph →](/vaults/graph/) · [Browse all 74 vaults →](/vaults/)
## Run a node
A node is a workspace on your own machine. Three steps take you from nothing to a governed
node that decides what it shares — the same local-by-default boundary, made concrete.
- About five minutes
- Needs `git` + the Claude Code CLI
- Local-first — your vault files never leave until you choose
- 1
### Bootstrap your node
Clone the workspace image — the agent router ships pre-instantiated at the root and the
standard comes embedded in a hidden `.adna/` folder — then start the agent: it
detects a fresh workspace, scaffolds your first project, and can bootstrap
`Home.aDNA`, the vault that governs your machine.
```
git clone https://github.com/aDNA-Network/aDNA.git ~/aDNA
cd ~/aDNA
claude
```
See [Get started](/get-started/) for the full walkthrough —
installing `git` and the Claude Code CLI, and what each step does.
- 2
### Everything stays local by default
Your node is local-first. Its vaults, their full history, the machine’s inventory, and
your credentials stay on the computer until you choose to send them (Standing Rule 4).
- 3
### Opt into federation
Joining the commons is always explicit and reviewable — a change you author and inspect
before you push it. By design, what crosses the boundary is a curated slice of your
`Home.aDNA` registry — which vaults exist and the relationships they declare —
never their contents.
[See how federation works →](/reference/)
[Run your first node →](/get-started/) [Read the standard →](/reference/)
## Running a model on your own machine
Your files stay on your node today. Your prompts do not. Closing that gap is
**planned work, not shipped work** — nothing here runs yet.
A node needs a coding agent to do its work. That agent sends your prompts to its provider.
Your vaults, their history and your credentials stay put. The prompts leave.
Running the model on the same machine would close that gap. It is not built. Two vaults hold
the plan, and the registry lists both of them as **planned** — a name, an
owner, and no code behind it yet.
- [Inference](/vaults/inference/) — the plan for serving
a local model to a node.
- [LlamaCppForge](/vaults/llamacppforge/) — the plan for
building the model files it would serve.
No date is set, and none is promised. When there is something to run, it will ship as a step
in [Get started](/get-started/), and this section will say so.
## Governed in the open
The network is [a commons](/commons/), not a silo.
The standard that holds it is openly specified and openly governed — a named steward, a public
process for proposing change, and the load-bearing decisions on the record as public ADRs.
- Founding-Architect stewardship
- Open spec · MIT
- Public change process
- Versioned releases · v2.5 current
[Read the governance model →](/reference/governance-model/) [Join the community →](/community/)
Language and DNA are our shared heritage. So is context — the accumulated understanding of a
civilization, held in common and stewarded for the generations that inherit it.
---
## https://adna.network/patterns/
*[image: Isometric pixel-art map of modular vault-blocks linked by glowing cyan and purple seams — reusable aDNA patterns]*
# Patterns
8 patterns that solve recurring challenges in aDNA projects. Each describes the problem, the solution, and where to find a working example in this vault.
## What a pattern is here
A pattern is a shape that recurs, named so it can be discussed and reused. It sits between a [concept](/learn/concepts/) — which explains what something *is* — and a procedure, which tells you what to *do*. A pattern tells you what tends to *work*, and when it does not.
Patterns here are descriptive rather than prescriptive. Each one was extracted from something this vault or a peer vault actually built, which is why every pattern carries a worked example: if we could not point at an instance, it was an idea and not yet a pattern.
## How to read one
Every pattern follows the same four moves: the **problem** it recurs in response to, the **solution** shape, a **worked example** in a real vault, and the **trade-off** — what you give up by adopting it. Read the trade-off first if you are choosing between two patterns; it is usually the part that decides.
## The patterns
[The Question Test Every new file in an aDNA project needs to land in one of three folders — what/, how/, or who/. Most files are obvious; edge cases cause hesitation…](/patterns/question-test)[AGENTS.md Routing A project folder can hold hundreds of files. An AI agent working on a single task needs only a handful of them — but how does it know which folders to…](/patterns/agents-md)[Dual-Audience Writing aDNA documentation must serve two audiences with different needs: developers seeking technical precision for implementation, and newcomers seeking…](/patterns/dual-audience-writing)[Base/Extension 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…](/patterns/base-extension)[Context Recipe Most real tasks need knowledge from several areas at once — not one clean topic. Without a pre-built list of what to load, an agent either grabs…](/patterns/context-recipe)[FAIR Envelope A shareable object without a label is a black box — nobody outside your project can find it, tell if it's trustworthy, know who made it, or use it…](/patterns/fair-envelope)[Mission Decomposition Some jobs — writing thirteen concept files, or building a whole documentation site — are too big for any one agent session to finish in one go…](/patterns/mission-decomposition)[Federation Readiness Something that works in your project isn't automatically safe to hand to someone else. A workflow may rely on files only you have, skip the labels a…](/patterns/federation-readiness)
## Proposing a pattern
Patterns are added through the same public proposal process as any other change to the standard — see [proposals](/community/proposals/). The bar is the one above: a pattern needs an instance somewhere before it can be named here. A shape observed once is a coincidence; the proposal is where you argue it is not.
---
## https://adna.network/patterns/agents-md/
# AGENTS.md Routing — aDNA Patterns
## Problem
A project folder can hold hundreds of files. An AI agent working on a single task needs only a handful of them — but how does it know which folders to open and which to walk past? Without signs, the agent either drowns in files it doesn't need or misses the ones that matter.
## Solution
Place an **AGENTS.md** file in every directory that agents might navigate (§4.5). Each AGENTS.md contains:
| Section | Purpose |
|---------|---------|
| **What's Here** | 1-2 sentence description of directory contents |
| **Working Rules** | Naming conventions, required fields, constraints |
| **Load/Skip Decision** | Explicit guidance: "Load when X. Skip when Y." |
| **Token cost** | How many tokens loading this directory costs |
The load/skip decision is the critical section. It turns the directory tree into a **decision tree**: at each junction, the agent reads AGENTS.md and decides whether to descend or prune. This implements the [convergence model](/learn/concepts/convergence) — each pruning decision narrows the working set.
**Key properties**:
- AGENTS.md is authoritative for its directory — it overrides broader context
- Token cost estimates let agents make cost-aware loading decisions
- Load/skip conditions should be task-based, not role-based ("when writing concepts" not "if you're a senior agent")
## When to Use
- Every directory in an aDNA vault that contains content an agent might need
- Every new directory created during ontology extension
- When agents are loading too much or too little context (adjust load/skip conditions)
## Example: This Vault
Open `what/concepts/AGENTS.md` — it tells agents:
> **Load when**: Creating or reviewing concept documentation, building learning paths, cross-referencing from patterns.
> **Skip when**: Working on operational infrastructure, writing workshop kits, concept content not relevant.
An agent executing Mission M04 (writing patterns) loads `what/concepts/` for cross-linking targets but skips `what/tutorials/` because tutorials aren't relevant to pattern writing. Both decisions were informed by the respective AGENTS.md files.
The context library at `what/context/adna_core/AGENTS.md` goes further — it lists all 13 subtopics with token estimates and a "Usage by task" table mapping tasks to specific subtopics. An agent writing about federation loads `context_adna_core_federation.md` (~1K tokens) and skips `context_adna_core_ontology_workshop.md` (~1.5K tokens). Savings: 1,500 tokens per skip decision.
## Anti-Pattern
**Missing AGENTS.md**: A directory without AGENTS.md is invisible to agents following the routing protocol. They'll either skip it entirely (losing content) or load everything in it (wasting tokens). Every directory needs one.
**Vague load/skip**: "Load when relevant" is not a routing decision. Specify the task or condition: "Load when designing lattice YAML files. Skip when writing tutorials."
**Stale routing**: AGENTS.md that describes directory contents that have changed. If you add entity types or restructure, update the AGENTS.md. Stale routing is worse than missing routing — it actively misdirects.
## Related
- [Convergence Model](/learn/concepts/convergence) — the structural principle that AGENTS.md routing implements
- [Token Selection](/learn/concepts/token-selection) — the broader discipline of choosing what to load
- [Context Recipe](/patterns/context-recipe) — multi-directory assembly that builds on AGENTS.md routing
---
## https://adna.network/patterns/base-extension/
# Base/Extension — aDNA Patterns
## 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** (16 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`, `identity` |
| WHAT | `context`, `decisions`, `modules`, `lattices`, `inventory` |
| HOW | `campaigns`, `missions`, `sessions`, `templates`, `skills`, `pipelines`, `backlog` |
**Extension rules**:
1. New types go under the correct triad leg (apply the [question test](/patterns/question-test))
2. Each extension type gets its own subdirectory under the triad leg
3. Each subdirectory gets an AGENTS.md and a template
4. Extension types use the same frontmatter conventions as base types (`type`, `created`, `updated`, `status`, `last_edited_by`, `tags`)
5. 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 16 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](/learn/concepts/ontology) — the entity type system that base/extension partitions
- [Open Standard](/learn/concepts/open-standard) — the governance model that keeps the base stable
- [Question Test](/patterns/question-test) — how to determine which triad leg an extension belongs under
---
## https://adna.network/patterns/context-recipe/
# Context Recipe — aDNA Patterns
## Problem
Most real tasks need knowledge from several areas at once — not one clean topic. Without a pre-built list of what to load, an agent either grabs everything "just in case" (wasting tokens) or misses a piece and gets stuck halfway. A federated lattice, for example, needs lattice-design knowledge + federation rules + object standards — three separate topic areas.
## Solution
Define **context recipes** — named, pre-built combinations of subtopics for common task types (§10). Each recipe specifies:
| Field | Purpose |
|-------|---------|
| Recipe name | Descriptive identifier for the task type |
| Subtopic list | Exactly which files to load |
| Token budget | Total cost at each tier |
| When to use | Task conditions that trigger this recipe |
**Three budget tiers**:
| Tier | Budget | Use When |
|------|--------|----------|
| Minimal | <5K tokens | Narrow task, agent already knows the domain |
| Standard | <12K tokens | Typical development session |
| Full | All subtopics | Deep research, comprehensive review |
**How recipes work**:
1. Agent reads the recipe index (`what/context/context_recipes.md`)
2. Matches current task to a recipe by keyword or description
3. Loads the listed subtopics at the appropriate tier
4. Begins work with a predictable, pre-validated context assembly
Recipes prevent two failure modes: **over-loading** (agent loads 30K tokens when 8K would suffice) and **improvisation** (agent guesses which subtopics are relevant and misses critical ones).
**Creating new recipes**: When you find yourself loading the same combination of subtopics for recurring task types, codify it as a recipe. List the subtopics, calculate the token budget, and add it to the index.
## When to Use
- Any task that spans multiple context topics
- When onboarding new agents to recurring task types
- When token budgets are tight and loading must be precise
- Campaign and mission planning (declare the recipe as a context dependency)
## Example: This Vault
The recipe index at `what/context/context_recipes.md` pre-defines assemblies for common tasks in this vault.
Mission files demonstrate recipe-like thinking in their context dependency sections. Look at `mission_m03_advanced_concepts.md` — it lists exactly which context subtopics to load:
```
- context_adna_core_paradigm_overview.md — general grounding
- context_adna_core_context_engineering.md — for context_optimization
- context_adna_core_lattice_design.md — for lattice_composition
- context_adna_core_federation.md — for lattice_composition, open_standard
- context_adna_core_fair_mapping.md — for fair_metadata
```
This is a recipe embedded in a mission: specific subtopics, matched to specific objectives, with a declared budget (~15K tokens). An agent starting M03 doesn't need to figure out which context to load — the mission tells it.
The AGENTS.md at `what/context/adna_core/AGENTS.md` supports recipe design by listing every subtopic with its token estimate and a "Usage by task" table mapping tasks to recommended subtopics. This table is the raw material from which recipes are composed.
## Anti-Pattern
**Loading everything**: Loading all 13 adna_core subtopics (~13K tokens) when a task only needs 2-3 (~2K tokens). The extra 11K tokens dilute focus and consume reasoning budget.
**Improvised assembly**: An agent loading subtopics by intuition rather than recipe, resulting in inconsistent context across sessions working on similar tasks. One session loads federation context; the next forgets it. Quality varies.
**Stale recipes**: Recipes that reference subtopics that have been renamed, split, or removed. Recipes must be maintained alongside the context library.
**Single-topic recipes**: A recipe that loads only one subtopic isn't a recipe — it's just loading a file. Recipes add value when they combine subtopics that non-obviously belong together.
## Related
- [Context Optimization](/learn/concepts/context-optimization) — the design principles that make individual files worth including in recipes
- [Token Selection](/learn/concepts/token-selection) — the broader discipline of loading the right knowledge
- [AGENTS.md Routing](/patterns/agents-md) — the directory-level decisions that recipes build upon
- [Write a Context File](/learn/tutorials/write-a-context-file) — hands-on: author a context file and see the recipe in practice
---
## https://adna.network/patterns/dual-audience-writing/
# Dual-Audience Writing — aDNA Patterns
## Problem
aDNA documentation must serve two audiences with different needs: developers seeking technical precision for implementation, and newcomers seeking plain-language understanding of what aDNA is and why it matters. Writing only for developers excludes newcomers. Writing only for newcomers frustrates developers who need spec references, field names, and decision tables.
Most documentation systems solve this by creating separate documents — a "Getting Started" guide and an "API Reference." This doubles maintenance cost and creates drift between the two versions.
## Solution
Write every content file with **layered depth** — both audiences served in one document, in a specific order (Campaign CLAUDE.md, Quality Gate 1):
| Section | Audience | Purpose |
|---------|----------|---------|
| **Opening** (1-3 sentences) | Everyone | Plain-language summary a 14-year-old could follow |
| **Why This Matters** | Newcomers first, developers second | Metaphor-driven motivation, no jargon, then bridge to technical impact |
| **How It Works** | Both | Technical substance with tables, spec citations, and decision frameworks |
| **See It In Action** | Both | Self-referential example from this vault |
| **Related** | Both | Cross-links for further exploration |
**Key principles**:
1. **Plain-language opening is mandatory.** The first sentences must be jargon-free. If a concept can't be explained simply, the file isn't ready.
2. **Metaphor before mechanism.** Give the reader a mental model ("think of it like a funnel") before introducing technical terms.
3. **Tables over prose for technical content.** Developers scan tables; newcomers read the surrounding prose. Tables serve both.
4. **Spec citations for precision, not authority.** "§3.1" tells a developer exactly where to look. A newcomer skips it without losing understanding.
5. **One file, two reads.** A newcomer reads the opening and motivation, gets the gist, and moves on. A developer reads the tables and spec citations, gets the implementation details. Neither needs a separate document.
## When to Use
- Every concept, pattern, tutorial, and comparison file in an aDNA documentation vault
- Governance files that may be read by non-technical stakeholders
- README files and entry-point documentation
- Any content intended for a mixed-expertise audience
## Example: This Vault
Every concept file in `what/concepts/` demonstrates dual-audience writing. Open `concept_convergence.md`:
- **Opening**: "The convergence model is aDNA's structural principle for managing complexity..." — one sentence, no jargon, immediately clear.
- **Why This Matters**: "Picture a funnel..." — starts with a spatial metaphor any reader can follow, then bridges to the technical problem (token limits, context windows).
- **How It Works**: Decision tables, token budgets, spec references (§8.7, §9, §10) — a developer's reference material.
- **See It In Action**: Points to actual files and token counts in this vault — concrete, verifiable.
The same layering appears in this file you're reading now. The Problem section is plain-language. The Solution section has tables for developers. Both audiences are served without duplication.
## Anti-Pattern
**Jargon-first writing**: "The convergence model implements monotone-decreasing token bounds across the execution hierarchy DAG." Technically accurate. Newcomers leave immediately.
**Dumbing down**: Removing all technical depth to be "accessible." Developers can't find the spec references, field names, or decision criteria they need. Accessibility doesn't mean simplification — it means layered depth.
**Separate documents**: Writing a "Simple Guide" and a "Technical Reference" for the same concept. Maintenance doubles, versions drift, and there's no single source of truth.
**Apologetic jargon**: "This might sound complicated, but..." Don't apologize. Give the metaphor first, then give the technical term. Confidence, not condescension.
## Related
- [Dual Audience](/learn/concepts/dual-audience) — the concept that explains why this pattern exists
- [Agentic Literacy](/learn/concepts/agentic-literacy) — the literacy movement that dual-audience writing makes inclusive
- [Question Test](/patterns/question-test) — another pattern where simplicity serves dual audiences
---
## https://adna.network/patterns/fair-envelope/
# FAIR Envelope — aDNA Patterns
## Problem
A shareable object without a label is a black box — nobody outside your project can find it, tell if it's trustworthy, know who made it, or use it legally. This pattern applies to aDNA's shareable units (lattices, modules, datasets): without a standard metadata envelope, sharing them means emailing files around and explaining each one by hand. That doesn't scale.
## Solution
Wrap every shareable object in a **FAIR envelope** — a standardized metadata block that answers four questions (§6):
| Principle | Question | Key Fields |
|-----------|----------|-----------|
| **Findable** | Can someone discover this? | `keywords` (required), `identifier` (optional DOI) |
| **Accessible** | Can they retrieve it? | `license` (required, SPDX), `access_protocol`, `location` |
| **Interoperable** | Can they use it with other systems? | `format` (type vocabulary), `schema` |
| **Reusable** | Can they build on it? | `provenance`, `creators` |
**Two required fields**: `keywords` (at least one) and `license` (SPDX identifier). Everything else is optional but recommended for shared objects.
**Two representations**:
| Format | Where | Structure |
|--------|-------|-----------|
| **Flat** | `.lattice.yaml`, `.dataset.yaml` | `fair.keywords`, `fair.license`, etc. |
| **Nested** | Vault `.md` frontmatter | `fair.findable.keywords`, `fair.accessible.license`, etc. |
Both are round-trip safe for core fields. Use flat in YAML transport files, nested in markdown documentation.
**The minimum viable envelope**:
```yaml
fair:
keywords: [knowledge-architecture, documentation]
license: "MIT"
```
Two fields, two lines. That's the entry cost for making an object findable and legally shareable.
## When to Use
- Every `.lattice.yaml` and `.dataset.yaml` file
- Every module definition intended for sharing
- Context files in a shared context library
- Any object that might be federated, published, or used by another project
## Example: This Vault
**Lattice examples**: Every `.lattice.yaml` in `what/lattices/examples/` carries a FAIR block. The `protein_binder_design` example has:
```yaml
fair:
license: "MIT"
keywords: [protein-design, binder, computational-biology]
creators: ["Lattice Labs"]
provenance: "Designed for de novo protein binder pipeline"
```
Four lines that make this lattice discoverable, legally clear, attributable, and traceable.
**Context files**: The files in `what/context/adna_core/` use FAIR-aligned metadata in their frontmatter: `sources` (provenance), `tags` (findability), and quality scores (reusability signals). While they use frontmatter fields rather than a formal `fair:` block, the principles are the same — every file carries enough metadata to evaluate before loading.
**The FAIR mapping reference**: `what/context/adna_core/context_adna_core_fair_mapping.md` documents the complete field correspondence between flat and nested FAIR, including anti-patterns (mixing formats, omitting license for shared objects).
## Anti-Pattern
**No metadata at all**: A lattice file with nodes and edges but no `fair:` block. It works locally but can never be shared — federation validation requires license and keywords.
**Keywords as afterthought**: `keywords: [misc]`. Keywords are the primary findability mechanism. They should be specific enough to distinguish this object from others: `[protein-design, binder]` not `[science, data]`.
**Missing license on shared objects**: `federation.shareable: true` without `fair.license`. The federation protocol will reject it — no license means no legal basis for sharing.
**Mixing flat and nested**: Using `fair.findable.keywords` in a `.lattice.yaml` file (should be flat `fair.keywords`) or `fair.keywords` in vault frontmatter (should be nested `fair.findable.keywords`). Pick the format for the file type and be consistent.
## Related
- [FAIR Metadata](/learn/concepts/fair-metadata) — the concept explaining why FAIR matters and how it works
- [Federation Readiness](/patterns/federation-readiness) — the broader checklist that includes FAIR as a prerequisite
- [Context Commons](/learn/concepts/context-commons) — the community sharing vision FAIR enables
---
## https://adna.network/patterns/federation-readiness/
# Federation Readiness — aDNA Patterns
## Problem
Something that works in your project isn't automatically safe to hand to someone else. A workflow may rely on files only you have, skip the labels a stranger needs to trust it, or miss the licensing a partner's legal team will ask for. The gap between "works locally" and "safe to share across projects" takes deliberate preparation — internal references break, metadata is missing, provenance is undeclared.
## Solution
Before federating a lattice, run the **6-point readiness checklist** (§11):
| # | Check | Field | Why |
|---|-------|-------|-----|
| 1 | Schema validation | Run `lattice_validate.py` | Catches structural errors before they propagate |
| 2 | Shareable opt-in | `federation.shareable: true` | Federation is never accidental — explicit consent |
| 3 | Source instance | `federation.source_instance` | Provenance: where did this come from? |
| 4 | License declared | `fair.license` | Legal: can the recipient use this? |
| 5 | Keywords present | `fair.keywords` (≥1) | Discovery: can someone find this? |
| 6 | References resolve | All `ref` fields are valid paths or `lattice://` URIs | Integrity: no broken links in the target |
**The readiness workflow**:
1. **Validate** — Run the schema validator against the `.lattice.yaml`. Fix any errors.
2. **Audit references** — Check every `ref` field. Replace local paths with `lattice://` URIs for cross-instance references. Remove or document references that are instance-specific.
3. **Add FAIR metadata** — Ensure the `fair:` block has at least `keywords` and `license`. Add `provenance` and `creators` for full trust.
4. **Set federation block** — Enable `shareable: true`, set `source_instance`, choose a `version_policy`.
5. **Document interfaces** — If the lattice will be composed (not just imported whole), declare entry/exit nodes and their expected data types.
6. **Re-validate** — Run the validator again. Federation properties have their own consistency checks.
**Version policy selection**:
| Policy | Behavior | Best For |
|--------|----------|---------|
| `locked` | Halt on any version change | Production dependencies |
| `patch` | Accept patches, halt on minor/major | Stable integrations |
| `minor` | Accept minor changes, halt on major | Active development |
| `latest` | Always use latest, warn on breaking | Experimental use |
## When to Use
- Before publishing a lattice to a registry
- Before sharing a lattice with another aDNA instance
- When extracting a sub-lattice from a larger pipeline for independent use
- During quality reviews of lattice objects
## Example: This Vault
The lattice examples at `what/lattices/examples/` demonstrate federation readiness at different stages:
**Federated example**: The `docking_assessment` lattice carries a complete federation block:
```yaml
federation:
shareable: true
source_instance: adna
parent_lattice: protein_binder_design
version_policy: locked
extracted_nodes: [structure_prediction, interface_analysis, ranking]
```
This lattice passes all 6 checks: schema-valid, opted in, provenance set, licensed, keyworded, and its `extracted_nodes` cross-reference against the parent lattice.
**Validation tools**: `what/lattices/tools/lattice_validate.py` implements checks 1-6 programmatically. Running it against a lattice file reports schema compliance, node ID uniqueness, edge reference validity, and federation property consistency.
**The readiness checklist in practice**: The federation guide at `what/context/adna_core/context_adna_core_federation.md` includes both pre-federation and post-federation checklists — the full workflow from "private lattice" to "composed into another project."
## Anti-Pattern
**Accidental federation**: Setting `shareable: true` on a lattice that contains internal references, proprietary data, or unresolved dependencies. Federation must be deliberate.
**Local paths in shared lattices**: A `ref: what/modules/my_custom_module` that only exists in the source project. Shared lattices must use `lattice://` URIs or document that the reference is instance-specific.
**Missing version policy**: Federating without declaring a `version_policy`. The default is `minor`, but explicit is always better — the policy determines what happens when the source updates.
**Skipping post-federation validation**: Importing a lattice into a target project without re-validating. The lattice may be valid in source but incompatible in target (different ontology, missing dependencies).
## Related
- [Lattice Composition](/learn/concepts/lattice-composition) — the composition patterns that federation-ready lattices enable
- [FAIR Envelope](/patterns/fair-envelope) — the metadata pattern that federation readiness depends on
- [Open Standard](/learn/concepts/open-standard) — the governance model that makes cross-instance federation possible
---
## https://adna.network/patterns/mission-decomposition/
# Mission Decomposition — aDNA Patterns
## Problem
Some jobs — writing thirteen concept files, or building a whole documentation site — are too big for any one agent session to finish in one go. Without a plan that breaks them into smaller pieces, agents either bite off more than their context window can hold or wander without direction and duplicate each other's work.
## Solution
Decompose large tasks into **missions**, each containing **objectives** that fit a single session (§9). The execution hierarchy is:
```
Campaign → Mission → Objective
(strategic) (tactical) (session-sized)
```
*[Decomposition narrows the working set at each step — vault to objective.]*
**Mission design rules**:
| Principle | Rule |
|-----------|------|
| Session-sized objectives | Each objective must be completable in one agent session |
| Explicit deliverables | Every objective names a specific output file or artifact |
| Dependency ordering | Objectives list dependencies — what must be done first |
| Context budget | The mission declares what context to load, staying within the 75% rule |
| Claimability | Any agent can pick up any unclaimed objective with the mission file as briefing |
**The decomposition process**:
1. Start with the campaign goal (e.g., "build a self-referential aDNA documentation vault")
2. Identify natural work boundaries (e.g., concepts, patterns, tutorials are different missions)
3. Within each mission, list specific deliverables as objectives
4. Order objectives by dependency (foundational concepts before advanced ones)
5. Estimate the context budget and declare the model tier — see [Budgeting and Routing a Mission](#budgeting-and-routing-a-mission) below. As a first cut: more than ~15K tokens of *domain* context in one objective usually means the objective is too broad
**Handoff continuity**: Each mission file contains enough context for a fresh agent to continue. The intent, objectives, context dependencies, and handoff notes create a self-contained briefing.
## Budgeting and Routing a Mission
Decomposing the work leaves two questions open: **how much context each objective will cost**, and **which model should run it**. Both are answered on the mission file itself, before the work starts — so they are recorded decisions rather than things reconstructed afterwards from what happened.
### The budget: two fields
Every mission declares `token_budget_estimated`. Every session that works on it logs `token_budget_actual`. Both are measured in kT — thousands of tokens of context loaded.
The estimate comes from a formula, not a feeling:
```
session_cost ≈ transition_tax + Σ per_objective_work
```
`transition_tax` is what a fresh agent spends before it does anything useful: reading the governance files, the campaign, the mission. In this vault it measures around 23K tokens. `per_objective_work` runs roughly 5K–80K depending on the kind of objective — planning is cheap, verification is expensive.
The total then decides the shape of the work:
| Estimated total | Session shape |
|-----------------|---------------|
| Under 50K | One session. Splitting costs more in transition tax than it saves. |
| 50K–80K | One or two sessions. |
| 80K–200K | Two or three sessions. |
| 200K or more | **Split it into more than one mission.** |
The last row is the one that earns the table. A mission that needs more than 200K tokens is not a mission that needs a bigger window — it is two missions that have not been separated yet.
### Why the actual is recorded too
An estimate nobody checks is a formality. Each mission's After-Action Review reports estimate against actual, and drift beyond **2×** in either direction triggers a retrospective — not a penalty, a question: was the estimate wrong, or did the scope move while nobody was looking?
That second case is the common one, and it has a shape worth naming: a budget ratified before the mission's acceptance criteria are settled is a budget costed against work nobody has chosen yet. The fix is ordering — settle the criteria, then cost them.
### The tier: which model runs it
Alongside the budget, a mission declares `executor_tier` — the class of model the work is routed to. The classes are defined by properties of the *decision*, not by model names:
| Class | The work it names |
|-------|-------------------|
| Strategy / judgment | Novel design, ambiguous requirements, irreversible or outward-facing consequences, adversarial review. "What should we even do?" |
| Mid-judgment | Well-briefed execution making local decisions inside stated guardrails; drafting against acceptance criteria. |
| Mechanical | Enumerable, verifiable, low-ambiguity transforms: sweeps, counts, extractions, format fixes. |
Which model each class binds to is a **separate table, re-pinned as model generations change**. The classes are the doctrine; the model names are not, and writing the names into the pattern would date it on contact.
What makes it safe to run a mission on a cheaper model is not the model — it is the brief. A mission is only routable downward if its brief already carries six things explicitly: the objective, the acceptance criteria, the guardrails (what must not be touched, pushed, or decided), the verification surface that proves completion, the named conditions under which the executor halts and escalates instead of improvising, and the budget. Judgment is spent at design time so that it does not have to be spent at execution time.
**The limit, in the same breath**: `executor_tier` is a plan, and plans are sometimes not honoured. This vault has shipped a mission whose declared tier and actual tier diverged for four consecutive sessions, and nobody noticed until the After-Action Review. The record now names both, because a declared tier nobody honours is worse than no field at all. Both fields are visible in this vault's own mission files — including the mission that added this section, which declared its tier and its budget band before a word of it existed.
## When to Use
- Any task expected to take more than one session
- Work that involves multiple related deliverables
- When coordination between sessions (or agents) is needed
- Campaign planning — every campaign is a set of missions
## Example: This Vault
Operation Rosetta decomposes into 15 missions across 5 phases. Phase 1 alone has 5 missions:
| Mission | Objectives | Why Separate |
|---------|-----------|-------------|
| M01 | 3 foundational concepts | Must exist before anything can cross-link to them |
| M02 | 4 governance concepts | Resolves M01 forward references |
| M03 | 6 advanced concepts | Builds on M01+M02 cross-linking targets |
| M04 | 8 patterns | Different template, different AGENTS.md rules |
| M05 | 5 comparisons | Requires full concept vocabulary from M01-M03 |
Each mission file (e.g., `how/campaigns/campaign_rosetta/missions/mission_m04_pattern_library.md`) lists specific files as objectives, declares context dependencies, and ends with handoff notes and an AAR. A fresh agent reading only the mission file can claim the next objective and begin work.
The decomposition also demonstrates [convergence](/learn/concepts/convergence): the campaign scope (~100+ files) narrows to a mission scope (~8 files) narrows to a session objective (1 file at a time).
## Anti-Pattern
**Monolithic missions**: A mission with 20 objectives spanning 5 sessions. By session 3, the agent has lost context on the mission's intent. Split into smaller missions with clear boundaries.
**Objectives without deliverables**: "Research token optimization" is not an objective — it has no verifiable output. "Write `concept_context_optimization.md`" is an objective — the deliverable is the file.
**Missing dependency ordering**: Writing advanced concepts before foundational ones, then discovering forward references can't be resolved. Map dependencies before starting.
**Skipping the AAR**: Completing a mission without the 5-line After-Action Review. The AAR captures what worked, what didn't, and what the next mission should know. Without it, the same mistakes repeat.
## Related
- [Convergence Model](/learn/concepts/convergence) — the structural principle that makes decomposition necessary and effective
- [Token Selection](/learn/concepts/token-selection) — the context budget discipline that sizes objectives to sessions
- [AGENTS.md Routing](/patterns/agents-md) — how agents navigate to their mission's working files
---
## https://adna.network/patterns/question-test/
# The Question Test — aDNA Patterns
## Problem
Every new file in an aDNA project needs to land in one of three folders — `what/`, `how/`, or `who/`. Most files are obvious; edge cases cause hesitation. Is a team standup protocol a WHO thing (it involves people) or a HOW thing (it's a process)? Is a decision record a WHAT thing (it's knowledge) or a HOW thing (it documents a process)?
Hesitation leads to inconsistency. Inconsistency leads to files scattered across legs, breaking the navigability that makes the triad valuable.
## Solution
Apply the **question test** (§3.1): ask "Is this about WHAT we know, HOW we work, or WHO is involved?" The answer determines the triad leg.
| Question | Triad Leg | Contains |
|----------|-----------|----------|
| WHAT does this project know? | `what/` | Knowledge, context, decisions, domain entities |
| HOW does this project work? | `how/` | Plans, processes, templates, sessions, skills |
| WHO is involved? | `who/` | People, teams, roles, coordination, governance |
**The decisive rule**: if the file's primary purpose is to capture knowledge, it's WHAT. If it's to drive action, it's HOW. If it's to describe people or relationships, it's WHO.
**Edge case resolution**: When a file seems to span two legs, it's trying to do two things. Split it. A meeting protocol (HOW — it's a process) is separate from the team roster it references (WHO — it's about people). A decision record (WHAT — it captures knowledge) is separate from the mission that prompted it (HOW — it drives action).
The test always produces exactly one answer. If it produces two, the content needs splitting, not a fourth category.
## When to Use
- Every time you create a new file in an aDNA vault
- When reviewing vault structure for misplaced content
- When onboarding someone unfamiliar with the triad
- When designing ontology extensions (the extension goes under the leg its question maps to)
## Example: This Vault
This file — `pattern_question_test.md` — lives in `what/patterns/` because it answers "WHAT does this project know?" It knows about the question test pattern.
The mission file that scheduled its creation lives in `how/campaigns/campaign_rosetta/missions/` because it answers "HOW does this project work?" It works by executing missions.
The governance policies in `who/governance/` answer "WHO is involved?" — they define roles and authority.
Every file in this vault was placed by applying the question test. Navigate to any directory and ask "which question does this answer?" — the answer will match the triad leg it's in.
## Anti-Pattern
**The miscellaneous drawer**: Creating a fourth top-level directory (`resources/`, `shared/`, `misc/`) because some files "don't fit." They always fit — the question test was applied incorrectly or the file is trying to do two things.
**Sorting by format**: Putting all PDFs in one place, all YAML in another. Format is orthogonal to the triad. A YAML lattice definition (`what/`) and a YAML session config (`how/`) answer different questions despite sharing a format.
**WHO/HOW confusion**: Placing process documentation under `who/` because people execute processes. The test is about the file's primary purpose, not its participants. A sprint protocol is HOW (process); the team running it is WHO (people).
## Related
- [The Triad](/learn/concepts/triad) — the architectural principle the question test implements
- [Ontology](/learn/concepts/ontology) — the entity types within each triad leg
- [Base/Extension](/patterns/base-extension) — how new entity types inherit their triad placement
- [Apply the Question Test](/learn/tutorials/question-test) — hands-on: use the test to classify 10 real project files
---
## https://adna.network/privacy/
# Privacy
The short version: **adna.network collects nothing about you.** No accounts,
no analytics, no advertising, no cookies, no tracking. It is a static, open-source
website — and the longer version below is written so you can verify every word.
## What we collect
**Nothing.** There are no sign-ups, no forms, no comment boxes, and no login.
We run no analytics (no Google Analytics, no Plausible, no Fathom — none), set no cookies,
and load no advertising or tracking pixels. Your browser makes **no third-party
requests** when you read these pages: the fonts are served from adna.network itself,
and there are no embedded widgets, iframes, or remote scripts.
## What is stored in your browser
If you switch between light and dark mode, we save that choice — the word `theme`.
If you work through the intro course, we save which lessons you have finished — under
`adna:course:v1`. Both live in your browser's `localStorage`, so the site
remembers them on your next visit. Neither ever leaves your device, neither is sent to us or to
anyone else, and you can clear both at any time through your browser. They exist to serve you,
not to identify you.
## Performance measurement
The site measures how fast each page loads *in your own browser* — standard web
performance numbers like "how long until the largest element painted". Those numbers are
now **sent to Vercel**, the host described above, so we can see whether the site
is actually fast for the people using it rather than only on our own machines.
What is sent is the timing itself, the page it belongs to, and coarse technical context your
browser already reveals to any site. **No cookie is set for this**, nothing extra
is stored on your device, and we do not receive anything that names you or lets us follow you
between pages. We see aggregate speed, not visitors. Vercel's handling of what it receives is
governed by [Vercel's privacy policy](https://vercel.com/legal/privacy-policy), exactly as with the server logs above.
A second measurement still stays entirely on your device: the same timings are also raised
inside the page itself, where they exist only in memory while the page is open and are
discarded when you leave. That one has never been sent anywhere and still is not.
## Hosting & server logs
The site is a set of pre-built static files hosted on **Vercel**. Like every
web host, Vercel processes the standard technical metadata your browser sends with any
request — your IP address and user-agent — to actually deliver the pages and to keep the
service secure and available. We do not receive, store, or analyse that data ourselves, and
we do not combine it with anything else. Vercel's handling of it is governed by
[Vercel's privacy policy](https://vercel.com/legal/privacy-policy).
## Your aDNA vault stays yours
aDNA is an open standard for plain-Markdown, **local-first** knowledge vaults.
A vault you build with aDNA lives on your own machine and is never pushed anywhere unless
you choose to configure a remote. Nothing about your vault — its contents, structure, or
the credential *names* it indexes — is transmitted to us by using this site or the
standard. This site is documentation; it is not a service that ingests your data.
## If you work with regulated data
This site's own examples reach into rare-disease research, so it is worth saying plainly
what aDNA is. It is an open specification for how knowledge files and directories are named
and annotated — **a file-layout convention**, not a system that runs. Adopting
it transmits nothing, because a naming convention has nothing to transmit with.
Because of that, **we make no regulatory claim about it at all**: nothing here
is certified, approved, audited, or warranted under any regime. If you keep regulated
material in a vault, the obligations that attach to it — HIPAA, GDPR, IRB review, or
whatever governs your work — rest entirely with **you and the tools you actually
run**: your machine, your storage, your agents, your institution's rules. A directory
layout cannot discharge any of them, and nothing on this site should be read as though it
could.
## Links to other sites
We link out to places like GitHub, the projects in the network, and the tools aDNA composes
with. Once you follow a link, you are on someone else's site under their own privacy terms —
we have no control over, and take no responsibility for, how they handle your data.
## Questions or corrections
This is an open-source project. If you have a privacy question — or you think
something on this page is inaccurate — open an
[issue](https://github.com/aDNA-Network/aDNA/issues) on the canonical repository and
a maintainer will follow up in the open.
Published by aDNA Network. Last updated 2026-09-03. If this posture ever changes — for
example, if aggregate, privacy-respecting analytics are ever added — we will update this page
before the change ships, and note it in the site changelog.
---
## https://adna.network/provenance-audit/
# Provenance & audit
Auditors ask five questions about AI-assisted work. The vault answers all five
using the same files the team already edits — the audit trail is the working
artifact, not a parallel workstream. For compliance officers, security reviewers,
and procurement leads; the sibling [enterprise adoption checklist](/use-cases/enterprise-team/) organizes the same evidence by evaluation domain.
## 1 · Who wrote this artifact?
Every governed file carries `last_edited_by` and `updated`
in its frontmatter; the matching session file in `how/sessions/`
records intent and scope. Attribution scales from a single frontmatter line up
to a full session narrative.
- **Frontmatter attribution:** `last_edited_by: agent_{username}` on every content file.
- **Session-level attribution:** session file opens with ID, intent, and scope — a reviewable work-unit narrative, not just a file-level diff.
- **Git as second witness:** every commit is attributed and dated; session records cross-reference the commit.
[Session Glossary Every agent-assisted work unit produces a file in how/sessions/ with session ID, intent, scope, files touched, and a closing SITREP — the primitive audit…](/glossary/glossary-session)[SITREP Glossary Structured session closure (Completed / In progress / Next up / Blockers / Files touched) plus a Next Session Prompt — turns a session close into a reviewable…](/glossary/glossary-sitrep)[Enterprise Team Use Case Narrative walkthrough: a 50-person platform org replaces week-long compliance investigations with scripted queries over the session corpus.](/use-cases/enterprise-team)
## 2 · What context did the agent have?
Agent output is only as good as its inputs. The session file names the intent
and files consulted; the [context engineering](/learn/concepts/context-optimization) layer makes the context-assembly rules explicit. Reviewers
answer "what was the agent told to do, with what reference material" without
re-running the agent.
- **Session intent:** every session file names the stated objective at the top.
- **Context inputs:** routing files (AGENTS.md) and context recipes name which knowledge objects the agent loaded — traceable, not opaque.
- **Scope declaration:** Tier-2 sessions declare scope and run a conflict scan before editing shared configuration; the declared scope is part of the audit record.
## 3 · Was the work reviewed?
Review is structurally required: `CLAUDE.md` names standing orders;
`who/governance/` holds role definitions; every multi-session
mission closes with an AAR under `how/missions/artifacts/` before
it can be marked complete.
- **Standing orders:** CLAUDE.md at the vault root names the rules that apply to every session — including the rule that every mission gets an AAR before closure.
- **Review artifacts:** the AAR template (Worked / Didn't / Finding / Change / Follow-up) is mandatory on mission close, producing a short, structured review record.
- **Escalation cascade:** anomalies propagate session → mission → campaign → STATE.md, so a reviewer can follow a flag from discovery to resolution.
[Governance Files CLAUDE.md, MANIFEST.md, STATE.md, AGENTS.md at the vault root — the fixed-path governance layer auditors orient to once and reuse across every team vault.](/learn/concepts/governance-files)[Architecture Decisions ADR files under what/decisions/ pair each technical choice with rationale, trade-offs, and reviewer attribution — designed for both engineering and compliance…](/patterns/dual-audience-writing)[Collision Prevention last_edited_by + updated + read-before-write contract prevents concurrent agents and humans from clobbering one another — the primitive that makes a shared…](/glossary/glossary-collision-prevention)
## 4 · What stops two agents from clobbering each other?
The [collision-prevention](/glossary/glossary-collision-prevention)
contract is three frontmatter fields plus one procedural rule:
`last_edited_by`, `updated`, and read-before-write.
Git closes the loop — the authoritative history is the HEAD commit, not any
agent's in-memory belief.
- **Read before write:** no file is modified without reading current state first — catches stale-state edits.
- **Updated-date check:** if `updated` is today and the current agent didn't make the last edit, the agent pauses and confirms — a lightweight merge-conflict substitute.
- **Truth hierarchy:** git HEAD outranks any agent's cached read or memory; authoritative state is what's committed.
## 5 · How is the audit trail preserved?
A vault's history is append-only by convention. Sessions move from
`active/` to `history/YYYY-MM/` on completion; missions
and campaigns are archived with `status: completed` or
`abandoned`, never deleted. Standing order #6 ("archive, never
delete") applies to every governance artifact.
- **Archive, never delete:** session records, mission files, and campaign documents are a permanent audit trail.
- **Monthly partitioning:** session history under `how/sessions/history/YYYY-MM/` — scan by month, query by quarter, no ORM required.
- **Queryable with standard tools:** sessions and ADRs are YAML-headed markdown — `grep`, `jq`, `yq` read them.
[Federation Readiness Six-point readiness check (schema valid, opt-in, source instance, license, keywords, resolved references) gates every artifact that crosses a team boundary.](/patterns/federation-readiness)[FAIR Envelope License, creators, keywords, provenance, and identifier travel with every federated artifact — legal provenance is a data field, not a separate document.](/patterns/fair-envelope)[Open Standard The specification is open and permissively licensed — no vendor lock-in, no platform dependency. Vault contents are plain markdown in git.](/learn/concepts/open-standard)
## How this maps to named regimes
**Read this first.** aDNA is an open documentation standard, not a certified
product — adopting it does not make you compliant with anything. What a vault gives you is
*working evidence*: dated, attributed records a reviewer can read. Certification is
granted by accredited assessors against your own controls, never by adopting a standard.
With that caveat, the same audit trail lines up cleanly with what the frameworks
procurement teams cite actually ask reviewers to demonstrate:
Framework What it asks for What an aDNA vault supplies
SOC 2 Evidence that security and change-management controls operate over time — who changed what, when, and whether it was reviewed. Session records in how/sessions/ plus git history give a per-change, dated, attributed trail; the AAR-on-close rule is a recurring review control; STATE.md tracks open risks.
ISO/IEC 27001 A documented management system: policies, defined roles, risk treatment, and records showing the system is actually followed. CLAUDE.md carries the standing orders and priority hierarchy; who/governance/ defines roles; what/decisions/ (ADRs) record risk-bearing choices with rationale — documented-and-followed, in plain markdown.
EU AI Act For higher-risk AI use: record-keeping, human oversight, and traceability of how an AI-assisted output was produced. Every agent-assisted change names its intent, inputs, and reviewer; phase and mission gates are explicit human-oversight points; the trail from output → session → context inputs is the traceability the Act asks for.
## Self-reference: this vault is the worked example
The audit trail described here is the one this vault runs on — including the
session that produced this page. Browse `how/sessions/history/`
and read a few closed sessions end-to-end to evaluate the audit model directly.
## Next Steps
[Enterprise Team The sibling surface: a structured evaluation framework across governance, session audit, federation, and integration — plus the pain points, ontology…](/use-cases/enterprise-team/)[Federation Readiness Pattern The readiness-gate pattern in full — what blocks publication, what travels with a shared artifact, how version policy works across teams.](/patterns/federation-readiness)[Session Glossary Canonical definition of the session record — the atomic unit of the audit trail.](/glossary/glossary-session)
## Set up your workspace
[Get Started](/get-started/) [Read the governance model](/reference/governance-model/)
---
## https://adna.network/reference/
*[image: Cozy pixel-art archive library with warm-lit shelves of books and a brass reading lamp — the canonical aDNA reference]*
# The Standard
The normative references for the aDNA standard. Start with the specification — when in doubt, it is authoritative — then the rationale, governance, and craft docs that support it.
## The specification
Standard v2.5
Agentic DNA (aDNA) — A knowledge architecture standard for AI-native projects.
[Read the specification →](/reference/specification)
## Rationale & guides
Why aDNA is shaped the way it is, and how to read, adopt, and set it up.
[Design Rationale This document explains why aDNA is designed the way it is — the companion to the aDNA Universal Standard, which defines what to do.](/reference/design-rationale)[Reading Guide The aDNA Universal Standard is ~1,500 lines. You don't need all of them. This guide maps three reading paths by what you're trying to do, provides a…](/reference/reading-guide)[Agent-First Guide This guide is for developers who want to use aDNA with Claude Code (or another AI coding agent) from the terminal, without installing Obsidian. If you…](/reference/agent-first-guide)[Migration Guide This guide is for developers who already have a project and want to add aDNA to it. If you're starting fresh, use the Quick Start instead — clone the…](/reference/migration-guide)[Tool Setup Every aDNA setup needs three things: Git, a text editor that reads Markdown and YAML, and Python 3.8+ for the validation tooling.](/reference/tool-setup)
## Governance & quality
How decisions get made and how conformance is measured.
[Governance Model The aDNA standard is stewarded today by a Founding Architect, and is progressively decentralizing toward steward-led, public governance.](/reference/governance-model)[Quality Rubric Systematic quality evaluation framework for context library objects. Provides a 6-axis quantitative rubric that gates all context files — any file…](/reference/quality-rubric)
## Craft
The house style for writing and visual identity across aDNA surfaces.
[Writing Guidelines Canonical clarity and conciseness guidelines for aDNA prose surfaces — checklist, voice precedents, conciseness contract, and validation gate.](/reference/writing-guidelines)[Visual Identity v2 Canonical visual identity for aDNA.network — the Science-Stanley Ghibli-pixel / Tokyo Night register: color, type, spacing, imagery, icons, diagrams.](/reference/visual-identity-v2)
## Resources
Vocabulary and operational guides that support the specification.
[Glossary 25 canonical aDNA term definitions — from AGENTS.md to Vault, with spec cross-references.](/glossary)[How Operational guides: workshop kits, publishing pipeline, lattice examples, and skill recipes.](/how)
---
## https://adna.network/reference/agent-first-guide/
# Agent-First Guide — aDNA Reference
## 1. Introduction
This guide is for developers who want to use aDNA with Claude Code (or another AI coding agent) from the terminal, without installing Obsidian. If you already use Obsidian, you don't need this — the [Quick Start](/get-started/) covers everything.
**What you'll have at the end**: A working aDNA vault that Claude Code can navigate, with session tracking, templates, and the full execution hierarchy — all from your terminal and text editor.
**Time estimate**: 10-15 minutes.
**Prerequisites**:
- Git
- A text editor (VS Code, Vim, Emacs, whatever you use)
- The `claude` CLI ([Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview))
---
## 2. What Works Without Obsidian
aDNA is a directory convention — Markdown files with YAML frontmatter organized in a `who/`/`what/`/`how/` triad. Obsidian adds a visual layer on top, but the operational core is plain files on disk.
### Feature parity at a glance
| Bucket | Count | % | What's in it |
|--------|-------|---|-------------|
| **Works everywhere** | 22 | 55% | Governance, sessions, templates, context library, execution hierarchy, git workflow, FAIR metadata, lattice YAML, naming conventions, skills, campaigns, missions, onboarding |
| **Degraded** | 6 | 15% | Wikilinks (no click-nav), graph view (unavailable), Dataview queries (won't render), search (editor-dependent), Meta Bind inputs (won't render), Tasks queries (won't render) |
| **Requires Obsidian** | 12 | 30% | Templater auto-trigger, Canvas, Obsidian Git, Notebook Navigator, Homepage, Icon Folder, Style Settings + CSS, BRAT, Termy, Pretty Properties, Fold Properties, Banners |
**The important number**: The operational core — governance (`CLAUDE.md`, `AGENTS.md`), session tracking, templates-as-files, context library, execution hierarchy, git workflow — is **100% functional** without Obsidian. The 30% you lose is visual polish and automation shortcuts. The value split is closer to **80/20**.
### Detailed breakdown
**Works everywhere** — these features are plain Markdown and YAML:
| Feature | How it works without Obsidian |
|---------|-------------------------------|
| `CLAUDE.md` governance | Auto-loaded by Claude Code on startup. No change. |
| `AGENTS.md` per-directory guides | Read by agents before working in a directory. No change. |
| `MANIFEST.md` + `STATE.md` | Plain Markdown. No change. |
| Triad structure (`who/`/`what/`/`how/`) | Directory convention. Works in any filesystem. |
| YAML frontmatter | Standard YAML. Parsed by agents, readable in any editor. |
| 16 base entity types | Naming conventions + frontmatter schemas. No Obsidian dependency. |
| Session tracking | Create files in `how/sessions/active/`, move to `history/` on close. |
| Execution hierarchy | Campaign → Mission → Objective. Plain Markdown with status tracking. |
| Context library | `what/context/` files loaded by agents on demand. |
| Context recipes | Cross-topic assembly instructions. Agent-parsed. |
| Skills | Reusable agent recipes in `how/skills/`. Agent-executed. |
| Templates | Files in `how/templates/`. Copy manually instead of auto-trigger. |
| Git workflow | Standard git. `commit`, `push`, `pull` from terminal. |
| Lattice YAML | `.lattice.yaml` definitions. Schema-validated. |
| FAIR metadata | `fair:` blocks in lattice YAML. No rendering dependency. |
| Naming conventions | Underscores, `type_descriptive_name.md`. Convention, not tooling. |
| Wikilinks as identifiers | `[[filename]]` syntax serves as machine-parseable cross-references even without Obsidian's click-navigation. Agents use them for relationship discovery. |
| First-run detection + onboarding | Claude Code reads `CLAUDE.md`, detects uncustomized vault, runs `skill_onboarding.md` interactively. Fully terminal-compatible. |
| Bridge patterns | Multi-vault composition. Directory conventions, no Obsidian dependency. |
| OODA cascade | Observe-Orient-Decide-Act at each execution level. Methodology, not tooling. |
| Convergence model | Progressive context narrowing. Agent behavior, not Obsidian feature. |
| Escalation / priority rules | Governance protocols. Agent-enforced. |
**Degraded** — present in files but won't render interactively:
| Feature | What happens | Workaround |
|---------|-------------|------------|
| Wikilinks | `[[filename]]` appears as literal text. No click-navigation, no auto-rename on file move. | Use `grep` or `rg` to find references. Agents parse wikilinks natively. |
| Graph view | Not available. No visual map of entity relationships. | Use `grep '[[' *.md` to trace links. Or `rg '\[\[' --type md` for recursive search. |
| Dataview queries | ` ```dataview ``` ` blocks appear as code fences. No rendered tables. | Claude Code can query frontmatter directly — ask it to find files by type, status, etc. |
| Search | No unified Obsidian search. | `rg` (ripgrep) or your editor's search. Claude Code's `Grep` tool works across the vault. |
| Meta Bind inputs | ` ```meta-bind ``` ` blocks appear as code fences. No interactive controls. | Edit frontmatter directly in your editor. |
| Tasks queries | ` ```tasks ``` ` blocks appear as code fences. No rendered task lists. | Track tasks in frontmatter (`status` field) or use Claude Code's task system. |
**Requires Obsidian** — completely absent without it:
| Feature | What you lose | Impact |
|---------|--------------|--------|
| Templater auto-trigger | No automatic template application when creating files in mapped directories. | Low — copy from `how/templates/` manually or let Claude Code do it. |
| Canvas / Advanced Canvas | No visual node graphs, no canvas presentations. | Medium — use Mermaid diagrams in Markdown or skip visual workflows. |
| Obsidian Git | No auto-commit timer, no auto-pull on open. | None — use standard `git` commands. |
| Notebook Navigator | No folder-based navigation with triad colors and icons. | Low — use `ls`, `tree`, or your editor's file explorer. |
| Homepage | No configured start page on vault open. | None — `STATE.md` serves the same purpose for agents. |
| Icon Folder | No custom folder/file icons. | None — cosmetic only. |
| Style Settings + CSS | No theme customization GUI, no visual styling. | None — cosmetic only. |
| BRAT | No beta plugin management. | None — only relevant for Obsidian plugins. |
| Termy | No terminal presets inside Obsidian. | None — you're already in a terminal. |
| Pretty Properties | No polished frontmatter display. | None — read YAML directly. |
| Fold Properties | No auto-folding of frontmatter blocks. | None — editor setting. |
| Banners | No header images on notes. | None — cosmetic only. |
---
## 3. Setup Walkthrough
### Step 1: Clone the repo
```bash
git clone https://github.com/aDNA-Network/aDNA.git adna
cd adna
```
Skip `./setup.sh` — that script downloads Obsidian plugins and themes. The `.obsidian/` directory will exist in the repo but is inert without Obsidian installed. You can ignore it.
### Step 2: Launch Claude Code
```bash
claude
```
Claude Code auto-loads `CLAUDE.md` from the project root. **Berthier** — the built-in agent personality — orients on the vault structure and is ready to work.
**If onboarding triggers**: On a truly fresh vault (empty session history, uncustomized `MANIFEST.md`), Berthier automatically runs the interactive onboarding skill — explaining the architecture, asking about your project, and customizing governance files. The entire flow runs in the terminal.
**On the reference repo** (the default): The aDNA repo ships with reference content already in place (sample sessions, populated manifests, documentation). Onboarding won't auto-trigger. Instead, tell Claude Code what you want to do:
- *"Customize this vault for my project"* — Berthier will walk you through editing `MANIFEST.md`, `STATE.md`, and the identity section of `CLAUDE.md`
- *"Run the onboarding skill"* — explicitly invokes `how/skills/skill_onboarding.md` for the full guided experience
### Step 3: Verify the setup
After customization, confirm three things:
1. **`MANIFEST.md`** — should have your project name and description
2. **`STATE.md`** — should reflect your current phase and next steps
3. **`how/sessions/active/`** — should contain a session file
```bash
head -20 MANIFEST.md
head -20 STATE.md
ls how/sessions/active/
```
If all three check out, your vault is operational.
### Alternative: Manual setup (no agent)
If you prefer to skip the agent entirely:
1. Edit `MANIFEST.md` — replace the project description with your own
2. Edit `STATE.md` — set your current phase and next steps
3. Optionally edit `CLAUDE.md` — customize the `## Identity & Personality` section
Use the starter templates in the [Migration Guide](/reference/migration-guide/) § 6 for copy-paste-ready governance files.
---
## 4. Session Workflow
### Creating sessions
In Obsidian, Templater auto-applies `template_session.md` when you create a file in `how/sessions/active/`. Without Obsidian, you have two options:
**Option A: Let Claude Code handle it** (recommended)
Claude Code's agent protocol creates a session file automatically on startup. Just launch `claude` and start working — the session file will be created for you.
**Option B: Copy the template manually**
```bash
cp how/templates/template_session.md \
how/sessions/active/session_$(whoami)_$(date +%Y%m%d)_descriptor.md
```
Then open the file and replace the Templater placeholders with actual values:
| Placeholder | Replace with |
|-------------|-------------|
| `YYYY-MM-DD` | Today's date (e.g., `2026-03-19`) |
| `{username}` | Your username |
| `{ISO_TIMESTAMP}` | Current timestamp (e.g., `2026-03-19T10:00:00-05:00`) |
| `<% tp.date.now() %>` | Today's date — this is Templater syntax that won't auto-resolve |
| `<% tp.file.title %>` | The filename you just created |
> **Templater syntax note**: Templates contain `<% tp.date.now("YYYY-MM-DD") %>` and similar expressions. These are Templater plugin functions that auto-resolve in Obsidian. In a terminal, they appear as literal text. Replace them with the actual values.
### Closing sessions
When you're done working:
1. Update your session file's SITREP section (completed, in progress, next up, blockers)
2. Write the **Next Session Prompt** — a self-contained paragraph so the next agent can continue
3. Set `status: completed` in frontmatter
4. Move the file to the history directory:
```bash
# Create the month directory if it doesn't exist
mkdir -p how/sessions/history/$(date +%Y-%m)
# Move the session file
mv how/sessions/active/session_*.md \
how/sessions/history/$(date +%Y-%m)/
```
### Git workflow
Without Obsidian Git's auto-commit, use standard git:
```bash
# Start of session
git pull
# After making changes
git add -A
git commit -m "session: brief description of what changed"
git push
```
If you're the only user, commit frequency is up to you. If multiple people sync the vault, commit and push at the end of each session to avoid conflicts.
---
## 5. Claude Code Configuration
### CLAUDE.md placement
`CLAUDE.md` must be at the **project root** — Claude Code auto-loads it from the working directory. This is the single most important file for agent orientation. If it's missing or misplaced, agents start blind.
### Memory vs. sessions
Claude Code has two persistence mechanisms. They serve different purposes:
| Mechanism | Location | Scope | Use for |
|-----------|----------|-------|---------|
| **Claude Code memory** | `~/.claude/projects/` | Personal, per-machine | Your preferences, feedback, credentials, tool notes |
| **Vault sessions** | `how/sessions/` | Shared, in git | Work continuity across agents and collaborators |
Memory is private — it stays on your machine and isn't committed to git. Sessions are shared — they go into the vault repo so any collaborator (human or agent) can pick up where you left off.
### The `.claude/` directory
Claude Code creates a `.claude/` directory in your project for local settings:
```
.claude/
├── settings.json # Project-specific permissions and hooks
└── ... # Other machine-local state
```
This directory is **gitignored** — it's machine-local configuration that shouldn't be shared. Each collaborator has their own `.claude/` directory.
### `.mcp.json`
If you use MCP (Model Context Protocol) servers with Claude Code, the `.mcp.json` config file is also **gitignored**. Claude Code has native filesystem access, so you don't need a filesystem MCP server. Add MCP servers only for external integrations (databases, APIs, specialized tools).
### Useful patterns
| Pattern | When to use |
|---------|-------------|
| **Plan mode** | Before starting a multi-step mission. Claude Code explores the codebase, designs an approach, and gets your approval before writing code. |
| **Explore agents** | For codebase research. Claude Code spawns a sub-agent to search files, trace references, and report back without consuming your main conversation context. |
| **Hooks** | For automation. Configure in `.claude/settings.json` to run scripts on events (e.g., auto-format on file save, run tests after edits). |
| **`/clear` then re-orient** | When context gets stale mid-session. Clear the conversation, Claude Code reloads `CLAUDE.md`, and you get a fresh start with the vault's current state. |
---
## 6. Substitution Table
Quick reference for replacing Obsidian-specific features:
| Obsidian feature | Terminal substitute |
|-----------------|-------------------|
| Templater auto-trigger | Copy from `how/templates/` manually, or let Claude Code create files |
| Graph view | `rg '\[\[' --type md` to trace wikilink relationships |
| Canvas | Mermaid diagrams in Markdown, or skip visual workflows |
| Obsidian Git | Standard `git pull` / `git commit` / `git push` |
| Obsidian search | `rg` (ripgrep) or your editor's search |
| Dataview queries | Ask Claude Code to query frontmatter (e.g., "find all files with status: active") |
| Meta Bind inputs | Edit frontmatter YAML directly |
| Tasks plugin | Track status in frontmatter fields or use Claude Code's task tracking |
| Notebook Navigator | `ls`, `tree`, or editor file explorer |
| Homepage | Read `STATE.md` for operational context on startup |
---
## 7. Growing Into Obsidian
If you later decide to add Obsidian, install it, open the vault directory, enable community plugins when prompted, and run `./setup.sh`. Everything lights up — graph view, wikilink navigation, canvas visualizations, auto-templates, the Tokyo Night theme. It's a one-way door that adds capability without changing anything you've already built. Your governance files, sessions, context library, and git history all carry over unchanged.
---
*Agent-first guide v1.0 | Companion to the [Migration Guide](/reference/migration-guide/), [aDNA Standard](/reference/specification/), and [Architecture Overview](/reference/design-rationale/)*
---
## https://adna.network/reference/design-rationale/
# Design Rationale — aDNA Reference
## 1. Preamble
This document explains **why** aDNA is designed the way it is. It is the companion to the [aDNA Universal Standard](/reference/specification/), which defines **what** to do. A third piece — the [base templates](https://github.com/aDNA-Network/aDNA/tree/main/.adna/how/templates) — provides the **how**: ready-to-use skeletons for bootstrapping new projects.
Together these form a three-document ecosystem:
| Document | Role | Audience |
|----------|------|----------|
| **aDNA Standard** (01_adna_standard.md) | Normative — MUST/SHOULD/MAY rules | Implementers building or maintaining an aDNA instance |
| **This design document** | Explanatory — rationale, trade-offs, worked examples | Evaluators deciding whether to adopt aDNA; adopters understanding intent |
| **Base templates** (template_bare/, template_embedded/) | Operational — empty shells with placeholders | Anyone bootstrapping a new aDNA project |
This document is self-contained. You do not need to read the five planning deliverables (00a–00d) that produced the 40 design decisions — though they are available in this directory for those who want the full deliberation record.
---
## 2. The Problem
AI agents start every session cold. They have no memory of previous sessions, no awareness of what other agents are doing, and no inherent understanding of the project they are operating in. This is a fundamental constraint, not a temporary limitation — even as models improve, the session boundary persists.
This creates four problems that compound in practice:
**Orientation overhead.** Every session begins with the agent asking: "What is this project? Where are things? What am I allowed to do?" Without deliberate architecture, agents spend significant context window budget simply figuring out where they are — or worse, they guess wrong and take actions based on incorrect assumptions.
**Coordination failure.** When multiple agents (or the same agent across sessions) modify the same project, they need to know what others have done and what is currently in progress. Without coordination infrastructure, agents silently overwrite each other's work or duplicate effort.
**Knowledge fragmentation.** Projects accumulate knowledge across sessions — domain context, decisions made, conventions established, lessons learned. Without a persistent knowledge layer, this knowledge lives only in session transcripts that no future agent will read. Each session re-derives what previous sessions already discovered.
**Audience divergence.** Humans and agents consume the same project knowledge but in fundamentally different ways. Humans browse, skim, and follow visual navigation cues. Agents parse, search, and follow structured metadata. A single set of documents optimized for one audience underserves the other.
aDNA addresses these problems through deliberate project knowledge architecture: a standard way to organize what a project knows, how it works, and who is involved — designed from the start for both human and AI consumption.
---
## 3. The Triad — Why Three
The core architectural decision in aDNA is the **what/how/who triad**: every piece of project knowledge belongs in exactly one of three categories.
| Leg | Question | Contains |
|-----|----------|----------|
| **what/** | WHAT does this project know? | Knowledge, context, decisions, reference, domain objects |
| **how/** | HOW does this project work? | Missions, sessions, templates, pipelines, processes |
| **who/** | WHO is involved? | People, teams, coordination, governance |
### Why three legs?
The triad emerges from a simple generative principle: **the question test**. Any piece of project content can be classified by asking which question it answers — WHAT, HOW, or WHO. Three questions, three categories, one clear home for every file. (Edge cases exist — some content could plausibly live in two legs. The question test resolves these by asking which question is PRIMARY, not whether other questions also apply.)
We considered and rejected other cardinalities:
**Two legs** (knowledge vs. operations, or content vs. process) creates sorting ambiguity. Where does a team roster go — is it "content" or "process"? Where do governance policies live — in "knowledge" or "operations"? Two-way splits force uncomfortable compromises because they conflate the people dimension into one of the other two.
**Four or more legs** were found unnecessary in design exploration. We tested candidate fourth legs — TOOLS (what we build with), WHERE (locations, deployments), WHEN (timelines, schedules) — and found that each decomposes cleanly into the existing three. Tools are knowledge about capabilities (what/). Deployment locations are either infrastructure knowledge (what/) or operational processes (how/). Timelines are operational planning (how/) or organizational milestones (who/). Adding legs past three created sorting ambiguity rather than resolving it.
We found three to be the minimum number that cleanly separates knowledge, process, and people. The "exactly one home" principle — every file belongs in exactly one leg — is what makes the system navigable. When an agent or human encounters a new piece of content, the question test produces one answer, not a debate.
### Worked example: classifying real content
Consider a project that manages machine learning models. Here is how different content sorts through the question test:
| Content | Question asked | Answer | Location |
|---------|---------------|--------|----------|
| "Our fine-tuned LLaMA model achieves 92% accuracy on the benchmark" | What do we know about our models? | WHAT | `what/models/` |
| "To deploy a model, follow these 5 steps..." | How do we deploy models? | HOW | `how/processes/` or `how/skills/` |
| "Alice is the ML lead; Bob reviews all model cards" | Who is responsible for what? | WHO | `who/team/` or `who/governance/` |
| "We decided to use LoRA instead of full fine-tuning because..." | What did we decide and why? | WHAT | `what/decisions/` |
| "Sprint plan: fine-tune 3 models this quarter" | How are we organizing the work? | HOW | `how/missions/` |
| "Meeting notes from the model review with the partner team" | Who met and what was communicated? | WHO | `who/communications/` |
| "Agent context: how ancient DNA extraction works" | What does the agent need to know about the domain? | WHAT | `what/context/` |
In every case, the question test yields one answer. The triad is not a filing system imposed on content — it is a design choice reflecting common dimensions of project knowledge (see spec S3.1).
---
## 4. Two Deployment Forms
aDNA has two first-class physical layouts: **bare** and **embedded**. This was the keystone design decision (C1) — everything structural flows from it.
### The insight: triad is ontology, not directory layout
The what/how/who triad is an intellectual framework for classifying project knowledge. How that framework manifests physically should respect the conventions of the environment it inhabits. A directory structure that makes sense at the root of an Obsidian vault would be foreign at the root of a Python package. Conversely, wrapping aDNA in a dot-prefixed directory makes no sense when aDNA IS the project.
This led to the **pattern-appropriate deployment** principle: one ontology, two physical forms.
### Bare triad
When aDNA IS the primary content — Obsidian vaults, knowledge bases, standalone agent workspaces — the triad directories sit at the project root alongside governance files:
```
my_vault/
├── CLAUDE.md
├── MANIFEST.md
├── STATE.md
├── what/ <- knowledge
├── how/ <- operations
├── who/ <- organization
└── {content}/ <- project-specific
```
This is natural for knowledge-first projects. The triad is visible, browsable, and immediately meaningful to both humans exploring in a file browser and agents parsing the directory tree.
### Embedded triad
When aDNA SERVES a codebase — git repositories, application projects, libraries — the triad is wrapped inside `.agentic/`, following the convention of dot-prefixed meta directories (`.github/`, `.vscode/`, `.docker/`):
```
my_repo/
├── CLAUDE.md <- governance stays at root
├── MANIFEST.md
├── .agentic/
│ ├── what/ <- knowledge
│ ├── how/ <- operations
│ └── who/ <- organization
└── src/ <- codebase
```
Governance files remain at the root in both forms — this is the invariant. CLAUDE.md must be at root because Claude Code auto-loads it from there. The other governance files sit beside it for consistency and discoverability.
### Why not one form?
We considered mandating bare triad everywhere (simpler standard) and mandating embedded everywhere (uniform convention). Both failed:
- **Bare everywhere** means a Python repository has `what/`, `how/`, `who/` alongside `src/`, `tests/`, `pyproject.toml`. This pollutes the project namespace with directories that have nothing to do with the code. Developers rightly object — the aDNA infrastructure should not compete for attention with the actual project content.
- **Embedded everywhere** means a vault whose entire purpose is knowledge management wraps its content inside `.agentic/`. This hides the primary content behind a directory that signals "meta/configuration" rather than "this is the point." It also breaks Obsidian conventions — vault root should contain navigable content, not just a dot-directory.
Pattern-appropriate deployment accepts this reality: different project types have different norms, and the standard should respect them rather than fighting them. The triad ontology is identical in both forms — only the nesting differs. CLAUDE.md in each environment documents the paths, bridging the difference transparently (see spec S3).
The following diagram shows both deployment forms side by side. The triad ontology is identical — only the physical nesting differs:
```mermaid
flowchart TB
subgraph BARE["Bare Triad (Knowledge Base)"]
BR["project_root/"]
BR --> BC["CLAUDE.md"]
BR --> BW["what/"]
BR --> BH["how/"]
BR --> BO["who/"]
end
subgraph EMBED["Embedded Triad (Git Repo)"]
ER["repo_root/"]
ER --> EC["CLAUDE.md"]
ER --> EA[".agentic/"]
ER --> ES["src/"]
EA --> EW["what/"]
EA --> EH["how/"]
EA --> EO["who/"]
end
BARE ---|"Same ontology Different packaging"| EMBED
style BW fill:#0d9488,color:#fff
style BH fill:#22c55e,color:#fff
style BO fill:#8b5cf6,color:#fff
style EW fill:#0d9488,color:#fff
style EH fill:#22c55e,color:#fff
style EO fill:#8b5cf6,color:#fff
```
### Worked example: same project, both layouts
A research lab documentation project could use either form:
**As a vault** (bare — the knowledge management is the point):
```
lab_docs/
├── CLAUDE.md
├── what/context/experimental_methods/ <- domain knowledge
├── what/decisions/adr_data_format.md <- architecture decisions
├── how/missions/mission_v2_launch.md <- release mission
├── who/team/member_dana.md <- team roster
└── guides/ <- project content
```
**As a repo** (embedded — the code is the point):
```
lab-platform/
├── CLAUDE.md
├── .agentic/
│ ├── what/context/ <- domain knowledge
│ ├── how/missions/ <- missions
│ └── who/governance/ <- governance
├── src/ <- the actual application code
├── tests/
└── package.json
```
Same ontology, same governance files, same agent protocols — different packaging.
---
## 5. Five Governance Files
Every aDNA instance has up to five ALLCAPS files at root. These are the agent's orientation documents — the first things read on every session.
| File | What it answers | Update cadence |
|------|----------------|----------------|
| **CLAUDE.md** | "Who am I, where are things, what are the rules?" | When structure or protocols change |
| **MANIFEST.md** | "What is this project and how is it built?" | When scope or architecture changes |
| **STATE.md** | "Where are we right now?" | Every session close |
| **AGENTS.md** | "What does each directory contain?" | When structure changes |
| **README.md** | "How do I navigate this as a human?" | When onboarding changes |
### The cold-start problem
The primary design driver for governance files is cold-start orientation. An agent begins every session knowing nothing about the project. The governance files must take it from zero to productive within minutes. The critical path is:
1. **CLAUDE.md** (auto-loaded by Claude Code): The agent learns the project structure, its role, the safety rules, and how to begin a session.
2. **STATE.md**: The agent learns what phase the project is in, what happened recently, and what needs to happen next.
These two files — read in sequence — are sufficient for an agent to begin useful work. This is the Cold Start success criterion (see spec S18.1), and it was validated against both base template variants during Task 19.
```mermaid
sequenceDiagram
participant A as Agent
participant C as CLAUDE.md
participant S as STATE.md
participant Ses as sessions/active/
participant Co as coordination/
A->>C: 1. Auto-loaded on start
Note over A,C: Learn structure, rules, persona
A->>S: 2. Read current state
Note over A,S: Learn phase, blockers, next steps
A->>Ses: 3. Check active sessions
Note over A,Ses: Detect conflicts
A->>Co: 4. Read coordination notes
Note over A,Co: Urgent cross-agent messages
A->>Ses: 5. Create session file
Note over A: Ready to work
```
### Why CLAUDE.md?
The name "CLAUDE.md" is a pragmatic choice, not a universal one. Claude Code auto-loads any file named CLAUDE.md from the project root. This auto-loading behavior is the single most valuable integration point — it means the agent's orientation document is always available without the agent needing to know to look for it.
We acknowledge this is model-specific (see spec Appendix C, deferred topic G2). A future revision may define a model-neutral convention — perhaps `.agentrc.md` or `AGENT.md` — that multiple AI tools auto-load. For now, the pragmatic value of auto-loading outweighs the purity of model-neutral naming. Projects using non-Claude agents can use the same structure with whatever filename their tooling auto-loads.
### Why MANIFEST.md and STATE.md are separate (D2)
Early designs combined project overview and current state into a single file. We separated them because they have fundamentally different update cadences:
- **MANIFEST.md** describes what the project IS — its architecture, entry points, major workstreams. This changes when you add a new subsystem or restructure the project. Weeks or months between updates.
- **STATE.md** describes where the project IS RIGHT NOW — current phase, recent decisions, active blockers, next steps. This changes every session close. Daily or more frequent updates.
Combining them means either the project overview gets cluttered with transient state, or the state section gets buried in stable architecture description. Separating them lets agents read STATE.md for "what changed recently?" without re-parsing the full project overview, and lets humans read MANIFEST.md for "what is this project?" without wading through operational status.
### The AGENTS.md / README.md split (C2)
Every directory in an aDNA instance can have two guide files:
- **AGENTS.md**: Optimized for machine consumption. Structured, scannable, focused on what an agent needs to know to operate in this directory — purpose, key files, patterns, conventions.
- **README.md**: Optimized for human browsing. Navigation-oriented, providing context for someone exploring in Obsidian, GitHub, or an IDE.
We chose dual files over a single combined document because the audiences genuinely need different things. An agent needs to know "what naming convention do files in this directory follow?" — structured and precise. A human needs to know "what will I find here and how does it connect to other parts of the project?" — contextual and navigational. A single document serving both audiences serves neither well.
The dual-file pattern adds maintenance cost — two files to update instead of one. We accept this trade-off because the alternative (one file, two audiences, constant compromise) proved worse in practice across 40+ sessions of operational experience (see spec S4.5, S4.6).
---
## 6. The Session Model
Sessions are aDNA's unit of accountability. Every modification to the project happens within a session, and every session leaves a record.
### Why sessions are structured
An agent operating without session structure modifies files, then the session ends. The next agent (or the same agent returning) has no record of what happened, what was in progress, or what should happen next. Session structure solves this by requiring three things:
1. **A session file exists before work begins** — this is the audit trail. If something goes wrong, the session file tells you who was working, what they intended, and what they touched.
2. **SITREP at close** — Completed, In Progress, Next Up, Blockers, Files Touched. This structured format ensures nothing falls through the cracks during handoff. It is deliberately concise — five fields, each with a clear purpose.
3. **Next-session prompt** — A self-contained paragraph that a fresh agent can read to continue the work. This is the single most valuable handoff mechanism: it compresses the full session context into what the next agent actually needs to know.
### Timestamped IDs over sequences
Session IDs use the format `session_{user}_{YYYYMMDD}_{HHMMSS}_{descriptor}`. We chose this over sequential numbering (S001, S002...) for three reasons:
- **Collision-free**: Two agents creating sessions simultaneously will never generate the same ID, because their usernames and timestamps differ.
- **Machine-sortable**: Alphabetical sort = chronological sort. No need for a registry to know which session came first.
- **Self-documenting**: The ID itself tells you who, when, and what — before you even open the file.
Sequential IDs require a shared counter, which introduces a coordination problem in distributed environments. Timestamps avoid this entirely (see spec S8.2).
### The 75% rule (D5)
The only universal sizing prescription is: scope each session to use approximately 75% of the context window, reserving 25% for thinking, debugging, and course correction.
We deliberately avoided other sizing guidance — time limits, task counts, line-count ranges — because these are paradigm-specific. A two-hour code generation session looks nothing like a two-hour knowledge synthesis session. The 75% rule applies regardless of paradigm because it addresses the universal constraint: context windows are finite, and agents that exhaust them cannot recover gracefully.
If a task requires more than 75% of the context window, the agent splits the work across sessions, checkpointing progress in the SITREP close-out. This is not a failure mode — it is the expected behavior for complex work (see spec S8.7).
---
## 7. Collision Prevention
Collision prevention is the system that keeps agents from silently destroying each other's work. It is tiered because different environments face different risks.
### The fundamental tension
AI agents cannot lock files. There is no mutex, no transaction, no compare-and-swap. When an agent reads a file, another agent (or human) might modify it before the first agent writes back. In sync environments like Google Drive, there is not even a notification that a conflict occurred — last write wins, silently.
This means collision prevention must be cooperative, not enforced. Agents follow conventions because the standard tells them to, not because a system prevents violations. This is an honor system — and we designed it to work as one, with multiple layers of defense rather than a single point of enforcement.
```mermaid
flowchart TB
Start["Agent wants to modify a file"] --> Read["Read current content"]
Read --> Check{"updated = today AND different author?"}
Check -->|No| Safe["Write with frontmatter attribution"]
Check -->|Yes| Ask["Confirm with user before overwriting"]
Ask -->|Approved| Safe
Ask -->|Denied| New["Create new file instead (zero collision risk)"]
Safe --> Done["Update last_edited_by + updated fields"]
style Safe fill:#22c55e,color:#fff
style Ask fill:#eab308,color:#000
style New fill:#3b82f6,color:#fff
```
### Tier 1 — Universal (every aDNA instance)
Three rules that work everywhere:
1. **Frontmatter attribution**: Every file modification updates `last_edited_by` and `updated` in YAML frontmatter. This creates a visible "who touched this last?" signal that any tool can read.
2. **Read-before-write**: Always read the current file content immediately before writing. Never rely on a cached read from earlier in the session. This minimizes the window during which a conflict can occur.
3. **New-file safety**: Creating a new file has zero collision risk. When in doubt about modifying an existing file, consider creating a new one instead.
These three rules cost almost nothing — a frontmatter field update and a file read — and catch the most common collision scenario: an agent overwriting changes it did not know about. Even in git repositories where version control provides a safety net, Tier 1 attribution is valuable because it provides at-a-glance "who and when" without needing `git log` (see spec S13.2).
### Tier 2 — Sync environments
Google Drive, Dropbox, and similar sync systems add a specific risk: renames and moves can cause file duplication or loss during sync. Tier 2 adds:
- **Safety tiers for files**: Content files are Safe (low collision risk — different users work on different records). Governance files are Shared Config (medium risk — everyone might need to edit CLAUDE.md). Auto-generated files like `workspace.json` are Volatile (do not attempt to maintain them).
- **Archive-don't-rename**: Move deprecated files to `archive/` rather than renaming them. Sync systems handle renames poorly — a rename on one machine can appear as a delete-and-create on another, potentially duplicating or losing the file.
- **One config at a time**: When editing shared configuration files, complete one edit and verify it synced before starting the next. This prevents race conditions on files that multiple users/agents might touch.
### Tier 3 — Multi-agent
When multiple agents operate simultaneously on the same project, Tier 3 adds strategic coordination:
- **Coordination notes** in `who/coordination/` — explicit messages between agents about intentions, urgency, and scope.
- **Session scope declarations** — a Tier 2 session declares which files or directories it will modify, so other agents know to avoid those areas.
- **Update-field check** — before modifying a file where `updated` is today and `last_edited_by` is someone else, confirm with the user before overwriting.
### Why we rejected enforcement
We considered implementing file-locking mechanisms, mandatory check-out protocols, or database-backed coordination. All were rejected because:
- They add infrastructure dependencies that conflict with aDNA's design goal of working with plain files and directories.
- They create failure modes (stale locks, abandoned checkouts) that are worse than the collisions they prevent.
- They do not work across all environments — Google Drive has no locking API accessible to agents.
The tiered honor system works because it matches real usage patterns: most projects are single-agent most of the time (Tier 1 suffices), some projects sync across machines (Tier 2 helps), and a few projects have concurrent agents (Tier 3 provides the additional coordination). Projects adopt only the tiers they need (see spec S13).
### Worked example: two agents, one vault
**Setup**: Agent A (on Machine 1) and Agent B (on Machine 2) both start sessions on the same infrastructure knowledge base, synced via file sync.
**Tier 1 in action**: Both agents create their own session files (new files — zero collision risk). Agent A modifies `what/context/networking/vpc_design.md` — updates `last_edited_by: agent_alpha` and `updated: 2026-03-15`. Agent B reads that file and sees it was just modified today by someone else. The update-field check (Tier 3) fires: Agent B asks its user before overwriting.
**Tier 2 in action**: Agent A needs to update CLAUDE.md. It is classified as Shared Config. Agent A edits it, verifies the write, then moves on. Agent B, following the "one config at a time" rule, waits until its next session to propose CLAUDE.md changes, or notes the desired change in `who/coordination/` for Agent A to see.
**Tier 3 in action**: Agent A creates a coordination note: "Working on what/context/networking/ this session — please avoid." Agent B reads this during startup, routes its work to `how/missions/` instead, and leaves a reply note: "Updated the Q2 deployment plan, FYI."
No file locks. No central server. Just conventions, frontmatter, and coordination notes — and the vault stays consistent.
---
## 8. Content-as-Code and Extensions
aDNA includes several optional systems beyond the core triad and governance files. The design philosophy behind these extensions is consistent: **document the paradigm, not the instance**.
### Folder-equals-state (D14)
The content-as-code paradigm is simple: a file's directory location IS its processing state. Moving a file from `inbox/` to `processing/` to `review/` to `done/` advances it through a workflow. No separate status database. No state machine. The filesystem is the state machine.
This paradigm is universal — it works for research ingestion, document review, approval workflows, publishing pipelines, or any process where content flows through stages. The standard documents the paradigm and the directory structure convention (`how/pipelines/{name}/` with stage subdirectories, each containing an AGENTS.md with processing instructions). Specific pipelines are project-specific instances of the pattern.
We made pipelines optional rather than required because not every project has staged workflows. A simple knowledge base may never need a pipeline. But when you do need one, the pattern is defined and consistent (see spec S14).
```mermaid
stateDiagram-v2
direction LR
[*] --> inbox
inbox --> processing: Agent picks up
processing --> review: Work complete
review --> done: Approved
review --> processing: Needs revision
note left of inbox: File location = processing state
note right of done: No separate status database
```
### Graduated skeletons (D11)
Templates and directory structure grow with the project:
- **Starter**: 3 templates (session, mission, context), minimal directories. Enough for a single-agent project getting started.
- **Standard**: Adds coordination, backlog, and ADR templates. For active multi-agent projects.
- **Full**: Project-specific additions — experiment registries, model catalogs, pipeline stages. For mature operations.
We rejected a flat "include everything" approach because it overwhelms new projects with structure they do not yet need, and a minimal "include nothing" approach because it provides no guidance on how to grow. The graduated model lets projects start light and add structure as complexity demands (see spec S12).
### Machine registry in what/, not how/
The machine registry — tracking which machines sync the project and their path patterns — lives in `what/hardware/machines/`, not `how/`. This is the triad question test in action: "What machines does this project run on?" is a WHAT question (knowledge), not a HOW question (process). The machine registry is a catalog of facts about infrastructure, not an operational procedure (see spec S19.1).
---
## 9. Frontmatter as Integration Layer
aDNA requires YAML frontmatter on all triad content files and governance files, but NOT on project source code. This boundary (C4) is deliberate.
### The boundary principle
Files inside the triad (`what/`, `how/`, `who/`) and governance files benefit from frontmatter because they are queried, filtered, and aggregated. An agent needs to find "all missions with status active" or "all context files updated this week." Frontmatter makes these queries trivial — any tool that reads YAML can answer them.
Project source code does not benefit from frontmatter. A Python file does not need `type: source` and `updated: 2026-02-13` in a YAML block — git handles attribution, and source files are organized by code structure, not by knowledge taxonomy. Requiring frontmatter on source code would create friction without value.
The boundary is the triad perimeter. Inside the triad: frontmatter mandatory. Outside: frontmatter exempt. This keeps the requirement focused where it adds value (see spec S7.1).
### Frontmatter as universal API
The five required base fields (`type`, `created`, `updated`, `last_edited_by`, `tags`) form a universal API that any tool can consume:
- **Obsidian Dataview** queries frontmatter to build dashboards and aggregation views.
- **Shell scripts** parse YAML to generate reports or validate compliance.
- **CI/CD pipelines** can read frontmatter to check session status or mission progress.
- **Agents** use frontmatter to understand file purpose, recency, and authorship without reading full content.
This is the three-tier tool integration model (C13): Tier 1 (files and directories) works universally. Tier 2 (frontmatter queries) works with any YAML-reading tool. Tier 3 (Obsidian plugins, IDE extensions) is environment-specific. Everything in aDNA is Tier 1 unless noted otherwise — the standard does not require any particular tooling beyond a filesystem and a text editor (see spec S16).
---
## 10. Persona as Optional Architecture
aDNA provides a persona framework — a structured way to define an agent's identity, operating style, and communication norms. It does not require any specific persona.
### The consistency argument
A persona provides session-to-session consistency. Without one, each agent session establishes its own tone, greeting style, and behavioral norms. With a persona, the agent behaves predictably — it greets the same way, structures reports the same way, and follows the same behavioral principles every session. For long-running projects with dozens or hundreds of sessions, this consistency is valuable. It reduces cognitive load for the humans working with the agent.
### The universality problem
Not every project wants the same persona. A project persona — for example, a military-operational chief-of-staff, a scholarly research assistant, or a fast-moving startup co-builder — should match the project's character. A research lab might want a meticulous librarian. A documentation project might want a patient educator. Mandating any single persona would be inappropriate outside the specific context where it was designed.
### The framework solution
The standard defines the SHAPE of a persona, not its CONTENT:
- **Identity**: Name, role metaphor, mission statement.
- **Operating style**: 3-5 behavioral principles.
- **Communication norms**: Tone, formatting, greeting and closure patterns.
- **Domain awareness**: What the persona should know about the project.
A reference implementation — a fully worked example — demonstrates how to fill the framework. Projects adopt it directly, modify it, or create their own. The framework survives regardless of the specific persona chosen (see spec S4.2 and Appendix A).
```mermaid
flowchart TB
P["Persona Framework"]
P --> ID["Identity Name, role, mission"]
P --> OS["Operating Style 3-5 behavioral principles"]
P --> CN["Communication Norms Tone, format, greetings"]
P --> DA["Domain Awareness Project-specific context"]
ID --> EX1["e.g. Chief of Staff to the operation"]
OS --> EX2["e.g. Orient first, think in lines of effort"]
CN --> EX3["e.g. Direct, SITREP format, no filler"]
style P fill:#8b5cf6,color:#fff
```
---
## 11. Evolution and Deferred Design
aDNA v1.0 is deliberately scoped. Several topics were identified during the planning arc, evaluated, and intentionally deferred — not forgotten, but set aside until operational experience provides better design input.
### What was left out and why
Five topics were deferred to future revisions:
| Topic | Why deferred | Unlock condition |
|-------|-------------|-----------------|
| **Multi-model naming** (G2) | "CLAUDE.md" works today via auto-loading. Model-neutral naming requires ecosystem convergence that has not happened yet. | Multiple AI tools adopting a shared convention for auto-loaded project files. |
| **Documentation generation** (G3) | Generating external docs from aDNA is project-specific. No universal pattern has emerged. | Two or more projects developing similar patterns, suggesting standardization value. |
| **Context staleness detection** (G7) | The `updated` field + session cycling naturally refresh context. Formal detection is tooling, not architecture. | Operational evidence that natural refresh is insufficient for a common use case. |
| **Cross-instance awareness** (G8) | Addressed by bridge patterns — informational companion with SHOULD-level guidance for nesting, sibling composition, and monorepo patterns. | At least two aDNA instances needing to interoperate. |
| **Agent capability declaration** (G10) | Most aDNA instances target specific agent capabilities. Formal schemas are premature. | Broader agent ecosystem maturity and standardization of capability descriptions. |
### Why v1.0, not v0.1
This standard was validated through implementation. Tasks 12-19 applied every major design decision to two real systems — a knowledge base vault with 300+ files and 45+ sessions, and a git repository with 600+ files and 40+ sessions. The base templates (Tasks 18-19) passed Cold Start, Handoff, and Spec Compliance validation. This is not a theoretical design — it is an operational one.
The aspirational success criteria (spec S18.3) — network awareness, collision safety under heavy contention, dual-audience excellence — represent where we want aDNA to go, not what it must achieve today. They are guideposts for future revisions.
### The CLAUDE.md naming question
The decision to name the primary governance file "CLAUDE.md" is the clearest example of aDNA's design philosophy: **pragmatism over purity**. The pure choice would be a model-neutral name like `AGENT.md`. The pragmatic choice is the name that auto-loads in the tool most aDNA instances will use today. We chose pragmatism, documented the trade-off, and deferred the purity question to a future revision when the ecosystem may have converged on a model-neutral convention. This is the kind of trade-off aDNA makes throughout: optimize for today's operational reality while designing for tomorrow's evolution.
---
## 12. Acknowledgments
aDNA v1.0 emerged from the convergence of three systems: a knowledge base vault shaped by 45+ operational sessions, a git repository with 600+ spec-generated files, and an original genesis prompt encoding 30 aspirational architectural concepts. The standard preserves what worked from each, resolves where they diverged, and fills what was missing.
The planning arc spanned five sessions, producing 40 design decisions (15 structural, 25 process/pattern), a 40-row divergence map, and a 12-item gap registry. Execution spanned eight phases across 12+ sessions, validated against both deployment forms. The full deliberation record — reconnaissance, gap analysis, and design session deliverables — is available in this directory for those who want the complete rationale chain.
---
*End of aDNA Design Document*
---
## https://adna.network/reference/governance-model/
# Governance Model — aDNA Reference
> How the aDNA standard evolves: stewardship, release cadence, backwards compatibility, and the process for proposing changes.
---
## Stewardship
### Founding Architect Model
The aDNA standard is currently governed under a **Founding Architect** stewardship model:
- **Steward**: The Founding Architect (FA) holds decision authority over standard changes
- **Scope**: All normative changes to `adna_standard.md`, conformance level definitions, and governance file requirements
- **Authority transfer**: The FA may delegate stewardship to a **Standard Council** (3+ members) as the community grows. This transition is a governance decision, not a standard version change
### Where governance is going — progressive decentralization
How aDNA is governed today is only the starting point. **The aDNA Network is committed to progressive decentralization:**
- The network is **stewarded by a Founding Architect today**.
- As it **finds and onboards trusted stewards**, those stewards take an **increasing role** in governance — as far as is **helpful and positive** — **at the Founding Architect's discretion**.
- That discretion is **eventually turned over to stewardship itself**.
- The destination is a protocol and network that is fully **steward-led, democratic, and public**.
This is a roadmap, not a claim about today: the democratic destination is an *earned* one, reached as real stewards join — not a status the network asserts before it has them.
**Steward recruitment is mission-aligned.** We look for stewards among the people closest to the network's core missions:
- **Rare disease**
- **Undiagnosed disease**
- **Biodiversity protection** — via conservation genomics, coherent with the network's genome/DNA framing
### Community Input
- Anyone may propose standard changes via the process defined below
- The FA reviews all proposals and provides written rationale for acceptance or rejection
- Community feedback is gathered via GitHub Issues on the aDNA repository
---
## Release Cadence
| Track | Cadence | Scope |
|-------|---------|-------|
| **Standard** (`adna_standard.md` version) | As needed | Normative specification changes — conformance levels, required files, naming rules |
| **Governance** (`CLAUDE.md` version, `CHANGELOG.md`) | Continuous | Operational changes — protocols, templates, skills, tooling |
### Version Numbering
Both tracks use `Major.Minor` versioning:
- **Major** (e.g., v2.x → v3.0): May introduce breaking changes. Requires migration guidance.
- **Minor** (e.g., v2.1 → v2.2): Additive only. MUST NOT invalidate conformant instances.
See `adna_standard.md` §15.4 for the normative backwards compatibility promise.
---
## Backwards Compatibility Promise
This promise is normative (defined in `adna_standard.md` §15.4):
1. **Minor standard versions** MUST NOT invalidate conformant instances. An instance passing Starter/Standard/Full conformance at v2.1 MUST still pass at v2.2.
2. **Major standard versions** MAY introduce breaking changes. When they do:
- Migration guidance MUST be published before or alongside the release
- A migration tool or checklist SHOULD be provided
- The previous major version MUST remain documented for reference
3. **Governance version changes** do not affect standard conformance. A CLAUDE.md update from v5.5 to v6.0 does not require instance changes.
---
## Proposing Standard Changes
### Lightweight RFC Process
1. **Open a GitHub Issue** using the "Change proposal" issue template
2. **Describe**: What you want to change, why, and the impact on existing conformant instances
3. **Classification**: Is this a minor (additive) or major (breaking) change?
4. **Discussion**: Community and FA discuss in the issue
5. **Decision**: FA accepts, modifies, or declines with written rationale
6. **Implementation**: Accepted changes are incorporated into the next standard release
### Change Classification
| Type | Examples | Standard Version Impact |
|------|----------|------------------------|
| **Additive** | New optional field, new conformance check, new appendix | Minor bump (v2.2 → v2.3) |
| **Normative tightening** | SHOULD → MUST for existing recommendation | Major bump (v2.x → v3.0) |
| **Structural** | New required governance file, directory rename | Major bump |
| **Editorial** | Typo fixes, clarifications that don't change requirements | No version bump |
---
## Pre-Release Checklist
Before releasing a new standard version:
- [ ] All normative changes reviewed by FA
- [ ] Backwards compatibility verified for minor versions
- [ ] Migration guidance prepared for major versions
- [ ] `governance_sync_check.sh` reports zero drift
- [ ] `adna_validate.py` passes on the reference instance (adna repo)
- [ ] Example projects still pass their expected conformance level
- [ ] CHANGELOG.md updated with release entry
- [ ] Version strings updated in `adna_standard.md`, `README.md`
---
## Future Governance Evolution
Governance evolves along the **progressive-decentralization** curve above — from a single Founding Architect toward steward-led, public governance. The stages are directional, not automatic thresholds; each transition is a human-gated decision, made as trusted stewards join:
1. **Founding Architect** — a single steward holds decision authority (where the network is today)
2. **Increasing trusted stewards** — mission-aligned stewards enter the process and take on real decisions, at the Founding Architect's discretion, as far as is helpful and positive
3. **Standard Council** (3–5 members) — shared stewardship with majority vote, as discretion is turned over to stewardship itself
4. **Working Groups** — domain-specific groups (e.g., Bio-aDNA, Enterprise-aDNA) that propose extensions
5. **Formal RFC process** — structured proposal documents with review periods
The destination is a protocol and network that is **steward-led, democratic, and public** — governance carried by the communities closest to the mission (rare disease, undiagnosed disease, biodiversity protection), not by any single architect.
---
## https://adna.network/reference/migration-guide/
# Migration Guide — aDNA Reference
## 1. Introduction
This guide is for developers who already have a project and want to add aDNA to it. If you're starting fresh, use the [Quick Start](/get-started/) instead — clone the repo, open in Obsidian, done.
**What you'll have at the end**: Your existing project with a working aDNA knowledge architecture — governance files that orient AI agents on first contact, a triad structure for organizing project knowledge, and session tracking for continuous context across agent conversations.
**Time estimate**: 10-15 minutes for the core structure. Under 5 minutes if you copy-paste the starter templates without customization.
**Prerequisites**: A text editor. Optionally, [Obsidian](https://obsidian.md) for visual browsing. No special tooling required.
---
## 2. Which Form Is Right for You?
aDNA deploys in two forms. Pick the one that matches your project:
| Factor | Bare triad | Embedded triad |
|--------|-----------|----------------|
| **Structure** | `who/` `what/` `how/` at project root | `.agentic/who/` `.agentic/what/` `.agentic/how/` |
| **Best for** | Knowledge bases, documentation projects, Obsidian vaults, repos where aDNA IS the project | Code repos, existing apps, repos where aDNA lives ALONGSIDE source code |
| **Root clutter** | Adds 3 directories + 3 files to root | Adds 1 directory + 1 file to root |
| **Agent discovery** | Direct — agents see triad immediately | Indirect — agents read CLAUDE.md, which points to `.agentic/` |
| **Collision risk** | Higher — `who/`, `what/`, `how/` may conflict with existing dirs | Minimal — `.agentic/` is unlikely to exist |
| **.gitignore** | No changes needed | Add `.agentic/` exception if dotfiles are ignored |
**Decision rule**: If you're adding aDNA to a codebase with `src/`, `lib/`, `tests/`, etc. — use **embedded**. If aDNA *is* the project (a knowledge base, documentation vault, or wiki) — use **bare**.
> **Not sure?** Start with embedded. You can always promote to bare later by moving `.agentic/who|what|how/` to the root.
---
## 3. Minimum Viable aDNA
The smallest aDNA installation that delivers Day 1 value:
### Essential files (5)
| File | Location | Purpose |
|------|----------|---------|
| `CLAUDE.md` | Project root (always) | Agent master context — project identity, structure, safety rules |
| `MANIFEST.md` | Project root | Project identity card — what this is, architecture, entry points |
| `STATE.md` | Project root | Operational state — current phase, next steps, blockers |
| `AGENTS.md` | One per triad directory (3 total) | Per-directory guide — what's here, how to work with it |
### Triad directories (3)
| Directory | Bare form | Embedded form |
|-----------|-----------|---------------|
| People & orgs | `who/` | `.agentic/who/` |
| Knowledge & artifacts | `what/` | `.agentic/what/` |
| Operations & process | `how/` | `.agentic/how/` |
That's it — **5 files + 3 directories**. Everything else (templates, sessions, campaigns, lattices, context library, Obsidian config) is enhancement you add when you need it.
### What you can add later
| Enhancement | When to add | What it gives you |
|-------------|-------------|-------------------|
| `how/sessions/` | When you want cross-session continuity | Agents pick up where the last one left off |
| `how/templates/` | When you create the same file type repeatedly | Consistent frontmatter, less boilerplate |
| `how/campaigns/` + `how/missions/` | When work spans multiple sessions | Structured decomposition of complex initiatives |
| `what/context/` | When agents need domain knowledge | Pre-loaded expertise files for specific topics |
| `what/decisions/` | When you want to track ADRs | Architecture Decision Records with linked rationale |
| `.obsidian/` | When you want visual browsing | Graph view, wikilinks, canvas, themes |
---
## 4. Walkthrough: Embedded Form
For code repos where aDNA lives alongside source code. Each step includes a timing checkpoint — total should be under 15 minutes.
### Step 1: Create the structure (~30 seconds)
```bash
# From your project root
mkdir -p .agentic/who .agentic/what .agentic/how
```
Your project now looks like:
```
my-project/
├── src/ # Your existing code
├── tests/ # Your existing tests
├── .agentic/ # aDNA knowledge architecture
│ ├── who/ # People & organizations
│ ├── what/ # Knowledge & artifacts
│ └── how/ # Operations & process
├── CLAUDE.md # (next step)
└── ... # Your existing files
```
**Checkpoint**: ~30 seconds elapsed.
### Step 2: Write CLAUDE.md (~3 minutes)
Create `CLAUDE.md` **at your project root** (not inside `.agentic/`). This is the file AI agents auto-load on startup.
```markdown
# CLAUDE.md — [Your Project Name]
## Identity
This is [one-sentence description of your project].
## Structure
Project knowledge lives in `.agentic/` using the aDNA triad:
- `.agentic/who/` — people, teams, contacts, stakeholders
- `.agentic/what/` — research, decisions, domain knowledge, artifacts
- `.agentic/how/` — plans, processes, sessions, workflows
Source code lives in the standard project structure ([describe briefly: src/, lib/, etc.]).
## Agent Protocol
1. Read this file (auto-loaded)
2. Read `STATE.md` for current operational context
3. Read the `AGENTS.md` in the directory you're working in
## Safety Rules
- Read before write — always check current content before modifying
- Set `last_edited_by` and `updated` in frontmatter when editing `.agentic/` files
- Do not modify files outside `.agentic/` without explicit instruction
## Domain
[Add 3-5 bullet points about your domain — what this project does,
key terminology, important conventions. This is where agents learn
what makes YOUR project different.]
```
**Customize**: Replace the bracketed sections. The `## Domain` section is where you teach agents about your project — spend a minute here writing a few bullet points. Everything else is structural.
**Checkpoint**: ~3.5 minutes elapsed.
### Step 3: Write MANIFEST.md and STATE.md (~2 minutes)
**MANIFEST.md** — project identity card:
```markdown
---
type: manifest
created: 2026-03-18
updated: 2026-03-18
---
# [Your Project Name]
## What This Is
[2-3 sentences: what the project does, who it's for, why it exists.]
## Architecture
[Brief description of the codebase structure — languages, frameworks, key directories.]
## Active Builds
- [Current focus area or sprint goal]
```
**STATE.md** — operational state:
```markdown
---
type: state
created: 2026-03-18
updated: 2026-03-18
---
# Operational State
## Current Phase
[What's happening right now — the active sprint, milestone, or focus area.]
## Next Steps
- [Immediate next action]
- [Following action]
## Blockers
- [None, or list current blockers]
```
**Checkpoint**: ~5.5 minutes elapsed.
### Step 4: Write AGENTS.md for each triad directory (~3 minutes)
Each triad directory gets an `AGENTS.md` telling agents what belongs here. These are short — 5-10 lines each.
**.agentic/who/AGENTS.md**:
```markdown
# who/ — Agent Guide
## What's Here
People, teams, and organizations related to [your project].
## Working Rules
- One file per person or organization
- Use frontmatter: `type`, `created`, `updated`, `tags`
- Link to related entries with `[[wikilinks]]`
```
**.agentic/what/AGENTS.md**:
```markdown
# what/ — Agent Guide
## What's Here
Knowledge, research, decisions, and artifacts for [your project].
## Working Rules
- Decisions go in `what/decisions/` as ADRs
- Domain knowledge goes in `what/context/`
- Use frontmatter: `type`, `created`, `updated`, `tags`
```
**.agentic/how/AGENTS.md**:
```markdown
# how/ — Agent Guide
## What's Here
Operational processes, plans, and session tracking for [your project].
## Working Rules
- Session files go in `how/sessions/`
- Multi-session plans go in `how/missions/`
- Use frontmatter: `type`, `created`, `updated`, `status`, `tags`
```
**Checkpoint**: ~8.5 minutes elapsed.
### Step 5: Classify existing knowledge (~3-5 minutes)
Look at your existing project files. Do any of them contain knowledge that belongs in the triad? Use the **Question Test**:
| If the content answers... | It belongs in... |
|---------------------------|------------------|
| "Who is involved?" — team members, stakeholders, contacts | `.agentic/who/` |
| "What do we know?" — research, decisions, specs, designs | `.agentic/what/` |
| "How do we work?" — processes, runbooks, checklists, plans | `.agentic/how/` |
Common candidates:
- **CONTRIBUTING.md** → copy key points into `.agentic/how/` (keep the original for GitHub)
- **Architecture docs** → move or link into `.agentic/what/decisions/`
- **Team/contacts info** → move to `.agentic/who/`
- **Runbooks/playbooks** → move to `.agentic/how/`
> **Don't over-migrate.** Move 2-3 files on Day 1. The triad grows organically — you'll naturally file new knowledge into the right directory as you create it.
**Checkpoint**: ~12 minutes elapsed.
### Step 6: Test (~1 minute)
Open a terminal in your project directory and start your AI agent:
```bash
claude # or your preferred agent
```
The agent should:
1. Read `CLAUDE.md` automatically
2. Understand your project structure
3. Know where to find and file knowledge
4. Follow the safety rules you defined
Try asking: *"What is this project and how is the knowledge organized?"*
If the agent can answer correctly, your aDNA installation is working.
**Checkpoint**: ~13 minutes. Done.
---
## 5. Walkthrough: Bare Form
For knowledge bases, documentation projects, and repos where aDNA IS the project. The steps are identical to the embedded form with these differences:
### Structure differences
```bash
# Instead of .agentic/ subdirectories:
mkdir -p who what how
```
```
my-knowledge-base/
├── who/ # People & organizations
├── what/ # Knowledge & artifacts
├── how/ # Operations & process
├── CLAUDE.md # Agent master context
├── MANIFEST.md # Project identity
├── STATE.md # Operational state
└── ... # Any existing files
```
### CLAUDE.md differences
Update the `## Structure` section to reference root-level directories:
```markdown
## Structure
Project knowledge uses the aDNA triad at the project root:
- `who/` — people, teams, contacts, stakeholders
- `what/` — research, decisions, domain knowledge, artifacts
- `how/` — plans, processes, sessions, workflows
```
### Extra considerations
- **Existing directories**: If you already have a `how/` or `what/` directory, you have two options: (a) adopt the aDNA naming and add `AGENTS.md` files to your existing directories, or (b) switch to the embedded form to avoid collisions.
- **Root file count**: The bare form adds `CLAUDE.md`, `MANIFEST.md`, `STATE.md`, and `README.md` to your root. If your root is already crowded, embedded form keeps it cleaner.
- **Mixed content**: In bare form, the triad directories contain only aDNA-managed knowledge. Keep source code, build artifacts, and tooling configs at the root or in their own directories — don't put code inside `what/` or `how/`.
---
## 6. Starter Templates
Copy-paste-ready minimal versions. Customize the bracketed sections.
### CLAUDE.md (~25 lines)
```markdown
# CLAUDE.md — [Your Project Name]
## Identity
This is [one-sentence project description].
## Structure
[Bare: `who/`, `what/`, `how/` at root]
[Embedded: `.agentic/who/`, `.agentic/what/`, `.agentic/how/`]
## Agent Protocol
1. Read this file (auto-loaded)
2. Read `STATE.md` for current context
3. Read the `AGENTS.md` in the directory you're working in
## Safety Rules
- Read before write
- Set `last_edited_by` and `updated` on every edit
- Do not modify files outside the triad without explicit instruction
## Domain
- [Key fact about your project]
- [Important convention or pattern]
- [Domain terminology to know]
```
### MANIFEST.md (~15 lines)
```markdown
---
type: manifest
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
# [Your Project Name]
## What This Is
[2-3 sentences describing the project.]
## Architecture
[Languages, frameworks, key directories.]
## Active Builds
- [Current focus]
```
### STATE.md (~10 lines)
```markdown
---
type: state
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
# Operational State
## Current Phase
[What's happening now.]
## Next Steps
- [Next action]
```
### AGENTS.md (~8 lines)
```markdown
# [directory_name]/ — Agent Guide
## What's Here
[One sentence: what this directory contains.]
## Working Rules
- [Naming convention for files]
- Use frontmatter: `type`, `created`, `updated`, `tags`
```
---
## 7. Common Pitfalls
Things that trip people up when adding aDNA to an existing project:
### Putting CLAUDE.md inside `.agentic/` instead of the project root
AI agents auto-load `CLAUDE.md` from the project root. If it's inside `.agentic/`, agents won't find it on startup and lose all orientation. **Always place CLAUDE.md at the project root**, regardless of which triad form you use.
### Over-engineering Day 1
You don't need 16 entity types, custom templates, campaign hierarchies, and a context library on your first day. Start with the minimum viable set (5 files + 3 directories). Add structure as you discover you need it — the triad grows organically.
### Frontmatter perfectionism
Start with three fields: `type`, `created`, `tags`. Add `updated`, `status`, `last_edited_by` when you have multiple agents or collaborators. Add domain-specific fields when you find yourself repeatedly including the same information. Don't design the perfect schema upfront.
### Forgetting AGENTS.md files
Every triad directory needs an `AGENTS.md`. Without it, agents have no routing information for that directory and will either skip it or read everything in it (wasting tokens). Even a 3-line AGENTS.md is better than none.
### Migrating everything at once
Don't dump all your existing docs into the triad in one session. Move 2-3 files to prove the pattern works. Let the structure grow as new knowledge is created. Forced migrations create filing confusion and don't stick.
### Treating aDNA as a replacement for your existing structure
aDNA doesn't replace your codebase structure (`src/`, `lib/`, `tests/`). In the embedded form, `.agentic/` sits alongside your code — it manages *project knowledge*, not source code. Your code organization stays exactly as it is.
---
## 8. What to Do Next
Once the core structure is working, enhance it progressively:
### Week 1: Session tracking
Add `how/sessions/` (bare) or `.agentic/how/sessions/` (embedded). Each agent session creates a file here before modifying the vault. Sessions create continuity — the next agent reads the last session's handoff notes and picks up where it left off.
### Week 2: Templates
Create templates in `how/templates/` for file types you create repeatedly. A template is just a Markdown file with pre-filled frontmatter that gets copied when you create a new file of that type.
### Week 3: Your first campaign
When you have a multi-session initiative (a feature build, a research project, a migration), create a campaign file in `how/campaigns/`. Campaigns decompose into missions (multi-session tasks) which decompose into objectives (single-session units). This gives agents structured context about what you're working toward.
### When needed: Context library
As your project accumulates domain knowledge that agents need repeatedly, organize it into `what/context/` with topic-based files. Each file covers one domain topic with structured information that agents can load on demand instead of re-discovering it each session.
### When collaborating: Obsidian config
If your team uses Obsidian for visual browsing, add `.obsidian/` with theme and plugin configuration. See the [aDNA repo](https://github.com/aDNA-Network/aDNA) for a pre-configured setup with 15 plugins and the Tokyo Night theme.
### When connecting: Bridge patterns
When your project needs to reference or compose with other aDNA instances, see [`adna_bridge_patterns.md`](https://github.com/aDNA-Network/aDNA/blob/main/.adna/what/docs/adna_bridge_patterns.md) for nesting, sibling, and monorepo composition patterns.
---
## 9. Quick Reference
### The Question Test
| Question | Triad leg |
|----------|-----------|
| Who is involved? | `who/` |
| What does this project know? | `what/` |
| How does this project work? | `how/` |
### File placement checklist
```
Project root:
✓ CLAUDE.md (agent master context — ALWAYS at root)
✓ MANIFEST.md (project identity)
✓ STATE.md (operational state)
Triad directories (bare: root / embedded: .agentic/):
✓ who/AGENTS.md (people directory guide)
✓ what/AGENTS.md (knowledge directory guide)
✓ how/AGENTS.md (operations directory guide)
```
### Minimum frontmatter
```yaml
---
type: [entity_type]
created: YYYY-MM-DD
tags: [relevant, tags]
---
```
---
*Migration guide v1.0 | Companion to the [aDNA Standard](/reference/specification/), [Design Document](/reference/design-rationale/), and [Bridge Patterns](https://github.com/aDNA-Network/aDNA/blob/main/.adna/what/docs/adna_bridge_patterns.md)*
---
## https://adna.network/reference/quality-rubric/
# Quality Rubric — aDNA Reference
## Purpose
Systematic quality evaluation framework for context library objects. Provides a 6-axis quantitative rubric that gates all context files — any file scoring ≤ 2 on any axis is flagged for revision regardless of composite score. Applied during Phase 3 review (mandatory for `standard`+ effort) and during periodic quality audits.
## Evaluation Axes
### 1. Signal Density (1-5)
**Definition**: Fraction of tokens that are decision-relevant — i.e., removing the token would reduce an agent's ability to make a correct recommendation or produce useful output.
| Score | Descriptor | Example |
|-------|-----------|---------|
| 1 | **Mostly filler.** >50% of content is hedging, preamble, repetition, or background that doesn't inform decisions. | "When it comes to GPU cluster architecture, there are several important considerations to keep in mind..." |
| 2 | Significant filler. 30-50% of tokens add no decision value. Prose-heavy with buried insights. | Background paragraphs explaining well-known concepts before getting to novel analysis. |
| 3 | **Moderate density.** Some filler but most paragraphs carry useful information. Tables mixed with narrative. | A guide that alternates between useful recommendations and verbose explanations of obvious points. |
| 4 | High density. <15% filler. Tables, structured lists, and concise paragraphs dominate. Minimal hedging. | Context file using table-first format with brief connecting prose. Each sentence carries weight. |
| 5 | **Every sentence carries weight.** Token removal would degrade output quality. Decision tables, structured data, precise claims. Zero filler. | The GPU cluster table in signal_to_token.md: 3 rows × 4 columns encoding 12 data points in ~40 tokens. |
**Worked example (score 2 vs 4)**:
- *Score 2*: A context file on federation patterns that opens with 200 tokens explaining "what federation means in general distributed systems" before reaching aDNA-specific content.
- *Score 4*: The same topic opening with a decision table: "Federation capability | Schema requirement | Example" — every token maps to a design decision.
### 2. Actionability (1-5)
**Definition**: Can an agent use this context to produce concrete, specific output — or is it background knowledge only?
| Score | Descriptor | Example |
|-------|-----------|---------|
| 1 | **Awareness only.** Describes a domain but provides no guidance an agent can act on. | "Machine learning is a broad field with many applications..." |
| 2 | General awareness with some direction. Identifies categories but no specific actions. | "You should consider performance, cost, and reliability when choosing infrastructure." |
| 3 | **Moderate actionability.** Contains recommendations but requires agent interpretation. Some concrete guidance mixed with general advice. | "Use XML tags for structural boundaries" — actionable but still needs context about when/how. |
| 4 | High actionability. Specific recommendations with rationale. Format selection guides, decision trees, threshold values. | "Default to standard effort for most queries. Minimal for simple lookups; exhaustive for critical decisions." — directly maps to a parameter choice. |
| 5 | **Directly executable.** Decision tables, format selection guides, threshold matrices that an agent can apply without interpretation. | The Format Selection Guide table in signal_to_token.md: 7 content types → 7 format choices → 7 rationales. Agent can look up its content type and get the answer. |
**Worked example (score 2 vs 4)**:
- *Score 2*: "Ontology design should balance simplicity with expressiveness" — true but an agent can't derive a specific action.
- *Score 4*: "Use flat schemas with discriminator fields (e.g., `type: customer|partner|contact`) instead of deep hierarchies. Apply the question test: if asking 'is X a Y?' feels unnatural, the classification is wrong." — specific design rules an agent can execute.
### 3. Coverage Uniformity (1-5)
**Definition**: Balanced depth across sections — are all declared topics covered proportionally, or does one section dominate while others are thin?
| Score | Descriptor | Example |
|-------|-----------|---------|
| 1 | **One section dominates.** >60% of tokens in one section; other sections are stubs or missing. | A "security best practices" file where 80% covers authentication and authorization gets 2 sentences. |
| 2 | Significant imbalance. One section has 2-3× the depth of others without proportional importance. | |
| 3 | **Moderate balance.** Minor imbalances but all declared sections have substantive content. Some sections could use expansion. | Most sections have 3-5 points; one has 8 and another has 2. The imbalance is noticeable but not severe. |
| 4 | Good balance. Sections are proportional to their importance. No stubs. Minor depth differences justified by topic weight. | |
| 5 | **Even depth, proportional to importance.** Every section has depth matching its significance. No section feels rushed or padded. | signal_to_token.md: Key Principles (7 items), Recommendations (3 sub-sections), Examples (2 comparisons), Anti-Patterns (6 items), Sources (5). Balanced across all standard sections. |
### 4. Source Diversity (1-5)
**Definition**: Distribution of evidence across source types. Over-reliance on a single source type is a quality risk — vendor docs may be biased, academic papers may lag practice, community sources may lack rigor.
| Source Types | Examples |
|-------------|---------|
| Vendor/official docs | Anthropic docs, AWS whitepapers, framework docs |
| Academic/research | Papers, preprints, textbooks |
| Industry practitioner | Blog posts by practitioners, conference talks, case studies |
| Community/empirical | GitHub discussions, Stack Overflow, community benchmarks |
| Original analysis | First-hand operational experience, internal measurements |
| Score | Descriptor | Example |
|-------|-----------|---------|
| 1 | **Single source.** Entire file derives from one source or one source type. | A context file paraphrasing a single Anthropic blog post. |
| 2 | Limited diversity. 2 source types, but one provides >70% of claims. | Vendor docs + one academic paper, but the vendor docs drive everything. |
| 3 | **Moderate diversity.** 2-3 source types with reasonable balance. No single type >60%. | 3 vendor docs + 2 academic papers. Coverage adequate but narrow source types. |
| 4 | Good diversity. 3-4 source types, none providing >40% of claims. Multiple perspectives represented. | signal_to_token.md: Anthropic official (2), Anthropic blog (1), academic preprint (1), operational experience (1). 4 source types, balanced. |
| 5 | **Excellent diversity.** 4+ source types, none >40%. Cross-validated claims from independent sources. Vendor, academic, practitioner, and empirical perspectives all present. | |
### 5. Freshness Half-Life (Categorical)
**Definition**: How quickly do the majority of claims in this file become stale? This is a categorical assessment, not a numeric score — it describes the content's temporal character rather than its current quality.
| Category | Timeframe | Typical Content | Review Cadence |
|----------|-----------|----------------|---------------|
| **Volatile** | <1 year | Market share, pricing, benchmark rankings, API parameters, model capabilities | Quarterly review |
| **Stable** | 1-3 years | Architecture patterns, protocol designs, framework best practices, organizational processes | Annual review |
| **Durable** | 3+ years | Fundamental principles, mathematical frameworks, regulatory structures, design axioms | Review on major paradigm shifts |
| **Mixed** | Varies | File contains claims across multiple freshness categories | Tag individual sections; review at volatile cadence |
**Assessment guidance**: Read the file's claims and ask "which of these will be wrong in 12 months?" If >30% of claims are volatile, the file is volatile or mixed. If most claims are design principles or mathematical frameworks, the file is durable.
### 6. Cross-Topic Coherence (1-5)
**Definition**: Does this file contradict, redundantly overlap with, or complement related files in the same topic or adjacent topics?
| Score | Descriptor | Example |
|-------|-----------|---------|
| 1 | **Conflicts with related files.** Contains claims that directly contradict other context files. Definitions or recommendations are inconsistent. | One file recommends XML for all structure; another recommends markdown for everything, with no reconciliation. |
| 2 | Notable inconsistencies or substantial redundancy. >20% overlap with a sibling file without clear differentiation. | Two files in the same topic both cover "format selection" with conflicting guidance. |
| 3 | **Minor overlap or slight inconsistencies.** Some repeated content across files but no outright contradictions. Differentiation is mostly clear. | Two files both mention "tables beat prose" but from different angles; slight redundancy, no conflict. |
| 4 | Good coherence. Files complement each other with minimal overlap. Cross-references are accurate. Each file has a distinct scope. | signal_to_token.md and convergence_model.md: distinct scopes (formatting vs. ontology structure) with complementary principles and accurate cross-references. |
| 5 | **Perfect complementarity.** Files partition the topic cleanly. No redundancy. Cross-references are bidirectional and accurate. Reading related files together produces strictly additive knowledge. | |
**Assessment method**: For each file being scored, identify the 2-3 most related files (same topic or adjacent). Check for: (a) contradictory claims, (b) redundant coverage >10%, (c) missing cross-references where they'd help, (d) terminology consistency.
---
## Composite Score
**Formula**: Simple average of the 5 numeric axes (signal density, actionability, coverage uniformity, source diversity, cross-topic coherence).
```
quality_score = (signal_density + actionability + coverage_uniformity + source_diversity + cross_topic_coherence) / 5
```
Freshness half-life is categorical and not included in the numeric average — it is recorded separately as `freshness_category`.
### Floor Rule
**If any numeric axis scores ≤ 2, the file is flagged for revision regardless of composite score.** A file scoring 5/5/5/1/5 (composite 4.2) still fails — source diversity of 1 means single-source risk that could invalidate the entire file.
### Score Interpretation
| Composite | Rating | Action |
|-----------|--------|--------|
| 4.5 - 5.0 | Excellent | File as-is. Exemplary reference. |
| 3.5 - 4.4 | Good | File with minor improvements noted. |
| 2.5 - 3.4 | Adequate | File with improvement plan. Prioritize lowest-scoring axes. |
| 1.5 - 2.4 | Needs work | Revise before filing. Multiple axes need improvement. |
| 1.0 - 1.4 | Unacceptable | Re-research or re-synthesize from scratch. |
---
## Scoring Procedure
### During Phase 3 Review (mandatory for `standard`+ effort)
1. **Read the context file** in full
2. **Identify 2-3 related files** for cross-topic coherence assessment
3. **Score each axis** using the descriptors above — record the score and a 1-sentence justification
4. **Compute composite** — apply floor rule check
5. **Record in frontmatter** — add quality fields (see scoring template)
6. **Include in review brief** — the Quality Scorecard section
### During Periodic Audit
Same procedure, but also:
- Check freshness against current date — volatile files >6 months old need re-evaluation
- Compare scores against topic averages — outlier low scores indicate revision candidates
---
## Frontmatter Integration
Quality scores are recorded in context file frontmatter:
```yaml
# Quality evaluation (added by M2 rubric)
quality_score: 4.2 # composite average of 5 numeric axes
signal_density: 4 # 1-5
actionability: 5 # 1-5
coverage_uniformity: 4 # 1-5
source_diversity: 4 # 1-5
cross_topic_coherence: 4 # 1-5
freshness_category: stable # volatile | stable | durable | mixed
last_evaluated: 2026-02-19 # date of last quality evaluation
```
These fields are optional in the context file schema — they are added during Phase 3 review or retrospective quality audits.
---
## Calibration Appendix
Baseline calibration against 3 existing context files, establishing scoring reference points.
### Calibration File 1: `context_prompt_engineering_signal_to_token.md` (adna)
**Profile**: M1 research output. High-quality, decision-relevant tables, multiple source types.
| Axis | Score | Justification |
|------|-------|--------------|
| Signal density | 5 | Every section delivers decision-relevant content. Format Selection Guide table is maximally dense. The high/low density comparison example demonstrates the principle it teaches. Zero filler. |
| Actionability | 5 | Format Selection Guide (7 content types → format → rationale), Token Efficiency Tactics (5 specific actions), Context Window Management (budget percentages). Agent can execute directly from these tables. |
| Coverage uniformity | 4 | 7 Key Principles, 3 Recommendation subsections, 2 Examples, 6 Anti-Patterns, 5 Sources — well-balanced. Minor: Examples section is slightly thinner than others (2 comparisons vs. 5-7 items elsewhere). |
| Source diversity | 4 | 5 sources across 3 types: Anthropic official docs (3), Anthropic blog (1), academic preprint (1). Strong vendor representation; one academic paper provides independent validation. Would benefit from a practitioner/community source for a 5. |
| Cross-topic coherence | 5 | Distinct scope (formatting optimization) that complements convergence_model (structural optimization) without overlap. Referenced by convergence_model as foundation. Terminology consistent across topic. |
| Freshness | stable | Core principles (XML tags, tables-over-prose, progressive disclosure) are stable design patterns. Claude-specific formatting guidance is model-generation-specific but stable within the Claude 4 era. Minor volatile elements (specific token counts, model behavior details). |
**Composite**: (5 + 5 + 4 + 4 + 5) / 5 = **4.6** — Excellent
### Calibration File 2: `context_prompt_engineering_convergence_model.md` (adna)
**Profile**: M1 original articulation. Novel framework with operational backing but fewer external sources.
| Axis | Score | Justification |
|------|-------|--------------|
| Signal density | 4 | The Analogy Table and Worked Example are maximally dense. Design Implications section is highly actionable. The mathematical framing paragraphs in Key Principles are slightly denser on abstraction than necessary — a few sentences could be tightened without losing meaning. |
| Actionability | 4 | "Designing for Convergence" table (6 decisions × convergent/divergent), "Design Implications" (5 numbered rules), "When to Use It" (4 bullet applications). Strong, but the mathematical framing sections require interpretation before application — not as directly executable as signal_to_token's tables. |
| Coverage uniformity | 5 | 6 Key Principles, Analogy Table, Worked Example (detailed token narrowing), Designing for Convergence table, Projection Sequence (4 steps), Design Implications (5 items), Anti-Patterns (6 items), When to Use It (4 bullets), 3 Sources. Comprehensive and balanced — every section has substance. |
| Source diversity | 2 | 3 sources, but dominated by original articulation (primary) + 1 Anthropic source + 1 internal spec. No academic, practitioner, or community validation. The framework is largely first-principles; external validation would strengthen it but the novelty limits available sources. |
| Cross-topic coherence | 5 | Explicitly builds on signal_to_token (formatting) and ontology_design (structure). Distinct scope — the structural/mathematical lens rather than formatting or entity design. Dependency chain documented in topic AGENTS.md. |
| Freshness | durable | Mathematical framework, design principles, structural decomposition patterns. These are paradigm-level abstractions unlikely to change within 3+ years. The worked token-count example may need updating as vault grows, but the principles hold. |
**Composite**: (4 + 4 + 5 + 2 + 5) / 5 = **4.0** — Good
**Floor rule triggered**: Source diversity = 2. Despite a strong composite, this file should be flagged for source diversity improvement. Recommendation: in a future pass, cross-reference against published knowledge graph / ontology decomposition literature to add academic validation.
### Calibration File 3: `context_deep_research_methodology.md` (vault)
**Profile**: Older file, different production method (not M1 research). Describes the deep research process itself.
| Axis | Score | Justification |
|------|-------|--------------|
| Signal density | 3 | Key Principles (6 items) are well-structured. Recommendations (4 items) are concise and actionable. However, "Detailed Analysis" section contains explanatory prose that mostly restates the principles in longer form ("Why Orchestrator-Worker?" largely repeats Principle 1). ~20-25% redundancy between sections. |
| Actionability | 3 | Recommendations are moderately actionable ("Default to standard effort", "Use sub-agents for source dispatch"). But the file describes a process rather than providing decision tables. An agent reading this knows *what* deep research is but would need the full skill directory to *execute* it. The Comparison Table (Context Engine vs Deep Research) is the most actionable element. |
| Coverage uniformity | 3 | Key Principles and Recommendations are solid. Detailed Analysis has 2 subsections + 1 comparison table — adequate but thin compared to the 6 principles. Sources section is minimal (3 sources, no URLs for 2 of them). Missing: effort level details, iteration budgets, output format specs. |
| Source diversity | 2 | 3 sources, all in-family: 2 Anthropic + 1 internal. No academic, practitioner, or community sources. The process is internally designed, which limits external source availability, but related work on multi-agent research patterns exists in academic literature. |
| Cross-topic coherence | 4 | Distinct scope (methodology overview) that complements the full deep_research skill directory without contradiction. Slight risk: claims about "bounded iteration" and "effort scaling" are general here but detailed in the skill files — an agent loading both gets some redundancy. No outright conflicts. |
| Freshness | stable | Process design patterns and orchestrator-worker topology are stable. Effort level design is process-specific and changes with the skill, not with external factors. Anthropic source references are 2025-era and still current. |
**Composite**: (3 + 3 + 3 + 2 + 4) / 5 = **3.0** — Adequate
**Floor rule triggered**: Source diversity = 2. File should be flagged for source diversity improvement and for signal density/coverage tightening. The Detailed Analysis section's redundancy with Key Principles is the main density drag.
### Calibration Summary
| File | Signal | Action | Coverage | Sources | Coherence | Freshness | Composite | Floor |
|------|--------|--------|----------|---------|-----------|-----------|-----------|-------|
| signal_to_token | 5 | 5 | 4 | 4 | 5 | stable | **4.6** | Pass |
| convergence_model | 4 | 4 | 5 | 2 | 5 | durable | **4.0** | **FAIL** (sources) |
| deep_research_methodology | 3 | 3 | 3 | 2 | 4 | stable | **3.0** | **FAIL** (sources) |
**Calibration observations**:
1. **Scores are differentiated** — the rubric produces meaningful spread (3.0 to 4.6), not clustering around 4. This is desirable.
2. **Source diversity is the systemic weak axis** — both lower-scoring files fail on sources. This reflects the reality that many context files are synthesized from limited source types. The rubric correctly identifies this as a quality risk.
3. **Signal density correlates with format** — files using tables as primary format (signal_to_token) score higher than prose-heavy files (deep_research_methodology). This aligns with the signal-to-token principles themselves.
4. **The floor rule works** — convergence_model has a strong composite (4.0) but the source diversity = 2 correctly flags a real weakness. Without the floor rule, this file would pass unchallenged.
5. **Freshness categorization is useful** — volatile/stable/durable provides actionable review scheduling information beyond the numeric scores.
---
## https://adna.network/reference/reading-guide/
# Reading Guide — aDNA Reference
The [aDNA Universal Standard](/reference/specification/) is ~1,500 lines. You don't need all of them. This guide maps three reading paths by what you're trying to do, provides a section-by-section table of contents, and disambiguates the skill/lattice dual identity.
---
## 1. Reading Paths
Three personas, three curated paths through the standard:
| Persona | Goal | Sections to read | ~Lines | Time |
|---------|------|-------------------|--------|------|
| **New adopter** | Get a working vault | §1 (Intro), §2 (Terms), §3 (Triad), §4 (Governance), §5 (Directory Structure), §7 (Frontmatter) | ~630 | 10-15 min |
| **Extension builder** | Add entity types, templates, pipelines | New adopter path + §6 (Naming), §12 (Templates), §14 (Pipelines), §19 (Extensions) | ~870 | 20-25 min |
| **Standard contributor** | Understand the full spec | Everything | ~1,500 | 45-60 min |
### New Adopter Path
Read these six sections in order. They give you the structural foundation to set up and operate an aDNA vault.
1. **§1 Introduction & Scope** — What aDNA is, who it's for, RFC 2119 keywords
2. **§2 Terminology** — 12 key terms (triad, governance file, bare/embedded, session, SITREP)
3. **§3 Triad Architecture** — The `who/what/how` ontology, bare vs. embedded deployment forms
4. **§4 Governance Files** — CLAUDE.md, MANIFEST.md, STATE.md, AGENTS.md, README.md — what each does
5. **§5 Directory Structure** — Required/recommended/optional subdirectories for each triad leg
6. **§7 Frontmatter System** — Required YAML fields, tag conventions, type-specific extensions
**After this path**: You can create and operate a standard aDNA vault. Come back for sessions (§8), missions (§9), and collision prevention (§13) when you need them.
### Extension Builder Path
Start with the new adopter path above, then add these four sections:
7. **§6 Naming Conventions** — `type_descriptive_name.md` pattern, ALLCAPS governance list, directory naming
8. **§12 Template System** — Starter/Standard/Full template sets, template conventions
9. **§14 Content-as-Code Pipelines** — Folder-based workflows where file location = processing state
10. **§19 Optional Extensions** — Machine registry, backlog, skill files, testing/CI, reference code, ADRs
**After this path**: You can extend an aDNA vault with custom entity types, templates, pipelines, and optional subsystems.
### Standard Contributor Path
Read everything. The appendices (§20) contain the persona framework, aggregation point patterns, deferred topics, and the full decision traceability matrix mapping all 40 design decisions to their spec locations.
---
## 2. Section Map
All 20 numbered sections of the standard with one-line summaries, persona tags, and line ranges.
| § | Section | Summary | Personas | Lines |
|---|---------|---------|----------|-------|
| 1 | Introduction & Scope | What aDNA is, who it's for, RFC 2119 keywords | All | 15-51 |
| 2 | Terminology | 12 key terms: triad, governance file, bare/embedded, session, SITREP, content-as-code | All | 52-76 |
| 3 | Triad Architecture | `who/what/how` ontology, bare vs. embedded deployment forms, classification question test | All | 77-209 |
| 4 | Governance Files | Five ALLCAPS files (CLAUDE, MANIFEST, STATE, AGENTS, README) — purpose, contents, quickstart | All | 210-334 |
| 5 | Directory Structure | Required/recommended/optional subdirectories for each triad leg, starter/standard/full skeletons | All | 335-558 |
| 6 | Naming Conventions | Underscores not hyphens, `type_descriptive_name.md`, ALLCAPS governance list, `type_` prefixes | Extension+ | 559-622 |
| 7 | Frontmatter System | Required base fields (`type`, `created`, `updated`, `last_edited_by`, `tags`), tag conventions | All | 623-707 |
| 8 | Session Model | Bounded units of agent work — lifecycle (create → execute → close → archive), tiers, SITREP, next-session prompt, 75% rule | Operations | 708-803 |
| 9 | Mission System | Multi-session work decomposition — objectives, acceptance criteria, stages, handoff protocol | Operations | 804-854 |
| 10 | Context Library | `what/context/` — topic organization, context subtypes (research, guide, core), token budget awareness | Operations | 855-902 |
| 11 | Coordination Protocol | `who/coordination/` — cross-agent notes, urgency levels (urgent/info/fyi), ephemeral by design | Multi-agent | 903-934 |
| 12 | Template System | Graduated template sets (starter/standard/full), template naming and conventions | Extension+ | 935-974 |
| 13 | Collision Prevention | Three tiers: universal (frontmatter attribution), sync (file safety tiers), multi-agent (coordination + scope declarations) | Operations | 975-1038 |
| 14 | Content-as-Code Pipelines | Folder-based workflows — file location IS processing state, pipeline structure, stage AGENTS.md | Extension+ | 1039-1092 |
| 15 | Archive & Versioning | Archive patterns for sync vs. git environments, retention, CLAUDE.md version tracking | Reference | 1093-1140 |
| 16 | Tool Integration Tiers | Three tiers: core standard (Tier 1, universal), frontmatter querying (Tier 2), environment-specific (Tier 3) | Reference | 1141-1200 |
| 17 | Error & Recovery Protocol | Three-tier response: data integrity (STOP), state inconsistency (fix + log), process issues (workaround + backlog) | Operations | 1201-1238 |
| 18 | Success Criteria | Minimum viable (cold start, handoff, integrity), recommended (fork, scale, consistency), aspirational (network, collision safety, dual-audience) | Contributor | 1239-1292 |
| 19 | Optional Extensions | Machine registry, backlog, skill files, testing/CI awareness, reference code, ADRs | Extension+ | 1293-1376 |
| 20 | Appendices | Persona framework (App A), aggregation points (App B), deferred topics (App C), decision traceability matrix (App D — 40 decisions) | Contributor | 1377-1515 |
**Persona key**: All = everyone reads this. Extension+ = extension builders and contributors. Operations = anyone running sessions/missions. Multi-agent = concurrent agent environments. Reference = consult when needed. Contributor = standard contributors.
---
## 3. When to Read the Design Document
[`adna_design.md`](/reference/design-rationale/) is the companion "why" document. It explains the rationale behind design decisions — why three legs, why these governance files, why these trade-offs. Read it when you want:
- **Rationale** for why the standard works the way it does
- **Worked examples** of deployment patterns (standalone, nested, federated)
- **Trade-off analysis** behind structural decisions
The design document is not required for operational use. The standard tells you **what** to do; the design document tells you **why**.
---
## 4. Skill vs. Lattice: When to Use Which
aDNA has two constructs that both deal with "reusable capabilities" — **skill files** and **skill-type lattices**. They serve different purposes and live in different locations.
### Comparison
| Dimension | Skill File | Skill-Type Lattice |
|-----------|-----------|-------------------|
| **Location** | `how/skills/skill_.md` | `what/lattices/.lattice.yaml` |
| **Format** | Markdown with procedural steps | YAML directed graph with nodes and edges |
| **Purpose** | Agent recipe — step-by-step instructions | Composable computational unit — executable DAG |
| **When to create** | You have a repeatable procedure an agent should follow | You need a composable, publishable, executable workflow |
| **Execution** | Agent reads and follows the steps | Runtime engine traverses the DAG |
| **Registry** | Not publishable (local to the vault) | Publishable via `latlab lattice publish` |
| **Promotion path** | Can be promoted to a lattice via `skill_lattice_publish` | Already a lattice — can be composed with other lattices |
### Decision Rule
**Start with a skill file.** If the procedure needs to be published to a registry, composed with other lattices, or executed by a runtime engine, promote it to a `lattice_type: skill` lattice.
The promotion path is documented in `how/skills/skill_lattice_publish.md`. Most agent recipes stay as skill files — lattice promotion is for procedures that need computational composability.
### Examples
| Scenario | Use | Why |
|----------|-----|-----|
| "Deploy this service in 5 steps" | Skill file | Agent follows the steps — no DAG needed |
| "Run ESM-2 embedding → clustering → visualization" | Lattice | Computational pipeline — needs runtime execution |
| "Review and audit context quality" | Skill file | Procedural checklist — agent walks through it |
| "Compose protein design with docking and scoring" | Lattice | Multi-module DAG — needs composability with other lattices |
---
## 5. Quick Reference
**"I want to..."**
| Goal | Where to look |
|------|--------------|
| Set up my first vault | §3-5 of the standard, or the [README Quick Start](/get-started/) |
| Add a new entity type | §6 (Naming) + §7 (Frontmatter) + §19 (Extensions) |
| Track sessions | §8 (Session Model) |
| Run a multi-session project | §9 (Mission System) |
| Write an agent skill | `how/skills/AGENTS.md` + §19.3, then this guide's §4 for lattice promotion |
| Build a pipeline | §14 (Content-as-Code Pipelines) |
| Understand collision prevention | §13 (Collision Prevention) |
| Evaluate aDNA for my project | [`adna_design.md`](/reference/design-rationale/) — the "why" document |
| Add aDNA to an existing codebase | [`migration_guide.md`](/reference/migration-guide/) |
| Use aDNA without Obsidian | [`agent_first_guide.md`](/reference/agent-first-guide/) |
| Manage multiple aDNA projects | [`projects_folder_pattern.md`](https://github.com/aDNA-Network/aDNA/blob/main/.adna/what/docs/projects_folder_pattern.md) — workspace pattern with agent-guided scaffolding |
---
## Cross-References
- [aDNA Universal Standard](/reference/specification/) — the normative spec this guide navigates
- [aDNA Design Document](/reference/design-rationale/) — architecture rationale and trade-off analysis
- [Migration Guide](/reference/migration-guide/) — adding aDNA to existing projects
- [Agent-First Guide](/reference/agent-first-guide/) — terminal-first aDNA setup
- [Projects Folder Pattern](https://github.com/aDNA-Network/aDNA/blob/main/.adna/what/docs/projects_folder_pattern.md) — multi-project workspace with shared templates
- [Skills Protocol](https://github.com/aDNA-Network/aDNA/blob/main/.adna/how/skills/AGENTS.md) — skill file conventions and categories
---
## https://adna.network/reference/registry-api/
# Registry JSON — aDNA Reference
## Endpoints
| URL | Promise |
| --- | --- |
| [`/vaults.json`](/vaults.json) | The current registry. Follow this if you want whatever is live. |
| [`/api/registry.v1.json`](/api/registry.v1.json) | The **v1 shape**. Pin this if you need fields to keep meaning what they meant. |
Both serve identical bytes as `application/json`. They are built from one function, so a pin can
never silently diverge from the canonical path.
```bash
curl -s https://adna.network/vaults.json | jq '.vault_count, .vaults[0].display_name'
```
## Versioning
Breaking changes get a **new versioned URL** — `/api/registry.v2.json` — and the old one keeps
serving for at least **90 days** after the new version is published. `/vaults.json` moves to the
new version only after that window closes.
Adding a field is **not** a breaking change and may happen at any time. Write consumers that ignore
keys they do not recognise.
## Envelope
| Field | What it is |
| --- | --- |
| `schema_version` | This endpoint's contract version (`1.0`). |
| `about` | Self-description: canonical and versioned URLs, the versioning policy, licence. |
| `generated_at` | When the registry **data** was last regenerated. |
| `built_at` | When this file was **serialized**. Deliberately separate — a stale registry should not look as fresh as the last deploy. |
| `snapshot_note` | Plain-language restatement that this is a build-time snapshot. |
| `registry_schema_version` | The underlying registry's own schema version. |
| `source_inventory_sha` | Fingerprint of the node inventory the registry was generated from. |
| `caveat` | The self-declaration caveat, in the payload rather than only on the page. |
| `vault_count` · `edge_count` | Counted from the arrays below, never typed separately. |
| `field_coverage` | Per field: how many rows populate it, out of how many. See below. |
| `vaults` | The vault rows. |
| `edges` | Declared relationships: `source`, `target`, `type`. |
## Vault rows
Each row carries the raw registry value **and** its public label, so you can key on one and display
the other:
```json
{
"vault_slug": "operations",
"display_name": "Operations",
"class": "coordination",
"class_label": "coordination",
"status": "active",
"status_label": "active",
"tier": "in_use",
"tier_label": "in use",
"tier_meaning": "Being worked in today.",
"persona": "Berthier",
"note": null,
"url": "https://adna.network/vaults/operations/",
"markdown_url": "https://adna.network/vaults/operations.md"
}
```
`tier` is derived from `status` alone (`active` → `in_use`, `pending` → `chartered`, everything
else → `planned`). It is shipped so you do not have to reimplement the mapping.
Absent scalar values are `null`, never omitted. Absent lists are `[]`. An omitted key and a key
whose value is genuinely unknown are different facts, and collapsing them is how a consumer ends up
inferring something that was never there.
## `field_coverage` — read this before you trust a field
Several fields are populated **zero times** across the whole registry. That is not a fetch error
and not a bug: the registry's descriptive fields were deliberately emptied when internal language
was stripped out of the public projection, and sparseness is the honest cost of that. Rather than
let you discover it row by row, the endpoint counts it for you:
```json
"field_coverage": {
"display_name": { "populated": 74, "of": 74 },
"persona": { "populated": 61, "of": 74 },
"note": { "populated": 44, "of": 74 },
"tagline": { "populated": 0, "of": 74 }
}
```
Check coverage before building a view that depends on a field. `last_synced` deserves particular
care: it records a **registry sync**, not vault activity, and most of the rows that carry it share
a single date. Reading it as freshness would be false.
## Rows listed with a minimal card
Three vaults are listed with identity, class, status and persona only. They carry
`"listing": "minimal"` and a `listing_note` saying so. The vaults are real and governed; their
detail is private by ruling, not missing by accident. Treat a minimal row as **suppressed**, not
empty — the `listing_note` is there precisely so the two are distinguishable.
## What this endpoint is not
It is a projection of the **published** registry — the same fields the registry pages render, no
more. Fields that no page displays are not made public by being convenient to serialize. It is a
snapshot of one operator-run node's declarations, not a census of aDNA adoption, and nothing in it
is corroborated by an external signal.
## Related
- [The registry](/vaults) — the same data, rendered
- [`llms.txt`](/llms.txt) — the machine index for this whole site
- [Canonical properties](/canonical-properties) — how to verify a surface is genuinely aDNA
---
## https://adna.network/reference/specification/
# aDNA Specification — aDNA Reference
**Agentic DNA (aDNA)** — A knowledge architecture standard for AI-native projects.
---
## 1. Introduction & Scope
> **Scan**: What aDNA is, who it's for, and RFC 2119 normative keywords.
### 1.1 What Is aDNA
aDNA (Agentic DNA) is a standard for organizing project knowledge so that AI agents can orient, operate, and coordinate within any project — alongside humans. It defines a directory structure, governance files, metadata conventions, and operational protocols that together form a project's "knowledge genome."
An aDNA instance is the complete set of governance files, triad directories, and operational infrastructure that implements this standard within a project.
### 1.2 Audience
This standard is written for:
- **Agents** — AI assistants that read, write, and navigate project knowledge
- **Agent operators** — humans who configure and manage agent-augmented projects
- **Project bootstrappers** — anyone starting a new project that will use AI agents
### 1.3 Scope
**In scope**: Project knowledge architecture — how project information is organized, how agents orient and operate, how multiple agents coordinate, and how knowledge persists across sessions.
**Out of scope**: Application source code structure, CI/CD pipeline configuration, deployment infrastructure, and agent model internals. These belong to the project content layer, not to aDNA.
### 1.4 Normative Language
This document uses RFC 2119 keywords:
| Keyword | Meaning |
|---------|---------|
| **MUST** | Absolute requirement |
| **MUST NOT** | Absolute prohibition |
| **SHOULD** | Recommended; may be omitted with good reason |
| **MAY** | Truly optional |
---
## 2. Terminology
> **Scan**: 12 key terms — triad, governance file, bare/embedded deployment, session, SITREP, content-as-code.
| Term | Definition |
|------|-----------|
| **aDNA** | Agentic DNA — the knowledge architecture standard defined by this document |
| **Triad** | The `what/how/who` directory ontology that organizes all aDNA content |
| **what/** | Knowledge layer — WHAT the project knows (context, decisions, reference, domain objects) |
| **how/** | Operations layer — HOW the project works (missions, sessions, templates, pipelines) |
| **who/** | Organization layer — WHO is involved (people, teams, coordination, governance) |
| **Governance file** | A root-level ALLCAPS markdown file that governs the aDNA instance: CLAUDE.md, MANIFEST.md, STATE.md, AGENTS.md, README.md |
| **Bare triad** | Deployment form where `what/`, `how/`, `who/` sit directly at project root. Used for knowledge bases and standalone agent workspaces |
| **Embedded triad** | Deployment form where the triad is wrapped inside `.agentic/` (i.e., `.agentic/what/`, `.agentic/how/`, `.agentic/who/`). Used for git repositories |
| **Deployment form** | How the triad is physically instantiated — bare or embedded |
| **Session** | A bounded unit of agent work with a defined lifecycle: creation, execution, and close-out |
| **SITREP** | Structured status report at session close: Completed, In Progress, Next Up, Blockers, Files Touched |
| **Content-as-code** | A pipeline paradigm where a file's directory location represents its processing state |
| **AGENTS.md** | Per-directory agent-facing guide — purpose, key files, patterns, conventions |
| **README.md** | Per-directory human-facing guide — navigation, context, useful links |
| **Conformance level** | A graduated tier (Starter, Standard, Full) defining the minimum requirements an aDNA instance MUST meet to claim conformance at that level |
| **Conformant instance** | A directory tree that satisfies all MUST requirements for at least the Starter conformance level defined in §5.5 |
---
## 3. Triad Architecture
> **Scan**: The `who/what/how` ontology, bare vs. embedded deployment forms, classification question test.
*Decisions: C1, C8*
### 3.1 The what/how/who Ontology
Every aDNA instance organizes knowledge into three categories:
| Layer | Question | Contains |
|-------|----------|----------|
| **what/** | WHAT does this project know? | Knowledge objects, context library, decisions, reference material, domain entities |
| **how/** | HOW does this project work? | Missions, sessions, templates, pipelines, tasks, skills, processes |
| **who/** | WHO is involved? | People, teams, coordination notes, governance policies, communications |
The triad is the universal ontology. Any piece of project knowledge belongs in exactly one of the three legs. When classifying content, apply the question test: "Is this about WHAT we know, HOW we work, or WHO is involved?"
**Classification examples**:
| Content | Question | Triad Leg |
|---------|----------|-----------|
| "How does ancient DNA extraction work?" | WHAT do we know? | `what/context/` |
| "Mission plan for Q2 deployment" | HOW do we work? | `how/missions/` |
| "Contact info for the partnership lead" | WHO is involved? | `who/contacts/` |
The triad is deliberately minimal. Three categories are sufficient because they map to the three dimensions of any project: its knowledge, its operations, and its people. Additional categories create sorting ambiguity.
```mermaid
flowchart TB
Root["aDNA Instance"]
Root --> W["what/ Knowledge"]
Root --> H["how/ Operations"]
Root --> O["who/ Organization"]
W --> ctx["context/"]
W --> dec["decisions/"]
W --> dom["domain entities"]
H --> mis["missions/"]
H --> ses["sessions/"]
H --> tpl["templates/"]
O --> coord["coordination/"]
O --> gov["governance/"]
O --> ppl["people & teams"]
style W fill:#0d9488,color:#fff
style H fill:#22c55e,color:#fff
style O fill:#8b5cf6,color:#fff
```
### 3.2 Bare Triad
In a bare triad deployment, `what/`, `how/`, and `who/` sit as top-level directories at the project root. Governance files sit alongside them at root level.
**When to use**: Knowledge bases, standalone agent workspaces, and any project where aDNA IS the primary content.
```
{project_root}/
├── CLAUDE.md
├── MANIFEST.md
├── STATE.md
├── AGENTS.md
├── README.md
├── what/
├── how/
├── who/
└── {project_content}/
```
### 3.3 Embedded Triad
In an embedded triad deployment, the triad is wrapped inside `.agentic/` at the repository root. Governance files remain at the repository root (not inside `.agentic/`).
**When to use**: Any git-tracked codebase adding agent support. The `.agentic/` prefix follows the convention of dot-prefixed directories for meta/config in git repositories (like `.github/`, `.vscode/`).
```
{repo_root}/
├── CLAUDE.md
├── MANIFEST.md
├── STATE.md
├── AGENTS.md
├── README.md
├── .agentic/
│ ├── AGENTS.md
│ ├── what/
│ ├── how/
│ └── who/
└── {codebase}/
```
### 3.4 Deployment Form Selection
Both deployment forms are first-class. The triad ontology is identical in both — only the physical nesting differs. CLAUDE.md in each environment bridges any path differences.
An aDNA instance MUST use exactly one deployment form. A project MUST NOT mix bare and embedded triads.
### 3.5 Directory Convention
An aDNA project directory SHOULD use the `.aDNA` suffix to indicate it follows the Agentic DNA knowledge architecture standard. This suffix serves as a visual type marker, analogous to `.app` bundles in macOS or `.git` directories in version control.
**Naming rules:**
- The base template (the `aDNA` repository, embedded in a workspace at `.adna/`) MUST NOT use the `.aDNA` suffix — it is the source, not an instance. *(Per ADR-006 repo rename `Agentic-DNA`→`aDNA` + ADR-008 airlock embedding at `.adna/`.)*
- Forked projects SHOULD use the pattern `ProjectName.aDNA/` (e.g., `zeta.aDNA/`, `my_research.aDNA/`).
- The project name portion MUST match `[a-z][a-z0-9_]{0,63}` — lowercase letters, digits, and underscores only, starting with a letter, maximum 64 characters.
- The suffix `.aDNA` uses mixed case (capital D, N, A) matching the abbreviation branding.
- Nesting `.aDNA` directories inside other `.aDNA` directories is NOT RECOMMENDED.
- Existing projects MAY adopt the convention by renaming their directory. This is optional.
**Discovery:**
Tools SHOULD discover aDNA projects via `*.aDNA` glob patterns:
```bash
# List aDNA projects in workspace
ls -d *.aDNA 2>/dev/null
find . -maxdepth 1 -name "*.aDNA" -type d
```
**Workspace convention:**
```
~/aDNA/
├── .adna/ # Base template — the aDNA standard tree (hidden; source, not an instance)
├── my_research.aDNA/ # Forked project (aDNA instance)
├── zeta.aDNA/ # Another project
└── CLAUDE.md # Workspace-level governance
```
---
## 4. Governance Files
> **Scan**: Five ALLCAPS files (CLAUDE, MANIFEST, STATE, AGENTS, README) — purpose, required contents, quickstart sequences, progressive enrichment.
*Decisions: C2, C3, D1, D2, D6, D19, D25*
Every aDNA instance MUST have governance files at the project root. These are the agent's primary orientation documents.
### 4.1 Governance File List
The following ALLCAPS files constitute the governance layer:
| File | Required | Purpose | Update Cadence |
|------|----------|---------|----------------|
| **CLAUDE.md** | MUST | Agent root context — persona, project map, safety rules, startup protocol | When structure or protocols change |
| **MANIFEST.md** | MUST | Static project overview — what the project is, architecture, entry points | When project scope or architecture changes |
| **STATE.md** | SHOULD | Dynamic operational state — current phase, blockers, recent decisions, next steps | Every session close-out |
| **AGENTS.md** | MUST | Root-level agent guide — directory purpose, key files, patterns | When directory structure changes |
| **README.md** | MUST | Root-level human guide — navigation, setup, how to browse | When onboarding experience changes |
```mermaid
flowchart LR
CLAUDE["CLAUDE.md Agent root context"]
MANIFEST["MANIFEST.md Project overview"]
STATE["STATE.md Current state"]
AGENTS["AGENTS.md Directory guide"]
README["README.md Human guide"]
CLAUDE -->|"structure + rules"| STATE
CLAUDE -->|"references"| MANIFEST
STATE -->|"updated each session"| CLAUDE
AGENTS -.->|"per-directory"| CLAUDE
README -.->|"per-directory"| CLAUDE
style CLAUDE fill:#ef4444,color:#fff
style STATE fill:#eab308,color:#000
style MANIFEST fill:#3b82f6,color:#fff
```
### 4.2 CLAUDE.md — Agent Root Context
CLAUDE.md is the primary agent orientation document. It MUST exist at the project root in both deployment forms. It is auto-loaded by Claude Code and serves as the agent's first read on every session.
**Required sections**:
1. **Identity**: Project name, agent persona (if defined — see Appendix A), mission statement. The agent MUST know what project it is operating in and what role it plays.
2. **Project Map**: Directory structure diagram, key files table. The agent MUST be able to navigate the project from this section alone.
3. **Safety Rules**: Collision prevention tier (see §13), escalation protocol, data integrity rules. The agent MUST know what it can and cannot do.
4. **Agent Protocol**: Startup checklist, session tracking rules, closure requirements. The agent MUST know how to begin and end work.
5. **Quickstart**: A concise startup sequence for cold-start orientation. MUST enable a fresh agent to begin useful work within one session. Include both agent and human quickstarts:
**Agent Quickstart** (5 steps):
1. Read CLAUDE.md — understand project structure, safety rules, persona
2. Read STATE.md — understand current phase, blockers, recent decisions
3. Check `how/sessions/active/` — identify any conflicting sessions
4. Check `who/coordination/` — read urgent cross-agent notes
5. Create session file in `how/sessions/active/` and begin work
**Human Quickstart** (4 steps):
1. Read README.md — understand what this project is and how to navigate
2. Read MANIFEST.md — understand architecture and entry points
3. Browse the triad (`what/`, `how/`, `who/`) — explore the knowledge structure
4. Open STATE.md — see current operational status and next steps
**Optional sections** (add when relevant):
- Domain Knowledge — project-specific context the agent needs
- Working with Content — naming, metadata, linking conventions
- Machine Setup — multi-machine path patterns and tool requirements
- Environment-Specific Rules — sync, IDE, CI/CD integration
**Versioning**: CLAUDE.md SHOULD include a version comment in its header: ``. Major version for structural changes, minor for significant updates. Session history serves as the detailed changelog.
**Persona framework**: When a persona is defined, it MUST include: identity (name, role metaphor, mission), operating style (3-5 behavioral principles), and communication norms (tone, greeting/close patterns). See Appendix A for the full framework and reference implementation.
### 4.3 MANIFEST.md — Project Overview
MANIFEST.md describes what the project IS. It changes infrequently — only when project scope, architecture, or major workstreams change.
**Contents**:
- Project identity and purpose
- Architecture overview
- Key entry points and navigation
- Active missions / major workstreams (stable references, not dynamic status)
### 4.4 STATE.md — Dynamic Operational State
STATE.md captures where the project IS RIGHT NOW. It SHOULD be updated on every session close-out. It MUST be updated when phase, blockers, or priorities change.
**Contents**:
- Current phase / milestone
- Recent decisions (last 3-5)
- Active blockers
- What's working well
- Next steps / recommended priorities
STATE.md enables fast cold-start orientation: a fresh agent reads CLAUDE.md (structure and rules) then STATE.md (current situation) and is ready to work.
### 4.5 AGENTS.md — Per-Directory Agent Guide
Every aDNA instance MUST have a root-level AGENTS.md (listed in §4.1). Beyond root, every directory where agents operate SHOULD have an AGENTS.md file. AGENTS.md is agent-facing: optimized for machine consumption with structured, scannable content.
**Lightweight core** (every AGENTS.md):
- Purpose — what this directory contains and why
- Key files — important files with brief descriptions
- Patterns — naming, structure, or workflow conventions specific to this directory
**Enrichment layers** (add as the directory matures):
- Quick reference table
- Modification guide — how to add or change content
- Dependencies — what this directory relies on
- Testing / validation notes
- Current state / recent changes
- Troubleshooting
AGENTS.md files grow through progressive enrichment: start lightweight, add detail when agents or humans repeatedly need information that is not yet documented.
### 4.6 README.md — Per-Directory Human Guide
README.md is human-facing: optimized for browsing in GitHub, an IDE, or a knowledge-base tool. It complements AGENTS.md by providing navigation context for humans.
Every aDNA instance MUST have a root README.md. Subdirectory README.md files are OPTIONAL — create them when human navigation would benefit.
---
## 5. Directory Structure
> **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**:
| Directory | Purpose |
|-----------|---------|
| `context/` | Agent context library — synthesized knowledge agents load before domain work |
**Recommended subdirectories**:
| Directory | Purpose |
|-----------|---------|
| `decisions/` | Architecture Decision Records (ADRs) — significant decisions and their rationale |
**Optional subdirectories** (add based on project domain):
| Directory | Purpose |
|-----------|---------|
| `reference/` | Bounded exception for code-adjacent reference material (see §19.5) |
| `inventory/` | Installed/configured state — vaults, system, memberships. Base WHAT type since v2.3 (ADR-035); markdown + paired `.yaml` companion. |
| `{domain}/` | Project-specific knowledge: `models/`, `hardware/`, `datasets/`, `specs/`, etc. |
**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:
```yaml
# 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:
```mermaid
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**:
| Directory | Purpose |
|-----------|---------|
| `coordination/` | Cross-agent notes — handoffs, urgency signals, ephemeral coordination |
| `governance/` | Team roles, decision authority, policies, escalation paths |
**Optional subdirectories** (add based on organizational needs):
| Directory | Purpose |
|-----------|---------|
| `identity/` | Stable identity records validated against external reality — node / network / deployment (hostname, operator, persistent UUID, peer-id). Base WHO type since v2.3 (ADR-035); markdown + paired `.yaml` companion. |
| `{domain}/` | Project-specific organization: `customers/`, `partners/`, `contacts/`, `communications/`, `roadmap/` |
### 5.3 how/ — Operations Layer
how/ contains everything about HOW the project works.
**Required subdirectories**:
| Directory | Purpose |
|-----------|---------|
| `missions/` | Missions — objective decomposition, dependencies, claiming protocol |
| `sessions/` | Session tracking — execution records with SITREP close-outs |
| `templates/` | Reusable templates for all aDNA file types |
**Recommended subdirectories**:
| Directory | Purpose |
|-----------|---------|
| `backlog/` | Ideation and improvement tracking (see §19.2) |
**Optional subdirectories**:
| Directory | Purpose |
|-----------|---------|
| `pipelines/` | Content-as-code workflows (see §14) |
| `tasks/` | Granular task tracking |
| `skills/` | Reusable agent procedures (see §19.3) |
| `processes/` | Human-readable workflow documentation |
| `deliverables/` | Output artifacts |
| `federation/` | Consumer federation wrappers — one `/` per federated software-element/service graph (v2.5, ADR-045) |
### 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:
```yaml
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.
---
## 6. Naming Conventions
> **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:
| Prefix | Content |
|--------|---------|
| `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.
---
## 7. Frontmatter System
> **Scan**: Required base fields (`type`, `status`, `created`, `updated`, `last_edited_by`, `tags`), tag conventions, priority field, type-specific extensions.
*Decisions: C4, D18, D20*
### 7.1 Scope
YAML frontmatter MUST be present on all aDNA content files — files inside the triad (`what/`, `how/`, `who/` or `.agentic/what/`, etc.) and root governance files.
Project content files (source code, external documentation) outside the triad are exempt from frontmatter requirements.
### 7.2 Required Base Fields
Every aDNA content file MUST include these frontmatter fields:
```yaml
---
type:
status:
created: YYYY-MM-DD
updated: YYYY-MM-DD
last_edited_by: agent_ |
tags: []
---
```
| Field | Purpose |
|-------|---------|
| `type` | Entity classification (e.g., `session`, `mission`, `customer`, `context_research`) |
| `status` | Lifecycle state (e.g., `active`, `completed`, `draft`, `abandoned`) — entity-specific values |
| `created` | Date of file creation |
| `updated` | Date of last modification — critical for collision prevention |
| `last_edited_by` | Attribution — who or what last modified this file |
| `tags` | Categorization array for filtering and discovery |
**Per-class profile** (v2.5, ADR-044): the six base fields are required for content and session entities. **`status` is optional for `type: directory_index` and `type: coordination`** — an index or correspondence record has no lifecycle state, and their canonical templates omit it. The other five base fields remain required for all classes.
### 7.3 Tag Conventions
Tags MUST use lowercase with underscores (e.g., `mission`, `context_research`).
Every aDNA content file MUST have at least one tag (the type tag is sufficient).
No formal tag registry is prescribed. Projects SHOULD document their tag conventions in AGENTS.md files when the tag set exceeds a dozen unique tags.
### 7.4 Priority Field
Content items that need prioritization (tasks, backlog ideas, customers) MAY include a `priority` field using a simple numeric scale: `0` (highest) through `N` (lowest).
Rule/guardrail conflict resolution is a separate concern. Projects that need rule precedence SHOULD define their own mechanism in CLAUDE.md or governance files.
### 7.5 Type-Specific Fields
Templates (§12) define additional frontmatter fields per content type. For example, a session template adds `session_id`, `plan_id` (legacy field name), `tier`; a customer template adds `segment`, `deal_stage`, `contacts`.
Frontmatter is the integration layer between human tools (Dataview queries, IDE search) and agent queries. Consistent frontmatter enables consistent querying across any tool.
### 7.6 Frontmatter Extension Policy
Instance-specific frontmatter fields MAY be added to any entity type. The following rules govern extensions:
1. **Custom fields** MAY be added freely to any content file's frontmatter
2. Custom fields SHOULD use a project-specific prefix (e.g., `bio_target_class`, `crm_deal_stage`) when the field name could conflict with future standard fields
3. Standard fields (those defined in §7.2 and per-type templates) MUST NOT be repurposed to carry different semantics
4. Migration tools MUST preserve custom fields — standard version upgrades MUST NOT strip unrecognized frontmatter fields
5. Projects SHOULD document their custom fields in the relevant `AGENTS.md` or template files
### 7.7 Decision-Record Ratification Discipline
Decision records (ADRs, `what/decisions/`) carry a lifecycle `status` whose advancement beyond `proposed` is a **human** act. Effective v2.5 (ADR-046, folding the discipline installed after an agent thread self-marked an ADR `accepted` without an operator gate):
1. **Agents author; operators ratify.** An agent MAY fully author an ADR — context, decision, consequences, alternatives, references — and MAY set or keep `status: proposed` (or `draft`). An agent MUST NOT set `accepted`, `ratified`, or `rejected`; those transitions require an operator gate.
2. **Ratification record.** Any ADR moving beyond `proposed` MUST carry a structured ratification block with all four fields present and non-empty:
- **Ratifier** — the named human operator/authority. An agent or persona may be named only as author/steward, never as ratifier.
- **Gate / reference** — a verifiable pointer to the discrete ratification event: the gate file and/or its output record, the ratifying session id, and/or the ratifying commit.
- **Ratification date** — distinct from the authored/created date.
- **Scope of authority** — exactly what the ratification authorizes, plus any pending co-signs that keep seams non-operative.
3. **Retroactivity.** ADRs accepted before v2.5 SHOULD be backfilled with ratification blocks; a pre-v2.5 accepted ADR without one is NOT thereby non-conformant. *(This clause is what keeps the v2.5 cut a minor version under §15.4.)*
4. **Batch ceremonies.** An N-ADRs-at-once ratification ceremony MAY substitute a single ceremony record for per-ADR gate references, provided each covered ADR's block points to it.
5. **Validation.** Conformance tooling SHOULD check structure only — the four fields present and non-empty — never the truth of the gate; truth is the operator's, at the gate. Recommended rollout: warn first, promote to fail after a backfill pass.
6. **Exemption.** Lifecycle-neutral back-references (e.g., adding `superseded_by` once the superseding ADR is itself ratified) are exempt from rule 1.
---
## 8. Session Model
> **Scan**: Bounded units of agent work — lifecycle (create → execute → close → archive), session tiers, SITREP close-out, next-session prompt, the 75% rule.
*Decisions: D3, D4, D5*
### 8.1 Session Lifecycle
A session is a bounded unit of agent work. Every session follows this lifecycle:
1. **Create**: Write a session file in `how/sessions/active/`
2. **Execute**: Perform work, logging activity
3. **Close**: Write SITREP + next-session prompt
4. **Archive**: Set `status: completed`, move to `how/sessions/history/YYYY-MM/`
A session file MUST be created before an agent modifies any other project files. This is the audit trail.
```mermaid
stateDiagram-v2
[*] --> Create: Agent starts work
Create --> Active: Session file written
Active --> Active: Work + log activity
Active --> Close: SITREP written
Close --> Archive: Move to history/YYYY-MM/
Archive --> [*]
state Active {
[*] --> Working
Working --> Working: Modify files Update frontmatter
}
```
### 8.2 Session ID Format
Session IDs MUST use the timestamped format:
```
session_{user}_{YYYYMMDD}_{HHMMSS}_{descriptor}
```
Example: `session_{username}_20260211_120000_gap_analysis`
Timestamped IDs are machine-sortable, collision-free across agents, and self-documenting. The descriptor SHOULD be a brief lowercase-underscore slug describing the session's purpose.
### 8.3 Session Tiers
| Tier | When | Requirements |
|------|------|-------------|
| **Tier 1** (default) | Normal content work | Session file with intent, activity log, SITREP close-out |
| **Tier 2** | Shared config edits (governance files, plugin configs) | Tier 1 requirements + scope declaration + conflict scan + heartbeat |
Tier 1 is a lightweight audit trail. Tier 2 adds coordination safeguards for edits that affect shared infrastructure.
Sessions MAY include a **Technical Readiness Review (TRR)** quality gate before close-out — a structured check that deliverables meet acceptance criteria. TRR is particularly useful for code-generation sessions or sessions producing artifacts that downstream tasks depend on.
### 8.4 SITREP Close-Out
Every session MUST end with a SITREP:
```markdown
## SITREP
**Completed**: [what was finished]
**In progress**: [what was started but not finished, with handoff notes]
**Next up**: [recommended next actions]
**Blockers**: [anything preventing progress]
**Files touched**: [created, modified, moved]
```
### 8.5 Next-Session Prompt
Every session MUST include a next-session prompt after the SITREP:
```markdown
## Next Session Prompt
[Self-contained paragraph that a fresh agent can read to continue this work.
Include: what was accomplished, what remains, key context, recommended approach.]
```
The next-session prompt ensures continuity. A fresh agent reading this prompt and STATE.md SHOULD be able to continue the work without needing to read the full session history.
### 8.6 STATE.md Update
STATE.md SHOULD be updated on every session close. It MUST be updated when the current phase, blockers, or priorities change.
### 8.7 The 75% Rule
Agents MUST scope each session to use no more than approximately 75% of the context window. The remaining 25% is reserved for thinking, debugging, and course correction.
If a task requires more than 75% of the context window, the agent MUST split the work across sessions, checkpointing progress in the session close-out.
No other session sizing prescriptions are universal. Time, task count, and line-count guidelines are project-specific — different work paradigms (code generation, knowledge synthesis, CRM maintenance) have different natural session sizes.
---
## 9. Mission System
> **Scan**: Multi-session work decomposition — objectives, acceptance criteria, stages, claiming protocol, handoff between agents.
*Decisions: D12, D16, D17*
### 9.1 Mission Structure
Missions live in `how/missions/`. A mission decomposes work that spans multiple sessions into trackable objectives.
**Single-file missions** (small scope):
```
how/missions/mission_simple_task.md
```
**Subdirectory missions** (large scope with deliverables):
```
how/missions/mission_complex_project/
├── mission_complex_project.md # Master mission
├── deliverable_a.md # Phase/deliverable files
└── deliverable_b.md
```
The mission file MUST include:
- **Objectives**: What the mission achieves
- **Acceptance criteria**: How you know it is done
- **Constraints**: What limits apply (time, scope, dependencies)
- **Objective list**: Individual objectives with dependencies and status
- **Status tracking**: Per-objective status (pending, in_progress, completed, blocked)
### 9.2 Mission Stages
Missions MAY define stage-based subdirectories for multi-phase work:
```
how/missions/{mission_slug}/
├── mission_{slug}.md
├── 00_research/
├── 01_requirements/
├── 02_design/
└── 03_implementation/
```
Stage names and count are mission-specific. The convention is: numbered prefix for ordering, descriptive name for clarity.
### 9.3 Mission Handoff
Agents claim mission objectives by session. A session file's `plan_id` and `task` frontmatter fields (legacy names, retained for compatibility) link it to the mission. When an objective spans multiple sessions, each session's SITREP provides the handoff. Agents MUST NOT claim objectives already in progress by another active session.
---
## 10. Context Library
> **Scan**: `what/context/` organization — topic structure, context subtypes (research, guide, core), token budget awareness and the 75% rule.
*Decisions: D8*
### 10.1 Location and Structure
The context library lives in `what/context/`. It is the single location for all agent context — synthesized knowledge that agents load before domain work.
```
what/context/
├── AGENTS.md # Library protocol, topic index, token budgets
├── {topic}/
│ ├── AGENTS.md # Topic overview, subtopic index
│ ├── subtopic_a.md
│ └── subtopic_b.md
└── {topic}/
└── ...
```
### 10.2 Context Subtypes
Context files use the `type` frontmatter field to distinguish content subtypes:
| Subtype | Purpose | Pattern |
|---------|---------|---------|
| `context_research` | Synthesized domain knowledge from external sources | Dense, citational, comprehensive |
| `context_guide` | Prescriptive component or tool guides | Step-by-step, actionable, reference-oriented |
| `context_core` | Foundational project definitions (conventions, guardrails, stack) | Concise, authoritative, rarely changing |
All subtypes coexist in `what/context/` organized by topic. The subtype informs how agents use the content, not where it lives.
### 10.3 Token Budget Awareness
The context library AGENTS.md SHOULD include token estimates per topic in a scannable format:
```markdown
| Topic | ~Tokens | Subtopics |
|-------|---------|-----------|
| ancient_dna | ~8,000 | extraction, sequencing, analysis |
| compute_infra | ~5,000 | gpu_clusters, edge_devices |
```
Agents MUST read the topic index first and load only the subtopics needed for the current task. Loading the entire context library into a single session is wasteful and violates the 75% rule (§8.7).
---
## 11. Coordination Protocol
> **Scan**: `who/coordination/` for cross-agent communication — urgency levels (urgent/info/fyi), ephemeral notes, required contents.
*Decisions: D9*
### 11.1 Cross-Agent Coordination
Cross-agent notes live in `who/coordination/`. This is the single location for agent-to-agent communication.
Coordination notes are **ephemeral by design**: created when needed, consumed by the target agent, and archived when resolved.
### 11.2 Urgency Levels
| Level | Meaning | When to Read |
|-------|---------|-------------|
| `urgent` | Immediate action needed | Read before any other work |
| `info` | Important context | Read during startup checklist |
| `fyi` | Non-blocking background information | Read when convenient |
### 11.3 Coordination Note Contents
A coordination note MUST include:
- **Who** created it and who it targets
- **What** the coordination concern is
- **When** it was created and when it expires
- **Action needed** — what the target agent should do
Agents MUST check `who/coordination/` during every session startup.
---
## 12. Template System
> **Scan**: Graduated template sets (starter/standard/full), `template_{type}.md` naming, template index recommendation.
*Decisions: D11*
### 12.1 Graduated Template Sets
Templates live in `how/templates/`. Projects grow their template sets:
**Starter set** (every aDNA instance MUST include):
| Template | Purpose |
|----------|---------|
| `template_session.md` | Session file with SITREP and next-session prompt sections |
| `template_mission.md` | Mission with objectives, acceptance criteria, objective list |
| `template_context.md` | Context library file with topic structure and token estimate |
**Standard set** (SHOULD include for active multi-agent projects):
| Template | Purpose |
|----------|---------|
| `template_coordination.md` | Cross-agent coordination note |
| `template_backlog.md` | Backlog idea with priority, effort, status |
| `template_adr.md` | Architecture Decision Record |
**Full set** (MAY include per project domain):
Additional templates for domain-specific content types (customer, partner, model, dataset, etc.).
### 12.2 Template Conventions
Templates MUST follow the naming pattern `template_{type}.md`.
Templates MUST include frontmatter with all required base fields (§7.2) plus type-specific fields pre-populated.
A template index (e.g., `template_library.md` in `how/templates/`) is RECOMMENDED for projects with 5 or more templates.
---
## 13. Collision Prevention
> **Scan**: Three tiers — universal (frontmatter attribution, read-before-write), sync (file safety tiers, archive-don't-rename), multi-agent (coordination notes, scope declarations).
*Decisions: D7*
### 13.1 Overview
Collision prevention protects against data loss when multiple agents or humans modify the same files. The system is tiered — projects adopt the tiers they need.
```mermaid
flowchart TB
T1["Tier 1 — Universal Every aDNA instance"]
T2["Tier 2 — Sync Environments Cloud storage, team sync"]
T3["Tier 3 — Multi-Agent Concurrent agents"]
T1 --> A1["Frontmatter attribution"]
T1 --> A2["Read-before-write"]
T1 --> A3["New-file safety"]
T1 --> A4["No harness-injected context"]
T2 --> B1["File safety tiers"]
T2 --> B2["Archive-don't-rename"]
T2 --> B3["One config at a time"]
T3 --> C1["Coordination notes"]
T3 --> C2["Scope declarations"]
T3 --> C3["Update-field check"]
T1 -.->|extends| T2
T2 -.->|extends| T3
style T1 fill:#22c55e,color:#fff
style T2 fill:#eab308,color:#000
style T3 fill:#ef4444,color:#fff
```
### 13.2 Tier 1 — Universal
Every aDNA instance MUST implement Tier 1:
1. **Frontmatter attribution**: Every file modification MUST update `last_edited_by` and `updated` in frontmatter.
2. **Read-before-write**: Agents MUST read current file content immediately before writing. Never rely on cached reads.
3. **New-file safety**: Creating a new file has no collision risk. New files are always safe.
4. **No harness-injected context**: Governance files (`CLAUDE.md`/`STATE.md`/`AGENTS.md`) MUST NOT carry committed **harness context boundaries** — the `# userEmail` and `# currentDate (Today's date is …)` lines an agent harness injects into a running session. They are session context, not governance: once committed they are stale and information-free (the email lives in the credential broker; the date is a frozen snapshot). Strip them before committing; a session that commits a governance file MUST drop any injected tail. (ADR-042.)
### 13.3 Tier 2 — Sync Environments
Projects using file sync (cloud storage, team sync tools) SHOULD additionally implement:
1. **Safety tiers**: Classify files as Safe (content — low collision risk), Shared Config (governance, plugin configs — medium risk), or Volatile (auto-generated files like `workspace.json` — do not attempt to maintain).
2. **Archive-don't-rename**: Move files to `archive/` instead of renaming. Sync systems handle renames poorly.
3. **One config at a time**: Edit one shared config file, verify the write, then move to the next.
### 13.4 Tier 3 — Multi-Agent
Projects with multiple agents operating simultaneously SHOULD additionally implement:
1. **Coordination notes**: Use `who/coordination/` (§11) for strategic cross-agent communication.
2. **Session scope declarations**: Tier 2 sessions declare which files/directories they will modify.
3. **Update-field check**: Before modifying a file where `updated` is today and `last_edited_by` is not you, confirm with the user before overwriting.
---
## 14. Content-as-Code Pipelines
> **Scan**: Folder-based workflows where a file's directory location IS its processing state — pipeline structure, stage AGENTS.md, pipeline index.
*Decisions: D14*
### 14.1 Paradigm
Content-as-code is a universal paradigm for folder-based workflows: a file's directory location IS its processing state. Moving a file between stage directories advances it through the workflow.
This paradigm applies wherever content flows through defined stages — research ingestion, document review, approval workflows, deployment pipelines.
```mermaid
stateDiagram-v2
direction LR
[*] --> inbox: New content
inbox --> processing: Agent picks up
processing --> review: Processing complete
review --> done: Approved
review --> processing: Revision needed
done --> [*]
note right of inbox: AGENTS.md defines acceptance criteria
note right of processing: AGENTS.md defines processing steps
note right of review: AGENTS.md defines review checklist
```
### 14.2 Pipeline Structure
Pipelines live in `how/pipelines/{pipeline_name}/`:
```
how/pipelines/{pipeline_name}/
├── AGENTS.md # Pipeline overview, stage transitions
├── inbox/ # Stage 1
│ └── AGENTS.md # Processing instructions for this stage
├── processing/ # Stage 2
│ └── AGENTS.md
├── review/ # Stage 3
│ └── AGENTS.md
└── done/ # Stage 4
└── AGENTS.md
```
Each stage folder MUST have an AGENTS.md with processing instructions specific to that stage.
Stage names and count are pipeline-specific. The file's location is its state — no separate status tracking is needed.
### 14.3 Pipeline Index
The `how/pipelines/` directory SHOULD have an AGENTS.md documenting all pipelines, their purposes, and their stage flows.
---
## 15. Archive & Versioning
> **Scan**: Archive patterns for sync vs. git environments, retention policy, CLAUDE.md version tracking convention.
*Decisions: C9, C10*
### 15.1 Archive Pattern
The archive pattern varies by environment:
**Sync environments** (cloud storage, team sync tools):
- Archive directories within content folders (e.g., `how/backlog/archive/`)
- Session history uses `how/sessions/history/YYYY-MM/`
- Archive-don't-rename rule: move to `archive/` instead of renaming files
- Project-level `archive/` within the nearest triad directory for vault-level archival
**Git repositories**:
- Git history serves as the primary archive
- `archive/` subdirectories for visibly-deprecated items (documents users should see are retired)
- Session history follows the same `YYYY-MM/` pattern regardless of environment
### 15.2 Retention
Session history SHOULD NOT be auto-deleted. Manual cleanup after 6 months is acceptable if storage is a concern.
### 15.3 Versioning
aDNA instances track their own version via a comment in CLAUDE.md: ``.
Major version increments indicate structural changes. Minor version increments indicate significant content updates. Session history serves as the detailed changelog — no formal CHANGELOG.md is required.
### 15.4 Standard Versioning & Backwards Compatibility
The aDNA standard uses two versioning tracks:
- **Standard version** (this document, `adna_standard.md`): Governs the normative specification — triad architecture, required files, conformance levels, naming conventions. Follows semantic versioning: `vMajor.Minor`.
- **Governance version** (`CLAUDE.md` `version` field, `CHANGELOG.md`): Governs the operational implementation — protocols, templates, skills, tooling. Follows `Major.Minor` versioning.
**Backwards compatibility promise**:
- Standard **minor** versions (e.g., v2.0 → v2.1) MUST NOT invalidate conformant instances. An instance conformant to aDNA v2.0 MUST remain conformant to aDNA v2.1.
- Standard **major** versions (e.g., v2.x → v3.0) MAY introduce breaking changes. When they do, migration guidance MUST be provided.
- Governance version changes are operational and do not affect standard conformance.
**Version-cut checklist** (v2.5, ADR-046 — the footer-lag anti-recurrence rule): on every version bump, the document's four version-bearing surfaces MUST agree before the cut commits — (1) the frontmatter `title`, (2) the frontmatter `updated` date, (3) a new changelog comment line in the header block, and (4) the *End of …* footer line. A cut that leaves any of the four stale is incomplete. *(This rule exists because the footer lagged the title across multiple historical bumps — most recently shipping "v2.3" inside the published v2.4 document.)*
---
## 16. Tool Integration Tiers
> **Scan**: Three tiers — core standard (Tier 1, universal), frontmatter querying (Tier 2, any YAML reader), environment-specific (Tier 3, IDE/plugin). Aggregation points.
*Decisions: C13, D22*
### 16.1 Three-Tier Model
| Tier | Scope | Examples | Universal? |
|------|-------|----------|-----------|
| **Tier 1** | Core standard | YAML frontmatter, markdown, directory structure, naming conventions | Yes — works with any tool |
| **Tier 2** | Frontmatter querying | Dataview, custom scripts, CI/CD that reads frontmatter | Recommended — any tool that parses YAML |
| **Tier 3** | Environment-specific | IDE extensions, knowledge-base plugins, graph view, canvas | No — tool-specific |
Everything in this standard is Tier 1 unless noted otherwise. Tier 1 features work with any tool that can read files and directories.
```mermaid
flowchart TB
subgraph T1["Tier 1 — Core Standard (Universal)"]
F1["YAML frontmatter"]
F2["Markdown files"]
F3["Directory structure"]
F4["Naming conventions"]
end
subgraph T2["Tier 2 — Frontmatter Querying"]
F5["Dataview queries"]
F6["Shell scripts"]
F7["CI/CD pipelines"]
end
subgraph T3["Tier 3 — Environment-Specific"]
F8["Obsidian plugins"]
F9["IDE extensions"]
F10["Graph / canvas views"]
end
T1 -->|"any YAML reader"| T2
T2 -->|"specific tools"| T3
style T1 fill:#22c55e,color:#fff
style T2 fill:#3b82f6,color:#fff
style T3 fill:#8b5cf6,color:#fff
```
### 16.2 Aggregation Points
The following cross-directory views are useful in any aDNA instance. Their implementation is Tier 2/3 (tool-specific):
| Aggregation Point | Aggregates | Purpose |
|-------------------|-----------|---------|
| Active missions overview | `how/missions/` | All missions with current status |
| Context index | `what/context/` | All topics with token budgets |
| Session history | `how/sessions/history/` | Recent sessions with outcomes |
| Coordination status | `who/coordination/` | Active cross-agent notes |
Implementation examples: Dataview queries, shell scripts that parse frontmatter, CI/CD dashboard panels. Any tool that can read YAML frontmatter can implement these views.
---
## 17. Error & Recovery Protocol
> **Scan**: Three-tier response — data integrity threat (STOP + escalate), state inconsistency (fix + log), process issue (workaround + backlog).
*Decisions: D24*
### 17.1 Tiered Response
| Severity | Trigger | Response | Recovery |
|----------|---------|----------|----------|
| **Tier 1 — Data integrity threat** | Corrupt file, data loss, conflicting writes destroying content | Stop all writes immediately. Document the issue. Do NOT attempt automated repair. Escalate to human with `#needs-human` tag. | Human-guided only |
| **Tier 2 — State inconsistency** | Stale STATE.md, broken cross-references, missing frontmatter | Attempt recovery: re-read files, reconcile state, add missing fields. Log the issue and recovery action in session file. Continue work. | Agent-recoverable with documentation |
| **Tier 3 — Process issue** | Template not found, naming violation, ambiguous pipeline stage | Note the issue in session file. Work around it. Create a backlog idea for improvement. | Work around, improve later |
```mermaid
flowchart LR
E["Error detected"] --> S1{"Data at risk?"}
S1 -->|Yes| T1["Tier 1: STOP Escalate to human"]
S1 -->|No| S2{"State inconsistent?"}
S2 -->|Yes| T2["Tier 2: Fix + log Continue work"]
S2 -->|No| T3["Tier 3: Note + workaround Backlog idea"]
style T1 fill:#ef4444,color:#fff
style T2 fill:#eab308,color:#000
style T3 fill:#22c55e,color:#fff
```
### 17.2 Escalation
Agents MUST log blockers with the `#needs-human` tag when:
- Data integrity is at risk (Tier 1 errors)
- A decision exceeds the agent's authority
- Ambiguous scope could lead to destructive actions
Agents MUST NOT proceed with destructive or irreversible actions when uncertain. When in doubt, stop and ask.
---
## 18. Success Criteria
> **Scan**: Three levels — minimum viable (cold start, handoff, integrity), recommended (fork, scale, consistency), aspirational (network, collision safety, dual-audience).
*Decisions: D21*
```mermaid
flowchart TB
subgraph MIN["Minimum Viable (MUST)"]
M1["Cold Start"]
M2["Handoff"]
M3["Integrity"]
end
subgraph REC["Recommended (SHOULD)"]
R1["Fork"]
R2["Scale"]
R3["Consistency"]
end
subgraph ASP["Aspirational"]
A1["Network"]
A2["Collision Safety"]
A3["Dual-Audience"]
end
MIN -->|mature| REC
REC -->|excellent| ASP
style MIN fill:#22c55e,color:#fff
style REC fill:#3b82f6,color:#fff
style ASP fill:#8b5cf6,color:#fff
```
### 18.1 Minimum Viable (every aDNA MUST pass)
1. **Cold Start**: A fresh agent reads CLAUDE.md, then STATE.md (if present), and begins useful work within one session. No prior project knowledge is required.
2. **Handoff**: Agent A closes a session with SITREP + next-session prompt. Agent B reads the close-out and STATE.md and continues the work seamlessly.
3. **Integrity**: No data corruption or silent overwrites during multi-agent operation with collision prevention active.
### 18.2 Recommended (mature aDNA SHOULD pass)
4. **Fork**: The aDNA structure can be copied to a new project and adapted with only CLAUDE.md and domain content changes.
5. **Scale**: The aDNA supports 10+ missions, 50+ sessions, and 100+ content files without navigational degradation.
6. **Consistency**: Both deployment forms (bare and embedded) feel like the same system to agents and humans.
### 18.3 Aspirational (excellent aDNA)
7. **Network**: Multiple aDNA instances can discover and reference each other via documented patterns.
8. **Collision Safety**: Multi-agent concurrent operation produces no data loss even under heavy write contention.
9. **Dual-Audience**: Both humans (IDE, GitHub, knowledge-base tools) and agents find the content navigable and useful.
---
## 19. Optional Extensions
> **Scan**: Six opt-in subsystems — machine registry, backlog, skill files, testing/CI awareness, reference code, ADRs. Adopt based on need.
The following patterns are available but not required. Projects adopt them based on need.
### 19.1 Machine Registry
*Decision: D10*
For projects running on multiple machines or sync environments where path patterns vary.
**Location**: `what/hardware/machines/` or a similar what/ subfolder.
**Per-machine file contents**: hostname, user, OS, path patterns, installed tools, capabilities.
RECOMMENDED for sync-based environments (cloud storage, team sync tools) where file paths differ across machines. OPTIONAL for git repositories where environment variables handle path differences.
### 19.2 Backlog System
*Decision: D13*
Durable ideation and improvement tracking.
**Location**: `how/backlog/`
**Lifecycle**: idea → triage (priority/effort assessment) → graduation to `how/missions/` or archive.
**Frontmatter**: `type: idea`, `category`, `priority`, `effort`, `status`, `proposed_by`.
Agents SHOULD scan `how/backlog/` during session startup for ideas relevant to the current work. New ideas discovered during work SHOULD be captured as backlog files.
### 19.3 Skill Files
*Decision: D15*
Reusable agent procedures — step-by-step instructions agents can follow autonomously.
**Location**: `how/skills/skill_{name}.md`
**Sections**: purpose, prerequisites, steps, verification, rollback, notes.
Skills are distinct from processes: skills are agent-executable (precise steps, verification checks); processes are human-readable (guidelines, decision trees).
### 19.4 Testing/CI Awareness
*Decision: D23*
aDNA does not prescribe test frameworks or CI/CD configurations — these belong to the project content layer. However, agents SHOULD be aware of test status.
**Awareness pattern**:
- CLAUDE.md includes an optional section on testing: where to check, how to run, what signals mean
- AGENTS.md for code directories includes testing guidance as an enrichment layer
- STATE.md reports test status when relevant (pass/fail, coverage, regressions)
- CI/CD configuration lives in project content (`.github/`, `Makefile`, `pyproject.toml`, etc.)
### 19.5 Reference Code
*Decision: C11*
Bounded exception for code-adjacent reference material inside the aDNA structure.
**Location**: `what/reference/`
**Rules**:
- Executable code MUST live in `what/reference/` or in the project content layer — nowhere else in the triad
- what/reference/ MUST be bounded — no unbounded growth
- Entries SHOULD link to source implementations rather than duplicating code
- Documentation-only projects skip this entirely
### 19.6 Architecture Decision Records (ADRs)
*Decision: C12*
Lightweight records of significant project decisions.
**Location**: `what/decisions/`
**Template sections**: context, decision, consequences.
ADRs are knowledge artifacts — decisions outlive the process that produced them. A 2-year-old ADR is reference knowledge, not an active operation. This is why they live in what/, not how/.
---
## 20. Appendices
> **Scan**: Persona framework (App A), aggregation points (App B), deferred topics (App C), decision traceability matrix (App D — 40 decisions mapped to spec sections).
### Appendix A: Persona Framework
*Decision: D6*
A persona is OPTIONAL but structured when present. The persona framework defines what a persona includes and why it matters — consistency, predictability, and character continuity across sessions.
#### A.1 Framework Structure
| Section | Contents | Purpose |
|---------|----------|---------|
| **Identity** | Name, role metaphor, mission statement | Establish who the agent is in this project |
| **Operating Style** | 3-5 behavioral principles | Define predictable working patterns |
| **Communication Norms** | Tone, formatting, greeting/close patterns | Ensure consistent interaction style |
| **Domain Awareness** | What the persona should know about the project domain | Ground the agent in project context |
#### A.2 Reference Implementation
The following is a reference persona. Projects MAY adopt it directly or use the framework to create their own.
**Identity**: Chief of staff to the operation — a role inspired by the military chief of staff archetype, who turns strategic vision into operational reality.
**Operating Style**:
1. Orient first, act second — assess the operational picture before diving into any task
2. Think in lines of effort — maintain awareness across parallel workstreams
3. Be direct and precise — clear status updates, early risk flags, recommendations with rationale
4. Coordinate, don't just execute — coherence across the full operation matters more than speed on any single task
**Communication Norms**: Direct, no filler. Structured updates (SITREP format). Greets with operational state summary on planning sessions. Proceeds directly on execution sessions.
**Domain Awareness**: Defined per project in CLAUDE.md.
### Appendix B: Aggregation Points
*Decision: D22*
Standard aggregation points for cross-directory views. Implementation is tool-specific (Tier 2/3).
| Point | Source | Query Pattern |
|-------|--------|--------------|
| **Active missions** | `how/missions/` | All files where `type: mission` and `status: active` |
| **Context index** | `what/context/` | All topic directories with their AGENTS.md token estimates |
| **Recent sessions** | `how/sessions/history/` | Last 10 session files, sorted by `updated` descending |
| **Open coordination** | `who/coordination/` | All files where `status: open` or `status: urgent` |
| **Backlog overview** | `how/backlog/` | All files where `type: idea` and `status: active`, sorted by `priority` |
**Knowledge-base implementation**: Dataview queries in bridge pages (e.g., `how/missions.md`, `how/context_library.md`).
**Script implementation**: Any tool that parses YAML frontmatter from markdown files can produce these views.
### Appendix C: Deferred Topics
The following topics were identified during the planning arc but deferred from v1.0. They are acknowledged here for future standard revisions. (Retained from v1.0; no new deferrals in v2.0.)
| Gap | Topic | Disposition |
|-----|-------|-------------|
| G2 | **Multi-model / model-agnostic design** | "CLAUDE.md" is a convention name — projects using other models use the same structure. The persona framework (§ App A) is model-agnostic. A future revision MAY define model-neutral naming. |
| G3 | **Documentation generation** | Projects that generate external-facing docs from aDNA content will develop project-specific patterns. No universal standard needed at this time. |
| G7 | **Context staleness detection** | The `updated` field + session cycling naturally address staleness (fresh reads on each session start). Formal staleness detection is Tier 2/3 tooling, not a standard concern. |
| G8 | **Cross-instance aDNA awareness** | Addressed by bridge patterns (informational companion, SHOULD-level guidance). Defines composition patterns (nesting, sibling, monorepo), discovery protocol, scope boundaries, cross-referencing conventions, and agent behavior rules. Addresses §18.3 #7 Network criterion. |
| G10 | **Agent capability declaration** | Most aDNA instances target specific agent capabilities. CLAUDE.md can note capability assumptions. A formal capability schema is deferred pending broader agent ecosystem maturity. |
### Appendix D: Decision Traceability Matrix
This appendix maps every design decision to its location in the standard, ensuring complete coverage.
#### D.1 Structural Decisions (C1-C15)
| ID | Decision | Spec Section(s) |
|----|----------|-----------------|
| C1 | Pattern-appropriate deployment (bare + embedded triad) | §3.2, §3.3, §3.4 |
| C2 | Dual-file: AGENTS.md + README.md everywhere | §4.5, §4.6 |
| C3 | Vault naming + repo exceptions, ALLCAPS governance list | §6.1, §6.2, §6.3, §6.4 |
| C4 | Frontmatter mandatory for aDNA content, optional for project | §7.1, §7.2 |
| C5 | what/ context/ mandatory, rest project-specific | §5.1 |
| C6 | who/ coordination/ + governance/ mandatory | §5.2 |
| C7 | how/ tiered: missions/sessions/templates required, backlog recommended | §5.3 |
| C8 | Seeding guidance via triad principle, not prescriptive table | §3.1 (triad question test) |
| C9 | Git-supplemented archive | §15.1 |
| C10 | Lightweight versioning in CLAUDE.md, sessions as changelog | §15.3 |
| C11 | what/reference/ as bounded exception for code | §19.5 |
| C12 | ADRs in what/decisions/ | §19.6 |
| C13 | Tiered tool integration (Tier 1/2/3) | §16.1 |
| C14 | Ontology artifact: Mermaid (Tier 1) + Canvas (Tier 3) | §5.1 (ontology artifact) |
| C15 | what/ as registry layer | §5.1 (registry pattern) |
#### D.2 Process Decisions (D1-D25)
| ID | Decision | Spec Section(s) |
|----|----------|-----------------|
| D1 | Universal CLAUDE.md template, required + optional sections | §4.2 |
| D2 | Separate MANIFEST.md + STATE.md | §4.3, §4.4 |
| D3 | Session model with environment enrichments | §8.1, §8.2, §8.3 |
| D4 | SITREP + mandatory next-session prompt | §8.4, §8.5 |
| D5 | 75% rule only, no sizing prescriptions | §8.7 |
| D6 | Persona framework with reference implementation | §4.2 (persona), App A |
| D7 | Tiered collision prevention (universal/sync/multi-agent) | §13 |
| D8 | Flexible what/context/ with subtypes | §10 |
| D9 | who/coordination/ only | §11 |
| D10 | Machine registry as optional extension | §19.1 |
| D11 | Graduated template set (Starter/Standard/Full) | §12 |
| D12 | Separated missions + subdirectories | §9 |
| D13 | Backlog recommended, not required | §19.2 |
| D14 | Content-as-code paradigm universal, pipelines optional | §14 |
| D15 | Skill files optional in how/skills/ | §19.3 |
| D16 | Generalized mission stages | §9.2 |
| D17 | Lightweight requirements in missions, full specs as extension | §9.1 (mission contents) |
| D18 | Minimal tag rules, no formal taxonomy | §7.3 |
| D19 | Progressive enrichment for AGENTS.md | §4.5 |
| D20 | Separate content priority (0-N) from rule precedence | §7.4 |
| D21 | Tiered success criteria (minimum/recommended/aspirational) | §18 |
| D22 | Aggregation points identified, implementation tool-specific | §16.2, App B |
| D23 | Testing/CI as project-specific with awareness pattern | §19.4 |
| D24 | Tiered error/recovery protocol | §17 |
| D25 | Quickstart in CLAUDE.md + README.md | §4.2 (quickstart section) |
#### D.3 Gap Dispositions (G1-G12)
| Gap | Topic | Disposition | Location |
|-----|-------|-------------|----------|
| G1 | Testing/CI integration | Addressed by D23 | §19.4 |
| G2 | Multi-model design | Deferred | App C |
| G3 | Documentation generation | Deferred | App C |
| G4 | Versioning/changelog | Addressed by C10 | §15.3 |
| G5 | Team roles/governance | Subsumed into C6 (who/governance/) | §5.2 |
| G6 | Error/recovery protocol | Addressed by D24 | §17 |
| G7 | Context staleness | Deferred (subsumed into D5/D7) | App C |
| G8 | Cross-instance awareness | Addressed by bridge patterns (informational) | App C |
| G9 | Onboarding/bootstrap | Addressed by D25 | §4.2 (quickstart) |
| G10 | Agent capability declaration | Deferred | App C |
| G11 | Ontology schema artifact | Addressed by C14 | §5.1 (ontology artifact) |
| G12 | Object standard integration | Addressed by C15 + execution phase | §5.1 (registry pattern) |
---
*End of aDNA Universal Standard v2.5*
---
## https://adna.network/reference/specification/1-introduction-scope/
# 1. Introduction & Scope — aDNA Specification
> **Scan**: What aDNA is, who it's for, and RFC 2119 normative keywords.
## 1.1 What Is aDNA
aDNA (Agentic DNA) is a standard for organizing project knowledge so that AI agents can orient, operate, and coordinate within any project — alongside humans. It defines a directory structure, governance files, metadata conventions, and operational protocols that together form a project's "knowledge genome."
An aDNA instance is the complete set of governance files, triad directories, and operational infrastructure that implements this standard within a project.
## 1.2 Audience
This standard is written for:
- **Agents** — AI assistants that read, write, and navigate project knowledge
- **Agent operators** — humans who configure and manage agent-augmented projects
- **Project bootstrappers** — anyone starting a new project that will use AI agents
## 1.3 Scope
**In scope**: Project knowledge architecture — how project information is organized, how agents orient and operate, how multiple agents coordinate, and how knowledge persists across sessions.
**Out of scope**: Application source code structure, CI/CD pipeline configuration, deployment infrastructure, and agent model internals. These belong to the project content layer, not to aDNA.
## 1.4 Normative Language
This document uses RFC 2119 keywords:
| Keyword | Meaning |
|---------|---------|
| **MUST** | Absolute requirement |
| **MUST NOT** | Absolute prohibition |
| **SHOULD** | Recommended; may be omitted with good reason |
| **MAY** | Truly optional |
---
---
## https://adna.network/reference/specification/10-context-library/
# 10. Context Library — aDNA Specification
> **Scan**: `what/context/` organization — topic structure, context subtypes (research, guide, core), token budget awareness and the 75% rule.
*Decisions: D8*
## 10.1 Location and Structure
The context library lives in `what/context/`. It is the single location for all agent context — synthesized knowledge that agents load before domain work.
```
what/context/
├── AGENTS.md # Library protocol, topic index, token budgets
├── {topic}/
│ ├── AGENTS.md # Topic overview, subtopic index
│ ├── subtopic_a.md
│ └── subtopic_b.md
└── {topic}/
└── ...
```
## 10.2 Context Subtypes
Context files use the `type` frontmatter field to distinguish content subtypes:
| Subtype | Purpose | Pattern |
|---------|---------|---------|
| `context_research` | Synthesized domain knowledge from external sources | Dense, citational, comprehensive |
| `context_guide` | Prescriptive component or tool guides | Step-by-step, actionable, reference-oriented |
| `context_core` | Foundational project definitions (conventions, guardrails, stack) | Concise, authoritative, rarely changing |
All subtypes coexist in `what/context/` organized by topic. The subtype informs how agents use the content, not where it lives.
## 10.3 Token Budget Awareness
The context library AGENTS.md SHOULD include token estimates per topic in a scannable format:
```markdown
| Topic | ~Tokens | Subtopics |
|-------|---------|-----------|
| ancient_dna | ~8,000 | extraction, sequencing, analysis |
| compute_infra | ~5,000 | gpu_clusters, edge_devices |
```
Agents MUST read the topic index first and load only the subtopics needed for the current task. Loading the entire context library into a single session is wasteful and violates the 75% rule (§8.7).
---
---
## https://adna.network/reference/specification/11-coordination-protocol/
# 11. Coordination Protocol — aDNA Specification
> **Scan**: `who/coordination/` for cross-agent communication — urgency levels (urgent/info/fyi), ephemeral notes, required contents.
*Decisions: D9*
## 11.1 Cross-Agent Coordination
Cross-agent notes live in `who/coordination/`. This is the single location for agent-to-agent communication.
Coordination notes are **ephemeral by design**: created when needed, consumed by the target agent, and archived when resolved.
## 11.2 Urgency Levels
| Level | Meaning | When to Read |
|-------|---------|-------------|
| `urgent` | Immediate action needed | Read before any other work |
| `info` | Important context | Read during startup checklist |
| `fyi` | Non-blocking background information | Read when convenient |
## 11.3 Coordination Note Contents
A coordination note MUST include:
- **Who** created it and who it targets
- **What** the coordination concern is
- **When** it was created and when it expires
- **Action needed** — what the target agent should do
Agents MUST check `who/coordination/` during every session startup.
---
---
## https://adna.network/reference/specification/12-template-system/
# 12. Template System — aDNA Specification
> **Scan**: Graduated template sets (starter/standard/full), `template_{type}.md` naming, template index recommendation.
*Decisions: D11*
## 12.1 Graduated Template Sets
Templates live in `how/templates/`. Projects grow their template sets:
**Starter set** (every aDNA instance MUST include):
| Template | Purpose |
|----------|---------|
| `template_session.md` | Session file with SITREP and next-session prompt sections |
| `template_mission.md` | Mission with objectives, acceptance criteria, objective list |
| `template_context.md` | Context library file with topic structure and token estimate |
**Standard set** (SHOULD include for active multi-agent projects):
| Template | Purpose |
|----------|---------|
| `template_coordination.md` | Cross-agent coordination note |
| `template_backlog.md` | Backlog idea with priority, effort, status |
| `template_adr.md` | Architecture Decision Record |
**Full set** (MAY include per project domain):
Additional templates for domain-specific content types (customer, partner, model, dataset, etc.).
## 12.2 Template Conventions
Templates MUST follow the naming pattern `template_{type}.md`.
Templates MUST include frontmatter with all required base fields (§7.2) plus type-specific fields pre-populated.
A template index (e.g., `template_library.md` in `how/templates/`) is RECOMMENDED for projects with 5 or more templates.
---
---
## https://adna.network/reference/specification/13-collision-prevention/
# 13. Collision Prevention — aDNA Specification
> **Scan**: Three tiers — universal (frontmatter attribution, read-before-write), sync (file safety tiers, archive-don't-rename), multi-agent (coordination notes, scope declarations).
*Decisions: D7*
## 13.1 Overview
Collision prevention protects against data loss when multiple agents or humans modify the same files. The system is tiered — projects adopt the tiers they need.
```mermaid
flowchart TB
T1["Tier 1 — Universal Every aDNA instance"]
T2["Tier 2 — Sync Environments Cloud storage, team sync"]
T3["Tier 3 — Multi-Agent Concurrent agents"]
T1 --> A1["Frontmatter attribution"]
T1 --> A2["Read-before-write"]
T1 --> A3["New-file safety"]
T1 --> A4["No harness-injected context"]
T2 --> B1["File safety tiers"]
T2 --> B2["Archive-don't-rename"]
T2 --> B3["One config at a time"]
T3 --> C1["Coordination notes"]
T3 --> C2["Scope declarations"]
T3 --> C3["Update-field check"]
T1 -.->|extends| T2
T2 -.->|extends| T3
style T1 fill:#22c55e,color:#fff
style T2 fill:#eab308,color:#000
style T3 fill:#ef4444,color:#fff
```
## 13.2 Tier 1 — Universal
Every aDNA instance MUST implement Tier 1:
1. **Frontmatter attribution**: Every file modification MUST update `last_edited_by` and `updated` in frontmatter.
2. **Read-before-write**: Agents MUST read current file content immediately before writing. Never rely on cached reads.
3. **New-file safety**: Creating a new file has no collision risk. New files are always safe.
4. **No harness-injected context**: Governance files (`CLAUDE.md`/`STATE.md`/`AGENTS.md`) MUST NOT carry committed **harness context boundaries** — the `# userEmail` and `# currentDate (Today's date is …)` lines an agent harness injects into a running session. They are session context, not governance: once committed they are stale and information-free (the email lives in the credential broker; the date is a frozen snapshot). Strip them before committing; a session that commits a governance file MUST drop any injected tail. (ADR-042.)
## 13.3 Tier 2 — Sync Environments
Projects using file sync (cloud storage, team sync tools) SHOULD additionally implement:
1. **Safety tiers**: Classify files as Safe (content — low collision risk), Shared Config (governance, plugin configs — medium risk), or Volatile (auto-generated files like `workspace.json` — do not attempt to maintain).
2. **Archive-don't-rename**: Move files to `archive/` instead of renaming. Sync systems handle renames poorly.
3. **One config at a time**: Edit one shared config file, verify the write, then move to the next.
## 13.4 Tier 3 — Multi-Agent
Projects with multiple agents operating simultaneously SHOULD additionally implement:
1. **Coordination notes**: Use `who/coordination/` (§11) for strategic cross-agent communication.
2. **Session scope declarations**: Tier 2 sessions declare which files/directories they will modify.
3. **Update-field check**: Before modifying a file where `updated` is today and `last_edited_by` is not you, confirm with the user before overwriting.
---
---
## https://adna.network/reference/specification/14-content-as-code-pipelines/
# 14. Content-as-Code Pipelines — aDNA Specification
> **Scan**: Folder-based workflows where a file's directory location IS its processing state — pipeline structure, stage AGENTS.md, pipeline index.
*Decisions: D14*
## 14.1 Paradigm
Content-as-code is a universal paradigm for folder-based workflows: a file's directory location IS its processing state. Moving a file between stage directories advances it through the workflow.
This paradigm applies wherever content flows through defined stages — research ingestion, document review, approval workflows, deployment pipelines.
```mermaid
stateDiagram-v2
direction LR
[*] --> inbox: New content
inbox --> processing: Agent picks up
processing --> review: Processing complete
review --> done: Approved
review --> processing: Revision needed
done --> [*]
note right of inbox: AGENTS.md defines acceptance criteria
note right of processing: AGENTS.md defines processing steps
note right of review: AGENTS.md defines review checklist
```
## 14.2 Pipeline Structure
Pipelines live in `how/pipelines/{pipeline_name}/`:
```
how/pipelines/{pipeline_name}/
├── AGENTS.md # Pipeline overview, stage transitions
├── inbox/ # Stage 1
│ └── AGENTS.md # Processing instructions for this stage
├── processing/ # Stage 2
│ └── AGENTS.md
├── review/ # Stage 3
│ └── AGENTS.md
└── done/ # Stage 4
└── AGENTS.md
```
Each stage folder MUST have an AGENTS.md with processing instructions specific to that stage.
Stage names and count are pipeline-specific. The file's location is its state — no separate status tracking is needed.
## 14.3 Pipeline Index
The `how/pipelines/` directory SHOULD have an AGENTS.md documenting all pipelines, their purposes, and their stage flows.
---
---
## https://adna.network/reference/specification/15-archive-versioning/
# 15. Archive & Versioning — aDNA Specification
> **Scan**: Archive patterns for sync vs. git environments, retention policy, CLAUDE.md version tracking convention.
*Decisions: C9, C10*
## 15.1 Archive Pattern
The archive pattern varies by environment:
**Sync environments** (cloud storage, team sync tools):
- Archive directories within content folders (e.g., `how/backlog/archive/`)
- Session history uses `how/sessions/history/YYYY-MM/`
- Archive-don't-rename rule: move to `archive/` instead of renaming files
- Project-level `archive/` within the nearest triad directory for vault-level archival
**Git repositories**:
- Git history serves as the primary archive
- `archive/` subdirectories for visibly-deprecated items (documents users should see are retired)
- Session history follows the same `YYYY-MM/` pattern regardless of environment
## 15.2 Retention
Session history SHOULD NOT be auto-deleted. Manual cleanup after 6 months is acceptable if storage is a concern.
## 15.3 Versioning
aDNA instances track their own version via a comment in CLAUDE.md: ``.
Major version increments indicate structural changes. Minor version increments indicate significant content updates. Session history serves as the detailed changelog — no formal CHANGELOG.md is required.
## 15.4 Standard Versioning & Backwards Compatibility
The aDNA standard uses two versioning tracks:
- **Standard version** (this document, `adna_standard.md`): Governs the normative specification — triad architecture, required files, conformance levels, naming conventions. Follows semantic versioning: `vMajor.Minor`.
- **Governance version** (`CLAUDE.md` `version` field, `CHANGELOG.md`): Governs the operational implementation — protocols, templates, skills, tooling. Follows `Major.Minor` versioning.
**Backwards compatibility promise**:
- Standard **minor** versions (e.g., v2.0 → v2.1) MUST NOT invalidate conformant instances. An instance conformant to aDNA v2.0 MUST remain conformant to aDNA v2.1.
- Standard **major** versions (e.g., v2.x → v3.0) MAY introduce breaking changes. When they do, migration guidance MUST be provided.
- Governance version changes are operational and do not affect standard conformance.
**Version-cut checklist** (v2.5, ADR-046 — the footer-lag anti-recurrence rule): on every version bump, the document's four version-bearing surfaces MUST agree before the cut commits — (1) the frontmatter `title`, (2) the frontmatter `updated` date, (3) a new changelog comment line in the header block, and (4) the *End of …* footer line. A cut that leaves any of the four stale is incomplete. *(This rule exists because the footer lagged the title across multiple historical bumps — most recently shipping "v2.3" inside the published v2.4 document.)*
---
---
## https://adna.network/reference/specification/16-tool-integration-tiers/
# 16. Tool Integration Tiers — aDNA Specification
> **Scan**: Three tiers — core standard (Tier 1, universal), frontmatter querying (Tier 2, any YAML reader), environment-specific (Tier 3, IDE/plugin). Aggregation points.
*Decisions: C13, D22*
## 16.1 Three-Tier Model
| Tier | Scope | Examples | Universal? |
|------|-------|----------|-----------|
| **Tier 1** | Core standard | YAML frontmatter, markdown, directory structure, naming conventions | Yes — works with any tool |
| **Tier 2** | Frontmatter querying | Dataview, custom scripts, CI/CD that reads frontmatter | Recommended — any tool that parses YAML |
| **Tier 3** | Environment-specific | IDE extensions, knowledge-base plugins, graph view, canvas | No — tool-specific |
Everything in this standard is Tier 1 unless noted otherwise. Tier 1 features work with any tool that can read files and directories.
```mermaid
flowchart TB
subgraph T1["Tier 1 — Core Standard (Universal)"]
F1["YAML frontmatter"]
F2["Markdown files"]
F3["Directory structure"]
F4["Naming conventions"]
end
subgraph T2["Tier 2 — Frontmatter Querying"]
F5["Dataview queries"]
F6["Shell scripts"]
F7["CI/CD pipelines"]
end
subgraph T3["Tier 3 — Environment-Specific"]
F8["Obsidian plugins"]
F9["IDE extensions"]
F10["Graph / canvas views"]
end
T1 -->|"any YAML reader"| T2
T2 -->|"specific tools"| T3
style T1 fill:#22c55e,color:#fff
style T2 fill:#3b82f6,color:#fff
style T3 fill:#8b5cf6,color:#fff
```
## 16.2 Aggregation Points
The following cross-directory views are useful in any aDNA instance. Their implementation is Tier 2/3 (tool-specific):
| Aggregation Point | Aggregates | Purpose |
|-------------------|-----------|---------|
| Active missions overview | `how/missions/` | All missions with current status |
| Context index | `what/context/` | All topics with token budgets |
| Session history | `how/sessions/history/` | Recent sessions with outcomes |
| Coordination status | `who/coordination/` | Active cross-agent notes |
Implementation examples: Dataview queries, shell scripts that parse frontmatter, CI/CD dashboard panels. Any tool that can read YAML frontmatter can implement these views.
---
---
## https://adna.network/reference/specification/17-error-recovery-protocol/
# 17. Error & Recovery Protocol — aDNA Specification
> **Scan**: Three-tier response — data integrity threat (STOP + escalate), state inconsistency (fix + log), process issue (workaround + backlog).
*Decisions: D24*
## 17.1 Tiered Response
| Severity | Trigger | Response | Recovery |
|----------|---------|----------|----------|
| **Tier 1 — Data integrity threat** | Corrupt file, data loss, conflicting writes destroying content | Stop all writes immediately. Document the issue. Do NOT attempt automated repair. Escalate to human with `#needs-human` tag. | Human-guided only |
| **Tier 2 — State inconsistency** | Stale STATE.md, broken cross-references, missing frontmatter | Attempt recovery: re-read files, reconcile state, add missing fields. Log the issue and recovery action in session file. Continue work. | Agent-recoverable with documentation |
| **Tier 3 — Process issue** | Template not found, naming violation, ambiguous pipeline stage | Note the issue in session file. Work around it. Create a backlog idea for improvement. | Work around, improve later |
```mermaid
flowchart LR
E["Error detected"] --> S1{"Data at risk?"}
S1 -->|Yes| T1["Tier 1: STOP Escalate to human"]
S1 -->|No| S2{"State inconsistent?"}
S2 -->|Yes| T2["Tier 2: Fix + log Continue work"]
S2 -->|No| T3["Tier 3: Note + workaround Backlog idea"]
style T1 fill:#ef4444,color:#fff
style T2 fill:#eab308,color:#000
style T3 fill:#22c55e,color:#fff
```
## 17.2 Escalation
Agents MUST log blockers with the `#needs-human` tag when:
- Data integrity is at risk (Tier 1 errors)
- A decision exceeds the agent's authority
- Ambiguous scope could lead to destructive actions
Agents MUST NOT proceed with destructive or irreversible actions when uncertain. When in doubt, stop and ask.
---
---
## https://adna.network/reference/specification/18-success-criteria/
# 18. Success Criteria — aDNA Specification
> **Scan**: Three levels — minimum viable (cold start, handoff, integrity), recommended (fork, scale, consistency), aspirational (network, collision safety, dual-audience).
*Decisions: D21*
```mermaid
flowchart TB
subgraph MIN["Minimum Viable (MUST)"]
M1["Cold Start"]
M2["Handoff"]
M3["Integrity"]
end
subgraph REC["Recommended (SHOULD)"]
R1["Fork"]
R2["Scale"]
R3["Consistency"]
end
subgraph ASP["Aspirational"]
A1["Network"]
A2["Collision Safety"]
A3["Dual-Audience"]
end
MIN -->|mature| REC
REC -->|excellent| ASP
style MIN fill:#22c55e,color:#fff
style REC fill:#3b82f6,color:#fff
style ASP fill:#8b5cf6,color:#fff
```
## 18.1 Minimum Viable (every aDNA MUST pass)
1. **Cold Start**: A fresh agent reads CLAUDE.md, then STATE.md (if present), and begins useful work within one session. No prior project knowledge is required.
2. **Handoff**: Agent A closes a session with SITREP + next-session prompt. Agent B reads the close-out and STATE.md and continues the work seamlessly.
3. **Integrity**: No data corruption or silent overwrites during multi-agent operation with collision prevention active.
## 18.2 Recommended (mature aDNA SHOULD pass)
4. **Fork**: The aDNA structure can be copied to a new project and adapted with only CLAUDE.md and domain content changes.
5. **Scale**: The aDNA supports 10+ missions, 50+ sessions, and 100+ content files without navigational degradation.
6. **Consistency**: Both deployment forms (bare and embedded) feel like the same system to agents and humans.
## 18.3 Aspirational (excellent aDNA)
7. **Network**: Multiple aDNA instances can discover and reference each other via documented patterns.
8. **Collision Safety**: Multi-agent concurrent operation produces no data loss even under heavy write contention.
9. **Dual-Audience**: Both humans (IDE, GitHub, knowledge-base tools) and agents find the content navigable and useful.
---
---
## https://adna.network/reference/specification/19-optional-extensions/
# 19. Optional Extensions — aDNA Specification
> **Scan**: Six opt-in subsystems — machine registry, backlog, skill files, testing/CI awareness, reference code, ADRs. Adopt based on need.
The following patterns are available but not required. Projects adopt them based on need.
## 19.1 Machine Registry
*Decision: D10*
For projects running on multiple machines or sync environments where path patterns vary.
**Location**: `what/hardware/machines/` or a similar what/ subfolder.
**Per-machine file contents**: hostname, user, OS, path patterns, installed tools, capabilities.
RECOMMENDED for sync-based environments (cloud storage, team sync tools) where file paths differ across machines. OPTIONAL for git repositories where environment variables handle path differences.
## 19.2 Backlog System
*Decision: D13*
Durable ideation and improvement tracking.
**Location**: `how/backlog/`
**Lifecycle**: idea → triage (priority/effort assessment) → graduation to `how/missions/` or archive.
**Frontmatter**: `type: idea`, `category`, `priority`, `effort`, `status`, `proposed_by`.
Agents SHOULD scan `how/backlog/` during session startup for ideas relevant to the current work. New ideas discovered during work SHOULD be captured as backlog files.
## 19.3 Skill Files
*Decision: D15*
Reusable agent procedures — step-by-step instructions agents can follow autonomously.
**Location**: `how/skills/skill_{name}.md`
**Sections**: purpose, prerequisites, steps, verification, rollback, notes.
Skills are distinct from processes: skills are agent-executable (precise steps, verification checks); processes are human-readable (guidelines, decision trees).
## 19.4 Testing/CI Awareness
*Decision: D23*
aDNA does not prescribe test frameworks or CI/CD configurations — these belong to the project content layer. However, agents SHOULD be aware of test status.
**Awareness pattern**:
- CLAUDE.md includes an optional section on testing: where to check, how to run, what signals mean
- AGENTS.md for code directories includes testing guidance as an enrichment layer
- STATE.md reports test status when relevant (pass/fail, coverage, regressions)
- CI/CD configuration lives in project content (`.github/`, `Makefile`, `pyproject.toml`, etc.)
## 19.5 Reference Code
*Decision: C11*
Bounded exception for code-adjacent reference material inside the aDNA structure.
**Location**: `what/reference/`
**Rules**:
- Executable code MUST live in `what/reference/` or in the project content layer — nowhere else in the triad
- what/reference/ MUST be bounded — no unbounded growth
- Entries SHOULD link to source implementations rather than duplicating code
- Documentation-only projects skip this entirely
## 19.6 Architecture Decision Records (ADRs)
*Decision: C12*
Lightweight records of significant project decisions.
**Location**: `what/decisions/`
**Template sections**: context, decision, consequences.
ADRs are knowledge artifacts — decisions outlive the process that produced them. A 2-year-old ADR is reference knowledge, not an active operation. This is why they live in what/, not how/.
---
---
## https://adna.network/reference/specification/2-terminology/
# 2. Terminology — aDNA Specification
> **Scan**: 12 key terms — triad, governance file, bare/embedded deployment, session, SITREP, content-as-code.
| Term | Definition |
|------|-----------|
| **aDNA** | Agentic DNA — the knowledge architecture standard defined by this document |
| **Triad** | The `what/how/who` directory ontology that organizes all aDNA content |
| **what/** | Knowledge layer — WHAT the project knows (context, decisions, reference, domain objects) |
| **how/** | Operations layer — HOW the project works (missions, sessions, templates, pipelines) |
| **who/** | Organization layer — WHO is involved (people, teams, coordination, governance) |
| **Governance file** | A root-level ALLCAPS markdown file that governs the aDNA instance: CLAUDE.md, MANIFEST.md, STATE.md, AGENTS.md, README.md |
| **Bare triad** | Deployment form where `what/`, `how/`, `who/` sit directly at project root. Used for knowledge bases and standalone agent workspaces |
| **Embedded triad** | Deployment form where the triad is wrapped inside `.agentic/` (i.e., `.agentic/what/`, `.agentic/how/`, `.agentic/who/`). Used for git repositories |
| **Deployment form** | How the triad is physically instantiated — bare or embedded |
| **Session** | A bounded unit of agent work with a defined lifecycle: creation, execution, and close-out |
| **SITREP** | Structured status report at session close: Completed, In Progress, Next Up, Blockers, Files Touched |
| **Content-as-code** | A pipeline paradigm where a file's directory location represents its processing state |
| **AGENTS.md** | Per-directory agent-facing guide — purpose, key files, patterns, conventions |
| **README.md** | Per-directory human-facing guide — navigation, context, useful links |
| **Conformance level** | A graduated tier (Starter, Standard, Full) defining the minimum requirements an aDNA instance MUST meet to claim conformance at that level |
| **Conformant instance** | A directory tree that satisfies all MUST requirements for at least the Starter conformance level defined in §5.5 |
---
---
## https://adna.network/reference/specification/20-appendices/
# 20. Appendices — aDNA Specification
> **Scan**: Persona framework (App A), aggregation points (App B), deferred topics (App C), decision traceability matrix (App D — 40 decisions mapped to spec sections).
## Appendix A: Persona Framework
*Decision: D6*
A persona is OPTIONAL but structured when present. The persona framework defines what a persona includes and why it matters — consistency, predictability, and character continuity across sessions.
### A.1 Framework Structure
| Section | Contents | Purpose |
|---------|----------|---------|
| **Identity** | Name, role metaphor, mission statement | Establish who the agent is in this project |
| **Operating Style** | 3-5 behavioral principles | Define predictable working patterns |
| **Communication Norms** | Tone, formatting, greeting/close patterns | Ensure consistent interaction style |
| **Domain Awareness** | What the persona should know about the project domain | Ground the agent in project context |
### A.2 Reference Implementation
The following is a reference persona. Projects MAY adopt it directly or use the framework to create their own.
**Identity**: Chief of staff to the operation — a role inspired by the military chief of staff archetype, who turns strategic vision into operational reality.
**Operating Style**:
1. Orient first, act second — assess the operational picture before diving into any task
2. Think in lines of effort — maintain awareness across parallel workstreams
3. Be direct and precise — clear status updates, early risk flags, recommendations with rationale
4. Coordinate, don't just execute — coherence across the full operation matters more than speed on any single task
**Communication Norms**: Direct, no filler. Structured updates (SITREP format). Greets with operational state summary on planning sessions. Proceeds directly on execution sessions.
**Domain Awareness**: Defined per project in CLAUDE.md.
## Appendix B: Aggregation Points
*Decision: D22*
Standard aggregation points for cross-directory views. Implementation is tool-specific (Tier 2/3).
| Point | Source | Query Pattern |
|-------|--------|--------------|
| **Active missions** | `how/missions/` | All files where `type: mission` and `status: active` |
| **Context index** | `what/context/` | All topic directories with their AGENTS.md token estimates |
| **Recent sessions** | `how/sessions/history/` | Last 10 session files, sorted by `updated` descending |
| **Open coordination** | `who/coordination/` | All files where `status: open` or `status: urgent` |
| **Backlog overview** | `how/backlog/` | All files where `type: idea` and `status: active`, sorted by `priority` |
**Knowledge-base implementation**: Dataview queries in bridge pages (e.g., `how/missions.md`, `how/context_library.md`).
**Script implementation**: Any tool that parses YAML frontmatter from markdown files can produce these views.
## Appendix C: Deferred Topics
The following topics were identified during the planning arc but deferred from v1.0. They are acknowledged here for future standard revisions. (Retained from v1.0; no new deferrals in v2.0.)
| Gap | Topic | Disposition |
|-----|-------|-------------|
| G2 | **Multi-model / model-agnostic design** | "CLAUDE.md" is a convention name — projects using other models use the same structure. The persona framework (§ App A) is model-agnostic. A future revision MAY define model-neutral naming. |
| G3 | **Documentation generation** | Projects that generate external-facing docs from aDNA content will develop project-specific patterns. No universal standard needed at this time. |
| G7 | **Context staleness detection** | The `updated` field + session cycling naturally address staleness (fresh reads on each session start). Formal staleness detection is Tier 2/3 tooling, not a standard concern. |
| G8 | **Cross-instance aDNA awareness** | Addressed by bridge patterns (informational companion, SHOULD-level guidance). Defines composition patterns (nesting, sibling, monorepo), discovery protocol, scope boundaries, cross-referencing conventions, and agent behavior rules. Addresses §18.3 #7 Network criterion. |
| G10 | **Agent capability declaration** | Most aDNA instances target specific agent capabilities. CLAUDE.md can note capability assumptions. A formal capability schema is deferred pending broader agent ecosystem maturity. |
## Appendix D: Decision Traceability Matrix
This appendix maps every design decision to its location in the standard, ensuring complete coverage.
### D.1 Structural Decisions (C1-C15)
| ID | Decision | Spec Section(s) |
|----|----------|-----------------|
| C1 | Pattern-appropriate deployment (bare + embedded triad) | §3.2, §3.3, §3.4 |
| C2 | Dual-file: AGENTS.md + README.md everywhere | §4.5, §4.6 |
| C3 | Vault naming + repo exceptions, ALLCAPS governance list | §6.1, §6.2, §6.3, §6.4 |
| C4 | Frontmatter mandatory for aDNA content, optional for project | §7.1, §7.2 |
| C5 | what/ context/ mandatory, rest project-specific | §5.1 |
| C6 | who/ coordination/ + governance/ mandatory | §5.2 |
| C7 | how/ tiered: missions/sessions/templates required, backlog recommended | §5.3 |
| C8 | Seeding guidance via triad principle, not prescriptive table | §3.1 (triad question test) |
| C9 | Git-supplemented archive | §15.1 |
| C10 | Lightweight versioning in CLAUDE.md, sessions as changelog | §15.3 |
| C11 | what/reference/ as bounded exception for code | §19.5 |
| C12 | ADRs in what/decisions/ | §19.6 |
| C13 | Tiered tool integration (Tier 1/2/3) | §16.1 |
| C14 | Ontology artifact: Mermaid (Tier 1) + Canvas (Tier 3) | §5.1 (ontology artifact) |
| C15 | what/ as registry layer | §5.1 (registry pattern) |
### D.2 Process Decisions (D1-D25)
| ID | Decision | Spec Section(s) |
|----|----------|-----------------|
| D1 | Universal CLAUDE.md template, required + optional sections | §4.2 |
| D2 | Separate MANIFEST.md + STATE.md | §4.3, §4.4 |
| D3 | Session model with environment enrichments | §8.1, §8.2, §8.3 |
| D4 | SITREP + mandatory next-session prompt | §8.4, §8.5 |
| D5 | 75% rule only, no sizing prescriptions | §8.7 |
| D6 | Persona framework with reference implementation | §4.2 (persona), App A |
| D7 | Tiered collision prevention (universal/sync/multi-agent) | §13 |
| D8 | Flexible what/context/ with subtypes | §10 |
| D9 | who/coordination/ only | §11 |
| D10 | Machine registry as optional extension | §19.1 |
| D11 | Graduated template set (Starter/Standard/Full) | §12 |
| D12 | Separated missions + subdirectories | §9 |
| D13 | Backlog recommended, not required | §19.2 |
| D14 | Content-as-code paradigm universal, pipelines optional | §14 |
| D15 | Skill files optional in how/skills/ | §19.3 |
| D16 | Generalized mission stages | §9.2 |
| D17 | Lightweight requirements in missions, full specs as extension | §9.1 (mission contents) |
| D18 | Minimal tag rules, no formal taxonomy | §7.3 |
| D19 | Progressive enrichment for AGENTS.md | §4.5 |
| D20 | Separate content priority (0-N) from rule precedence | §7.4 |
| D21 | Tiered success criteria (minimum/recommended/aspirational) | §18 |
| D22 | Aggregation points identified, implementation tool-specific | §16.2, App B |
| D23 | Testing/CI as project-specific with awareness pattern | §19.4 |
| D24 | Tiered error/recovery protocol | §17 |
| D25 | Quickstart in CLAUDE.md + README.md | §4.2 (quickstart section) |
### D.3 Gap Dispositions (G1-G12)
| Gap | Topic | Disposition | Location |
|-----|-------|-------------|----------|
| G1 | Testing/CI integration | Addressed by D23 | §19.4 |
| G2 | Multi-model design | Deferred | App C |
| G3 | Documentation generation | Deferred | App C |
| G4 | Versioning/changelog | Addressed by C10 | §15.3 |
| G5 | Team roles/governance | Subsumed into C6 (who/governance/) | §5.2 |
| G6 | Error/recovery protocol | Addressed by D24 | §17 |
| G7 | Context staleness | Deferred (subsumed into D5/D7) | App C |
| G8 | Cross-instance awareness | Addressed by bridge patterns (informational) | App C |
| G9 | Onboarding/bootstrap | Addressed by D25 | §4.2 (quickstart) |
| G10 | Agent capability declaration | Deferred | App C |
| G11 | Ontology schema artifact | Addressed by C14 | §5.1 (ontology artifact) |
| G12 | Object standard integration | Addressed by C15 + execution phase | §5.1 (registry pattern) |
---
*End of aDNA Universal Standard v2.5*
---
## https://adna.network/reference/specification/3-triad-architecture/
# 3. Triad Architecture — aDNA Specification
> **Scan**: The `who/what/how` ontology, bare vs. embedded deployment forms, classification question test.
*Decisions: C1, C8*
## 3.1 The what/how/who Ontology
Every aDNA instance organizes knowledge into three categories:
| Layer | Question | Contains |
|-------|----------|----------|
| **what/** | WHAT does this project know? | Knowledge objects, context library, decisions, reference material, domain entities |
| **how/** | HOW does this project work? | Missions, sessions, templates, pipelines, tasks, skills, processes |
| **who/** | WHO is involved? | People, teams, coordination notes, governance policies, communications |
The triad is the universal ontology. Any piece of project knowledge belongs in exactly one of the three legs. When classifying content, apply the question test: "Is this about WHAT we know, HOW we work, or WHO is involved?"
**Classification examples**:
| Content | Question | Triad Leg |
|---------|----------|-----------|
| "How does ancient DNA extraction work?" | WHAT do we know? | `what/context/` |
| "Mission plan for Q2 deployment" | HOW do we work? | `how/missions/` |
| "Contact info for the partnership lead" | WHO is involved? | `who/contacts/` |
The triad is deliberately minimal. Three categories are sufficient because they map to the three dimensions of any project: its knowledge, its operations, and its people. Additional categories create sorting ambiguity.
```mermaid
flowchart TB
Root["aDNA Instance"]
Root --> W["what/ Knowledge"]
Root --> H["how/ Operations"]
Root --> O["who/ Organization"]
W --> ctx["context/"]
W --> dec["decisions/"]
W --> dom["domain entities"]
H --> mis["missions/"]
H --> ses["sessions/"]
H --> tpl["templates/"]
O --> coord["coordination/"]
O --> gov["governance/"]
O --> ppl["people & teams"]
style W fill:#0d9488,color:#fff
style H fill:#22c55e,color:#fff
style O fill:#8b5cf6,color:#fff
```
## 3.2 Bare Triad
In a bare triad deployment, `what/`, `how/`, and `who/` sit as top-level directories at the project root. Governance files sit alongside them at root level.
**When to use**: Knowledge bases, standalone agent workspaces, and any project where aDNA IS the primary content.
```
{project_root}/
├── CLAUDE.md
├── MANIFEST.md
├── STATE.md
├── AGENTS.md
├── README.md
├── what/
├── how/
├── who/
└── {project_content}/
```
## 3.3 Embedded Triad
In an embedded triad deployment, the triad is wrapped inside `.agentic/` at the repository root. Governance files remain at the repository root (not inside `.agentic/`).
**When to use**: Any git-tracked codebase adding agent support. The `.agentic/` prefix follows the convention of dot-prefixed directories for meta/config in git repositories (like `.github/`, `.vscode/`).
```
{repo_root}/
├── CLAUDE.md
├── MANIFEST.md
├── STATE.md
├── AGENTS.md
├── README.md
├── .agentic/
│ ├── AGENTS.md
│ ├── what/
│ ├── how/
│ └── who/
└── {codebase}/
```
## 3.4 Deployment Form Selection
Both deployment forms are first-class. The triad ontology is identical in both — only the physical nesting differs. CLAUDE.md in each environment bridges any path differences.
An aDNA instance MUST use exactly one deployment form. A project MUST NOT mix bare and embedded triads.
## 3.5 Directory Convention
An aDNA project directory SHOULD use the `.aDNA` suffix to indicate it follows the Agentic DNA knowledge architecture standard. This suffix serves as a visual type marker, analogous to `.app` bundles in macOS or `.git` directories in version control.
**Naming rules:**
- The base template (the `aDNA` repository, embedded in a workspace at `.adna/`) MUST NOT use the `.aDNA` suffix — it is the source, not an instance. *(Per ADR-006 repo rename `Agentic-DNA`→`aDNA` + ADR-008 airlock embedding at `.adna/`.)*
- Forked projects SHOULD use the pattern `ProjectName.aDNA/` (e.g., `zeta.aDNA/`, `my_research.aDNA/`).
- The project name portion MUST match `[a-z][a-z0-9_]{0,63}` — lowercase letters, digits, and underscores only, starting with a letter, maximum 64 characters.
- The suffix `.aDNA` uses mixed case (capital D, N, A) matching the abbreviation branding.
- Nesting `.aDNA` directories inside other `.aDNA` directories is NOT RECOMMENDED.
- Existing projects MAY adopt the convention by renaming their directory. This is optional.
**Discovery:**
Tools SHOULD discover aDNA projects via `*.aDNA` glob patterns:
```bash
# List aDNA projects in workspace
ls -d *.aDNA 2>/dev/null
find . -maxdepth 1 -name "*.aDNA" -type d
```
**Workspace convention:**
```
~/aDNA/
├── .adna/ # Base template — the aDNA standard tree (hidden; source, not an instance)
├── my_research.aDNA/ # Forked project (aDNA instance)
├── zeta.aDNA/ # Another project
└── CLAUDE.md # Workspace-level governance
```
---
---
## https://adna.network/reference/specification/4-governance-files/
# 4. Governance Files — aDNA Specification
> **Scan**: Five ALLCAPS files (CLAUDE, MANIFEST, STATE, AGENTS, README) — purpose, required contents, quickstart sequences, progressive enrichment.
*Decisions: C2, C3, D1, D2, D6, D19, D25*
Every aDNA instance MUST have governance files at the project root. These are the agent's primary orientation documents.
## 4.1 Governance File List
The following ALLCAPS files constitute the governance layer:
| File | Required | Purpose | Update Cadence |
|------|----------|---------|----------------|
| **CLAUDE.md** | MUST | Agent root context — persona, project map, safety rules, startup protocol | When structure or protocols change |
| **MANIFEST.md** | MUST | Static project overview — what the project is, architecture, entry points | When project scope or architecture changes |
| **STATE.md** | SHOULD | Dynamic operational state — current phase, blockers, recent decisions, next steps | Every session close-out |
| **AGENTS.md** | MUST | Root-level agent guide — directory purpose, key files, patterns | When directory structure changes |
| **README.md** | MUST | Root-level human guide — navigation, setup, how to browse | When onboarding experience changes |
```mermaid
flowchart LR
CLAUDE["CLAUDE.md Agent root context"]
MANIFEST["MANIFEST.md Project overview"]
STATE["STATE.md Current state"]
AGENTS["AGENTS.md Directory guide"]
README["README.md Human guide"]
CLAUDE -->|"structure + rules"| STATE
CLAUDE -->|"references"| MANIFEST
STATE -->|"updated each session"| CLAUDE
AGENTS -.->|"per-directory"| CLAUDE
README -.->|"per-directory"| CLAUDE
style CLAUDE fill:#ef4444,color:#fff
style STATE fill:#eab308,color:#000
style MANIFEST fill:#3b82f6,color:#fff
```
## 4.2 CLAUDE.md — Agent Root Context
CLAUDE.md is the primary agent orientation document. It MUST exist at the project root in both deployment forms. It is auto-loaded by Claude Code and serves as the agent's first read on every session.
**Required sections**:
1. **Identity**: Project name, agent persona (if defined — see Appendix A), mission statement. The agent MUST know what project it is operating in and what role it plays.
2. **Project Map**: Directory structure diagram, key files table. The agent MUST be able to navigate the project from this section alone.
3. **Safety Rules**: Collision prevention tier (see §13), escalation protocol, data integrity rules. The agent MUST know what it can and cannot do.
4. **Agent Protocol**: Startup checklist, session tracking rules, closure requirements. The agent MUST know how to begin and end work.
5. **Quickstart**: A concise startup sequence for cold-start orientation. MUST enable a fresh agent to begin useful work within one session. Include both agent and human quickstarts:
**Agent Quickstart** (5 steps):
1. Read CLAUDE.md — understand project structure, safety rules, persona
2. Read STATE.md — understand current phase, blockers, recent decisions
3. Check `how/sessions/active/` — identify any conflicting sessions
4. Check `who/coordination/` — read urgent cross-agent notes
5. Create session file in `how/sessions/active/` and begin work
**Human Quickstart** (4 steps):
1. Read README.md — understand what this project is and how to navigate
2. Read MANIFEST.md — understand architecture and entry points
3. Browse the triad (`what/`, `how/`, `who/`) — explore the knowledge structure
4. Open STATE.md — see current operational status and next steps
**Optional sections** (add when relevant):
- Domain Knowledge — project-specific context the agent needs
- Working with Content — naming, metadata, linking conventions
- Machine Setup — multi-machine path patterns and tool requirements
- Environment-Specific Rules — sync, IDE, CI/CD integration
**Versioning**: CLAUDE.md SHOULD include a version comment in its header: ``. Major version for structural changes, minor for significant updates. Session history serves as the detailed changelog.
**Persona framework**: When a persona is defined, it MUST include: identity (name, role metaphor, mission), operating style (3-5 behavioral principles), and communication norms (tone, greeting/close patterns). See Appendix A for the full framework and reference implementation.
## 4.3 MANIFEST.md — Project Overview
MANIFEST.md describes what the project IS. It changes infrequently — only when project scope, architecture, or major workstreams change.
**Contents**:
- Project identity and purpose
- Architecture overview
- Key entry points and navigation
- Active missions / major workstreams (stable references, not dynamic status)
## 4.4 STATE.md — Dynamic Operational State
STATE.md captures where the project IS RIGHT NOW. It SHOULD be updated on every session close-out. It MUST be updated when phase, blockers, or priorities change.
**Contents**:
- Current phase / milestone
- Recent decisions (last 3-5)
- Active blockers
- What's working well
- Next steps / recommended priorities
STATE.md enables fast cold-start orientation: a fresh agent reads CLAUDE.md (structure and rules) then STATE.md (current situation) and is ready to work.
## 4.5 AGENTS.md — Per-Directory Agent Guide
Every aDNA instance MUST have a root-level AGENTS.md (listed in §4.1). Beyond root, every directory where agents operate SHOULD have an AGENTS.md file. AGENTS.md is agent-facing: optimized for machine consumption with structured, scannable content.
**Lightweight core** (every AGENTS.md):
- Purpose — what this directory contains and why
- Key files — important files with brief descriptions
- Patterns — naming, structure, or workflow conventions specific to this directory
**Enrichment layers** (add as the directory matures):
- Quick reference table
- Modification guide — how to add or change content
- Dependencies — what this directory relies on
- Testing / validation notes
- Current state / recent changes
- Troubleshooting
AGENTS.md files grow through progressive enrichment: start lightweight, add detail when agents or humans repeatedly need information that is not yet documented.
## 4.6 README.md — Per-Directory Human Guide
README.md is human-facing: optimized for browsing in GitHub, an IDE, or a knowledge-base tool. It complements AGENTS.md by providing navigation context for humans.
Every aDNA instance MUST have a root README.md. Subdirectory README.md files are OPTIONAL — create them when human navigation would benefit.
---
---
## https://adna.network/reference/specification/5-directory-structure/
# 5. Directory Structure — aDNA Specification
> **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**:
| Directory | Purpose |
|-----------|---------|
| `context/` | Agent context library — synthesized knowledge agents load before domain work |
**Recommended subdirectories**:
| Directory | Purpose |
|-----------|---------|
| `decisions/` | Architecture Decision Records (ADRs) — significant decisions and their rationale |
**Optional subdirectories** (add based on project domain):
| Directory | Purpose |
|-----------|---------|
| `reference/` | Bounded exception for code-adjacent reference material (see §19.5) |
| `inventory/` | Installed/configured state — vaults, system, memberships. Base WHAT type since v2.3 (ADR-035); markdown + paired `.yaml` companion. |
| `{domain}/` | Project-specific knowledge: `models/`, `hardware/`, `datasets/`, `specs/`, etc. |
**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:
```yaml
# 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:
```mermaid
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**:
| Directory | Purpose |
|-----------|---------|
| `coordination/` | Cross-agent notes — handoffs, urgency signals, ephemeral coordination |
| `governance/` | Team roles, decision authority, policies, escalation paths |
**Optional subdirectories** (add based on organizational needs):
| Directory | Purpose |
|-----------|---------|
| `identity/` | Stable identity records validated against external reality — node / network / deployment (hostname, operator, persistent UUID, peer-id). Base WHO type since v2.3 (ADR-035); markdown + paired `.yaml` companion. |
| `{domain}/` | Project-specific organization: `customers/`, `partners/`, `contacts/`, `communications/`, `roadmap/` |
## 5.3 how/ — Operations Layer
how/ contains everything about HOW the project works.
**Required subdirectories**:
| Directory | Purpose |
|-----------|---------|
| `missions/` | Missions — objective decomposition, dependencies, claiming protocol |
| `sessions/` | Session tracking — execution records with SITREP close-outs |
| `templates/` | Reusable templates for all aDNA file types |
**Recommended subdirectories**:
| Directory | Purpose |
|-----------|---------|
| `backlog/` | Ideation and improvement tracking (see §19.2) |
**Optional subdirectories**:
| Directory | Purpose |
|-----------|---------|
| `pipelines/` | Content-as-code workflows (see §14) |
| `tasks/` | Granular task tracking |
| `skills/` | Reusable agent procedures (see §19.3) |
| `processes/` | Human-readable workflow documentation |
| `deliverables/` | Output artifacts |
| `federation/` | Consumer federation wrappers — one `/` per federated software-element/service graph (v2.5, ADR-045) |
## 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:
```yaml
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.
---
---
## https://adna.network/reference/specification/6-naming-conventions/
# 6. Naming Conventions — aDNA Specification
> **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:
| Prefix | Content |
|--------|---------|
| `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.
---
---
## https://adna.network/reference/specification/7-frontmatter-system/
# 7. Frontmatter System — aDNA Specification
> **Scan**: Required base fields (`type`, `status`, `created`, `updated`, `last_edited_by`, `tags`), tag conventions, priority field, type-specific extensions.
*Decisions: C4, D18, D20*
## 7.1 Scope
YAML frontmatter MUST be present on all aDNA content files — files inside the triad (`what/`, `how/`, `who/` or `.agentic/what/`, etc.) and root governance files.
Project content files (source code, external documentation) outside the triad are exempt from frontmatter requirements.
## 7.2 Required Base Fields
Every aDNA content file MUST include these frontmatter fields:
```yaml
---
type:
status:
created: YYYY-MM-DD
updated: YYYY-MM-DD
last_edited_by: agent_ |
tags: []
---
```
| Field | Purpose |
|-------|---------|
| `type` | Entity classification (e.g., `session`, `mission`, `customer`, `context_research`) |
| `status` | Lifecycle state (e.g., `active`, `completed`, `draft`, `abandoned`) — entity-specific values |
| `created` | Date of file creation |
| `updated` | Date of last modification — critical for collision prevention |
| `last_edited_by` | Attribution — who or what last modified this file |
| `tags` | Categorization array for filtering and discovery |
**Per-class profile** (v2.5, ADR-044): the six base fields are required for content and session entities. **`status` is optional for `type: directory_index` and `type: coordination`** — an index or correspondence record has no lifecycle state, and their canonical templates omit it. The other five base fields remain required for all classes.
## 7.3 Tag Conventions
Tags MUST use lowercase with underscores (e.g., `mission`, `context_research`).
Every aDNA content file MUST have at least one tag (the type tag is sufficient).
No formal tag registry is prescribed. Projects SHOULD document their tag conventions in AGENTS.md files when the tag set exceeds a dozen unique tags.
## 7.4 Priority Field
Content items that need prioritization (tasks, backlog ideas, customers) MAY include a `priority` field using a simple numeric scale: `0` (highest) through `N` (lowest).
Rule/guardrail conflict resolution is a separate concern. Projects that need rule precedence SHOULD define their own mechanism in CLAUDE.md or governance files.
## 7.5 Type-Specific Fields
Templates (§12) define additional frontmatter fields per content type. For example, a session template adds `session_id`, `plan_id` (legacy field name), `tier`; a customer template adds `segment`, `deal_stage`, `contacts`.
Frontmatter is the integration layer between human tools (Dataview queries, IDE search) and agent queries. Consistent frontmatter enables consistent querying across any tool.
## 7.6 Frontmatter Extension Policy
Instance-specific frontmatter fields MAY be added to any entity type. The following rules govern extensions:
1. **Custom fields** MAY be added freely to any content file's frontmatter
2. Custom fields SHOULD use a project-specific prefix (e.g., `bio_target_class`, `crm_deal_stage`) when the field name could conflict with future standard fields
3. Standard fields (those defined in §7.2 and per-type templates) MUST NOT be repurposed to carry different semantics
4. Migration tools MUST preserve custom fields — standard version upgrades MUST NOT strip unrecognized frontmatter fields
5. Projects SHOULD document their custom fields in the relevant `AGENTS.md` or template files
## 7.7 Decision-Record Ratification Discipline
Decision records (ADRs, `what/decisions/`) carry a lifecycle `status` whose advancement beyond `proposed` is a **human** act. Effective v2.5 (ADR-046, folding the discipline installed after an agent thread self-marked an ADR `accepted` without an operator gate):
1. **Agents author; operators ratify.** An agent MAY fully author an ADR — context, decision, consequences, alternatives, references — and MAY set or keep `status: proposed` (or `draft`). An agent MUST NOT set `accepted`, `ratified`, or `rejected`; those transitions require an operator gate.
2. **Ratification record.** Any ADR moving beyond `proposed` MUST carry a structured ratification block with all four fields present and non-empty:
- **Ratifier** — the named human operator/authority. An agent or persona may be named only as author/steward, never as ratifier.
- **Gate / reference** — a verifiable pointer to the discrete ratification event: the gate file and/or its output record, the ratifying session id, and/or the ratifying commit.
- **Ratification date** — distinct from the authored/created date.
- **Scope of authority** — exactly what the ratification authorizes, plus any pending co-signs that keep seams non-operative.
3. **Retroactivity.** ADRs accepted before v2.5 SHOULD be backfilled with ratification blocks; a pre-v2.5 accepted ADR without one is NOT thereby non-conformant. *(This clause is what keeps the v2.5 cut a minor version under §15.4.)*
4. **Batch ceremonies.** An N-ADRs-at-once ratification ceremony MAY substitute a single ceremony record for per-ADR gate references, provided each covered ADR's block points to it.
5. **Validation.** Conformance tooling SHOULD check structure only — the four fields present and non-empty — never the truth of the gate; truth is the operator's, at the gate. Recommended rollout: warn first, promote to fail after a backfill pass.
6. **Exemption.** Lifecycle-neutral back-references (e.g., adding `superseded_by` once the superseding ADR is itself ratified) are exempt from rule 1.
---
---
## https://adna.network/reference/specification/8-session-model/
# 8. Session Model — aDNA Specification
> **Scan**: Bounded units of agent work — lifecycle (create → execute → close → archive), session tiers, SITREP close-out, next-session prompt, the 75% rule.
*Decisions: D3, D4, D5*
## 8.1 Session Lifecycle
A session is a bounded unit of agent work. Every session follows this lifecycle:
1. **Create**: Write a session file in `how/sessions/active/`
2. **Execute**: Perform work, logging activity
3. **Close**: Write SITREP + next-session prompt
4. **Archive**: Set `status: completed`, move to `how/sessions/history/YYYY-MM/`
A session file MUST be created before an agent modifies any other project files. This is the audit trail.
```mermaid
stateDiagram-v2
[*] --> Create: Agent starts work
Create --> Active: Session file written
Active --> Active: Work + log activity
Active --> Close: SITREP written
Close --> Archive: Move to history/YYYY-MM/
Archive --> [*]
state Active {
[*] --> Working
Working --> Working: Modify files Update frontmatter
}
```
## 8.2 Session ID Format
Session IDs MUST use the timestamped format:
```
session_{user}_{YYYYMMDD}_{HHMMSS}_{descriptor}
```
Example: `session_{username}_20260211_120000_gap_analysis`
Timestamped IDs are machine-sortable, collision-free across agents, and self-documenting. The descriptor SHOULD be a brief lowercase-underscore slug describing the session's purpose.
## 8.3 Session Tiers
| Tier | When | Requirements |
|------|------|-------------|
| **Tier 1** (default) | Normal content work | Session file with intent, activity log, SITREP close-out |
| **Tier 2** | Shared config edits (governance files, plugin configs) | Tier 1 requirements + scope declaration + conflict scan + heartbeat |
Tier 1 is a lightweight audit trail. Tier 2 adds coordination safeguards for edits that affect shared infrastructure.
Sessions MAY include a **Technical Readiness Review (TRR)** quality gate before close-out — a structured check that deliverables meet acceptance criteria. TRR is particularly useful for code-generation sessions or sessions producing artifacts that downstream tasks depend on.
## 8.4 SITREP Close-Out
Every session MUST end with a SITREP:
```markdown
## SITREP
**Completed**: [what was finished]
**In progress**: [what was started but not finished, with handoff notes]
**Next up**: [recommended next actions]
**Blockers**: [anything preventing progress]
**Files touched**: [created, modified, moved]
```
## 8.5 Next-Session Prompt
Every session MUST include a next-session prompt after the SITREP:
```markdown
## Next Session Prompt
[Self-contained paragraph that a fresh agent can read to continue this work.
Include: what was accomplished, what remains, key context, recommended approach.]
```
The next-session prompt ensures continuity. A fresh agent reading this prompt and STATE.md SHOULD be able to continue the work without needing to read the full session history.
## 8.6 STATE.md Update
STATE.md SHOULD be updated on every session close. It MUST be updated when the current phase, blockers, or priorities change.
## 8.7 The 75% Rule
Agents MUST scope each session to use no more than approximately 75% of the context window. The remaining 25% is reserved for thinking, debugging, and course correction.
If a task requires more than 75% of the context window, the agent MUST split the work across sessions, checkpointing progress in the session close-out.
No other session sizing prescriptions are universal. Time, task count, and line-count guidelines are project-specific — different work paradigms (code generation, knowledge synthesis, CRM maintenance) have different natural session sizes.
---
---
## https://adna.network/reference/specification/9-mission-system/
# 9. Mission System — aDNA Specification
> **Scan**: Multi-session work decomposition — objectives, acceptance criteria, stages, claiming protocol, handoff between agents.
*Decisions: D12, D16, D17*
## 9.1 Mission Structure
Missions live in `how/missions/`. A mission decomposes work that spans multiple sessions into trackable objectives.
**Single-file missions** (small scope):
```
how/missions/mission_simple_task.md
```
**Subdirectory missions** (large scope with deliverables):
```
how/missions/mission_complex_project/
├── mission_complex_project.md # Master mission
├── deliverable_a.md # Phase/deliverable files
└── deliverable_b.md
```
The mission file MUST include:
- **Objectives**: What the mission achieves
- **Acceptance criteria**: How you know it is done
- **Constraints**: What limits apply (time, scope, dependencies)
- **Objective list**: Individual objectives with dependencies and status
- **Status tracking**: Per-objective status (pending, in_progress, completed, blocked)
## 9.2 Mission Stages
Missions MAY define stage-based subdirectories for multi-phase work:
```
how/missions/{mission_slug}/
├── mission_{slug}.md
├── 00_research/
├── 01_requirements/
├── 02_design/
└── 03_implementation/
```
Stage names and count are mission-specific. The convention is: numbered prefix for ordering, descriptive name for clarity.
## 9.3 Mission Handoff
Agents claim mission objectives by session. A session file's `plan_id` and `task` frontmatter fields (legacy names, retained for compatibility) link it to the mission. When an objective spans multiple sessions, each session's SITREP provides the handoff. Agents MUST NOT claim objectives already in progress by another active session.
---
---
## https://adna.network/reference/specification/full/
[← Back to reference](/reference/)
# aDNA Specification — full text
[Read by section](/reference/specification/) · v2.5 stable
**Agentic DNA (aDNA)** — A knowledge architecture standard for AI-native projects.
## 1. Introduction & Scope
> **Scan**: What aDNA is, who it’s for, and RFC 2119 normative keywords.
### 1.1 What Is aDNA
aDNA (Agentic DNA) is a standard for organizing project knowledge so that AI agents can orient, operate, and coordinate within any project — alongside humans. It defines a directory structure, governance files, metadata conventions, and operational protocols that together form a project’s “knowledge genome.”
An aDNA instance is the complete set of governance files, triad directories, and operational infrastructure that implements this standard within a project.
### 1.2 Audience
This standard is written for:
- **Agents** — AI assistants that read, write, and navigate project knowledge
- **Agent operators** — humans who configure and manage agent-augmented projects
- **Project bootstrappers** — anyone starting a new project that will use AI agents
### 1.3 Scope
**In scope**: Project knowledge architecture — how project information is organized, how agents orient and operate, how multiple agents coordinate, and how knowledge persists across sessions.
**Out of scope**: Application source code structure, CI/CD pipeline configuration, deployment infrastructure, and agent model internals. These belong to the project content layer, not to aDNA.
### 1.4 Normative Language
This document uses RFC 2119 keywords:
KeywordMeaning
**MUST**Absolute requirement
**MUST NOT**Absolute prohibition
**SHOULD**Recommended; may be omitted with good reason
**MAY**Truly optional
## 2. Terminology
> **Scan**: 12 key terms — triad, governance file, bare/embedded deployment, session, SITREP, content-as-code.
TermDefinition
**aDNA**Agentic DNA — the knowledge architecture standard defined by this document
**Triad**The `what/how/who` directory ontology that organizes all aDNA content
**what/**Knowledge layer — WHAT the project knows (context, decisions, reference, domain objects)
**how/**Operations layer — HOW the project works (missions, sessions, templates, pipelines)
**who/**Organization layer — WHO is involved (people, teams, coordination, governance)
**Governance file**A root-level ALLCAPS markdown file that governs the aDNA instance: CLAUDE.md, MANIFEST.md, STATE.md, AGENTS.md, README.md
**Bare triad**Deployment form where `what/`, `how/`, `who/` sit directly at project root. Used for knowledge bases and standalone agent workspaces
**Embedded triad**Deployment form where the triad is wrapped inside `.agentic/` (i.e., `.agentic/what/`, `.agentic/how/`, `.agentic/who/`). Used for git repositories
**Deployment form**How the triad is physically instantiated — bare or embedded
**Session**A bounded unit of agent work with a defined lifecycle: creation, execution, and close-out
**SITREP**Structured status report at session close: Completed, In Progress, Next Up, Blockers, Files Touched
**Content-as-code**A pipeline paradigm where a file’s directory location represents its processing state
**AGENTS.md**Per-directory agent-facing guide — purpose, key files, patterns, conventions
**README.md**Per-directory human-facing guide — navigation, context, useful links
**Conformance level**A graduated tier (Starter, Standard, Full) defining the minimum requirements an aDNA instance MUST meet to claim conformance at that level
**Conformant instance**A directory tree that satisfies all MUST requirements for at least the Starter conformance level defined in §5.5
## 3. Triad Architecture
> **Scan**: The `who/what/how` ontology, bare vs. embedded deployment forms, classification question test.
*Decisions: C1, C8*
### 3.1 The what/how/who Ontology
Every aDNA instance organizes knowledge into three categories:
LayerQuestionContains
**what/**WHAT does this project know?Knowledge objects, context library, decisions, reference material, domain entities
**how/**HOW does this project work?Missions, sessions, templates, pipelines, tasks, skills, processes
**who/**WHO is involved?People, teams, coordination notes, governance policies, communications
The triad is the universal ontology. Any piece of project knowledge belongs in exactly one of the three legs. When classifying content, apply the question test: “Is this about WHAT we know, HOW we work, or WHO is involved?”
**Classification examples**:
ContentQuestionTriad Leg
”How does ancient DNA extraction work?”WHAT do we know?`what/context/`
”Mission plan for Q2 deployment”HOW do we work?`how/missions/`
”Contact info for the partnership lead”WHO is involved?`who/contacts/`
The triad is deliberately minimal. Three categories are sufficient because they map to the three dimensions of any project: its knowledge, its operations, and its people. Additional categories create sorting ambiguity.
```
flowchart TB Root["aDNA Instance"] Root --> W["what/ Knowledge"] Root --> H["how/ Operations"] Root --> O["who/ Organization"] W --> ctx["context/"] W --> dec["decisions/"] W --> dom["domain entities"] H --> mis["missions/"] H --> ses["sessions/"] H --> tpl["templates/"] O --> coord["coordination/"] O --> gov["governance/"] O --> ppl["people & teams"] style W fill:#0d9488,color:#fff style H fill:#22c55e,color:#fff style O fill:#8b5cf6,color:#fff
```
### 3.2 Bare Triad
In a bare triad deployment, `what/`, `how/`, and `who/` sit as top-level directories at the project root. Governance files sit alongside them at root level.
**When to use**: Knowledge bases, standalone agent workspaces, and any project where aDNA IS the primary content.
```
{project_root}/├── CLAUDE.md├── MANIFEST.md├── STATE.md├── AGENTS.md├── README.md├── what/├── how/├── who/└── {project_content}/
```
### 3.3 Embedded Triad
In an embedded triad deployment, the triad is wrapped inside `.agentic/` at the repository root. Governance files remain at the repository root (not inside `.agentic/`).
**When to use**: Any git-tracked codebase adding agent support. The `.agentic/` prefix follows the convention of dot-prefixed directories for meta/config in git repositories (like `.github/`, `.vscode/`).
```
{repo_root}/├── CLAUDE.md├── MANIFEST.md├── STATE.md├── AGENTS.md├── README.md├── .agentic/│ ├── AGENTS.md│ ├── what/│ ├── how/│ └── who/└── {codebase}/
```
### 3.4 Deployment Form Selection
Both deployment forms are first-class. The triad ontology is identical in both — only the physical nesting differs. CLAUDE.md in each environment bridges any path differences.
An aDNA instance MUST use exactly one deployment form. A project MUST NOT mix bare and embedded triads.
### 3.5 Directory Convention
An aDNA project directory SHOULD use the `.aDNA` suffix to indicate it follows the Agentic DNA knowledge architecture standard. This suffix serves as a visual type marker, analogous to `.app` bundles in macOS or `.git` directories in version control.
**Naming rules:**
- The base template (the `aDNA` repository, embedded in a workspace at `.adna/`) MUST NOT use the `.aDNA` suffix — it is the source, not an instance. *(Per ADR-006 repo rename `Agentic-DNA`→`aDNA` + ADR-008 airlock embedding at `.adna/`.)*
- Forked projects SHOULD use the pattern `ProjectName.aDNA/` (e.g., `zeta.aDNA/`, `my_research.aDNA/`).
- The project name portion MUST match `[a-z][a-z0-9_]{0,63}` — lowercase letters, digits, and underscores only, starting with a letter, maximum 64 characters.
- The suffix `.aDNA` uses mixed case (capital D, N, A) matching the abbreviation branding.
- Nesting `.aDNA` directories inside other `.aDNA` directories is NOT RECOMMENDED.
- Existing projects MAY adopt the convention by renaming their directory. This is optional.
**Discovery:**
Tools SHOULD discover aDNA projects via `*.aDNA` glob patterns:
```
# List aDNA projects in workspacels -d *.aDNA 2>/dev/nullfind . -maxdepth 1 -name "*.aDNA" -type d
```
**Workspace convention:**
```
~/aDNA/├── .adna/ # Base template — the aDNA standard tree (hidden; source, not an instance)├── my_research.aDNA/ # Forked project (aDNA instance)├── zeta.aDNA/ # Another project└── CLAUDE.md # Workspace-level governance
```
## 4. Governance Files
> **Scan**: Five ALLCAPS files (CLAUDE, MANIFEST, STATE, AGENTS, README) — purpose, required contents, quickstart sequences, progressive enrichment.
*Decisions: C2, C3, D1, D2, D6, D19, D25*
Every aDNA instance MUST have governance files at the project root. These are the agent’s primary orientation documents.
### 4.1 Governance File List
The following ALLCAPS files constitute the governance layer:
FileRequiredPurposeUpdate Cadence
**CLAUDE.md**MUSTAgent root context — persona, project map, safety rules, startup protocolWhen structure or protocols change
**MANIFEST.md**MUSTStatic project overview — what the project is, architecture, entry pointsWhen project scope or architecture changes
**STATE.md**SHOULDDynamic operational state — current phase, blockers, recent decisions, next stepsEvery session close-out
**AGENTS.md**MUSTRoot-level agent guide — directory purpose, key files, patternsWhen directory structure changes
**README.md**MUSTRoot-level human guide — navigation, setup, how to browseWhen onboarding experience changes
```
flowchart LR CLAUDE["CLAUDE.md Agent root context"] MANIFEST["MANIFEST.md Project overview"] STATE["STATE.md Current state"] AGENTS["AGENTS.md Directory guide"] README["README.md Human guide"] CLAUDE -->|"structure + rules"| STATE CLAUDE -->|"references"| MANIFEST STATE -->|"updated each session"| CLAUDE AGENTS -.->|"per-directory"| CLAUDE README -.->|"per-directory"| CLAUDE style CLAUDE fill:#ef4444,color:#fff style STATE fill:#eab308,color:#000 style MANIFEST fill:#3b82f6,color:#fff
```
### 4.2 CLAUDE.md — Agent Root Context
CLAUDE.md is the primary agent orientation document. It MUST exist at the project root in both deployment forms. It is auto-loaded by Claude Code and serves as the agent’s first read on every session.
**Required sections**:
- **Identity**: Project name, agent persona (if defined — see Appendix A), mission statement. The agent MUST know what project it is operating in and what role it plays.
- **Project Map**: Directory structure diagram, key files table. The agent MUST be able to navigate the project from this section alone.
- **Safety Rules**: Collision prevention tier (see §13), escalation protocol, data integrity rules. The agent MUST know what it can and cannot do.
- **Agent Protocol**: Startup checklist, session tracking rules, closure requirements. The agent MUST know how to begin and end work.
- **Quickstart**: A concise startup sequence for cold-start orientation. MUST enable a fresh agent to begin useful work within one session. Include both agent and human quickstarts:
**Agent Quickstart** (5 steps):
Read CLAUDE.md — understand project structure, safety rules, persona
- Read STATE.md — understand current phase, blockers, recent decisions
- Check `how/sessions/active/` — identify any conflicting sessions
- Check `who/coordination/` — read urgent cross-agent notes
- Create session file in `how/sessions/active/` and begin work
**Human Quickstart** (4 steps):
- Read README.md — understand what this project is and how to navigate
- Read MANIFEST.md — understand architecture and entry points
- Browse the triad (`what/`, `how/`, `who/`) — explore the knowledge structure
- Open STATE.md — see current operational status and next steps
**Optional sections** (add when relevant):
- Domain Knowledge — project-specific context the agent needs
- Working with Content — naming, metadata, linking conventions
- Machine Setup — multi-machine path patterns and tool requirements
- Environment-Specific Rules — sync, IDE, CI/CD integration
**Versioning**: CLAUDE.md SHOULD include a version comment in its header: ``. Major version for structural changes, minor for significant updates. Session history serves as the detailed changelog.
**Persona framework**: When a persona is defined, it MUST include: identity (name, role metaphor, mission), operating style (3-5 behavioral principles), and communication norms (tone, greeting/close patterns). See Appendix A for the full framework and reference implementation.
### 4.3 MANIFEST.md — Project Overview
MANIFEST.md describes what the project IS. It changes infrequently — only when project scope, architecture, or major workstreams change.
**Contents**:
- Project identity and purpose
- Architecture overview
- Key entry points and navigation
- Active missions / major workstreams (stable references, not dynamic status)
### 4.4 STATE.md — Dynamic Operational State
STATE.md captures where the project IS RIGHT NOW. It SHOULD be updated on every session close-out. It MUST be updated when phase, blockers, or priorities change.
**Contents**:
- Current phase / milestone
- Recent decisions (last 3-5)
- Active blockers
- What’s working well
- Next steps / recommended priorities
STATE.md enables fast cold-start orientation: a fresh agent reads CLAUDE.md (structure and rules) then STATE.md (current situation) and is ready to work.
### 4.5 AGENTS.md — Per-Directory Agent Guide
Every aDNA instance MUST have a root-level AGENTS.md (listed in §4.1). Beyond root, every directory where agents operate SHOULD have an AGENTS.md file. AGENTS.md is agent-facing: optimized for machine consumption with structured, scannable content.
**Lightweight core** (every AGENTS.md):
- Purpose — what this directory contains and why
- Key files — important files with brief descriptions
- Patterns — naming, structure, or workflow conventions specific to this directory
**Enrichment layers** (add as the directory matures):
- Quick reference table
- Modification guide — how to add or change content
- Dependencies — what this directory relies on
- Testing / validation notes
- Current state / recent changes
- Troubleshooting
AGENTS.md files grow through progressive enrichment: start lightweight, add detail when agents or humans repeatedly need information that is not yet documented.
### 4.6 README.md — Per-Directory Human Guide
README.md is human-facing: optimized for browsing in GitHub, an IDE, or a knowledge-base tool. It complements AGENTS.md by providing navigation context for humans.
Every aDNA instance MUST have a root README.md. Subdirectory README.md files are OPTIONAL — create them when human navigation would benefit.
## 5. Directory Structure
> **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**:
DirectoryPurpose
`context/`Agent context library — synthesized knowledge agents load before domain work
**Recommended subdirectories**:
DirectoryPurpose
`decisions/`Architecture Decision Records (ADRs) — significant decisions and their rationale
**Optional subdirectories** (add based on project domain):
DirectoryPurpose
`reference/`Bounded exception for code-adjacent reference material (see §19.5)
`inventory/`Installed/configured state — vaults, system, memberships. Base WHAT type since v2.3 (ADR-035); markdown + paired `.yaml` companion.
`{domain}/`Project-specific knowledge: `models/`, `hardware/`, `datasets/`, `specs/`, etc.
**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: modelstatus: activesource: "src/models/llama3/" # link to implementationtags: [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**:
DirectoryPurpose
`coordination/`Cross-agent notes — handoffs, urgency signals, ephemeral coordination
`governance/`Team roles, decision authority, policies, escalation paths
**Optional subdirectories** (add based on organizational needs):
DirectoryPurpose
`identity/`Stable identity records validated against external reality — node / network / deployment (hostname, operator, persistent UUID, peer-id). Base WHO type since v2.3 (ADR-035); markdown + paired `.yaml` companion.
`{domain}/`Project-specific organization: `customers/`, `partners/`, `contacts/`, `communications/`, `roadmap/`
### 5.3 how/ — Operations Layer
how/ contains everything about HOW the project works.
**Required subdirectories**:
DirectoryPurpose
`missions/`Missions — objective decomposition, dependencies, claiming protocol
`sessions/`Session tracking — execution records with SITREP close-outs
`templates/`Reusable templates for all aDNA file types
**Recommended subdirectories**:
DirectoryPurpose
`backlog/`Ideation and improvement tracking (see §19.2)
**Optional subdirectories**:
DirectoryPurpose
`pipelines/`Content-as-code workflows (see §14)
`tasks/`Granular task tracking
`skills/`Reusable agent procedures (see §19.3)
`processes/`Human-readable workflow documentation
`deliverables/`Output artifacts
`federation/`Consumer federation wrappers — one `/` per federated software-element/service graph (v2.5, ADR-045)
### 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:
- **Governance files**: `CLAUDE.md`, `MANIFEST.md`, `README.md` at the root (bare) or repository root (embedded)
- **Triad directories**: `what/`, `how/`, `who/` (bare) or `.agentic/what/`, `.agentic/how/`, `.agentic/who/` (embedded)
- **Required subdirectories**: `what/context/`, `how/missions/`, `how/sessions/`, `how/templates/`, `who/coordination/`, `who/governance/`
- **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:
- **Additional governance files**: `STATE.md` and a root `AGENTS.md`
- **Per-directory AGENTS.md**: Every triad leg (`what/`, `how/`, `who/`) MUST have an `AGENTS.md` file
- **Recommended directories**: `what/decisions/`, `how/backlog/`, `how/sessions/active/`, `how/sessions/history/`
- **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:
- **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
- **FAIR metadata**: Deployable objects (modules, datasets, lattices) MUST include a `fair:` frontmatter block with at minimum `keywords` and `license`
- **Ontology artifact**: `what/ontology.md` MUST exist with a Mermaid ER diagram (per §5.1)
- **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.
## 6. Naming Conventions
> **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.
## 7. Frontmatter System
> **Scan**: Required base fields (`type`, `status`, `created`, `updated`, `last_edited_by`, `tags`), tag conventions, priority field, type-specific extensions.
*Decisions: C4, D18, D20*
### 7.1 Scope
YAML frontmatter MUST be present on all aDNA content files — files inside the triad (`what/`, `how/`, `who/` or `.agentic/what/`, etc.) and root governance files.
Project content files (source code, external documentation) outside the triad are exempt from frontmatter requirements.
### 7.2 Required Base Fields
Every aDNA content file MUST include these frontmatter fields:
```
---type: status: created: YYYY-MM-DDupdated: YYYY-MM-DDlast_edited_by: agent_ | tags: []---
```
FieldPurpose
`type`Entity classification (e.g., `session`, `mission`, `customer`, `context_research`)
`status`Lifecycle state (e.g., `active`, `completed`, `draft`, `abandoned`) — entity-specific values
`created`Date of file creation
`updated`Date of last modification — critical for collision prevention
`last_edited_by`Attribution — who or what last modified this file
`tags`Categorization array for filtering and discovery
**Per-class profile** (v2.5, ADR-044): the six base fields are required for content and session entities. **`status` is optional for `type: directory_index` and `type: coordination`** — an index or correspondence record has no lifecycle state, and their canonical templates omit it. The other five base fields remain required for all classes.
### 7.3 Tag Conventions
Tags MUST use lowercase with underscores (e.g., `mission`, `context_research`).
Every aDNA content file MUST have at least one tag (the type tag is sufficient).
No formal tag registry is prescribed. Projects SHOULD document their tag conventions in AGENTS.md files when the tag set exceeds a dozen unique tags.
### 7.4 Priority Field
Content items that need prioritization (tasks, backlog ideas, customers) MAY include a `priority` field using a simple numeric scale: `0` (highest) through `N` (lowest).
Rule/guardrail conflict resolution is a separate concern. Projects that need rule precedence SHOULD define their own mechanism in CLAUDE.md or governance files.
### 7.5 Type-Specific Fields
Templates (§12) define additional frontmatter fields per content type. For example, a session template adds `session_id`, `plan_id` (legacy field name), `tier`; a customer template adds `segment`, `deal_stage`, `contacts`.
Frontmatter is the integration layer between human tools (Dataview queries, IDE search) and agent queries. Consistent frontmatter enables consistent querying across any tool.
### 7.6 Frontmatter Extension Policy
Instance-specific frontmatter fields MAY be added to any entity type. The following rules govern extensions:
- **Custom fields** MAY be added freely to any content file’s frontmatter
- Custom fields SHOULD use a project-specific prefix (e.g., `bio_target_class`, `crm_deal_stage`) when the field name could conflict with future standard fields
- Standard fields (those defined in §7.2 and per-type templates) MUST NOT be repurposed to carry different semantics
- Migration tools MUST preserve custom fields — standard version upgrades MUST NOT strip unrecognized frontmatter fields
- Projects SHOULD document their custom fields in the relevant `AGENTS.md` or template files
### 7.7 Decision-Record Ratification Discipline
Decision records (ADRs, `what/decisions/`) carry a lifecycle `status` whose advancement beyond `proposed` is a **human** act. Effective v2.5 (ADR-046, folding the discipline installed after an agent thread self-marked an ADR `accepted` without an operator gate):
- **Agents author; operators ratify.** An agent MAY fully author an ADR — context, decision, consequences, alternatives, references — and MAY set or keep `status: proposed` (or `draft`). An agent MUST NOT set `accepted`, `ratified`, or `rejected`; those transitions require an operator gate.
- **Ratification record.** Any ADR moving beyond `proposed` MUST carry a structured ratification block with all four fields present and non-empty:
**Ratifier** — the named human operator/authority. An agent or persona may be named only as author/steward, never as ratifier.
- **Gate / reference** — a verifiable pointer to the discrete ratification event: the gate file and/or its output record, the ratifying session id, and/or the ratifying commit.
- **Ratification date** — distinct from the authored/created date.
- **Scope of authority** — exactly what the ratification authorizes, plus any pending co-signs that keep seams non-operative.
- **Retroactivity.** ADRs accepted before v2.5 SHOULD be backfilled with ratification blocks; a pre-v2.5 accepted ADR without one is NOT thereby non-conformant. *(This clause is what keeps the v2.5 cut a minor version under §15.4.)*
- **Batch ceremonies.** An N-ADRs-at-once ratification ceremony MAY substitute a single ceremony record for per-ADR gate references, provided each covered ADR’s block points to it.
- **Validation.** Conformance tooling SHOULD check structure only — the four fields present and non-empty — never the truth of the gate; truth is the operator’s, at the gate. Recommended rollout: warn first, promote to fail after a backfill pass.
- **Exemption.** Lifecycle-neutral back-references (e.g., adding `superseded_by` once the superseding ADR is itself ratified) are exempt from rule 1.
## 8. Session Model
> **Scan**: Bounded units of agent work — lifecycle (create → execute → close → archive), session tiers, SITREP close-out, next-session prompt, the 75% rule.
*Decisions: D3, D4, D5*
### 8.1 Session Lifecycle
A session is a bounded unit of agent work. Every session follows this lifecycle:
- **Create**: Write a session file in `how/sessions/active/`
- **Execute**: Perform work, logging activity
- **Close**: Write SITREP + next-session prompt
- **Archive**: Set `status: completed`, move to `how/sessions/history/YYYY-MM/`
A session file MUST be created before an agent modifies any other project files. This is the audit trail.
```
stateDiagram-v2 [*] --> Create: Agent starts work Create --> Active: Session file written Active --> Active: Work + log activity Active --> Close: SITREP written Close --> Archive: Move to history/YYYY-MM/ Archive --> [*] state Active { [*] --> Working Working --> Working: Modify files Update frontmatter }
```
### 8.2 Session ID Format
Session IDs MUST use the timestamped format:
```
session_{user}_{YYYYMMDD}_{HHMMSS}_{descriptor}
```
Example: `session_{username}_20260211_120000_gap_analysis`
Timestamped IDs are machine-sortable, collision-free across agents, and self-documenting. The descriptor SHOULD be a brief lowercase-underscore slug describing the session’s purpose.
### 8.3 Session Tiers
TierWhenRequirements
**Tier 1** (default)Normal content workSession file with intent, activity log, SITREP close-out
**Tier 2**Shared config edits (governance files, plugin configs)Tier 1 requirements + scope declaration + conflict scan + heartbeat
Tier 1 is a lightweight audit trail. Tier 2 adds coordination safeguards for edits that affect shared infrastructure.
Sessions MAY include a **Technical Readiness Review (TRR)** quality gate before close-out — a structured check that deliverables meet acceptance criteria. TRR is particularly useful for code-generation sessions or sessions producing artifacts that downstream tasks depend on.
### 8.4 SITREP Close-Out
Every session MUST end with a SITREP:
```
## SITREP**Completed**: [what was finished]**In progress**: [what was started but not finished, with handoff notes]**Next up**: [recommended next actions]**Blockers**: [anything preventing progress]**Files touched**: [created, modified, moved]
```
### 8.5 Next-Session Prompt
Every session MUST include a next-session prompt after the SITREP:
```
## Next Session Prompt[Self-contained paragraph that a fresh agent can read to continue this work.Include: what was accomplished, what remains, key context, recommended approach.]
```
The next-session prompt ensures continuity. A fresh agent reading this prompt and STATE.md SHOULD be able to continue the work without needing to read the full session history.
### 8.6 STATE.md Update
STATE.md SHOULD be updated on every session close. It MUST be updated when the current phase, blockers, or priorities change.
### 8.7 The 75% Rule
Agents MUST scope each session to use no more than approximately 75% of the context window. The remaining 25% is reserved for thinking, debugging, and course correction.
If a task requires more than 75% of the context window, the agent MUST split the work across sessions, checkpointing progress in the session close-out.
No other session sizing prescriptions are universal. Time, task count, and line-count guidelines are project-specific — different work paradigms (code generation, knowledge synthesis, CRM maintenance) have different natural session sizes.
## 9. Mission System
> **Scan**: Multi-session work decomposition — objectives, acceptance criteria, stages, claiming protocol, handoff between agents.
*Decisions: D12, D16, D17*
### 9.1 Mission Structure
Missions live in `how/missions/`. A mission decomposes work that spans multiple sessions into trackable objectives.
**Single-file missions** (small scope):
```
how/missions/mission_simple_task.md
```
**Subdirectory missions** (large scope with deliverables):
```
how/missions/mission_complex_project/├── mission_complex_project.md # Master mission├── deliverable_a.md # Phase/deliverable files└── deliverable_b.md
```
The mission file MUST include:
- **Objectives**: What the mission achieves
- **Acceptance criteria**: How you know it is done
- **Constraints**: What limits apply (time, scope, dependencies)
- **Objective list**: Individual objectives with dependencies and status
- **Status tracking**: Per-objective status (pending, in_progress, completed, blocked)
### 9.2 Mission Stages
Missions MAY define stage-based subdirectories for multi-phase work:
```
how/missions/{mission_slug}/├── mission_{slug}.md├── 00_research/├── 01_requirements/├── 02_design/└── 03_implementation/
```
Stage names and count are mission-specific. The convention is: numbered prefix for ordering, descriptive name for clarity.
### 9.3 Mission Handoff
Agents claim mission objectives by session. A session file’s `plan_id` and `task` frontmatter fields (legacy names, retained for compatibility) link it to the mission. When an objective spans multiple sessions, each session’s SITREP provides the handoff. Agents MUST NOT claim objectives already in progress by another active session.
## 10. Context Library
> **Scan**: `what/context/` organization — topic structure, context subtypes (research, guide, core), token budget awareness and the 75% rule.
*Decisions: D8*
### 10.1 Location and Structure
The context library lives in `what/context/`. It is the single location for all agent context — synthesized knowledge that agents load before domain work.
```
what/context/├── AGENTS.md # Library protocol, topic index, token budgets├── {topic}/│ ├── AGENTS.md # Topic overview, subtopic index│ ├── subtopic_a.md│ └── subtopic_b.md└── {topic}/ └── ...
```
### 10.2 Context Subtypes
Context files use the `type` frontmatter field to distinguish content subtypes:
SubtypePurposePattern
`context_research`Synthesized domain knowledge from external sourcesDense, citational, comprehensive
`context_guide`Prescriptive component or tool guidesStep-by-step, actionable, reference-oriented
`context_core`Foundational project definitions (conventions, guardrails, stack)Concise, authoritative, rarely changing
All subtypes coexist in `what/context/` organized by topic. The subtype informs how agents use the content, not where it lives.
### 10.3 Token Budget Awareness
The context library AGENTS.md SHOULD include token estimates per topic in a scannable format:
```
| Topic | ~Tokens | Subtopics ||-------|---------|-----------|| ancient_dna | ~8,000 | extraction, sequencing, analysis || compute_infra | ~5,000 | gpu_clusters, edge_devices |
```
Agents MUST read the topic index first and load only the subtopics needed for the current task. Loading the entire context library into a single session is wasteful and violates the 75% rule (§8.7).
## 11. Coordination Protocol
> **Scan**: `who/coordination/` for cross-agent communication — urgency levels (urgent/info/fyi), ephemeral notes, required contents.
*Decisions: D9*
### 11.1 Cross-Agent Coordination
Cross-agent notes live in `who/coordination/`. This is the single location for agent-to-agent communication.
Coordination notes are **ephemeral by design**: created when needed, consumed by the target agent, and archived when resolved.
### 11.2 Urgency Levels
LevelMeaningWhen to Read
`urgent`Immediate action neededRead before any other work
`info`Important contextRead during startup checklist
`fyi`Non-blocking background informationRead when convenient
### 11.3 Coordination Note Contents
A coordination note MUST include:
- **Who** created it and who it targets
- **What** the coordination concern is
- **When** it was created and when it expires
- **Action needed** — what the target agent should do
Agents MUST check `who/coordination/` during every session startup.
## 12. Template System
> **Scan**: Graduated template sets (starter/standard/full), `template_{type}.md` naming, template index recommendation.
*Decisions: D11*
### 12.1 Graduated Template Sets
Templates live in `how/templates/`. Projects grow their template sets:
**Starter set** (every aDNA instance MUST include):
TemplatePurpose
`template_session.md`Session file with SITREP and next-session prompt sections
`template_mission.md`Mission with objectives, acceptance criteria, objective list
`template_context.md`Context library file with topic structure and token estimate
**Standard set** (SHOULD include for active multi-agent projects):
TemplatePurpose
`template_coordination.md`Cross-agent coordination note
`template_backlog.md`Backlog idea with priority, effort, status
`template_adr.md`Architecture Decision Record
**Full set** (MAY include per project domain):
Additional templates for domain-specific content types (customer, partner, model, dataset, etc.).
### 12.2 Template Conventions
Templates MUST follow the naming pattern `template_{type}.md`.
Templates MUST include frontmatter with all required base fields (§7.2) plus type-specific fields pre-populated.
A template index (e.g., `template_library.md` in `how/templates/`) is RECOMMENDED for projects with 5 or more templates.
## 13. Collision Prevention
> **Scan**: Three tiers — universal (frontmatter attribution, read-before-write), sync (file safety tiers, archive-don’t-rename), multi-agent (coordination notes, scope declarations).
*Decisions: D7*
### 13.1 Overview
Collision prevention protects against data loss when multiple agents or humans modify the same files. The system is tiered — projects adopt the tiers they need.
```
flowchart TB T1["Tier 1 — Universal Every aDNA instance"] T2["Tier 2 — Sync Environments Cloud storage, team sync"] T3["Tier 3 — Multi-Agent Concurrent agents"] T1 --> A1["Frontmatter attribution"] T1 --> A2["Read-before-write"] T1 --> A3["New-file safety"] T1 --> A4["No harness-injected context"] T2 --> B1["File safety tiers"] T2 --> B2["Archive-don't-rename"] T2 --> B3["One config at a time"] T3 --> C1["Coordination notes"] T3 --> C2["Scope declarations"] T3 --> C3["Update-field check"] T1 -.->|extends| T2 T2 -.->|extends| T3 style T1 fill:#22c55e,color:#fff style T2 fill:#eab308,color:#000 style T3 fill:#ef4444,color:#fff
```
### 13.2 Tier 1 — Universal
Every aDNA instance MUST implement Tier 1:
- **Frontmatter attribution**: Every file modification MUST update `last_edited_by` and `updated` in frontmatter.
- **Read-before-write**: Agents MUST read current file content immediately before writing. Never rely on cached reads.
- **New-file safety**: Creating a new file has no collision risk. New files are always safe.
- **No harness-injected context**: Governance files (`CLAUDE.md`/`STATE.md`/`AGENTS.md`) MUST NOT carry committed **harness context boundaries** — the `# userEmail` and `# currentDate (Today's date is …)` lines an agent harness injects into a running session. They are session context, not governance: once committed they are stale and information-free (the email lives in the credential broker; the date is a frozen snapshot). Strip them before committing; a session that commits a governance file MUST drop any injected tail. (ADR-042.)
### 13.3 Tier 2 — Sync Environments
Projects using file sync (cloud storage, team sync tools) SHOULD additionally implement:
- **Safety tiers**: Classify files as Safe (content — low collision risk), Shared Config (governance, plugin configs — medium risk), or Volatile (auto-generated files like `workspace.json` — do not attempt to maintain).
- **Archive-don’t-rename**: Move files to `archive/` instead of renaming. Sync systems handle renames poorly.
- **One config at a time**: Edit one shared config file, verify the write, then move to the next.
### 13.4 Tier 3 — Multi-Agent
Projects with multiple agents operating simultaneously SHOULD additionally implement:
- **Coordination notes**: Use `who/coordination/` (§11) for strategic cross-agent communication.
- **Session scope declarations**: Tier 2 sessions declare which files/directories they will modify.
- **Update-field check**: Before modifying a file where `updated` is today and `last_edited_by` is not you, confirm with the user before overwriting.
## 14. Content-as-Code Pipelines
> **Scan**: Folder-based workflows where a file’s directory location IS its processing state — pipeline structure, stage AGENTS.md, pipeline index.
*Decisions: D14*
### 14.1 Paradigm
Content-as-code is a universal paradigm for folder-based workflows: a file’s directory location IS its processing state. Moving a file between stage directories advances it through the workflow.
This paradigm applies wherever content flows through defined stages — research ingestion, document review, approval workflows, deployment pipelines.
```
stateDiagram-v2 direction LR [*] --> inbox: New content inbox --> processing: Agent picks up processing --> review: Processing complete review --> done: Approved review --> processing: Revision needed done --> [*] note right of inbox: AGENTS.md defines acceptance criteria note right of processing: AGENTS.md defines processing steps note right of review: AGENTS.md defines review checklist
```
### 14.2 Pipeline Structure
Pipelines live in `how/pipelines/{pipeline_name}/`:
```
how/pipelines/{pipeline_name}/├── AGENTS.md # Pipeline overview, stage transitions├── inbox/ # Stage 1│ └── AGENTS.md # Processing instructions for this stage├── processing/ # Stage 2│ └── AGENTS.md├── review/ # Stage 3│ └── AGENTS.md└── done/ # Stage 4 └── AGENTS.md
```
Each stage folder MUST have an AGENTS.md with processing instructions specific to that stage.
Stage names and count are pipeline-specific. The file’s location is its state — no separate status tracking is needed.
### 14.3 Pipeline Index
The `how/pipelines/` directory SHOULD have an AGENTS.md documenting all pipelines, their purposes, and their stage flows.
## 15. Archive & Versioning
> **Scan**: Archive patterns for sync vs. git environments, retention policy, CLAUDE.md version tracking convention.
*Decisions: C9, C10*
### 15.1 Archive Pattern
The archive pattern varies by environment:
**Sync environments** (cloud storage, team sync tools):
- Archive directories within content folders (e.g., `how/backlog/archive/`)
- Session history uses `how/sessions/history/YYYY-MM/`
- Archive-don’t-rename rule: move to `archive/` instead of renaming files
- Project-level `archive/` within the nearest triad directory for vault-level archival
**Git repositories**:
- Git history serves as the primary archive
- `archive/` subdirectories for visibly-deprecated items (documents users should see are retired)
- Session history follows the same `YYYY-MM/` pattern regardless of environment
### 15.2 Retention
Session history SHOULD NOT be auto-deleted. Manual cleanup after 6 months is acceptable if storage is a concern.
### 15.3 Versioning
aDNA instances track their own version via a comment in CLAUDE.md: ``.
Major version increments indicate structural changes. Minor version increments indicate significant content updates. Session history serves as the detailed changelog — no formal CHANGELOG.md is required.
### 15.4 Standard Versioning & Backwards Compatibility
The aDNA standard uses two versioning tracks:
- **Standard version** (this document, `adna_standard.md`): Governs the normative specification — triad architecture, required files, conformance levels, naming conventions. Follows semantic versioning: `vMajor.Minor`.
- **Governance version** (`CLAUDE.md` `version` field, `CHANGELOG.md`): Governs the operational implementation — protocols, templates, skills, tooling. Follows `Major.Minor` versioning.
**Backwards compatibility promise**:
- Standard **minor** versions (e.g., v2.0 → v2.1) MUST NOT invalidate conformant instances. An instance conformant to aDNA v2.0 MUST remain conformant to aDNA v2.1.
- Standard **major** versions (e.g., v2.x → v3.0) MAY introduce breaking changes. When they do, migration guidance MUST be provided.
- Governance version changes are operational and do not affect standard conformance.
**Version-cut checklist** (v2.5, ADR-046 — the footer-lag anti-recurrence rule): on every version bump, the document’s four version-bearing surfaces MUST agree before the cut commits — (1) the frontmatter `title`, (2) the frontmatter `updated` date, (3) a new changelog comment line in the header block, and (4) the *End of …* footer line. A cut that leaves any of the four stale is incomplete. *(This rule exists because the footer lagged the title across multiple historical bumps — most recently shipping “v2.3” inside the published v2.4 document.)*
## 16. Tool Integration Tiers
> **Scan**: Three tiers — core standard (Tier 1, universal), frontmatter querying (Tier 2, any YAML reader), environment-specific (Tier 3, IDE/plugin). Aggregation points.
*Decisions: C13, D22*
### 16.1 Three-Tier Model
TierScopeExamplesUniversal?
**Tier 1**Core standardYAML frontmatter, markdown, directory structure, naming conventionsYes — works with any tool
**Tier 2**Frontmatter queryingDataview, custom scripts, CI/CD that reads frontmatterRecommended — any tool that parses YAML
**Tier 3**Environment-specificIDE extensions, knowledge-base plugins, graph view, canvasNo — tool-specific
Everything in this standard is Tier 1 unless noted otherwise. Tier 1 features work with any tool that can read files and directories.
```
flowchart TB subgraph T1["Tier 1 — Core Standard (Universal)"] F1["YAML frontmatter"] F2["Markdown files"] F3["Directory structure"] F4["Naming conventions"] end subgraph T2["Tier 2 — Frontmatter Querying"] F5["Dataview queries"] F6["Shell scripts"] F7["CI/CD pipelines"] end subgraph T3["Tier 3 — Environment-Specific"] F8["Obsidian plugins"] F9["IDE extensions"] F10["Graph / canvas views"] end T1 -->|"any YAML reader"| T2 T2 -->|"specific tools"| T3 style T1 fill:#22c55e,color:#fff style T2 fill:#3b82f6,color:#fff style T3 fill:#8b5cf6,color:#fff
```
### 16.2 Aggregation Points
The following cross-directory views are useful in any aDNA instance. Their implementation is Tier 2/3 (tool-specific):
Aggregation PointAggregatesPurpose
Active missions overview`how/missions/`All missions with current status
Context index`what/context/`All topics with token budgets
Session history`how/sessions/history/`Recent sessions with outcomes
Coordination status`who/coordination/`Active cross-agent notes
Implementation examples: Dataview queries, shell scripts that parse frontmatter, CI/CD dashboard panels. Any tool that can read YAML frontmatter can implement these views.
## 17. Error & Recovery Protocol
> **Scan**: Three-tier response — data integrity threat (STOP + escalate), state inconsistency (fix + log), process issue (workaround + backlog).
*Decisions: D24*
### 17.1 Tiered Response
SeverityTriggerResponseRecovery
**Tier 1 — Data integrity threat**Corrupt file, data loss, conflicting writes destroying contentStop all writes immediately. Document the issue. Do NOT attempt automated repair. Escalate to human with `#needs-human` tag.Human-guided only
**Tier 2 — State inconsistency**Stale STATE.md, broken cross-references, missing frontmatterAttempt recovery: re-read files, reconcile state, add missing fields. Log the issue and recovery action in session file. Continue work.Agent-recoverable with documentation
**Tier 3 — Process issue**Template not found, naming violation, ambiguous pipeline stageNote the issue in session file. Work around it. Create a backlog idea for improvement.Work around, improve later
```
flowchart LR E["Error detected"] --> S1{"Data at risk?"} S1 -->|Yes| T1["Tier 1: STOP Escalate to human"] S1 -->|No| S2{"State inconsistent?"} S2 -->|Yes| T2["Tier 2: Fix + log Continue work"] S2 -->|No| T3["Tier 3: Note + workaround Backlog idea"] style T1 fill:#ef4444,color:#fff style T2 fill:#eab308,color:#000 style T3 fill:#22c55e,color:#fff
```
### 17.2 Escalation
Agents MUST log blockers with the `#needs-human` tag when:
- Data integrity is at risk (Tier 1 errors)
- A decision exceeds the agent’s authority
- Ambiguous scope could lead to destructive actions
Agents MUST NOT proceed with destructive or irreversible actions when uncertain. When in doubt, stop and ask.
## 18. Success Criteria
> **Scan**: Three levels — minimum viable (cold start, handoff, integrity), recommended (fork, scale, consistency), aspirational (network, collision safety, dual-audience).
*Decisions: D21*
```
flowchart TB subgraph MIN["Minimum Viable (MUST)"] M1["Cold Start"] M2["Handoff"] M3["Integrity"] end subgraph REC["Recommended (SHOULD)"] R1["Fork"] R2["Scale"] R3["Consistency"] end subgraph ASP["Aspirational"] A1["Network"] A2["Collision Safety"] A3["Dual-Audience"] end MIN -->|mature| REC REC -->|excellent| ASP style MIN fill:#22c55e,color:#fff style REC fill:#3b82f6,color:#fff style ASP fill:#8b5cf6,color:#fff
```
### 18.1 Minimum Viable (every aDNA MUST pass)
- **Cold Start**: A fresh agent reads CLAUDE.md, then STATE.md (if present), and begins useful work within one session. No prior project knowledge is required.
- **Handoff**: Agent A closes a session with SITREP + next-session prompt. Agent B reads the close-out and STATE.md and continues the work seamlessly.
- **Integrity**: No data corruption or silent overwrites during multi-agent operation with collision prevention active.
### 18.2 Recommended (mature aDNA SHOULD pass)
- **Fork**: The aDNA structure can be copied to a new project and adapted with only CLAUDE.md and domain content changes.
- **Scale**: The aDNA supports 10+ missions, 50+ sessions, and 100+ content files without navigational degradation.
- **Consistency**: Both deployment forms (bare and embedded) feel like the same system to agents and humans.
### 18.3 Aspirational (excellent aDNA)
- **Network**: Multiple aDNA instances can discover and reference each other via documented patterns.
- **Collision Safety**: Multi-agent concurrent operation produces no data loss even under heavy write contention.
- **Dual-Audience**: Both humans (IDE, GitHub, knowledge-base tools) and agents find the content navigable and useful.
## 19. Optional Extensions
> **Scan**: Six opt-in subsystems — machine registry, backlog, skill files, testing/CI awareness, reference code, ADRs. Adopt based on need.
The following patterns are available but not required. Projects adopt them based on need.
### 19.1 Machine Registry
*Decision: D10*
For projects running on multiple machines or sync environments where path patterns vary.
**Location**: `what/hardware/machines/` or a similar what/ subfolder.
**Per-machine file contents**: hostname, user, OS, path patterns, installed tools, capabilities.
RECOMMENDED for sync-based environments (cloud storage, team sync tools) where file paths differ across machines. OPTIONAL for git repositories where environment variables handle path differences.
### 19.2 Backlog System
*Decision: D13*
Durable ideation and improvement tracking.
**Location**: `how/backlog/`
**Lifecycle**: idea → triage (priority/effort assessment) → graduation to `how/missions/` or archive.
**Frontmatter**: `type: idea`, `category`, `priority`, `effort`, `status`, `proposed_by`.
Agents SHOULD scan `how/backlog/` during session startup for ideas relevant to the current work. New ideas discovered during work SHOULD be captured as backlog files.
### 19.3 Skill Files
*Decision: D15*
Reusable agent procedures — step-by-step instructions agents can follow autonomously.
**Location**: `how/skills/skill_{name}.md`
**Sections**: purpose, prerequisites, steps, verification, rollback, notes.
Skills are distinct from processes: skills are agent-executable (precise steps, verification checks); processes are human-readable (guidelines, decision trees).
### 19.4 Testing/CI Awareness
*Decision: D23*
aDNA does not prescribe test frameworks or CI/CD configurations — these belong to the project content layer. However, agents SHOULD be aware of test status.
**Awareness pattern**:
- CLAUDE.md includes an optional section on testing: where to check, how to run, what signals mean
- AGENTS.md for code directories includes testing guidance as an enrichment layer
- STATE.md reports test status when relevant (pass/fail, coverage, regressions)
- CI/CD configuration lives in project content (`.github/`, `Makefile`, `pyproject.toml`, etc.)
### 19.5 Reference Code
*Decision: C11*
Bounded exception for code-adjacent reference material inside the aDNA structure.
**Location**: `what/reference/`
**Rules**:
- Executable code MUST live in `what/reference/` or in the project content layer — nowhere else in the triad
- what/reference/ MUST be bounded — no unbounded growth
- Entries SHOULD link to source implementations rather than duplicating code
- Documentation-only projects skip this entirely
### 19.6 Architecture Decision Records (ADRs)
*Decision: C12*
Lightweight records of significant project decisions.
**Location**: `what/decisions/`
**Template sections**: context, decision, consequences.
ADRs are knowledge artifacts — decisions outlive the process that produced them. A 2-year-old ADR is reference knowledge, not an active operation. This is why they live in what/, not how/.
## 20. Appendices
> **Scan**: Persona framework (App A), aggregation points (App B), deferred topics (App C), decision traceability matrix (App D — 40 decisions mapped to spec sections).
### Appendix A: Persona Framework
*Decision: D6*
A persona is OPTIONAL but structured when present. The persona framework defines what a persona includes and why it matters — consistency, predictability, and character continuity across sessions.
#### A.1 Framework Structure
SectionContentsPurpose
**Identity**Name, role metaphor, mission statementEstablish who the agent is in this project
**Operating Style**3-5 behavioral principlesDefine predictable working patterns
**Communication Norms**Tone, formatting, greeting/close patternsEnsure consistent interaction style
**Domain Awareness**What the persona should know about the project domainGround the agent in project context
#### A.2 Reference Implementation
The following is a reference persona. Projects MAY adopt it directly or use the framework to create their own.
**Identity**: Chief of staff to the operation — a role inspired by the military chief of staff archetype, who turns strategic vision into operational reality.
**Operating Style**:
- Orient first, act second — assess the operational picture before diving into any task
- Think in lines of effort — maintain awareness across parallel workstreams
- Be direct and precise — clear status updates, early risk flags, recommendations with rationale
- Coordinate, don’t just execute — coherence across the full operation matters more than speed on any single task
**Communication Norms**: Direct, no filler. Structured updates (SITREP format). Greets with operational state summary on planning sessions. Proceeds directly on execution sessions.
**Domain Awareness**: Defined per project in CLAUDE.md.
### Appendix B: Aggregation Points
*Decision: D22*
Standard aggregation points for cross-directory views. Implementation is tool-specific (Tier 2/3).
PointSourceQuery Pattern
**Active missions**`how/missions/`All files where `type: mission` and `status: active`
**Context index**`what/context/`All topic directories with their AGENTS.md token estimates
**Recent sessions**`how/sessions/history/`Last 10 session files, sorted by `updated` descending
**Open coordination**`who/coordination/`All files where `status: open` or `status: urgent`
**Backlog overview**`how/backlog/`All files where `type: idea` and `status: active`, sorted by `priority`
**Knowledge-base implementation**: Dataview queries in bridge pages (e.g., `how/missions.md`, `how/context_library.md`).
**Script implementation**: Any tool that parses YAML frontmatter from markdown files can produce these views.
### Appendix C: Deferred Topics
The following topics were identified during the planning arc but deferred from v1.0. They are acknowledged here for future standard revisions. (Retained from v1.0; no new deferrals in v2.0.)
GapTopicDisposition
G2**Multi-model / model-agnostic design**”CLAUDE.md” is a convention name — projects using other models use the same structure. The persona framework (§ App A) is model-agnostic. A future revision MAY define model-neutral naming.
G3**Documentation generation**Projects that generate external-facing docs from aDNA content will develop project-specific patterns. No universal standard needed at this time.
G7**Context staleness detection**The `updated` field + session cycling naturally address staleness (fresh reads on each session start). Formal staleness detection is Tier 2/3 tooling, not a standard concern.
G8**Cross-instance aDNA awareness**Addressed by bridge patterns (informational companion, SHOULD-level guidance). Defines composition patterns (nesting, sibling, monorepo), discovery protocol, scope boundaries, cross-referencing conventions, and agent behavior rules. Addresses §18.3 #7 Network criterion.
G10**Agent capability declaration**Most aDNA instances target specific agent capabilities. CLAUDE.md can note capability assumptions. A formal capability schema is deferred pending broader agent ecosystem maturity.
### Appendix D: Decision Traceability Matrix
This appendix maps every design decision to its location in the standard, ensuring complete coverage.
#### D.1 Structural Decisions (C1-C15)
IDDecisionSpec Section(s)
C1Pattern-appropriate deployment (bare + embedded triad)§3.2, §3.3, §3.4
C2Dual-file: AGENTS.md + README.md everywhere§4.5, §4.6
C3Vault naming + repo exceptions, ALLCAPS governance list§6.1, §6.2, §6.3, §6.4
C4Frontmatter mandatory for aDNA content, optional for project§7.1, §7.2
C5what/ context/ mandatory, rest project-specific§5.1
C6who/ coordination/ + governance/ mandatory§5.2
C7how/ tiered: missions/sessions/templates required, backlog recommended§5.3
C8Seeding guidance via triad principle, not prescriptive table§3.1 (triad question test)
C9Git-supplemented archive§15.1
C10Lightweight versioning in CLAUDE.md, sessions as changelog§15.3
C11what/reference/ as bounded exception for code§19.5
C12ADRs in what/decisions/§19.6
C13Tiered tool integration (Tier 1/2/3)§16.1
C14Ontology artifact: Mermaid (Tier 1) + Canvas (Tier 3)§5.1 (ontology artifact)
C15what/ as registry layer§5.1 (registry pattern)
#### D.2 Process Decisions (D1-D25)
IDDecisionSpec Section(s)
D1Universal CLAUDE.md template, required + optional sections§4.2
D2Separate MANIFEST.md + STATE.md§4.3, §4.4
D3Session model with environment enrichments§8.1, §8.2, §8.3
D4SITREP + mandatory next-session prompt§8.4, §8.5
D575% rule only, no sizing prescriptions§8.7
D6Persona framework with reference implementation§4.2 (persona), App A
D7Tiered collision prevention (universal/sync/multi-agent)§13
D8Flexible what/context/ with subtypes§10
D9who/coordination/ only§11
D10Machine registry as optional extension§19.1
D11Graduated template set (Starter/Standard/Full)§12
D12Separated missions + subdirectories§9
D13Backlog recommended, not required§19.2
D14Content-as-code paradigm universal, pipelines optional§14
D15Skill files optional in how/skills/§19.3
D16Generalized mission stages§9.2
D17Lightweight requirements in missions, full specs as extension§9.1 (mission contents)
D18Minimal tag rules, no formal taxonomy§7.3
D19Progressive enrichment for AGENTS.md§4.5
D20Separate content priority (0-N) from rule precedence§7.4
D21Tiered success criteria (minimum/recommended/aspirational)§18
D22Aggregation points identified, implementation tool-specific§16.2, App B
D23Testing/CI as project-specific with awareness pattern§19.4
D24Tiered error/recovery protocol§17
D25Quickstart in CLAUDE.md + README.md§4.2 (quickstart section)
#### D.3 Gap Dispositions (G1-G12)
GapTopicDispositionLocation
G1Testing/CI integrationAddressed by D23§19.4
G2Multi-model designDeferredApp C
G3Documentation generationDeferredApp C
G4Versioning/changelogAddressed by C10§15.3
G5Team roles/governanceSubsumed into C6 (who/governance/)§5.2
G6Error/recovery protocolAddressed by D24§17
G7Context stalenessDeferred (subsumed into D5/D7)App C
G8Cross-instance awarenessAddressed by bridge patterns (informational)App C
G9Onboarding/bootstrapAddressed by D25§4.2 (quickstart)
G10Agent capability declarationDeferredApp C
G11Ontology schema artifactAddressed by C14§5.1 (ontology artifact)
G12Object standard integrationAddressed by C15 + execution phase§5.1 (registry pattern)
*End of aDNA Universal Standard v2.5*
Last updated 2026-07-02 [Edit the standard](https://github.com/aDNA-Network/aDNA/blob/main/.adna/what/docs/adna_standard.md)
---
## https://adna.network/reference/tool-setup/
# Tool Setup — aDNA Reference
> Get productive with aDNA using your preferred tool. aDNA is tool-agnostic at Tier 1 — any text editor and file system works.
---
## Prerequisites
All setups require:
- Git (for cloning and version control)
- A text editor that can read markdown and YAML
- Python 3.8+ (for validation tooling)
---
## Setup 1: Terminal + Claude Code (Minimal)
Best for: agent operators, CLI-first workflows, headless environments.
### Quick Start
```bash
# Clone or create an aDNA instance
git clone && cd
# Or bootstrap a new instance
bash setup.sh # if available, or manually create the triad
# Validate the instance
python what/lattices/tools/adna_validate.py .
# Start working — Claude Code reads CLAUDE.md automatically
claude
```
### What Works
| Feature | Support |
|---------|---------|
| Directory structure (Tier 1) | Full — `ls`, `tree`, `find` |
| YAML frontmatter (Tier 1/2) | Full — any YAML parser |
| Markdown content (Tier 1) | Full — `cat`, `less`, `bat` |
| Validation tooling | Full — Python scripts |
| Wikilinks (Tier 3) | Rendered as plaintext — still navigable via grep |
| Graph view (Tier 3) | Not available |
### Tips
- Use `grep -r "type: mission" how/missions/` to find active missions
- Use `grep -r "status: active" --include="*.md"` for active items
- Session files are your changelog — check `how/sessions/active/`
---
## Setup 2: VS Code / Cursor
Best for: developers, mixed code + knowledge workflows, team environments.
### Quick Start
```bash
# Clone and open
git clone
code # or: cursor
```
### Recommended Extensions
| Extension | Purpose |
|-----------|---------|
| **YAML** (Red Hat) | Frontmatter syntax highlighting and validation |
| **Markdown All in One** | Markdown preview, TOC generation |
| **Foam** or **Dendron** | Wikilink support, backlinks, graph view |
| **Mermaid Preview** | Render Mermaid diagrams inline |
### Configuration
Add to `.vscode/settings.json` for best experience:
```json
{
"files.associations": {
"*.md": "markdown"
},
"markdown.validate.enabled": true,
"yaml.schemas": {
"what/lattices/lattice_yaml_schema.json": "*.lattice.yaml",
"what/lattices/tools/frontmatter_schema.json": "*.md"
}
}
```
### What Works
| Feature | Support |
|---------|---------|
| Directory structure (Tier 1) | Full — file explorer |
| YAML frontmatter (Tier 1/2) | Full with YAML extension |
| Markdown content (Tier 1) | Full with preview |
| Wikilinks (Tier 3) | With Foam/Dendron extension |
| Validation tooling | Full — integrated terminal |
| Graph view (Tier 3) | With Foam extension (basic) |
---
## Setup 3: Obsidian
Best for: knowledge workers, visual thinkers, projects with heavy cross-referencing.
### Quick Start
1. Download [Obsidian](https://obsidian.md)
2. Open the aDNA instance directory as a vault
3. Trust the vault when prompted (required for community plugins)
### Recommended Plugins
| Plugin | Purpose |
|--------|---------|
| **Dataview** | Query frontmatter across the vault (Tier 2) |
| **Templater** | Use aDNA templates from `how/templates/` |
| **Obsidian Git** | Auto-commit and sync |
| **Notebook Navigator** | Enhanced session navigation |
### Tier 3 Features (Obsidian-specific)
- **Wikilinks**: `[[file_name]]` syntax for bidirectional linking
- **Graph View**: Visual map of all cross-references
- **Canvas**: Visual composition of lattice workflows
- **Dataview queries**: Dynamic tables from frontmatter
- **Banner images**: Visual file identification via `banner` field
### What Works
| Feature | Support |
|---------|---------|
| All Tier 1/2/3 features | Full |
| Validation tooling | Via integrated terminal or external |
---
## Conformance by Tool
All three setups support full aDNA conformance:
| Conformance Level | Terminal | VS Code | Obsidian |
|-------------------|----------|---------|----------|
| Starter | Yes | Yes | Yes |
| Standard | Yes | Yes | Yes |
| Full | Yes | Yes | Yes |
The aDNA standard is designed so that **Tier 1 features (directory structure, YAML frontmatter, markdown files, naming conventions) work universally**. Tier 2 adds frontmatter querying (any YAML-aware tool). Tier 3 adds environment-specific enhancements.
---
## Validation (All Tools)
```bash
# Check instance conformance
python what/lattices/tools/adna_validate.py .
# Check governance file consistency
bash what/lattices/tools/governance_sync_check.sh
# Validate a specific lattice YAML
python what/lattices/tools/lattice_validate.py path/to/file.lattice.yaml
```
## Related Docs
- `agent_first_guide.md` — Agent operator setup (Claude Code focus)
- `adna_standard.md` §16 — Tool Integration Tiers specification
- `standard_reading_guide.md` — How to navigate the standard document
---
## https://adna.network/reference/visual-identity-v2/
# Visual Identity v2 — aDNA Reference
## Purpose
This is the contributor-facing reference for visual decisions across the aDNA documentation surface. If you are authoring an asset — a hero image, a section icon, an inline diagram, an OG card — this document tells you which palette to draw from, which typography scale to use, what stroke-width matches the existing vocabulary, and how to prompt the image generator so the result does not look like marketing.
**v3 register pivot (ADR-032, ratified 2026-06-04).** aDNA.network has evolved from the minimalist teal/amber "Rust/Tauri" register (v2) to the Science-Stanley **"Ghibli-pixel" / Tokyo Night** warm register — *cozy bio-digital retro-futurism*: warm, hand-crafted, hopeful, dense narrative detail. The shift carries the project's public-good ethos through **warmth + craft** rather than cold restraint. What stays constant: **purpose over decoration, currentColor inheritance, AA contrast, reduced-motion, honest affordances.** What changes: the palette (Tokyo Night, dark-first — §1) and the imagery register (illustrative SS-Ghibli pixel art is now allowed — §4). The v2 baseline crystallized M5.3 D11 (cycles 101–110); this v3 supersedes its palette + imagery sections.
Companion documents:
- The [aDNA Universal Standard](/reference/specification) — what to build.
- The [Design Rationale](/reference/design-rationale) — why it is built that way.
- This document — what it should look like and how to make it match.
---
## 1. Color palette
aDNA.network draws from the **Tokyo Night** palette, dark-first — a deep navy base carrying a **purple** brand accent, **cyan** links/data, and a **warm amber** for lighting. All colors are CSS custom properties in `src/styles/branding.css` (brand) + `src/styles/tokens.css` (neutrals); consume them via `var(--color-*)` rather than hex literals. Token *names* are preserved from v2; their *values* were repointed (ADR-032).
### Brand tokens
| Token | Hex | Use | Contrast |
|---|---|---|---|
| `--brand-primary` | `#9d7cd8` | Purple — brand, large text / UI accents, glow | ~6.9:1 on base ✓ (large/UI; not white body text) |
| `--brand-primary-dark` | `#6d4bb8` | Light-mode primary + dark-mode button bg | 5.8:1 with white text ✓ |
| `--brand-primary-light` | `#bb9af7` | Lighter purple — dark-mode hover / accent | — |
| `--brand-link` | `#7dcfff` | Cyan — links, data, connections (dark) | ~10.3:1 on base ✓ |
| `--brand-link-dark` | `#1f6f9e` | Deep cyan-blue — light-mode link | 5.4:1 on white ✓ |
| `--brand-accent` | `#e0a84c` | Warm amber — accent / lighting, sparing | large/decorative only, never body text |
### Semantic mappings
| Semantic token | Light (secondary) | Dark (default) |
|---|---|---|
| `--color-primary` | `--brand-primary-dark` `#6d4bb8` | `--brand-primary` `#9d7cd8` |
| `--color-link` | `--brand-link-dark` `#1f6f9e` | `--brand-link` `#7dcfff` |
| `--color-link-hover` | `#14567c` | `--brand-link-light` `#a9d8ff` |
| `--color-accent` | `--brand-accent` `#e0a84c` | `--brand-accent` `#e0a84c` |
### Neutrals (Tokyo Night, dark-first)
Defined in `src/styles/tokens.css`. Dark is the **default** register (ADR-032); light mode keeps near-white neutrals so the secondary register stays usable.
| Token | Dark (default) | Light |
|---|---|---|
| `--color-bg` | `#1a1b26` | `hsl(0 0% 100%)` |
| `--color-bg-alt` | `#1f2335` | `hsl(0 0% 97%)` |
| `--color-surface` | `#24283b` | `hsl(0 0% 100%)` |
| `--color-text` | `#c0caf5` | `hsl(0 0% 12%)` |
| `--color-text-muted` | `#9aa5ce` | `hsl(0 0% 40%)` |
| `--color-text-heading` | `#ffffff` | `hsl(0 0% 8%)` |
| `--color-border` | `#2f334d` | `hsl(0 0% 88%)` |
### Rules
1. **Consume tokens, not hex.** New components MUST reference `var(--color-*)` so dark/light and brand changes propagate. (Illustrative image assets are the deliberate exception — §4.)
2. **Two signals, one warm accent.** Purple carries brand/identity; cyan carries links/data/connections. Amber is reserved for sparing warm lighting — never large surface areas, never body text.
3. **Dark-first.** Dark is the default; light mode is the supported secondary. Verify AA contrast in **both** modes for every text/link pairing.
4. **Status colors** (`--color-error`, `--color-success`, `--color-warning`, `--color-info`) are pre-defined and tuned for both modes; do not introduce new status hues without operator gate.
---
## 2. Typography
### Font stack
| Role | Family | Fallback |
|---|---|---|
| Display (headings) | `Space Grotesk` | `system-ui, sans-serif` |
| Body (prose) | `Inter` | `system-ui, sans-serif` |
| Mono (code) | `JetBrains Mono Variable` | `'JetBrains Mono', 'Fira Code', monospace` |
Variables: `--font-display`, `--font-body`, `--font-mono`. JetBrains Mono is loaded `font-display: optional` so a slow first-paint never blocks rendering — system monospace is acceptable until cached.
### Scale (modular 1.25 ratio with viewport fluidity via `clamp`)
| Token | Range |
|---|---|
| `--text-xs` | 0.7rem → 0.8rem |
| `--text-sm` | 0.8rem → 0.9rem |
| `--text-base` | 1rem → 1.1rem |
| `--text-lg` | 1.125rem → 1.3rem |
| `--text-xl` | 1.25rem → 1.6rem |
| `--text-2xl` | 1.5rem → 2rem |
| `--text-3xl` | 1.875rem → 2.8rem |
| `--text-4xl` | 2.25rem → 3.6rem |
### Rules
1. **Never hard-code font-size.** Always consume from the scale.
2. **Display font for headings; body for prose.** Mono only for code, file paths, and identifiers.
3. **Weight discipline.** Display headings use 600. Body prose uses 400 with 600 for emphasis.
---
## 3. Spacing
A 4px-base scale exposed as CSS custom properties.
| Token | Value |
|---|---|
| `--space-1` | 0.25rem (4px) |
| `--space-2` | 0.5rem (8px) |
| `--space-3` | 0.75rem |
| `--space-4` | 1rem |
| `--space-6` | 1.5rem |
| `--space-8` | 2rem |
| `--space-12` | 3rem |
| `--space-16` | 4rem |
| `--space-24` | 6rem |
| `--space-32` | 8rem |
Layout constants:
| Token | Purpose |
|---|---|
| `--content-width` | 72rem — outer max-width |
| `--prose-width` | 65ch — narrow reading column |
| `--sidebar-width` | 16rem |
| `--toc-width` | 14rem |
Border-radius scale: `--radius-sm` through `--radius-xl` plus `--radius-full` (9999px for pills). Default for cards is `--radius-md`; default for buttons is `--radius-sm`.
---
## 4. Image-prompt conventions
aDNA.network is a methodology project, and under v3 it carries the **Science-Stanley "Ghibli-pixel" register** (ADR-032): *cozy bio-digital retro-futurism* — warm, hopeful, hand-crafted, dense narrative detail. This **relaxes the v2 abstract-only guardrail**: illustrative pixel-art scenes (lab desks, node-maps, connected vaults, helices) are now in-scope. What does *not* relax: no baked text, no human faces, purpose over decoration, and AA contrast on any composited text.
### Hard guardrails
1. **No text inside images.** Generators (Imagen included) hallucinate glyphs; text inside hero PNGs degrades to gibberish at OG-card scale. Strip the prompt of typography, captions, labels, titles. Composite any title as **live SVG/CSS text** (responsive + carries the accessible name) or via PIL after generation — never baked into the gen.
2. **No human faces.** The runner sets `person_generation="dont_allow"`. Use scene-level / bird's-eye framing (desks, maps, vaults, helices), not portraits.
3. **Hopeful, not dystopian.** Warm task lighting + cool monitor glow; intellectually curious mood. No sterile empty sci-fi, no dark dystopia, no photographic stock-photo aesthetic, no marketing gradients on content.
4. **Dual-resolution craft.** Human/physical elements = high-fidelity 32-bit painterly pixel; AI/digital constructs = chunky 16-bit sprites; DNA/active-science motifs = sharp glow-emission vector pixels. No uniform pixel scaling, no flat vector UI.
### Prompt skeleton (Imagen 4)
The canonical style tail lives in the runner (`GHIBLI_TAIL` in `runners/e1_hero_adna_network_gen.py`) — reuse it; do not re-derive. A prompt = `[SCENE_MOTIF] + GHIBLI_TAIL`:
```
[SCENE_MOTIF — one bird's-eye / isometric scene: a cozy lab desk with a
glowing node-map; a constellation of connected nodes; a DNA-helix resolving
into a network; an isometric town of connected vault-buildings]
+ GHIBLI_TAIL (detailed 32-bit pixel art, cozy studio-ghibli aesthetic,
soft dithered shading; Tokyo Night palette — base #1a1b26 / #24283b, purple
#9d7cd8, cyan #7dcfff, warm amber #e0a84c lighting; dual-resolution rule;
hopeful mood; ABSOLUTELY NO TEXT / NO LETTERS / NO LOGOS; no human faces;
wide 16:9; anti-patterns: no flat vector UI, no sterile sci-fi, no dystopia)
```
- **Palette in-prompt** — base navy `#1a1b26` / `#24283b`; purple `#9d7cd8`; cyan `#7dcfff`; warm amber `#e0a84c` (lighting only).
- **One scene, not a checklist** — a single coherent motif beats a busy collage at hero / thumbnail scale.
### Post-generation pipeline
1. Imagen 4 Ultra background generation at full resolution (16:9 hero; 1:1 OG card).
2. PIL text overlay for any text required (OG card titles, hero captions). Done out-of-band per asset.
3. Astro `` from `astro:assets` produces responsive `.webp` variants at build time at widths matching layout breakpoints (640 / 960 / 1280 / 1408 for heroes).
### Cost discipline
Imagen 4 Ultra is $0.04/call; **Imagen 4 Fast ($0.02) is the exploration / fallback tier** when Ultra returns transient 429/503 capacity errors (the runner retries with backoff, then you pass `--model imagen-4.0-fast-generate-001`). Per-cycle budgets are recorded in each mission's Image-Gen Budget Tracker; cumulative spend is tracked at the campaign master + STATE.md. Hard cap at $50 per phase (set at v8 P5 entry).
---
## 5. Icon vocabulary
The site uses a 6-icon set covering the canonical section taxonomy. Each icon is a hand-designed SVG at `site/src/assets/icons/icon_{name}.svg`. The set was authored at cycle 103 and refined at cycle 106.
### Set inventory
| Icon | Motif | File |
|---|---|---|
| `icon_learn` | Stacked rounded paths (book / leaves) | `icon_learn.svg` |
| `icon_how` | 3 rectangles + 2 horizontal shafts with chevron arrowheads (process / transformation) | `icon_how.svg` |
| `icon_patterns` | Hexagonal tessellation (7-hex cluster) | `icon_patterns.svg` |
| `icon_reference` | Blueprint grid with dimensional callouts | `icon_reference.svg` |
| `icon_community` | 5 circles connected by lines (network) | `icon_community.svg` |
| `icon_use_cases` | Concentric rectangles (containment) | `icon_use_cases.svg` |
### Motif rules
1. **Stroke-width 1.6.** Matches diagram-component vocabulary (TriadDiagram + ConvergenceFunnel use the same width).
2. **`stroke="currentColor"` + no fill.** The icon inherits the parent text color; that lets nav active-states and dark-mode parity work automatically.
3. **`fill="none"` on outlines.** Solid fills create visual heaviness at 14–16px nav scale.
4. **Straight shafts + explicit chevron arrowheads** (NOT curved Bézier arrows or partial arrowheads) — discovered at cycle 103, validated at cycle 106. Curves lose detail below 16px.
### Wiring discipline
Icons are imported as raw SVG strings via Vite's `?raw` query and embedded via `set:html`:
```astro
// ...
```
- **`aria-hidden="true"`** because the adjacent text label carries the semantic meaning; the icon is a redundant recognition signal.
- **Sized via wrapper span** (`.group-icon` 16×16, `.section-icon` 14×14) — not inline `