AgenticMD

Examples

One canonical worked example. Drawn from examples/hotl.md in the repository. Demonstrates: required frontmatter, brief cap, four of the seven node types (domain_brief, decision, guardrail, correction, failure, project_rule), and a see-also terminal section.

The example, rendered

hotl

brief {#hotl-brief node:domain_brief}

HOTL — Humans Out Of The Loop — is a design constraint for agent-first systems. The human sets direction, approves at boundaries, and owns the artifacts. Rework that would otherwise interrupt the human’s attention is internalized into the runtime instead.

why-it-exists {#hotl-rationale node:decision}

HITL (human-in-the-loop) tools make the human the iteration mechanism. Every accept/reject is a context switch costing 40s–3min. Five to fifteen of these per task is the dominant cost. As model quality climbs, the override rate erodes the justification for keeping the human in the loop. HOTL’s bet: a multi-agent stack pays back its tokens by avoiding rework.

guardrail-do-not-interrupt {#hotl-guardrail-interrupt node:guardrail}

Never intervene mid-generation unless a hard boundary is at stake. Interrupting mid-stream wastes the rework already paid for and resets the loop to HITL by default. Read artifacts (PRs, audit reports, council verdicts) after the fact, not streams during.

correction-never-route-around {#hotl-correction-route node:correction}

When the system flags a verdict (council BLOCK, audit regression), the wrong move is to bypass the verdict and ship anyway. The verdicts are the system. Suppressing them collapses HOTL back to HITL and destroys the compounding-savings bet. Always investigate the verdict; never route around it.

anti-pattern-mid-stream {#hotl-anti-mid-stream node:failure}

Symptom: operator interrupts a streaming response mid-flight to “correct” the agent. Why it fails: the correction enters as user input on the next turn anyway; the intervention saves no time and adds queue contention. Right move: wait for the turn to finish, read the result, then send a follow-up if needed.

stance {#hotl-stance node:project_rule}

When operating inside a HOTL system:

  • Trust the verdicts unless they contradict observable reality.
  • Treat verdicts as artifacts you OWN, not obstacles you BYPASS.
  • Read artifacts, not streams.

see-also

  • AgenticMD SPEC.md for the format this example demonstrates
  • examples/smoke_test.amx for the action-file counterpart

What to notice

  • The brief is short (well under 80 words) and serves as a relevance probe — you can read it and decide whether the rest of the topic is what you need.
  • Each ## section carries a marker like {#hotl-brief node:domain_brief}. The node:type is from the closed seven; the section ID is prefixed with the topic's frontmatter.id.
  • The failure section follows the three-beat shape: symptom → why it fails → right move.
  • The correction declares a position the agent MUST treat as invalidating earlier claims.
  • No anaphora across sections. Each section stands alone if retrieved as a chunk.