Give your project a knowledge architecture that both humans and AI agents can navigate.

Every project accumulates knowledge — decisions, contacts, research, processes, context. Without structure, that knowledge fragments across chat logs, scattered docs, and individual memory. AI agents start every session cold, re-discovering what the project is and how it works.

aDNA (Agentic DNA) is a knowledge architecture that solves this. It organizes any project's knowledge into three directories — who/, what/, how/ — with lightweight governance files that give AI agents instant orientation and give humans a browsable knowledge graph in Obsidian.

Clone this repo to get a ready-to-use aDNA vault with templates, tools, and examples. Customize it for your domain in minutes.

aDNA originated from the Lattice Protocol for federated AI compute, but the architecture is domain-neutral — any project that uses AI agents (or just wants structured knowledge) benefits.

AI agents start every session cold. No memory of past work, no awareness of other agents, no understanding of the project they're operating in. This creates four compounding failures:

aDNA solves these by giving projects a deliberate knowledge architecture — structured knowledge that both humans and agents can read, navigate, and build on.

aDNA works for any project that manages knowledge. Here are four common use cases:

Startup founder — You're tracking investors, customers, product roadmap, hiring, and fundraising. Your who/ leg holds investor profiles, customer records, and team members. Your what/ leg holds product decisions, market research, and competitive analysis. Your how/ leg holds fundraising campaigns, sprint plans, and onboarding processes. One vault replaces scattered Notion pages, Google Docs, and Slack threads.

Researcher — You're managing papers, datasets, experiments, and collaborations. Your what/ leg holds literature reviews, dataset documentation, and methodology decisions. Your who/ leg holds collaborators, lab members, and funding contacts. Your how/ leg holds research missions, publication pipelines, and grant application workflows.

Creative professional — You're juggling clients, projects, creative assets, and revision cycles. Your who/ leg holds client profiles and collaborator contacts. Your what/ leg holds project briefs, asset libraries, and style guides. Your how/ leg holds project workflows, revision pipelines, and delivery checklists.

Personal knowledge manager — You're organizing learning goals, reading notes, skills development, and personal projects. Your what/ leg holds course notes, book summaries, and topic deep-dives. Your how/ leg holds learning paths, habit tracking, and project plans. Your who/ leg holds mentors, communities, and professional contacts.

Each of these users starts with the same base structure and extends it with domain-specific directories. See Extending the Ontology for how.

Every piece of project knowledge answers exactly one of three questions:

who/     →  Who is involved?                 (people, teams, organizations)
what/    →  What does this project know?     (knowledge, decisions, artifacts)
how/     →  How does this project work?      (processes, plans, operations)

This is the triad — three directories, three questions, complete coverage.

The Question Test classifies any content:

Why three? Two legs create sorting ambiguity — people get conflated into either knowledge or process. Four or more legs proved unnecessary in practice; candidates like TOOLS, WHERE, and WHEN all decompose cleanly into the existing three. Three is the minimum that separates knowledge, process, and people without overlap.

This repo is a bare triad — the full aDNA experience. When adding aDNA to an existing codebase, use the embedded form so it doesn't collide with your source tree.

Five files provide the structural skeleton:

Agents read CLAUDE.md → STATE.md → directory-level AGENTS.md files. Humans read README.md → MANIFEST.md → browse the triad. Same knowledge, two entry paths.

Key terms used throughout this documentation:

Base aDNA ships 14 entity types across the triad — the minimal operational ontology any project needs:

You extend by adding domain-specific entities under the appropriate triad leg. The base gives you operational infrastructure — sessions, missions, coordination — that works from day one. Your extensions add the domain knowledge that makes the project yours.

Here are some examples of how different teams extend the base:

The triad doesn't prescribe your domain — it gives you the scaffold to build your domain ontology on.

When related entities share a directory, use a frontmatter field to distinguish them:

# what/modules/tool_lattice_validate.md
type: module
module_type: tool        # ← discriminator

# what/modules/model_protein_binder.md
type: module
module_type: model       # ← discriminator

This keeps the directory structure flat while preserving semantic precision. The base ontology uses three discriminators: module_type (tool, model, preprocessor, ...), lattice_type (pipeline, agent, context_graph, workflow), and skill_type (agent, process).

