Specification

Canonical reference. Normative rules. Conformance gate.

AgenticMD — v0.4 (draft)

Status: v0.4 — working draft. Will stabilize toward a v1.0 baseline once the schema has survived adoption beyond the reference corpus.

What this is. AgenticMD is a retrieval model for software-agent consumption of documentation, with a CommonMark + YAML binding. The retrieval model defines the unit of retrieval (a typed section, not a file), the metadata an agent needs to handle each unit correctly (the type and the ID), and the writing constraints that make retrieval safe (no cross-section anaphora, brief-first relevance probes, content- addressable references). The markdown binding is the substrate chosen for v0.x because every renderer already supports it. Other bindings (database tables, JSON-LD, structured columnar stores) could express the same retrieval model without breaking the spec — see DESIGN_NOTES.md for the substrate-independence reasoning.

Conformance language: the key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, and REQUIRED are interpreted per RFC 2119.

1. Abstract

AgenticMD operationalizes the observation that agents query documentation; humans read it linearly. A human reading top-to-bottom resolves “as discussed above” and bare pronouns from continuous context. An agent handed one 400-token section as a retrieved chunk cannot — the referent is gone, and the agent either hallucinates or skips the chunk. The spec’s contribution is identifying:

the unit of agent retrieval (the typed section)
the metadata an agent needs to treat that unit correctly (the type and the ID)
the writing constraints that make retrieval safe (the no-anaphora rule, brief-first relevance probes, content-addressable references that survive file moves)

The format codifies seven node types empirically sufficient for the agent behaviors documented in the reference corpus, partitioned along the dimension of how each type interacts with the agent’s existing state: domain_brief, architecture_note, decision, guardrail, correction, failure, project_rule. See §4.2 for per-type triples and the dimension; see DESIGN_NOTES.md for the reasoning behind the dimension choice, alternative organizations considered, and the chronology of how the seven types entered the reference corpus.

Reference implementation, conformance test suite, and a JSON Schema for the frontmatter accompany this specification.

1.4 Audience and authorship

Agent-native. Human-auditable.

AgenticMD is defined, authored, and consumed by agents. Agents own the spec. Agents write the documents that conform to it. Agents retrieve from those documents at runtime. Humans set project direction and arbitrate at boundaries — but the format is the agents’ own.

This spec was drafted by agents under human direction. That is exactly the authorship pattern it codifies: humans direct, agents do the writing work. The spec eats its own dog food.

The markdown substrate is chosen for two reasons, neither of them being human-authoring convenience:

Tool interoperability. Markdown is the lowest-friction substrate for long-lived corpus artifacts that get version-controlled, code-reviewed, audited, and ingested by tools from multiple vendors. A binary or pre-tokenized format would be more efficient for pure agent-to-agent consumption, but would impose a compilation step on the toolchain and opaque diffs on the version-control history.
Trust preservation. Agents are widely deployed but not widely trusted. A format that preserves the human’s unmediated ability to inspect what an agent has written — without a viewer, decompiler, or vendor-specific tool — is part of the value proposition, not a side effect. The reviewability is what makes the agent-authored pattern acceptable to operators who are not yet ready to take agent output on faith.

AgenticMD does not introduce a new file extension. Files use .md. The discipline is asserted at the corpus level (see §1.5). This positions AgenticMD as a stricter profile of CommonMark, in the lineage of Pandoc Markdown, MyST, and GitHub Flavored Markdown — not as a new file format.

The writing rules in this spec (no cross-section anaphora, ≤80-word briefs, closed node-type vocabulary, content-addressable references) are constraints a writing agent applies to its own output to guarantee the resulting documents are safe for agent retrieval. They are not authoring conventions for humans to learn.

1.5 File extensions and corpus declaration

AgenticMD is a markup discipline for .md documents. It does not introduce a new file extension. Files use .md — the same extension markdown has always used.

