11 · Design Principles & The Central Rule

What AgentMark must deliberately avoid. For durability, do not bake vendor-specific concepts into the core grammar. Vendor names belong in values, not syntax. The grammar must outlive the vendors.

# Bad — vendors fused into the grammar
[claude-code-subagent]
[codex-run]
[qwen-mcp-bad]

# Good — stable types, vendors as values
[agent: Reviewer {vendor: Anthropic, harness: Claude Code}]
[harness: Codex]
[claim: Qwen MCP reliability weak]

The same discipline applies to agent roles (one agent type + roles property, not 50 agent types) and to fast-moving detail (push it into { } properties, keep node types stable).

Keep the surface viral, the depth durable. A notation must be trivial to start yet rigorous when needed. The answer is the three modes — Sketch / Spec / Decision — sharing one grammar. Beginners write four arrows; engineers add IDs, roles, and middleware; architects add claims, constraints, and invalidation. Nobody is forced up the ladder before they need it.

The five-layer mental model:

1. Graph      What exists and how it connects
2. Runtime    How it executes
3. Contracts  What must / must not happen
4. Claims     What we currently believe
5. Decisions  What we chose and why

Prior topology notations handled only layer 1. The real, differentiating power is layers 3–5.

The Central Rule — the rule that makes AgentMark categorically 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.

Why it matters. AgentMark is not just a way to draw AI systems. It is a way to prevent AI architecture from lying as the market changes. It documents the system plus its assumptions, decisions, constraints, confidence levels, and the shifting landscape that caused it to exist — fused into one source-of-truth file, projected into many views, and continuously checkable for staleness. Draw the system. Record the assumptions. Expire the claims.