lattice-adna/
├── CLAUDE.md                           # Agent master context
├── MANIFEST.md                         # Project identity (customize this)
├── STATE.md                            # Operational state (customize this)
├── what/                               # Knowledge
│   ├── context/                        #   Context library
│   ├── decisions/                      #   Architecture Decision Records
│   ├── docs/                           #   aDNA specification documents
│   │   ├── adna_standard.md            #     Full normative spec (v2.1)
│   │   ├── adna_design.md              #     Architecture rationale
│   │   └── adna_bridge_patterns.md     #     Multi-instance composition
│   └── lattices/                       #   Lattice definitions
│       ├── lattice_yaml_schema.json    #     JSON Schema
│       ├── canvas_yaml_interop.md      #     Canvas ↔ YAML spec
│       ├── examples/                   #     13 example lattices
│       └── tools/                      #     validate, convert, interop
├── how/                                # Operations
│   ├── templates/                      #   10 auto-triggering templates
│   ├── pipelines/prd_rfc/              #   R&D → PRD → RFC pipeline
│   ├── sessions/                       #   Session tracking
│   ├── campaigns/                      #   Multi-mission initiatives
│   ├── missions/                       #   Task decomposition
│   ├── skills/                         #   Agent recipes & procedures
│   └── backlog/                        #   Ideas & improvements
├── who/                                # Organization
│   ├── coordination/                   #   Cross-agent notes
│   └── governance/                     #   Project governance
└── .obsidian/                          # Visual config (theme, snippets, plugins)

Clone and open: ~5 minutes. Agent-guided customization: 15-30 minutes. Manual customization: 30-45 minutes.

git clone https://github.com/lat-labs/lattice-adna.git
cd lattice-adna

./setup.sh

Downloads and installs 12 community plugins and the Tokyo Night theme. Run with --force to re-download everything.

Optionally install Space Grotesk font — the vault falls back to system fonts without it.

