▢→AgentMarkv0.2.0

9 · Tooling: Views, Linter & CLI

The viral thing stays simple text. The durable thing is the compiler/linter ecosystem around it. Because the .agentmark document is the source of truth, tooling can project, validate, and flag staleness automatically.

Projections — one file, many views. Same file, different generated diagrams. Each view declares which node types it shows.

view topology:
  show: [human, ui, agent, harness, middleware, mcp, tool, data]
view runtime:
  show: [agent, runtime, queue, event, retry, timeout, sandbox]
view decision:
  show: [decision, constraint, claim, landscape, matrix]
view risk:
  show: [trust, policy, guardrail, approval, secret, authority]
view cost:
  show: [model, api, budget, metric]
view eval:
  show: [bench, eval, metric, claim]

CLI:

am render hermes.agentmark --view topology --to mermaid
am render hermes.agentmark --view decision --to svg
am render hermes.agentmark --view risk     --to png
am lint  hermes.agentmark
am stale hermes.agentmark
  • render — project a view to Mermaid / SVG / PNG.
  • lint — enforce documentation quality.
  • stale — report claims/decisions past their review_by or with broken invalid_if conditions.

Linter rules — what makes the standard enforce useful documentation rather than merely permit it. Example output:

$ am lint hermes.agentmark

ERROR  D-001 depends on expired claim C-003.
WARN   Qwen Coder marked "caution" but no benchmark evidence linked.
WARN   Browser Agent uses headless Chromium but no sandbox declared.
ERROR  Refund API has mode: write but no approval policy.
WARN   MCP Gateway exposes 84 tools but no selector/middleware documented.

These checks operationalize the Central Rule: every time-sensitive statement needs dates, every comparison needs scope + metric, every high-risk action needs an authority/approval link, and every decision-bearing claim needs confidence + evidence.

Middleware as a real architecture feature. Documenting it captures a genuine design decision ("we do not expose all MCP tools; we shortlist first"), not a comment.

[middleware: MCP Tool Selector]
[middleware: Prompt Injector Guard]
[middleware: PII Scrubber]
[middleware: Rate Limiter]
[middleware: Cost Governor]
[middleware: Context Compressor]
[middleware: Tool Permission Filter]
[middleware: Audit Logger]

[agent#coder: Coding Agent]
  -> [middleware#mcp_selector: MCP Tool Selector {strategy: shortlist, top_k: 12}]
  -> [mcp#gateway: MCP Gateway]
[middleware#mcp_selector] -> [policy: Allowed Tools Policy]
[middleware#mcp_selector] -> [log: Tool Selection Trace]

Note: in this implementation, am render supports svg and mermaid; PNG export is available in the web editor.