> Markdown twin of https://adna.network/learn/tutorials/extend-the-ontology/
> Index: https://adna.network/llms.txt · Full corpus: https://adna.network/llms-full.txt
> State is a build-time snapshot generated 2026-08-30 (UTC); nothing here is live.

# 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