AgenticMD

Quickstart

Write a conformant document. Validate it. Hand it to an agent. About ten minutes.

1. Declare a corpus

AgenticMD conformance is asserted at the corpus level. A corpus is a directory that contains (or has a descendant containing) a file with node_type: corpus_root. Create one: 

# docs/my-corpus/INDEX.md

---
id: index
cluster: my-corpus
node_type: corpus_root
pinned: true
version: v0.1.0
spec_version: 0.4
status: living
depends_on: []
referenced_by: [all topics]
last_verified_against:
  ref: HEAD
  date: 2026-05-24
---

# my-corpus

## brief {#index-brief node:domain_brief}
One paragraph saying what this corpus is. Under 80 words.

2. Write a topic

Every file in the corpus is a topic. The first ## section MUST be the brief. Subsequent sections carry typed markers — pick the right node:type from the closed seven (domain_brief, architecture_note, decision, guardrail, correction, failure, project_rule). 

# docs/my-corpus/topic.md

---
id: my-topic
cluster: my-corpus
node_type: topic_root
pinned: true
version: v0.1.0
spec_version: 0.4
status: in-progress
depends_on: []
referenced_by: []
last_verified_against:
  ref: HEAD
  date: 2026-05-24
---

# my-topic

## brief {#my-topic-brief node:domain_brief}
What this topic is, in 80 words or fewer. Treat this as a
relevance probe, not a summary.

## the-thing {#my-topic-thing node:architecture_note}
How the thing works. See [ref:another-topic] for related concepts.

## guardrail-never-x {#my-topic-guardrail-x node:guardrail}
**Never do X** — and here is why. Agents MUST NOT elide guardrails
when summarizing.

## see-also
- [ref:another-topic]

3. Validate

Install the reference Dart package and validate your corpus: 

dart pub global activate agenticmd
agenticmd validate docs/my-corpus/

Output: 

OK  2 AgenticMD documents — all conformant

Or, if you broke a rule: 

1 violation(s):
  topic.md: [amd.sections.brief_length] brief body has 142 words; cap is 80 (SPEC §5.2)

Fix the file, not the validator. The validator is the gate, not the convention.

4. (Optional) Hand it to an agent

Paste the Agent Primer into your LLM's system prompt. The agent now knows how to read and write AgenticMD documents — closed vocabulary, no-anaphora rule, brief-cap, content-addressable references, all of it. A single-file reference that fits in any modern context window.

What you just did

  • Declared a corpus (the INDEX.md with node_type: corpus_root).
  • Wrote a topic (a .md file with typed ## sections).
  • Validated structural conformance (the validator caught mistakes mechanically, not by review).
  • Made the corpus retrievable by software agents (typed sections route correctly; brief is a cheap probe; references survive moves).

Where to go next

  • Specification — the normative rules. Read §1.4 (audience) and §4.2 (node-type triples) first.
  • Agent primer — paste-into-prompt reference for the LLM that will operate on your corpus.
  • Examples — canonical worked example.
  • Design notes — why the spec chose what it chose, what was set aside, the .amd reversal story.