Core Concepts
Story maps & INTENT.md
How a project's spec is structured — personas, activities, stories, releases — and how INTENT.md persists it as a plain-markdown file.
The story map
A project's spec is a story map: personas, an activity backbone (the user journey, e.g. "Set up profile → Take bookings → Run the day → Get paid"), and stories filed under each activity. Every story carries:
- A stable id (a UUID — commands accept a prefix of it).
- A priority:
must,should, orcould. - An effort estimate:
S,M,L, orXL. - A release it belongs to (MVP is release 1; later scope lives in release 2, 3, ...).
- A user story, optionally broken into as-a / I-want / so-that.
- Zero or more acceptance criteria — see Acceptance criteria.
- Optional dependencies on other stories, which gate when it can be picked up — see Build sequences.
Levels of intent
Intent has a natural granularity, and the story map keeps all four levels in one place:
| Level | Carries | What an agent uses it for |
|---|---|---|
| Product | The problem, who it's for, and why now — one paragraph | Grounding: the sentence every downstream decision is checked against |
| Release | Sequencing — what must exist first (MVP), what can wait | Scope control: an agent asked to build release 1 has a hard boundary |
| Story | One capability from the user's point of view, with priority and effort | The unit of work: picked up, implemented, and reported on by id |
| Acceptance criterion | A single verifiable statement of what done means | The unit of verification: each criterion becomes a check the implementation must pass |
INTENT.md
INTENT.md is a single markdown file at the root of your repository that persists the story map — what's being built, for whom, and what done means — in a structure both human developers and AI coding agents can read. It's format version 1.0, and it's an open format: you can write one by hand, no IntentDocs account required, and any agent that reads markdown can consume it. intent init, intent scope, and intent sync generate and maintain it for you; they don't own it.
Sections
| Section | Required? | Contains |
|---|---|---|
| Header | Yes | Title plus provenance — where the file came from, when it was last exported. Agents use the timestamp to judge staleness. |
## Product | Yes | Product name and a short brief — the grounding paragraph every implementation decision gets checked against. |
## Personas | No | One ### subsection per persona — name, role, goals, pain points. Breaks ties when two implementations are both plausible. |
## User journey | No | The activity backbone as a single arrow-joined line. |
## MVP stories — build these first (and ## Release 2 — ..., etc.) | Yes | Stories grouped by activity: title, id, as-a/I-want/so-that, priority, effort, and a Done when: list of acceptance criteria. This is the contract verification checks against. |
## Sync with intentdocs | No | Present only when connected to a live project — the commands to refresh the file and report progress back. A hand-written INTENT.md simply omits this section. |
How INTENT.md relates to CLAUDE.md
They're complementary, not overlapping: CLAUDE.md tells an agent how to work in the repository — conventions, commands, style. INTENT.md tells it what the product is and what to build — personas, stories, acceptance criteria. CLAUDE.md typically points at INTENT.md for product context; see Getting Started → What is IntentDocs? for the full six-layer context harness CLAUDE.md assembles.
Staying current
- Connected to a project:
intent syncrefreshes the file, and agents can pull the latest live over MCP — the spec never goes stale mid-session. - Hand-written: it stays current the way any document does — you edit it.
The Last exported timestamp in the header is the tell for whether a copy you're looking at is fresh.