Skip to content

SPEC.md

Latest commit

 

History

History
80 lines (55 loc) · 5.34 KB

SPEC.md

File metadata and controls

80 lines (55 loc) · 5.34 KB

MDA Open Spec

The current normative version is MDA Open Spec v1.0, located at spec/v1.0/.

Canonical URL: https://mda.sno.dev/spec/v1.0/

What MDA is

A portable, structured metadata format for AI-agent artifacts. A single .mda source compiles to byte-equivalent .md outputs that drop into every major agent ecosystem: SKILL.md, AGENTS.md, CLAUDE.md, and MCP-SERVER.md.

The wedge: cross-runtime portability + machine-readable dependency graph + open-extensible capability declarations. Cryptographic identity (Sigstore-anchored signatures) is an enabler that makes enterprise adoption viable, not the wedge itself.

Design priority order

Every MDA design decision follows P0 > P1 > P2:

  • P0 — AI-agent authorability. An LLM with only this Open Spec in context MUST be able to produce conforming output.
  • P1 — Human authorability. A human with a text editor and standard hashing and DSSE-capable signing tools MUST be able to produce conforming output.
  • P2 — Tooling convenience. Reference implementations are convenience, not requirement.

See spec/v1.0/00-overview.md §0.5 for the normative statement.

Three authoring modes

MDA artifacts MAY be produced in any of three equivalent ways:

  1. Agent mode — an AI agent writes the .md directly (primary use case in 2026)
  2. Human mode — a human writes the .md directly with standard tooling
  3. Compiled mode — an author writes a .mda source; the MDA compiler emits one or more .md outputs

See spec/v1.0/00-overview.md §0.6 and docs/create-sign-verify-mda.md for the human and agent-author paths.

Quick links

Governance

MDA is an independent project. It actively serves AAIF (Linux Foundation Agentic AI Foundation) governed targets — AGENTS.md and MCP-SERVER.md — as first-class compile destinations. MDA does not seek to join AAIF in v1.0. See spec/v1.0/00-overview.md §0.8.

Companion artifacts

  • JSON Schemas: schemas/ — frontmatter-source, frontmatter-skill-md, frontmatter-agents-md, frontmatter-mcp-server-md, relationship-footnote, mda-trust-policy, plus _defs/ for integrity, signature, requires, depends-on, version-range
  • Conformance suite: conformance/ — fixtures + manifest.yaml
  • Examples: examples/ — source-only/, skill-md/ (additional target examples land alongside reference-implementation maturity)
  • Vendor namespace registry: REGISTRY.md — also lists standard requires keys, reserved Sigstore OIDC issuers, reserved transparency log providers, and reserved DSSE payload-type values
  • Create-sign-verify recipes: docs/create-sign-verify-mda.md — hand-author and sign without the MDA CLI
  • Reference implementation: apps/cli/ — TypeScript, npm: @markdown-ai/cli. Architecture spec: apps/cli/IMPL-SPEC.md

Versioning

MDA v1.0 is the only major+minor planned. Future development:

  • Patch releases (v1.0.1, v1.0.2, …) deliver editorial fixes and reference-implementation maturity. They do not change the conformance contract.
  • Pre-release cycle: the current release candidate is v1.0.0-rc.3. The final v1.0.0 lands when the reference implementation passes 100% conformance.
  • Minor releases (v1.1.0) are not pre-planned. They emerge from observed adoption.
  • Major releases (v2.0.0) ship breaking changes in a new directory; previous versions remain immutable at their canonical URLs.

See spec/v1.0/00-overview.md §0.9.

License

This document set is licensed under CC-BY-4.0. Schemas and tooling under Apache-2.0.