Agent-First Guide

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

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

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:

Degraded — present in files but won’t render interactively:

Requires Obsidian — completely absent without it:

3. Setup Walkthrough

Step 1: Clone the repo

git clone https://github.com/LatticeProtocol/Agentic-DNA.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

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

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

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:

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:

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

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

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

6. Substitution Table

Quick reference for replacing Obsidian-specific features:

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, aDNA Standard, and Architecture Overview