Open lattice-adna/ as a vault in Obsidian. Enable community plugins when prompted. The accent color (Rebecca Purple #663399) and CSS snippets activate automatically.

Option A: Agent-guided setup (recommended, ~15-30 min)

Open a terminal in the vault directory and start Claude Code:

claude

Berthier — the vault's built-in agent personality — will detect this is a fresh vault and walk you through interactive onboarding:

• Explains the aDNA architecture and triad structure
• Asks about your project, domain, and goals
• Suggests domain-specific ontology extensions
• Customizes governance files with your project identity
• Offers personality customization for your agent

This is the fastest way to go from clone to productive vault. Everything Berthier does is inspectable — see how/skills/skill_onboarding.md.

Option B: Manual setup (~30-45 min)

See Using Without AI Agents below.

aDNA works perfectly well as a human-only knowledge management system. The triad structure, templates, and Obsidian integration don't require AI agents at all.

1. Clone and install — Follow Quick Start steps 1-3 above.

2. Edit MANIFEST.md — Replace the project description with your project's name and purpose. This file is your project's identity card — update it to describe what you're building.

3. Edit STATE.md — Replace the current phase and next steps with your own. This is your operational dashboard — use it to track what's happening now and what's next.

4. Edit CLAUDE.md (optional) — If you plan to use AI agents later, update the project description in the ## Identity & Personality section. If not, you can ignore this file.

5. Create your first content file — Pick the triad leg that matches your first piece of knowledge and create a file:

• A decision? Create what/decisions/adr_your_decision.md
• A team member? Create who/governance/team_member_name.md
• A project plan? Create how/missions/plan_your_project.md

Use the templates in how/templates/ as starting points — each one has the required frontmatter fields pre-filled.

• Session tracking — designed for multi-agent coordination. For solo human use, it's optional.
• Collision prevention — the updated / last_edited_by fields prevent multi-agent conflicts. Solo users can still use them as an audit trail, but they're not critical.
• AGENTS.md files — these are instructions for AI agents. As a human, browse directories directly in Obsidian.
• Lattices — YAML workflow definitions for executable pipelines. Useful for computational work, but the triad handles knowledge management without them.

aDNA is designed for human-agent collaboration. The architecture serves both audiences simultaneously.

When an AI agent (Claude Code, Cursor, etc.) opens an aDNA vault, it reads CLAUDE.md and immediately understands:

• Project structure and where to find things
• Safety rules and what not to touch
• Active state — what's in progress, what's blocked
• Session protocol — how to track its work
• Domain knowledge — project-specific context

No prompt engineering required. The architecture is the prompt.

When an agent first opens a fresh vault, it runs an interactive onboarding flow to help customize the vault for your project.

Every agent session creates a file in how/sessions/active/ before modifying vault files:

On completion, sessions close with a SITREP — a structured handoff:

• Completed — what got done
• In progress — what's started but unfinished
• Next up — recommended next actions
• Blockers — anything preventing progress
• Files touched — full audit trail

The next agent reads the last SITREP and picks up where the previous one left off. Knowledge compounds instead of evaporating.

For work larger than a single session:

Campaign  (strategic initiative — weeks to months)
├── Phase  (logical grouping with human gate between phases)
│   ├── Mission  (multi-session task — 1-5 sessions)
│   │   ├── Objective  (session-sized unit of work)
│   │   └── Objective
│   └── Mission
└── Phase

• Campaigns coordinate multiple missions toward a strategic goal
• Missions decompose complex tasks into claimable objectives
• Objectives are what actually get done in a session
• Phases group missions with human approval gates between them

When multiple agents work on the same project, they coordinate through who/coordination/ — structured notes that flag dependencies, handoffs, and blockers. Each agent checks coordination on startup, before starting work.

Adding a new entity type takes three steps:

Place it under the right triad leg:

mkdir -p who/customers    # People/orgs → who/
# or
mkdir -p what/datasets    # Knowledge objects → what/
# or
mkdir -p how/runbooks     # Operational processes → how/

Every directory needs an AGENTS.md telling agents what lives here:

# customers/ — Agent Guide

## What's Here
Customer records for active and prospective accounts.

## Working Rules
- One file per customer: `customer_<name>.md`
- Check `updated` field before modifying
- Set `last_edited_by` and `updated` on every edit
- Link to contacts via `[[contacts/contact_name]]`

Add a template in how/templates/ so new entities are consistent:

---
type: customer
created: <% tp.date.now("YYYY-MM-DD") %>
updated: <% tp.date.now("YYYY-MM-DD") %>
status: prospect
last_edited_by:
tags: [customer]
---

# customer_<name>

Configure Templater to auto-trigger the template when files are created in the new directory.

Using an AI agent? The entity scaffolding skill (how/skills/skill_new_entity_type.md) automates all three steps — just tell the agent what entity type you need and where it belongs.

Lattices are optional. The triad structure handles knowledge management without them. Lattices add value when you need to model executable workflows, computational pipelines, or multi-step reasoning processes. If your use case is purely knowledge organization, you can skip this section entirely.

A lattice is a directed graph connecting datasets, modules, reasoning nodes, and processes into an executable composition. Lattices bridge human knowledge graphs and machine-executable workflows.

Every lattice carries FAIR metadata — making it findable, accessible, interoperable, and reusable by default:

fair:
  license: "MIT"
  creators: ["Lattice Labs"]
  keywords: [research, context engineering, multi-agent]
  provenance: "Designed for deep research workflows"

Example lattices ship in what/lattices/examples/ across multiple domains:

Copy one to start customizing:

cp what/lattices/examples/hello_world.lattice.yaml what/lattices/my_first.lattice.yaml

A .lattice.yaml has five sections:

lattice:
  name: my_first                    # URL-safe identifier
  version: "1.0.0"                  # Semver
  lattice_type: pipeline            # pipeline | agent | context_graph | workflow
  description: "What this lattice does"
  execution:
    mode: hybrid                    # workflow | reasoning | hybrid
    runtime: local                  # local | ray | kubernetes
    tier: L1                        # L1 (edge) | L2 (regional) | L3 (cloud)
  nodes:
    - id: input_data
      type: dataset                 # dataset | module | process | reasoning
      description: "Input description"
    - id: analyze
      type: reasoning
      description: "What this node decides"
      prompt: "Instructions for the LLM"
      model_override: "claude-opus-4-6"
  edges:
    - from: input_data
      to: analyze
      label: "raw data"
      condition: "optional routing condition"
  fair:
    license: "MIT"
    keywords: [your, domain, tags]

Nodes are the units of work — datasets hold data, modules execute code, processes coordinate, reasoning nodes use LLMs. Edges define the flow between them, with optional conditions for branching and loops.

cd what/lattices
pip install -r tools/requirements.txt
python -c "
from tools.lattice_validate import validate_lattice_file
result = validate_lattice_file('my_first.lattice.yaml')
print(f'Valid: {result.valid}')
for e in result.errors: print(f'  ERROR: {e}')
for w in result.warnings: print(f'  WARN:  {w}')
"

Convert to an Obsidian canvas for visual editing:

python -c "
from tools.lattice2canvas import lattice_file_to_canvas
lattice_file_to_canvas('my_first.lattice.yaml', 'my_first.canvas')
print('Canvas created — open in Obsidian')
"

Edit the canvas visually in Obsidian (drag nodes, reroute edges), then convert back:

python -c "
from tools.canvas2lattice import canvas_file_to_lattice
canvas_file_to_lattice('my_first.canvas', 'my_first.lattice.yaml')
print('Lattice updated from canvas')
"

Note: YAML is the source of truth. Canvas is a derived visualization. Round-tripping preserves node IDs, refs, and edge topology, but canvas-only properties (positions, dimensions, groups) don't survive the return trip. See canvas_yaml_interop.md for the full mapping spec.

Token efficiency is the constraint that shapes everything. Every token in an agent's context window must earn its place.

The what/context/ directory implements these principles as a context library — structured knowledge files with token estimates, tiered information, and progressive loading. Agents load only the subtopics they need for the current task.

Files flow through stage directories. A file's location is its processing state:

how/pipelines/prd_rfc/
├── 01_research/        # Problem exploration
├── 02_requirements/    # PRD authoring (human gate)
├── 03_design/          # RFC authoring
└── 04_review/          # Final approval (human gate)

Each stage has an AGENTS.md with instructions. Drop a file into stage 1, and agents (or humans) advance it through the pipeline by moving it to the next stage directory.

Lattices specify which compute tier they target:

Three rules keep multi-agent work safe:

1. Read before write — always read current content immediately before writing
2. Check updated — if another agent edited today, confirm before overwriting
3. Set last_edited_by — every edit updates the frontmatter audit trail

MIT