▢→AgentMarkv0.2.0

AgentMark

Markdown for AI architecture, agent topology, and volatile AI decisions. Motto: Draw the system. Record the assumptions. Expire the claims.

AgentMark is a text-first notation for describing AI systems. It begins as a terse, Mermaid-like way to sketch agent topology, and matures into an AI Architecture Knowledge Language — a single source-of-truth document that captures not only what connects to what, but why it was chosen, under what assumptions, what constraints apply, what evidence supports it, when it expires, and how we know it still works.

A diagram language answers one question: What connects to what?

AgentMark answers seven: What connects to what — why was it chosen — under what assumptions — what constraints apply — what evidence supports this — when does it expire — and how do we know it still works?

That is the leap. Traditional notations (UML, C4, BPMN, Mermaid, ADRs) document the system. AgentMark documents the system plus the assumptions, decisions, constraints, confidence levels, and the shifting AI landscape that caused the system to exist — the part AI teams lose every two weeks when the ecosystem moves underneath them.

The biggest design idea

The diagram is not the source of truth. The .agentmark document is. The diagram is just one view generated from it. One file projects into many views: topology, runtime, decision, risk, cost, eval, landscape.

The central rule

This single rule is what makes AgentMark different from Mermaid, UML, C4, BPMN, and ADRs.

Any time-sensitive statement   MUST   include as_of and review_by.
Any comparative statement      MUST   include scope and metric.
Any decision                   SHOULD link to claims and constraints.
Any high-risk action           MUST   link to policy, approval, or authority.
Any claim used by a decision   MUST   have confidence and evidence.

The sketch core (what stays viral)

[User] -> [Agent] -> [Model]
[Agent] -> [MCP] -> [Tool]
[Agent] -> [RAG] -> [Data]
[Agent] -> [Eval] -> [Agent]

People should never need to learn a language to start. Everything advanced is optional and layers on top.

Three modes

Mode Purpose Surface
Sketch Virality, whiteboard, posts Tiny arrow grammar
Spec Engineering IDs, roles, properties, middleware
Decision Time-sensitive AI architecture Claims, constraints, decisions, invalidation

How this spec is organized

Read the pages in order. Each is a self-contained section of the AgentMark v0.2 specification.

  1. Overview & Philosophy — the leap, the precedents, the three modes
  2. The 8-Layer Meta-Model — L1 Actors → L8 Infrastructure
  3. Concept Ontology & Node Taxonomy — the durable vocabulary
  4. Syntax & Notation — arrows, edge labels, stable IDs, preamble, SemVer
  5. Knowledge Layer: Claims, Constraints, Decisions — the three-way split
  6. Market Intelligence — landscape radar, capability matrices, tradeoffs
  7. Temporal Validity, Benchmarks & Invalidation — making the document alive
  8. Governance & Observability — trust boundaries, authority, risk, telemetry
  9. Tooling: Views, Linter & CLI — projections and enforcement
  10. Full Worked Example: Hermes Coding Harness — the complete file
  11. Design Principles & The Central Rule — what to avoid, what to enforce
  12. Grammar Specification (EBNF & Conformance) — the implementable syntax

Spec status: draft v0.2 · Owner: Joel Tong.