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
> 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/<token>/context > INTENT.md
```

Story ids are shortened here 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, 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

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 →

7-day free trial · no card required