4 · Syntax & Notation

The guiding principle: the core stays tiny. People should not need to learn a language to start. Everything advanced is optional.

The viral core:

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

A few arrows, not fifteen. Reduce edge semantics to a small closed set. Anything more specific becomes an edge label.

[A] -> [B]    # uses / calls / sends to
[A] => [B]    # hands off / escalates to
[A] x> [B]    # blocks / forbids
[A] ~> [B]    # observes / subscribes to
[A] <-> [B]   # interacts with (two-way)

The <-> arrow models two-way / channel interaction — e.g. a user who talks to a harness over a chat channel and gets replies back the same way. Model the channel as a node and read it as one two-way chain — clearer than drawing the request and the response as separate edges:

[human#me: Me] <->[Telegram] [mcp#tg: Telegram MCP] <->[Telegram] [harness#hermes: Hermes]

If you do want to show the request and response as distinct directed edges, you can — the renderer fans out parallel edges between the same pair so the round-trip stays legible:

[human#me: Me] ->[/command] [mcp#tg: Telegram MCP] -> [harness#hermes: Hermes]
[harness#hermes] ->[response] [mcp#tg] -> [human#me]

Layout direction

Diagrams render left→right by default. Set direction: TB in the frontmatter (or use the editor's layout toggle / am render --direction TB) for a top→bottom flow.

---
agentmark: 0.2.0
title: Top-down view
direction: TB
---
[User] -> [Agent] -> [Model]

Edge labels for specificity:

[Agent]  ->[selects tools] [MCP Tool Selector]
[Agent]  ->[streams tokens] [Chat UI]
[Policy] x>[forbids]        [Delete Production DB]

Stable IDs for round-tripping. Every important node gets an optional stable ID via type#id: Label.

[agent#coder: Coding Agent]
[harness#codex: Codex Harness]
[middleware#mcp_selector: MCP Tool Selector]

The renderer shows pretty labels while the source retains durable IDs. That solves the reverse-diagram problem.

Properties. Fast-changing detail lives in { ... } property blocks, never in the node type:

[agent#coder: Coding Agent {roles: [coder, tester], autonomy: 3}]
[browser#chromium: Chromium {mode: headless}]
[middleware#mcp_selector: MCP Tool Selector {strategy: shortlist, top_k: 12}]

The preamble (YAML frontmatter):

---
agentmark: 0.2.0
title: Hermes Coding Harness
id: hermes-coding-harness
owner: Joel Tong
status: draft
as_of: 2026-06-02
review_by: 2026-06-16
timezone: Asia/Singapore
views: [topology, runtime, decision, risk, cost, eval]
imports:
  - agentmark/mcp@0.1
  - agentmark/a2a@0.1
---

Versioning the language (SemVer):

0.2.0 = experimental
1.0.0 = stable core
1.1.0 = backward-compatible additions
2.0.0 = breaking changes