Migration Guide

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 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 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:

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)

Triad directories (3)

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

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)

# 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.

# 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:

---
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:

---
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:

# 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:

# 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:

# 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:

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:

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

# 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:

## 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)

# 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)

---
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)

---
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)

# [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 14 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 Agentic-DNA repo 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 for nesting, sibling, and monorepo composition patterns.

9. Quick Reference

The Question Test

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

---
type: [entity_type]
created: YYYY-MM-DD
tags: [relevant, tags]
---

Migration guide v1.0 | Companion to the aDNA Standard, Design Document, and Bridge Patterns