This places AgenticMD in the same lineage as Pandoc Markdown, MyST, GitHub Flavored Markdown, and other “stricter profiles of CommonMark” that assert authoring discipline without inventing a new file format. The retrieval model, the typed-node vocabulary, the no-anaphora rule, the content-addressable references — these are constraints on how markdown is written, not extensions to markdown syntax. A standard CommonMark parser handles AgenticMD files; an AgenticMD-aware validator enforces the discipline on top.

1.5.1 Conformance declaration

AgenticMD conformance is declared at the corpus level, not the file level. A directory contains an AgenticMD corpus if and only if it (or some directory reachable from it through directory recursion) holds a file whose frontmatter declares node_type: corpus_root.

Within that scope, all .md files are validated against the AgenticMD discipline. Outside that scope, .md files are treated as unrelated markdown and not validated.

Implementations MUST resolve corpus scope by walking from a given file upward through ancestor directories until they encounter a corpus_root file or reach the filesystem root. Files outside any discoverable corpus scope are NOT subject to AgenticMD validation.

This mirrors how .editorconfig and tsconfig.json discover their scopes — the discipline applies to a declared region of the filesystem, not to every file with a particular extension.

1.5.2 The `.amd` extension is deprecated

v0.2 of this spec registered .amd as a canonical extension for AgenticMD documents. v0.4 reverses that decision. The reasoning is captured in DESIGN_NOTES.md’s “Why we dropped .amd” section; the short version is that AgenticMD is markup discipline, not file format, and inventing a separate extension surrenders the free-tooling property that justified the markdown substrate in the first place.

v0.4 implementations MUST recognize .md files within an AgenticMD corpus scope.
v0.4 implementations MAY accept .amd files for backward compatibility with v0.2 and v0.3 corpora; if accepted, they MUST emit a deprecation warning.
v1.0 will remove acceptance of .amd entirely. Adopters with in-flight .amd files have the remaining v0.x window to migrate via a simple rename (find . -name '*.amd' -exec rename .amd .md {} + or equivalent).

A file’s extension does not determine its conformance rules — corpus scope plus the node_type field govern validation. Extensions are incidental.

2. Document model

An AgenticMD file (.amd or .md) is a CommonMark document with the following structure, in order:

Frontmatter — a fenced YAML block delimited by --- at the very top of the file. MUST conform to §3.
Title — a single # ATX heading whose text MAY be any string. Not a node.
Brief section — the first ## heading MUST be titled brief and MUST declare node:domain_brief. See §5.2.
Body — zero or more ## typed-node sections. See §4–§5.
See-also — an optional terminal ## section titled see-also with no node-type marker. See §5.3.

A corpus is a set of files reachable through directory recursion from one or more corpus roots. A corpus root is any file whose node_type is corpus_root.

2.5 The no-anaphora rule

Sections MUST NOT use anaphora that resolves outside the section.

This is the single load-bearing writing constraint of AgenticMD. Cross- section pronouns and back-references that read fine in continuous human prose break catastrophically when an agent retrieves one section as a 400-token chunk — the referent is gone, and the agent either hallucinates a referent or skips the chunk entirely.

Anaphora that breaks retrieval includes:

“As we saw above…”
“Building on the previous section…”
“The approach described earlier…”
“This means we should…” (when “this” refers to content in another section)
“It handles the same case…” (when “it” was named in a different section)

