A reader sees .intent as the middle ground between PDF and Markdown: the goal is locked, and the work stays free as long as it still meets it.

The .intent vision

Every era of digital documents froze one layer. PDF, born from John Warnock’s 1991 vision of “view and print anywhere,” froze appearance: a page looks identical on every machine, but its content is locked and hard to edit. Markdown, created by John Gruber in 2004, froze meaning: the source stays readable as plain text, while each renderer decides how it looks. Neither format captures what matters most in the age of AI agents: what the document is for.

.intent is the next step. It freezes intent. A .intent file combines PDF’s locking with Markdown’s readability, and adds something neither ever had: built-in verification.

Each file has a simple structure: a name, a version, an optional link to the version it supersedes, a locked goal, evals, and a fulfillment. The goal is one plain sentence stating the expected outcome. The evals are checks an agent runs on demand to verify the work meets the goal. Some are runnable tests with a hard pass or fail; others are plain sentences an AI judges with a written reason. The fulfillment is the actual work, whether text, design, spec, or code, and stays free to edit.

The contract is strict. The goal and evals never change within a version. Changing either one requires a new version, which points back to the old one through supersedes, building a traceable history of how the goal evolved. Old evals can be rerun on new work to catch regressions.

.intent is plain text readable in any editor, but it is its own format, opened and verified by .intent tools. It is aimed at any digital product, not just code.

The goal of publishing is to follow Markdown’s path: an open spec, a small reference tool, real examples, and a launch story. PDF locked appearance, Markdown locked meaning, and .intent locks purpose.

View source

---
name: launch
version: 1
---

# Goal
A reader sees .intent as the middle ground between PDF and Markdown: the goal is locked, and the work stays free as long as it still meets it.

# Evals
- test: readable in under 5 minutes → [ "$(intent words "$INTENT_FILE")" -le 1100 ]
- judge: a reader with no context can explain the middle ground in one sentence
- review: it says what I actually think

# Fulfillment
## The .intent vision

Every era of digital documents froze one layer. PDF, born from John Warnock’s 1991 vision of “view and print anywhere,” froze appearance: a page looks identical on every machine, but its content is locked and hard to edit. Markdown, created by John Gruber in 2004, froze meaning: the source stays readable as plain text, while each renderer decides how it looks. Neither format captures what matters most in the age of AI agents: what the document is for.

.intent is the next step. It freezes intent. A .intent file combines PDF’s locking with Markdown’s readability, and adds something neither ever had: built-in verification.

Each file has a simple structure: a name, a version, an optional link to the version it supersedes, a locked goal, evals, and a fulfillment. The goal is one plain sentence stating the expected outcome. The evals are checks an agent runs on demand to verify the work meets the goal. Some are runnable tests with a hard pass or fail; others are plain sentences an AI judges with a written reason. The fulfillment is the actual work, whether text, design, spec, or code, and stays free to edit.

The contract is strict. The goal and evals never change within a version. Changing either one requires a new version, which points back to the old one through supersedes, building a traceable history of how the goal evolved. Old evals can be rerun on new work to catch regressions.

.intent is plain text readable in any editor, but it is its own format, opened and verified by .intent tools. It is aimed at any digital product, not just code.

The goal of publishing is to follow Markdown’s path: an open spec, a small reference tool, real examples, and a launch story. PDF locked appearance, Markdown locked meaning, and .intent locks purpose.

Raw file: /posts/launch/v1.intent