This page takes a package you write in Markdown and shows you the XML your agent reads in its place. On the way you learn why VibeVM turns every text into XML, and why that costs an author nothing. You learn how to name a rule so that a machine can point at it. And you learn to split a long text into a short header and a long body, the way C and C++ programmers split a library. You build one small package by hand, watch it compile, and prove that the two forms are one. Plan for about half an hour, with no agent required.
| What | Why | Where to get it |
| `vibe` | creates the project, converts the text and compiles it | [Install vibe](../start/install-vibe.xml) |
| a text editor | you write three short files by hand | any |
| about thirty minutes | the whole walk, with no agent in it |
In a project that asks for it, every text a package brings lands on disk as XML, whatever its author wrote it in. The texts are [specifications](../glossary/index.xml#specification), the rules a package states for the agents that work under it, and the reason for the conversion is the reader. A model that reads `<TESTS-FIRST fact="true" status="spec/done">` knows where the rule starts, where it ends, what it is called and what state it is in, without guessing at layout. Prose asks the model to infer all four.
The measurement agrees with the instinct. In a benchmark study, Yuan Sui and colleagues gave GPT-3.5 and GPT-4 the same tables written six ways, from plain text with separators to CSV, JSON, XML, HTML and Markdown ([WSDM 2024](https://arxiv.org/abs/2305.13062)). Across seven kinds of question, markup that names its parts beat the same content in prose. HTML did best overall, by 6.76 percent in the paper's own figure. On one task, telling where a table's parts begin and end, XML scored 96.00 percent against 93.00 for plain text and 92.33 for Markdown. The study is about tables, and that is exactly as far as this page takes it.
Vendor advice says the same from the other side. Anthropic's prompting guide for Claude, guidance rather than research, tells you to wrap each kind of content in its own XML tag so that the model parses a long prompt without ambiguity ([the guide](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)). Oleg Chirukhin, the author of VibeVM, found this in practice before any published work said it. The `xml` target is the form the projects of this manual use, and the one the specification names as the future primary form.
The names matter as much as the brackets. A section becomes an element named after itself, `<tests-first title="Tests before fixes">`. A rule becomes an element named after its id with one marker attribute, `fact="true"`, so that a reader who knows nothing of your vocabulary finds every rule by one test. The first reader of this dialect is an agent, and a tag that says what it holds needs no legend.
One caution for the readers who train models. The evidence above is about text a model reads. For text a model writes, it runs the other way: forcing an answer into JSON, XML or YAML can cost reasoning quality ([Tam and colleagues, EMNLP 2024](https://arxiv.org/abs/2408.02442)). VibeVM shapes what an agent reads and never what it answers, so that finding does not touch it.
Under the hood the two forms are one thing. Every document, Markdown or XML, is parsed into one tree: a title, a status, and sections nested by heading depth. Inside the sections sit paragraphs, lists, tables, fenced code and quotes, some carrying a [fact](../glossary/index.xml#fact), one named rule with a status. vibe never rewrites Markdown text into XML text. It parses into the tree and prints from it, in either direction.
Compiler writers call such a tree an *intermediate representation*, or IR: the one form that every front end parses into and every back end prints from. A compiler for three languages and four processors needs three front ends and four back ends, not twelve translators, and a rule stated once about the tree holds for every language. VibeVM has the same shape with two front ends and two back ends, Markdown and XML on each side.
It needs the tree for the same two reasons. Without it, each pair of forms would need its own converter, and converters drift. A survey of the code in 2026 found four readers of Markdown inside vibe, each accepting a slightly different dialect: the disease one shared tree is meant to cure. And every tool that reads a specification reads XML through the same tree: the checker of facts, the compiler that builds an agent's reading list, the router that resolves an address. So an XML document and its Markdown twin give every tool the same answer.
The tree has a future beyond conversion. The compiler names its levels, from one document's text up to the whole reachable closure of a project, and a compiler plugin may read and rewrite them. A long-horizon agent could plan over that closure one day: not a wall of text but a graph of named units with addresses. That is a direction, not a feature you can run today. And VibeVM itself is not an agent. It never reads your rules to act on them; it prepares the text, the tree and the addresses for whichever agent you run.
The consequence for you is plain. Write the specifications of your own packages in Markdown, the form your editor and your reviewers already handle. Every property of the XML form arrives on its own: named elements, machine-checked facts, an address on every rule. The steps below do exactly that, and end by proving it.
1. Create a project in an empty folder, as on [Create your first project](../start/first-project.xml). The name becomes the folder:
2. Open `review-lab/vibe.toml`, the project's [manifest](../glossary/index.xml#manifest), and add one line under `[project]`:
3. Work inside the folder from here on: `cd review-lab`.
The line decides the form of every text a package brings in. With `xml`, vibe converts what an author wrote in Markdown as it copies the package in, and copies XML as it is. Your own files are never converted. Without the line, each file keeps its author's form.
1. Add a package to the project. It is a `flow`, a package of working rules for an agent, and it asks for the `normal` format, whose meaning step 4 explains:
2. Open the manifest the scaffold wrote:
3. Change two lines: give the package a `description`, and set `link = "static"`. The end of the file then reads:
The [link type](../glossary/index.xml#link-type) says how the package's text reaches the agent. With `static`, vibe compiles the text into the one file an agent reads first, in full, at every session start. With `dynamic`, the scaffold's choice, it lists the file for the agent to open on its own. This page uses `static`, so that you can watch the compiler work.
The package needs two documents. The first is the note an agent reads at session start, the package's [boot snippet](../glossary/index.xml#boot-snippet). The second is the contract: the rules themselves, each with an address.
1. Replace the scaffold's note, `vibevm/vibepacks/org.acme/review/v0.1.0/vibevm/vibespecs/boot/10-flow-review.md`, with this:
The line that starts with `#use` is a directive: an instruction to the compiler, not prose. It pulls the contract in ahead of the note, so that the agent meets the rules before the note referring to them.
2. Create `vibevm/vibespecs/contract/REVIEW.md` inside the same package:
Read the file as a machine does. A heading carries an [anchor](../glossary/index.xml#anchor) in braces, `{#one-idea}`: the name a citation uses, the part after `#` in an address. A paragraph that opens with `@fact:ONE-IDEA` is a fact, one anchored rule with a status. The `@status:spec/done` at its end says that the rule is settled and not yet built. The `<status>` element under the title is the same marker for the whole document. Heading anchors and fact ids share one namespace, so no two may repeat in a document.
The case of an id is a signal. Upper-case ids mark rules with binding weight; lower-case ids mark headings, lead-ins and notes. The first rule's address is `spec://org.acme/review/contract/REVIEW#ONE-IDEA`. It joins the package's [coordinate](../glossary/index.xml#coordinate), the document's path under `vibevm/vibespecs/` without its extension, and the anchor. The address does not change when the file changes form.
3. Check the markup of the package:
The check reads every document under the package's `vibevm/vibespecs/`. A marker on a paragraph without an anchor, and an id defined twice, are errors that name the line.
4. Install the package into its own project:
The install copies the package into `vibevm/vibedeps/`, converting both documents to XML. It also compiles the [boot lane](../glossary/index.xml#boot-lane), the ordered list of files an agent reads at session start. The last two lines of the diff are that lane: `INDEX.md` gained the line that names the compiled file, and `STATIC.xml` appeared.
5. Open the contract as the agent will read it:
Every part is named after itself. The section `{#one-idea}` became the element `<one-idea>`, with its title as an attribute. The fact became `<ONE-IDEA fact="true" status="spec/done">`. The `@fact:` prefix and the `@status:` suffix are gone from the text: they were spelling, and the tree keeps only meaning. Inline Markdown, such as backticks and links, rides inside the text unchanged.
A contract that says everything is expensive. Every word in the boot lane is read by every agent at every session start. So the text that must always be present wants to be short, and the reasoning behind it wants to sit where an agent can reach it when it asks. C solved a problem of this shape in the 1970s with two files, and C++ kept the answer. A header, `.h`, declares in a few lines what a library offers; a translation unit, `.c` or `.cpp`, carries the implementation. Everyone who uses the library includes the header, and nobody pastes the implementation into their own code.
VibeVM borrows the split for text. A package in the `normal` format keeps two folders under `vibevm/vibespecs/`. `contract/` is the header: small, cheap to load, the surface other packages and agents see. `source/` is the implementation: the heavy body, pulled in only when something asks for it. A C compiler sees the whole program and matches declarations to definitions itself; vibe has no such view of your text, so the contract names its implementation with a `#source` directive. The default format, `simple`, has none of this: such a package is carried whole and read because it is present.
The specifications call this machinery inheritance, as in C++: one document builds on another without copying its text. Two directives do the pulling, and you have met one. `#use` names a document or a section that must be read before the text that uses it; the compiler copies it in ahead, and the copy brings along whatever the copied document pulls in itself. `#source` names the implementation of a contract, and the compiler compiles it in behind the contract. In the compiled file both directives are gone, consumed. A third, `#embed`, splices exactly one addressed node into the place where it stands, a macro rather than an include.
1. Create `vibevm/vibespecs/source/details.md` in the package, the implementation of the contract:
Every anchor here differs from the contract's, `one-idea-why` beside `one-idea`; the edge cases below say why. The last section is a list in which every item is a fact.
2. In `contract/REVIEW.md`, add one line after the first paragraph:
The address names a whole document, with no anchor, so the compiler takes it from the title down.
3. Install again:
No package was added, so the lane is the only line of the diff: the compiled file grew by the implementation.
4. Ask vibe what an agent reads first:
One package, linked `static`, and the `x` says that its text is compiled into `STATIC.xml`.
5. Open the compiled file:
Read it from the top. The comments come first: the rules an agent applies to the labels in this file, then a table of every renamed anchor. XML forbids two hyphens inside a comment, so the `--` of a label is written `-%2D` there; the elements below carry the real `--`. Then one XML document: the contract first, then the implementation compiled in behind it as one nested section. Last comes the note from the snippet, as a plain `<section>`, because its heading had no anchor. The `#source` and `#use` lines are gone.
Every anchor now carries the prefix `org-acme--review--`, the label of its origin. Two packages that both name a section `root` cannot collide in one file, and the table at the top says what each short name became. Cite the source document, never this file: it is a cache that changes whenever a package changes.
6. Open the record vibe keeps beside its copy of the package:
`spec_format` names the target and `converter_recipe` the converter's version. Each row says whether a file was `copied` or `converted`, with the hash of what landed. Keep the file in mind: step 5 reads it again.
The constructs this page used, side by side, from its own files:
| Markdown | XML |
| `# Review rules {#root}` | `<title id="root">Review rules</title>` |
| `<status stage="spec" state="done"/>` | the same element, unchanged |
| `## One idea per change {#one-idea}` and the text under it | `<one-idea title="One idea per change">…</one-idea>` |
| a paragraph | `<p>…</p>` |
| `@fact:ONE-IDEA … @status:spec/done` | `<p><ONE-IDEA fact="true" status="spec/done">…</ONE-IDEA></p>` |
| `- @fact:CHECK-SCOPE … @status:spec/done`, a list of facts | `<facts ordered="false"><CHECK-SCOPE fact="true" status="spec/done">…</CHECK-SCOPE></facts>` |
| `#source spec://…`, a directive | `<p>#source spec://…</p>`, a plain paragraph |
| `# Review flow`, a title without an anchor | `<title>Review flow</title>` |
| backticks, emphasis, links, `spec://` addresses | the same characters inside the text |
The dialect is closed, and it is small on purpose. It expresses exactly what Markdown can express, so that converting in either direction loses nothing in meaning, and an element outside it is a loud error, never a silent skip. Two anchors have no element of their own: one that starts with a digit, and one that collides with a word of the dialect such as `title` or `list`. For those, a generic `<section id="…">` or `<fact id="…">` stands in, and every reader accepts both spellings. The one exception to the rule of equivalence is the vocabulary of documentation packages, this manual among them: their runnable examples and live citations have no Markdown form, and project to Markdown one way only.
You wrote Markdown and shipped XML. The last step shows that the XML you would have written by hand is the same file, to the byte.
1. Ask the converter what a conversion would lose:
The converter parses each file into the tree, prints the XML, reads that back and prints Markdown again, then compares. The verdict `ir-stable-loss` means that the tree survived and the bytes did not, and the diff shows what changed. Here it is one blank line at the end of each file, added by the Markdown printer. Without `--force` the command refuses a file over such a loss. A change of meaning it refuses always, because that would be a defect of the converter, never of your file.
2. Convert the three documents. The command writes each `.xml` beside its `.md` and deletes the `.md` in one act. The tree never holds a document in both forms:
3. In the package manifest, point `source` at the new file, `vibevm/vibespecs/boot/10-flow-review.xml`.
4. Install again:
5. Open the record again:
Compare it with the record of step 4. Each of the three documents is now `copied`, and the hash of each is the hash it had as `converted`. What the converter wrote from your Markdown is what the install wrote from it, to the byte. The compiled file did not change either:
The same bytes, the same lines. This is what one model underneath means in practice. The form you write in is your choice; the text that reaches the agent is the same either way. A project with `spec_format = "markdown"` runs the same road the other way. The Markdown it writes from your XML is your original file plus that one blank line.
Your package lives under `vibevm/vibepacks/org.acme/review/v0.1.0/`: a manifest, a README and three XML documents, yours to edit. vibe's copy of it lives under `vibevm/vibedeps/org.acme.review/0.1.0/`, with the record `.vibe-slot.toml` beside it, and is rewritten at every install. `vibevm/vibespecs/boot/` holds the compiled `STATIC.xml` and `INDEX.md`, whose `static` line names the compiled file, next to your two boot files, which no install touches. `vibe.lock`, the project's [lock file](../glossary/index.xml#lock-file), pins the package to its version and its hash.
Under `spec_format = "xml"`, a source section must not reuse an anchor of the contract, and the note's title carries no anchor. The compiler merges sections that share an anchor, and the merged result does not compile into `STATIC.xml` today. The install stops with `fact id … is defined twice`; the copy of the package is already on disk, and the lock is not written. Two documents whose titles are both `{#root}` collide the same way. Under the default `spec_format` the same package compiles.
A dot inside an anchor is a path, not a character. `{#verification.timeout}` cannot be addressed, while `#verification.timeout` reaches a section `timeout` nested under a section `verification`. An anchor is a letter followed by letters, digits, `_` and `-`.
`vibe init package` writes `link = "dynamic"` whatever `--link` you pass. Set the link in the manifest, as step 2 does.
With `link = "dynamic"` there is no compiled file. `INDEX.md` names the note itself, and the agent that opens it meets the `#use` line and must follow it on its own.
`vibe explain` answers only for a package that carries a [traceability map](../glossary/index.xml#traceability-map). For this one it says so and stops.
`vibe facts check` catches a misspelt state in the element form, `state="finished"`, and names the value. In the shorthand, `@status:spec/finished` is not read as a marker at all, and the file passes as clean. The states are `plan`, `work`, `done`, `hold` and `void`; the stages are `idea`, `spec`, `impl`, `test`, `doc`, `freeze` and `unknown`.