Format· Format v1.0

The INTENT.md format

INTENT.md is a single markdown file at the root of a repository that captures the product's intent — what is being built, for whom, and what done means — in a structure both human developers and AI coding agents can read.

INTENT.md is the persistence layer of intent-driven development: the Intent Loop runs Intent → Specification → Plan → Implementation → Verification → Updated intent, and this file is where the intent lives — diffable, versioned with the code it describes, and portable across agents.

Why an open format

Intent should outlive any tool. A spec locked inside a platform dies with your subscription; a markdown file at the repo root survives agent switches, editor switches, and vendor switches. So the format is open: you can write INTENT.md by hand — no IntentDocs account required — and any agent that can read markdown can consume it. IntentDocs generates and maintains the file for you; it doesn't own it.

A complete example

# INTENT.md
> Last updated: 2026-10-13

## Product
**Willow — bookings for dog groomers**

Independent groomers lose evenings to WhatsApp back-and-forth. Willow gives
them a booking page, automated reminders, and a simple day view.

## Personas
### Sam — solo mobile groomer
**Goals:** fill the calendar without answering messages at 9pm
**Pain points:** no-shows, double bookings, deposits are awkward to ask for

## User journey
Set up profile → Take bookings → Run the day → Get paid

## MVP stories — build these first

### Take bookings
**Client books a slot from the public page** (id: `b7e2f1a0`)
*As a dog owner, I want to pick an open slot and book it, so that I don't have to message back and forth*
Priority: must | Effort: M
*Done when:*
- Open slots reflect the groomer's working hours and existing bookings
- Booking creates a confirmed appointment and sends the owner an email
- Double-booking the same slot is impossible

**Groomer takes a deposit at booking** (id: `c4d90e12`)
Priority: should | Effort: M
*Done when:*
- Card payment is taken via Stripe before the slot is confirmed
- Deposit amount is configurable per service

## Release 2 — Enhancements

### Run the day
**Day view shows the route between mobile appointments** (id: `f81a3c55`)
Priority: could | Effort: L
*Done when:*
- Appointments render in order with travel time between them

Ids can be any stable string — files generated by IntentDocs carry full UUIDs.

The sections

`Header`

The # INTENT.md title, optionally followed by provenance lines: where the file came from and when it was last updated (a generated file says Last exported).

Why agents need it: Agents use the timestamp to judge staleness; humans use it to know whether to refresh before trusting it.

`## Product`

The product name in bold, followed by a short brief — the problem being solved, in prose.

Why agents need it: This is the agent's grounding context. Every implementation decision downstream is checked against this paragraph.

`## Personas` (optional)

One ### subsection per persona — name, role, goals, pain points.

Why agents need it: Lets an agent resolve ambiguity the way the user would: when two implementations are both plausible, the persona's goals break the tie.

`## User journey` (optional)

The activity backbone as a single arrow-joined line: Set up → Use → Pay.

Why agents need it: The journey is the map's spine — it tells an agent how features relate in the user's world, not just in the codebase.

`## MVP stories — build these first`

Release 1's stories, grouped by activity. Each story carries its title, a stable id, an optional as-a/I-want/so-that line, priority and effort, and a *Done when:* list of acceptance criteria.

Why agents need it: This is the contract. The id lets agents report progress against a specific story; the acceptance criteria are what verification checks against. Later releases follow in their own sections (## Release 2 — …), same shape.

`## Sync with intentdocs` (optional)

Present when the file is connected to a live IntentDocs project: the commands that refresh the file, list remaining work, and mark stories done.

Why agents need it: Turns the file from a snapshot into a loop — the agent can pull the current truth and write completion back, which is what keeps built-versus-planned auditable. A hand-written INTENT.md simply omits this section.

Levels of intent

Intent has a natural granularity, and each level answers a different question. INTENT.md keeps all four in one file:

Product — carries: The problem, who it's for, and why now — one paragraph. Agent use: Grounding: the sentence every downstream decision is checked against.
Release — carries: Sequencing — what must exist first (MVP), what can wait. Agent use: Scope control: an agent asked to build release 1 has a hard boundary.
Story — carries: One capability from the user's point of view, with priority and effort. Agent use: The unit of work: picked up, implemented, and reported on by id.
Acceptance criterion — carries: A single verifiable statement of what done means. Agent use: The unit of verification: each criterion becomes a check the implementation must pass.

Tooling

npx intentdocs init — connect a repository and generate INTENT.md from a live story map
intent sync — refresh the file with the current stories and their status
MCP — agents like Claude Code and Cursor read the same content live over MCP, so the spec never goes stale mid-session
By hand — the format is plain markdown; hand-written files are first-class

A file connected to IntentDocs ends with the optional sync section, so an agent can refresh it and report progress:

---

## Sync with intentdocs

This story map is connected to intentdocs.com. Use these commands to keep it in sync.

**Refresh this file** (get latest stories from intentdocs):
```bash
curl -s https://intentdocs.com/api/sync/<token>/context > INTENT.md
```

Versioning & licence

This page documents format version 1.0 — exactly what the intentdocs generator produces today. Changes to the format will bump the version and be listed here. The format specification text is licensed CC BY 4.0: use it, implement it, build tooling against it. If you're comparing file-based approaches to specs, see the spec-driven development tools guide.

Frequently asked questions

How is INTENT.md different from CLAUDE.md?

CLAUDE.md tells an agent how to work in a repository: conventions, commands, style. INTENT.md tells it what the product is and what to build: personas, stories, acceptance criteria. They complement each other — many repositories carry both, and CLAUDE.md typically points at INTENT.md for product context.

Do I need IntentDocs to use INTENT.md?

No. The format is open and the file is plain markdown — you can write one by hand and any agent can read it. IntentDocs generates and maintains it for you: an AI interview produces the first version, intent sync keeps it current, and the sync section connects it to a live audit trail — but a hand-written INTENT.md is a valid INTENT.md.

How does INTENT.md relate to spec-kit's markdown files or SpecDD's .sdd files?

Spec-kit produces workflow artifacts (constitution, plan, tasks) for a single feature cycle, and SpecDD scatters many per-module contract files beside the code. INTENT.md is one product-level source of truth: the whole map of what's being built and what done means, in a single file at the root. The approaches compose — INTENT.md carries product intent while per-module files carry local detail.

Where does the file live and how does it stay current?

At the repository root, committed like any other file. If it's connected to IntentDocs, `intent sync` refreshes it and agents can pull the latest over MCP or the sync API; the Last exported timestamp in the header shows staleness at a glance. If it's hand-written, it stays current the way any document does — you edit it.

Ready to build what you intended?

Turn your idea into a structured spec and hand it to Claude Code or Cursor over MCP — with an audit trail of built versus planned.

Start free →

Plan free · first build free · no card required