# 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. Version 1.0 · Format text licensed CC BY 4.0 · Maintained by [intentdocs.com](https://www.intentdocs.com) INTENT.md is the persistence layer of [intent-driven development](https://www.intentdocs.com/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, and portable across agents. You can write one by hand; no IntentDocs account required. ## A complete example ```markdown # INTENT.md > Generated by intentdocs.com — paste this file into Claude Code as project context. > Last exported: 2026-08-14T09:00:00.000Z ## 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 --- ## 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//context > INTENT.md ``` ``` *Story ids are shortened above for readability — generated files carry full UUIDs.* ## The sections ### Header The # INTENT.md title plus provenance lines: where the file came from and when it was 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. INTENT.md keeps all four levels 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 ## 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. ## 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. --- More: [What is Intent-Driven Development?](https://www.intentdocs.com/intent-driven-development) · [Using IntentDocs with Claude Code](https://www.intentdocs.com/integrations/claude-code) · [Using IntentDocs with Cursor](https://www.intentdocs.com/integrations/cursor) · [Spec-driven development tools](https://www.intentdocs.com/blog/best-spec-driven-development-tools)