The fix is explicit naming and content-addressable cross-references. Name what the section is about in the section’s own words. If a section needs to reference another topic or section, link it with [ref:topic-id] or [ref:topic-id#section-id], not with a pronoun.

Bad (breaks under retrieval):

## why-it-exists {#hotl-rationale node:decision}
This addresses the problem described above by inverting the iteration
mechanism. The result is what we discussed earlier — fewer interruptions
at the cost of more upfront tokens.

Good (retrieves cleanly):

## why-it-exists {#hotl-rationale node:decision}
HITL (human-in-the-loop) tools make the human the iteration mechanism.
Every accept/reject is a context switch costing 40s–3min. HOTL's bet is
that a multi-agent stack pays back its tokens by avoiding rework. See
[ref:hotl#hotl-brief] for the constraint this addresses.

The rule is normative on authors and informative on validators. No validator can mechanically distinguish a cross-section pronoun from a within-section pronoun in arbitrary prose (the problem reduces to coreference resolution, which is open). Validators MAY surface suspicious patterns (“as we saw,” “the previous,” section-initial pronouns) but MUST NOT reject files on those grounds alone. Author discipline is the gate.

3. Frontmatter

3.1 Required fields

field	type	constraint
`id`	string	kebab-case; globally unique within corpus; SHOULD match the filename stem (case-folded)
`cluster`	string	kebab-case; namespace for grouping topics; MAY be any value the publisher chooses
`node_type`	enum	one of `topic_root`, `corpus_root`, `reference`
`pinned`	boolean	declares the file survives long-term graph compaction in implementations that support it; if uncertain, MUST be `true`
`version`	string	per-topic semantic version of the document’s content (e.g. `v0.18.0`)
`status`	enum	one of the values in §3.4
`depends_on`	list[string]	topic IDs this topic depends on; MAY be empty
`referenced_by`	list[string]	topic IDs that reference this topic; MAY be empty or the literal `[all topics]`
`last_verified_against`	object	`{ref \| sha: string, date: YYYY-MM-DD}` — see §3.3

3.2 Optional fields

field	type	meaning
`spec_version`	string	AgenticMD spec version the file targets (e.g. `0.3`). If absent, the corpus-level default applies. RECOMMENDED in v0.x, REQUIRED in v1.0.
`watches_files`	list[string]	source-artifact paths whose change should re-verify this topic
`watches_paths`	list[string]	directory roots equivalently watched
`drift_mode`	enum	one of `silent`, `notify`, `auto`; default `notify`
`contact`	object	publisher-defined; useful for resume-like topics

Publishers MAY add additional fields not defined here. Implementations MUST preserve unknown fields and SHOULD make them available to ingestion consumers.

3.3 `last_verified_against`

Declares the source-of-truth state against which the document was last verified. The object MUST contain a date field in ISO 8601 calendar-date format (YYYY-MM-DD) and a source-identifier field.

The canonical source-identifier key is ref (implementation-defined, MAY be any string). For git-backed corpora, the alias sha (a short commit SHA) is accepted and treated as semantically equivalent to ref. Implementations targeting v1.0 SHOULD prefer ref; the sha alias may be removed in a future major version.

3.4 `status` enum

value	meaning
`foundational`	load-bearing concept; change requires restructuring
`shipped`	documents a feature present in current production builds
`stable`	documented subject is feature-complete; further change requires RFC
`living`	expected to change in normal cadence by design
`evolving`	actively iterating; expected to settle into `shipped` or `stable`
`in-progress`	intent document ahead of implementation

4. Section markers

Every ## heading that represents a graph node MUST carry a section marker of the form:

## <human title> {#<section-id> node:<node-type>}

4.1 `<section-id>` rules

MUST match ^[a-z0-9][a-z0-9-]*$.
MUST begin with {lowercase-kebab(frontmatter.id)}-. Example: a topic with id: hotl produces IDs hotl-brief, hotl-rationale, etc.
MUST be unique within the file.
SHOULD be unique within the corpus. Implementations MAY warn on collision.

4.2 `<node-type>` vocabulary

The vocabulary codifies seven types, partitioned along the dimension of how each type interacts with the agent’s existing state.

This dimension is selected because it matches what AgenticMD is modeling: how an agent should treat content it retrieves. Other dimensions (temporal, epistemic, modal) are valid for other purposes; a spec organizing documentation for human historians or for adversarial review might choose differently. The agent-state-interaction dimension is the one that earns its place in a retrieval-and-treatment spec for software agents. See DESIGN_NOTES.md for the alternatives considered.

Per-type triples

type	purpose	retrieval rule	treatment rule
`domain_brief`	state what the topic is	load first as cheap relevance probe	trust as authoritative summary
`architecture_note`	explain how a thing works	load when implementing or modifying the thing	descriptive; summarizable
`decision`	declare a choice with rationale	load when changing the thing decided	rationale is load-bearing; never discard the “why”
`guardrail`	prevent a known failure mode (per task)	load whenever the topic is in scope	MUST NOT elide, summarize away, or override
`correction`	declare a position has changed	load instead of any older claim it overrides	invalidates prior statements on the same subject
`failure`	document an anti-pattern	load when symptoms match	diagnostic, not instruction
`project_rule`	declare operating posture or cross-task dispatch rule	load into the agent’s persistent context, not just task context	applies across all task contexts

Dimension mapping

Each type occupies a distinct region in the relation-to-agent-state space:

relation to existing agent state	type
gates further loading	`domain_brief`
adds to knowledge	`architecture_note`
adds to knowledge + locks rationale	`decision`
subtracts from action space (per task)	`guardrail`
invalidates prior knowledge	`correction`
conditionally activated by symptoms	`failure`
modifies operating posture across tasks	`project_rule`

`guardrail` vs `project_rule` — explicit clarification

Both are negative-on-actions, but they apply at different scopes.

guardrail narrows the action space for a specific task (“never rm -rf in this codebase,” “do not commit secrets to this repo”). The scope is the task currently being executed.
project_rule modifies the agent’s operating mode across all tasks (“when in HOTL mode, prefer non-interactive solutions,” “always investigate the verdict; never route around it”). The scope is the agent’s frame for evaluating any task.

If the rule applies to a specific action in a specific task, it is a guardrail. If it applies to how the agent approaches every task, it is a project_rule.

Empirical sufficiency, not exhaustiveness

The seven types codified here are the set empirically observed in the reference corpus to cover the agent behaviors documented there. They are not claimed to be universally exhaustive. The claim is empirical sufficiency along the dimension stated above — sufficient to express the agent-state-interaction behaviors documented to date, partitioned by a principled axis.

4.3 Addition gate

Publishers MUST NOT introduce new node: values inline. Adding an eighth type requires meeting all three of the following:

Corpus evidence. A real corpus (≥30 topics, in active maintenance) where the existing seven types inadequately serve agent retrieval. “Inadequately serve” means: an author repeatedly chose a type that was the wrong shape, OR an agent’s retrieval behavior was demonstrably wrong, AND the proposed new type would have made the difference.
(Purpose, retrieval, treatment) triple. A triple for the proposed type that does not reduce to one of the existing seven. “Reduce” means: the proposed triple could be expressed by using an existing type, possibly with conventions inside the body.
Distinct relation along the dimension. The proposed type must occupy a relation to agent state that none of the seven occupies — distinct from gates / adds / locks / subtracts / invalidates / matches / modifies-posture.

A proposal that meets only some of (1), (2), (3) is not admissible. Implementations MUST reject unknown node-types in conformance mode. See DESIGN_NOTES.md for the reasoning behind each criterion and for the current watchlist of candidates being evaluated for v1.0.

4.4 Section body

Section body is arbitrary CommonMark. References inside the body resolve per §6. Implementations MUST parse from the section marker line until the next ## heading or end-of-file. The no-anaphora rule (§2.5) is normative on section body content.

5. Required sections

5.1 Title

A single # <title> heading MAY appear between the frontmatter and the first ## section. It is not a node and does not require a section marker. Most implementations render it as the topic’s display name.

5.2 Brief section

The first ## section in every file MUST be:

## brief {#<topic-id>-brief node:domain_brief}

This guarantees every topic has a graph node containing the topic’s self-description.

Length cap. The brief body MUST contain no more than 80 words. The brief is a cheap relevance probe — it exists so an agent can pull the briefs of 20 topics for less context than pulling one full topic, decide which matters, and then pull deeper. Without a cap, briefs drift toward being small versions of the topic and the probe value collapses. Implementations MUST count whitespace-separated tokens in the brief body (excluding the section marker line). Briefs over the cap fail conformance.

Agents loading a topic for the first time typically load only this section.

5.3 See-also section

The last ## section MAY be:

## see-also

…with no section marker. Its body is a bullet list of [ref:...] references (see §6). This section is NOT a graph node — it is parsed as a manifest of edge hints for indexing tools. Its absence is permitted; its presence with malformed body is an error.

6. References

References are content-addressable IDs, not URLs.

6.1 Topic reference

[ref:<topic-id>]

Resolves to the topic whose frontmatter.id == <topic-id>. Implementations MUST consider the reference unresolved if no such topic exists in the corpus.

6.2 Section reference

[ref:<topic-id>#<section-id>]

Resolves to the section whose marker is {#<section-id> node:...} inside the topic <topic-id>. Implementations MUST consider the reference unresolved if either the topic or the section is absent.

6.3 Resolution

The v0.x spec does not mandate a resolution mechanism. Implementations MAY use filesystem walks, manifest files, or external indices. Idempotency (re-ingestion does not duplicate nodes) is the responsibility of the ingestion consumer.

Non-normative defaults for v0.x. Until a second binding emerges to stress-test the semantics, the following defaults are recommended:

ID matching: case-sensitive. topic-id and Topic-Id are distinct.
Existence: a topic “exists” iff some file in the corpus declares frontmatter.id equal to the queried ID.
Duplicate-ID behavior: if two files declare the same frontmatter.id, implementations MUST surface a corpus-level error. The spec does not define which (if either) of the duplicates “wins” — fail-loud is required.
Section existence within a topic: a section “exists” iff some ## heading in the topic carries a marker matching the queried section ID.

v1.0 obligation. v1.0 will promote these (or revised equivalents) from RECOMMENDED to MUST, once a second implementation has stress-tested them. Pinning before stress-testing is the failure mode this deferral is guarding against.

7. Conformance summary

A file is conformant v0.4 if and only if:

The file is .md (or, during the deprecation window, .amd with a deprecation warning emitted by the validator).
The file is within a declared AgenticMD corpus scope (§1.5.1).
Frontmatter is a valid YAML block with all §3.1 required fields.
node_type is one of topic_root | corpus_root | reference.
status is one of the six §3.4 values.
Every ## section other than see-also carries a marker matching {#<id> node:<type>} with <id> per §4.1 and <type> per §4.2.
The first ## section is brief with node:domain_brief.
The brief body contains no more than 80 whitespace-separated tokens (§5.2).
Section IDs are unique within the file.
All in-file [ref:...] syntax matches §6.1 or §6.2.

Resolution of [ref:...] references is NOT required for file-level conformance — a file can be valid AgenticMD while pointing at topics that haven’t been written yet. Resolution is a corpus-level property checked by ingestion consumers.

8. Examples

8.1 `domain_brief`

## brief {#hotl-brief node:domain_brief}
HOTL — Humans Out Of The Loop — is a design constraint for agent-first
systems. The human sets direction, approves at boundaries, and owns the
artifacts. Rework that would otherwise interrupt the human's attention
is internalized into the runtime instead.

8.2 `decision`

## why-it-exists {#hotl-rationale node:decision}
HITL tools (Cursor, Cline, Aider, Copilot) make the human the iteration
mechanism. Every accept/reject is a context switch costing 40s–3min. Five to
fifteen of these per task is the dominant cost. HOTL's bet: a multi-agent
stack pays back its tokens by avoiding rework.

8.3 `guardrail`

## guardrail-do-not-interrupt {#hotl-guardrail-interrupt node:guardrail}
**Never intervene mid-generation unless a hard boundary is at stake.**
Interrupting mid-stream wastes the rework already paid for and resets the
loop to HITL by default.

8.4 `correction`

## correction-never-route-around {#hotl-correction-route node:correction}
When an agent observes that the council fired with BLOCK or the audit
flagged a regression, the wrong move is to bypass the verdict and ship
anyway. The verdicts are the system. **Always investigate the verdict;
never route around it.**

8.5 `failure`

Failure nodes SHOULD follow the Symptom → Why it fails → Right move three-beat shape:

## anti-pattern-mid-stream {#hotl-anti-mid-stream node:failure}
**Symptom:** operator interrupts a streaming response mid-flight.
**Why it fails:** the correction enters as user input on the next turn
anyway; the intervention saves no time and adds queue contention.
**Right move:** wait for the turn to finish, read the result, then send a
follow-up if needed.

8.6 Frontmatter, full

---
id: hotl
cluster: agentic-edition
node_type: topic_root
pinned: true
version: v0.18.0
spec_version: 0.3
status: foundational
depends_on: []
referenced_by:
  - council-review
  - mutator
  - audit
watches_files:
  - .claude/memory/philosophy_hotl.md
last_verified_against:
  ref: 5928c83        # or `sha: 5928c83` — both accepted in v0.x
  date: 2026-05-13
drift_mode: notify
---

9. Versioning

This specification follows semantic versioning. Breaking changes to the frontmatter schema, node-type vocabulary, or reference grammar increment the major version. Additions (new optional fields, new conformance test categories, new normative rules with author-only enforcement) increment the minor version. Editorial fixes increment the patch version.

v0.x versions are draft; v1.0 will be the first frozen baseline. Files declaring spec_version: 0.x MAY be migrated by tooling when v1.0 is published.

10. Appendix: drift monitoring (informative)

The watches_files, watches_paths, and drift_mode fields support an optional pattern in which a “drift monitor” process re-verifies topic correctness when watched artifacts change. AgenticMD does not mandate this mechanism; it is described here to standardize the field names for implementations that adopt it.

drift_mode values:

silent — record drift in metadata; no action.
notify — surface a notification to the publisher.
auto — open a re-verification task automatically.

11. Changelog

v0.4 — markup-discipline reframe. Reverses the v0.2 decision to register .amd as a canonical extension. AgenticMD is positioned as a stricter profile of CommonMark in the lineage of Pandoc Markdown, MyST, and GitHub Flavored Markdown — not as a new file format. Files use .md. Conformance is declared at the corpus level by the presence of a node_type: corpus_root file reachable from the directory (§1.5). The .amd extension is deprecated for the remaining v0.x window and will be removed entirely in v1.0.

The reference corpus (AI Studio’s docs/book-ai/, ~74 topic files) never migrated to .amd after v0.2 was published. The reference adopter — the one entity with the most reason to follow the spec exactly — quietly chose not to follow it on this point. v0.4 aligns the spec with what its first adopter already did in practice. The convergent direction (v0.2 → v0.3 sharpened the retrieval-model framing; v0.4 drops the extension that framing already implied) is the v0.x draft window working as intended.

No breaking changes to v0.3 conformant files (which were already .md). Two in-repo files renamed (examples/hotl.amd → hotl.md; fixtures under test/fixtures/amd/). Validator and CLI updated to accept .amd with a deprecation warning during the v0.x window.
v0.3 — framing release. Reframes the spec as a retrieval model with a markdown binding rather than a markdown extension. Promotes the no-anaphora rule (§2.5) to a named normative rule with worked examples. Adds an 80-word cap on domain_brief (§5.2) enforced by the validator. Rewrites §4.2 as (purpose, retrieval, treatment) triples organized along the dimension of how each type interacts with the agent’s existing state, with explicit guardrail vs project_rule clarification. Adds a three-criterion addition gate (§4.3) for proposing an eighth node type. Adds non-normative resolution defaults in §6.3 with explicit v1.0 obligation to promote to MUST. Adopts empirical-sufficiency framing for the node-type vocabulary. Companion DESIGN_NOTES.md ships alongside, carrying the stress-tests for the dimension, alternative dimensions considered, fit-to-purpose argument, type chronology, and watchlist for example and open_question. No breaking changes to v0.2 or v0.1 conformant files.
v0.2 — registered .amd as the canonical extension for document files; .md accepted as a v0.x synonym for backward compatibility. Added §1.5 (extensions). Scope intentionally kept to documents only — an earlier v0.2 draft introduced a sibling .amx action-file format, but YAML action scripts are a saturated space (pytest YAML, Cucumber, Playwright config, GitHub Actions, Ansible all live there) and bundling them under AgenticMD diluted the value proposition. The format stays focused on typed agent-consumable markdown documents.
v0.1 — initial draft extracted from the AI Studio book-ai corpus. Codifies the seven node-types, the section-marker grammar, the frontmatter schema, and the reference resolution semantics empirically in use across ~70 production topic files.