AgenticMD

Changelog

Versioned history. The v1.0 backlog section tracks explicit deferrals so they don't drift indefinitely.

AgenticMD Changelog

All notable changes to the AgenticMD specification will be documented here. The format follows Keep a Changelog; versioning follows Semantic Versioning.

[Unreleased]

No changes pending.

v1.0 backlog

The following are explicit deferrals to v1.0+. They are tracked here so they don’t drift indefinitely.

  • Remove .amd extension acceptance. v0.4 deprecated .amd with acceptance through the remaining v0.x window. v1.0 removes acceptance entirely. Validator becomes .md-only.
  • project_rule split decision. The reviewer in the v0.2 → v0.3 cycle flagged that project_rule may be doing two jobs: operating posture and conditional dispatch. v0.3 tightens the definition to cover both (“rules the agent applies across tasks rather than to a specific task”). v1.0 will revisit if a second corpus exposes a real divergence in practice.
  • Mandatory resolution semantics (§6.3). v0.3 ships non-normative defaults (case-sensitive IDs, single-file uniqueness, “exists” means frontmatter.id matches). v1.0 will promote these (or revised equivalents) from RECOMMENDED to MUST, once a second implementation has stress-tested them.
  • example and open_question node-type promotion decisions. Both are on the v1.0 watchlist (see DESIGN_NOTES.md). Indefinite watchlist is not acceptable. If no second-corpus evidence has emerged by the v1.0 timeline, each will be resolved explicitly: either promoted (if the agent-state-interaction dimension shows the candidate is distinct and a corpus exposes the gap) or formally folded into existing types (with documentation of how those types should absorb the use case).
  • A second binding. A non-markdown binding (database table, JSON-LD, structured columnar store) to validate substrate- independence and stress-test the resolution semantics. None shipped yet.

[v0.4] — 2026-05-24

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.

Reversal: .amd extension dropped

The v0.2 decision to register .amd as the canonical extension is reversed. The reference corpus (AI Studio’s docs/book-ai/, ~74 topic files) never migrated to .amd after v0.2 was published. The reference adopter chose not to follow the spec on this point. v0.4 aligns the spec with what its first adopter already did in practice: AgenticMD files use .md, and the discipline is asserted at the corpus level.

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.

Added

  • §1.5 reframed as markup-discipline declaration. AgenticMD is now positioned as “a markup discipline for .md documents,” in the lineage of Pandoc Markdown, MyST, and GitHub Flavored Markdown.
  • §1.5.1 corpus-level conformance declaration. Conformance is declared by the presence of a node_type: corpus_root file reachable from the directory — operational, not aspirational. Validators implement scope resolution by walking ancestor directories until they find a corpus_root file or hit the filesystem root.
  • §1.5.2 .amd deprecation policy. v0.4 implementations MAY accept .amd files with a deprecation warning during the remaining v0.x window. v1.0 will remove acceptance entirely.
  • DESIGN_NOTES.md “Why we dropped .amd” section. Captures the comparable-format pattern (Pandoc/MyST/MDX/AsciiDoc), the reference-corpus-never-migrated signal, and the markup-discipline framing that v0.3 already implied.

Changed

  • SPEC §1.4 substrate paragraph clarifies that “markdown substrate” means .md files, not a new extension.
  • §7 conformance summary updated for v0.4 — adds the corpus-scope requirement and the .md-or-deprecated-.amd condition.
  • CLI (bin/agenticmd.dart) accepts .amd with a stderr deprecation warning during the v0.x window.
  • Examples + fixtures renamed from *.amd to *.md.

Notes

  • No breaking changes to v0.3 conformant files. Existing AgenticMD documents continue to validate.
  • The reference corpus (docs/book-ai/ in AI Studio) was already .md and required no migration.
  • Adopters with in-flight .amd files have the remaining v0.x window to migrate via a simple rename. The migration is mechanical.

[v0.3] — 2026-05-24

Framing release. No breaking changes; v0.1 and v0.2 conformant files continue to validate. The v0.3 wins are conceptual:

Reframed

  • Spec positioned as a retrieval model with a markdown binding, rather than a markdown extension. The substrate stops being load- bearing and becomes “what we picked because it has free renderers everywhere.” Future bindings (database tables, JSON-LD, etc.) could express the same retrieval model.
  • Abstract and §1 rewritten to lead with the agents-query-not-read thesis rather than with format mechanics.
  • §4.2 rewritten as (purpose, retrieval, treatment) triples organized along the dimension of how each type interacts with the agent’s existing state. Each type now declares its agent contract explicitly. Closedness defended by the dimension, not by exhaustive enumeration.
  • Empirical-sufficiency framing for the node-type vocabulary, replacing implicit exhaustiveness claims. The seven are “empirically sufficient along the stated dimension,” nothing more.

