From 55543daab251b792b7af1b98e8ec9e67e39ba84c Mon Sep 17 00:00:00 2001 From: Taras Mankovski <74687+taras@users.noreply.github.com> Date: Sat, 18 Jul 2026 21:39:59 -0400 Subject: [PATCH] docs(spec): record the Markdown Agents product vision MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Non-normative product direction for agent authoring: the agentic control flow is the document. Deterministic orchestration around nondeterministic model calls — named agents, explicit instructions and context as workflow data, bounded visible control flow, execution records that describe the real run, and a design test for future work. --- specs/markdown-agents-vision.md | 223 ++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 specs/markdown-agents-vision.md diff --git a/specs/markdown-agents-vision.md b/specs/markdown-agents-vision.md new file mode 100644 index 0000000..eed778b --- /dev/null +++ b/specs/markdown-agents-vision.md @@ -0,0 +1,223 @@ +# Markdown Agents: Product Vision + +- **Status:** Non-normative product direction +- **Audience:** Maintainers and contributors + +This document records the product direction for agent authoring in +Executable.md. It guides design without defining the current runtime contract. +The syntax examples are illustrative; the executable MDX specification remains +the authority for implemented behavior. + +## North star + +Executable.md is the easiest way to write reliable, well-behaved, observable, +and composable agents whose source code is Markdown. + +An agent document makes its orchestration readable. A reader can determine which +instructions an agent receives, which model acts, what context crosses an agent +boundary, how results flow into later steps, why execution repeats or stops, and +what output reaches the caller. + +The central product idea is: + +> The agentic control flow is the document. + +Executable.md provides deterministic orchestration around nondeterministic model +calls. It does not claim that model responses are deterministic. It makes the +construction, ordering, boundaries, and provenance of those calls explicit. + +## Product qualities + +### Easy + +- A useful agent starts as one readable Markdown file and runs with one command: + `xmd run reviewer.md`. +- Common workflows do not require JavaScript, provider components, or knowledge + of the execution engine. +- Defaults cover ordinary model invocation, instruction loading, output, and + cleanup. +- Invalid agent names, providers, props, references, and structured outputs fail + early with actionable diagnostics. + +### Reliable + +- Instructions are included explicitly and resolved by defined rules. +- Agent roles, providers, models, data dependencies, branches, and loop bounds + appear in the document. +- Structured results are validated before later steps consume them. +- Timeouts, iteration limits, and explicit termination prevent accidental + unbounded execution. +- Failures have defined propagation and output behavior. + +### Well-behaved + +- Work is scope-owned and cancelled when its enclosing operation ends. +- Providers, tools, permissions, budgets, and resources do not leak between + agent or component scopes. +- Sensitive context crosses agent and provider boundaries only when explicitly + selected. +- Expensive, destructive, or sensitive operations support visible approval + boundaries. + +### Observable + +An execution record can explain: + +- which instruction files were resolved and included; +- which agent, provider, and model handled each sample; +- what context and artifacts entered each call; +- which tools ran and what they returned; +- which values were captured; +- which branches and loop iterations executed; +- why the workflow completed, failed, or stopped; and +- what content was emitted as output. + +Observability describes the real execution rather than an agent's self-report. + +### Composable + +- Components package reusable agent behavior without hidden global state. +- Named agents can be invoked from multiple workflow steps. +- Captured and structured results become inputs to later components. +- Nested components may override contextual behavior without affecting parents + or siblings. +- Instructions, skills, tools, context transformations, and complete agents can + be composed explicitly. + +## Authoring model + +The following examples express the intended experience. They are not a frozen +syntax contract. + +### Deterministic repository instructions + +```text + + + +``` + +`` means that repository agent instructions are an explicit input to +the sample. Executable.md defines which applicable `AGENTS.md` files are read, +their precedence, and their order. The execution record identifies the exact +files and content used. + +There is no host-dependent question about whether an agent discovers the +instructions or which file it chooses to read. + +### Named agents and adversarial review + +```text + + You are the implementor agent. + + + + + You are the reviewer agent. + + + + + + Refactor the requested subsystem. + + + + Review the implementation and return a structured verdict. + + + + + + +``` + +In this model: + +- `` declares a named, scoped configuration; declaration alone does not + invoke the model. +- `` invokes a specific declared agent. +- `as="result"` captures validated workflow data rather than relying on prose + parsing by a later step. +- `` makes iteration visible and bounded. +- Conditional execution and `` make the termination rule part of the + document. +- Control components perform contextual behavior; child expansion does not + repair or rewrite an invalid parent structure. + +## Context as workflow data + +Context is an explicit value, not an invisible transcript shared by every agent. +An agent receives only the context passed to it. + +Context can contain messages, structured results, files, tool output, source +references, and other artifacts. It retains provenance and sensitivity metadata +when it crosses agent or provider boundaries. + +Context reduction has several distinct forms: + +- **Summarization** preserves a shorter narrative. +- **Selection** keeps only information relevant to the next task. +- **Distillation** converts history into structured decisions, evidence, state, + and open questions. +- **Externalization** stores large material as artifacts and passes references. +- **Deduplication** removes repeated instructions and unchanged content. + +Compression is explicit, observable, and non-destructive. It creates a derived +context while leaving the source context addressable. Its record includes the +source, instructions, strategy, model when applicable, token counts, and +resulting artifact. + +Structured distillation is preferred when later control flow depends on the +result. Free-form summaries are useful context, but they are not substitutes for +validated workflow state. + +## Foundation and agent layer + +Executable.md separates two concerns: + +1. The execution foundation provides component expansion, contextual APIs, + scoped resources, evaluation, controlled output, and execution records. +2. The agent authoring layer provides opinionated components for agents, + instructions, tools, skills, structured samples, context management, and + explicit control flow. + +The easy authoring experience builds on the foundation without exposing its +mechanics in ordinary agent documents. New agent capabilities should compose +through components and contextual APIs instead of adding unrelated special cases +to the expansion engine. + +## Relationship to Agent Skills + +[Agent Skills](https://agentskills.io/) packages reusable instructions, scripts, +references, and assets that an agent can load. Executable.md defines and runs +the explicit orchestration in which agents and capabilities participate. + +The concepts are complementary: + +- Agent Skills packages reusable procedural knowledge. +- Executable.md composes agents, instructions, model calls, dataflow, context, + and control flow into an inspectable workflow. + +Executable.md can consume standard skills explicitly without defining a +competing skill format. Skill inclusion remains visible in the agent document +and execution record rather than depending on heuristic activation. + +## Design test + +A design supports this direction when a reader can answer, from the document and +its declared inputs: + +1. Which agents exist, and what configures each one? +2. What exact instructions and context does each invocation receive? +3. Which model, provider, and tools can it use? +4. How does its result become data for the next step? +5. What bounds its cost, lifetime, and iteration? +6. What happens when it fails or returns invalid output? +7. Why did the workflow take a branch or stop? +8. What evidence in the execution record supports those answers? + +If those answers depend on hidden host behavior, implicit transcript sharing, or +an agent's own account of what it did, the design does not satisfy the product +goal.