Story maps & INTENT.md

A project's spec is a story map: what people do in your product, broken into stories, grouped into releases. INTENT.md is the same spec as one plain markdown file in your repository, so any agent can read it.

The story map

• Personas: who uses the product, with their goals and pain points.
• Activities: the user journey, left to right. For example Set up profile → Take bookings → Run the day → Get paid. An activity can be split into steps.
• Stories: one capability each, from the user's point of view, filed under an activity.
• Releases: rows across the map. Every story belongs to one release.
• Backlog: an optional place to park ideas that aren't ready. Backlog stories don't count as work and are left out of INTENT.md.

What a story carries

Field	Values
Key	The project's prefix and a number, for example PB-42. It never changes. You can rename the prefix in Project settings; old keys keep working.
User story	Optional As a … I want … so that ….
Priority	must, should or could.
Effort	XS, S, M, L or XL.
Release	Which release it's in.
Acceptance criteria	What "done" means. See Acceptance criteria.
Dependencies and build sequence	What it needs first, and its place in the build order. See Build order.
Design references	Screens it should match: a Figma frame, a Claude design, an image, a Storybook story or a path in the repo.
Status	Where it is in the work (below).

Agents and the CLI can name a story by its key (PB-42), its full id, an id prefix, or its place in the build order (#5).

Statuses

The same words appear everywhere in the app.

Status	Stored as	Means
To do	todo	Nobody has picked it up.
Ready for dev	ready_for_dev	A person declared it ready for an agent to build.
In progress	in_progress	An agent is building it.
Needs rework	needs_rework	It was built, and a person sent it back.
Dev complete	done	The code is written and it's waiting for a person to review it. An agent gets it here with complete_story, which checks every must criterion passes first.
Approved	approved	A person accepted it.

Ready for dev and approved are set by people in the web app. Agents can't set them.

Two things sit beside the status rather than replacing it:

• Blocked: an agent raised a blocker and needs a decision. It shows over whatever the status says.
• Cancelled: work stopped. A cancelled story keeps its status, drops out of progress counts and is hidden unless you filter for it. You can bring it back at any time; nothing is deleted.

Releases

Release 1 is the MVP. Later releases follow in order, and you can rename any of them. Every project also ends with Go live, a release that always sorts last. It holds the launch checks and any stories about going live. See The Validate tab.

One release is the current release: the one the team is working on now. It's the one a person chose with Make current, or else the first release with stories that isn't closed. Validate, the release filter and the agent tools start from it.

A person closes a release when it's done, and can reopen it. Releases don't close themselves.

INTENT.md

INTENT.md is a single markdown file at the root of your repository. It holds what's being built, for whom, and what done means, in a shape both people and agents can read. It is an open format, version 1.0: you can write one by hand and any agent that reads markdown can use it. The full format is at intentdocs.com/intent-md.

IntentDocs generates it from your story map:

Section	What's in it
Header	The title, where the file came from, and when it was last exported.
## Product	The product's name and brief.
## Personas	One ### per persona, with goals and pain points.
## User journey	The activities as one arrow-joined line.
## MVP stories — build these first	Release 1's stories by activity. Each has its title and id, its user story, priority and effort, a Done when: list of acceptance criteria, and any design references.
## Release 2 — … and on	Later releases, in the same shape, under their own names.
## Going live — operational constraints	Your answers to the going-live questions, when you've given any. Included in the file the CLI writes (init, scope and sync) and in the copy agents read with get_context.
## Sync with intentdocs	The CLI commands that refresh the file and report progress. A hand-written file leaves this out.

Refresh it from the live map with npx intentdocs sync. An agent connected over MCP reads the same content live with get_context, so it never works from a stale copy. Check the Last exported time in the header to see how fresh a copy is.

INTENT.md and CLAUDE.md

They do different jobs. CLAUDE.md tells an agent how to work in the repository: conventions, commands, style. INTENT.md tells it what to build: the product, the people and the stories. npx intentdocs init adds a line to an existing CLAUDE.md pointing at INTENT.md.