Added

  • §2.5 no-anaphora rule — promoted to a named normative rule with bad/good worked examples. Cross-section anaphora is the single most common writing failure that breaks agent retrieval; naming the failure mode makes the rule operational.
  • 80-word cap on domain_brief (§5.2). Enforced by the validator via a new amd.sections.brief_length rule. Briefs over the cap fail conformance. The cap protects the relevance-probe property — without it, briefs drift into being small versions of the topic and the probe value collapses.
  • §4.3 three-criterion addition gate for proposing an eighth node type. Requires: corpus evidence, a non-reducing (purpose, retrieval, treatment) triple, AND a distinct relation along the dimension. Operational, not aesthetic.
  • guardrail vs project_rule clarification in §4.2: per-task action narrowing vs. cross-task posture modification. Both are negative-on-actions but at different scopes.
  • Tightened project_rule definition without splitting: “rules the agent applies across tasks rather than to a specific task — both operating posture and conditional dispatch qualify.”
  • Non-normative resolution defaults in §6.3 + explicit v1.0 obligation to promote to MUST.
  • DESIGN_NOTES.md companion document. Carries the dimension stress-tests, alternative dimensions considered (temporal, epistemic, modal) and why each was set aside, fit-to-purpose argument, chronology of the seven types in the reference corpus, watchlist for example and open_question with timebox language, reasoning behind empirical-sufficiency.

Notes

  • Existing v0.2 and v0.1 conformant files MAY upgrade to spec_version: 0.3 for the brief-length check. Files staying at spec_version: 0.1 or 0.2 continue to validate against their declared version.
  • The reference corpus (74 .amd topics in AI Studio’s book-ai/) may need brief-trim on a handful of topics whose briefs exceed the new 80-word cap. Migration is per-file editorial, not structural.

[v0.2] — 2026-05-23

Registered .amd as the canonical extension for AgenticMD document files and clarified extension policy. Existing v0.1 corpora remain conformant (additive change, no migration required).

Added

  • .amd extension registered as the canonical extension for AgenticMD document files. .md accepted as a v0.x synonym for backward compatibility; MAY be deprecated in v1.0.
  • §1.5 (File extensions) — extension policy and recognition rules.

Scope decision (not shipped)

An earlier v0.2 draft introduced a sibling .amx action-file format (typed YAML action sequences) under the AgenticMD umbrella. It was removed before this release. Reason: 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 without strengthening the document format. AgenticMD stays focused on typed agent-consumable markdown documents.

If you need a structured action-file format, use the existing tool in that space that fits your runtime; AgenticMD is not it.

[v0.1] — 2026-05-23

Initial draft, extracted from the AI Studio book-ai corpus.

Added

  • Frontmatter schema — 9 required fields (id, cluster, node_type, pinned, version, status, depends_on, referenced_by, last_verified_against) plus 5 optional (spec_version, watches_files, watches_paths, drift_mode, contact). Closed enums for node_type (3 values) and status (6 values).
  • Typed-section header convention — ## title {#id node:type} where id is {lowercase-kebab(frontmatter.id)}-{suffix} and type is one of 7 fixed values (domain_brief, architecture_note, decision, guardrail, correction, failure, project_rule).
  • Reference grammar — [ref:topic-id] and [ref:topic-id#section-id] resolve content-addressably against the corpus.
  • Required and optional sections — ## brief is the mandatory first section, untyped ## see-also is the optional terminal section.
  • JSON Schema (draft-07) at SCHEMA.frontmatter.json covering the frontmatter rules.
  • In-tree validator at test/agenticmd_conformance_test.dart running 15 conformance checks under flutter test.
  • Migration tool at tool/agenticmd_migrate_v01_strict.dart that brings a lenient-conformant corpus (using sha: and omitting spec_version) to strict v0.1 conformance.

Notes

  • The sha: alias for last_verified_against.ref is accepted in v0.x for backward compatibility with git-backed corpora that pre-date AgenticMD. It will be removed in v1.0; the migration tool can flip all files.
  • spec_version is RECOMMENDED but optional in v0.x; it becomes REQUIRED in v1.0.

Conformance baseline

The AI Studio book-ai corpus (~73 topic files, ~1,200 typed nodes, ~1,700 references) is the reference conformance corpus. As of v0.1 release, all 73 files pass all 15 validator checks.