Getting Started

Connecting a repo

Run intent init to connect an existing project directory to a story map on intentdocs.com, and understand what it writes to disk.

`intent init [token]`

If you already have a project and story map on intentdocs.com, connect your local repository to it:

intent init

Run this inside the project directory you want to connect. If you aren't logged in yet, it prompts you to run intent login first.

The interactive flow:

Lists your projects on intentdocs.com.
Lists the story maps under the project you pick.
Validates the sync token for that map.
Writes .intent/config.json in the current directory.
Downloads INTENT.md.
Detects your tech stack (from package.json, pyproject.toml, requirements.txt, Cargo.toml, go.mod, or pubspec.yaml) and, if you don't already have one, scaffolds ARCHITECTURE.md pre-filled with what it found.
Adds .intent/ to .gitignore.
If a CLAUDE.md or .cursorrules already exists, appends a reference to INTENT.md into it.

intent init fails if the directory is already connected — there's no re-run/overwrite mode; disconnect first if you need to point at a different map.

There's also a legacy form, intent init <token>, that skips the login and project-picker steps and connects directly using a sync token you already have (a token starting with intent_sync_, pb_sync_, or sc_sync_).

What ends up in your repo

Path	Written by	Purpose
`.intent/config.json`	`intent init` / `intent scope`	Sync token, API base, project/map IDs. Auto-gitignored — never commit it.
`INTENT.md`	`intent sync` (and `init`/`scope`)	Plain-markdown snapshot of the story map: stories, acceptance criteria, status. See Story maps and INTENT.md.
`CLAUDE.md` / `AGENTS.md`	`intent sync --context` or `intent setup`	The full context harness — instructions, scope, memory, examples, tools, guardrails — assembled from your project page.
`ARCHITECTURE.md`	`intent init` (if missing)	Scaffolded with your detected stack.
`.intent/stories/<id>.md`	`intent next`, `implement`, `show`, `start`	Per-story working context: user story, acceptance criteria, and placeholders for your implementation notes — preserved across `intent sync`.

None of these are required to be committed except INTENT.md (and CLAUDE.md/ARCHITECTURE.md if you want them versioned) — .intent/ itself is local sync state and gets gitignored automatically.

Set up your AI coding tool

intent setup

Configures Claude Code and/or Cursor: slash commands for the full development workflow, CONVENTIONS.md scaffolding, and (for Claude Code) MCP server registration. See MCP Integration for what the MCP server exposes, and CLI Reference: Project setup for the full command details.

Start building

intent next          # pick up the next story
intent done <id>     # mark it complete — prompts for a decision or lesson learned
intent decide         # log an architectural decision
intent example         # log a reference pattern
intent sync            # refresh INTENT.md
intent sync --context  # regenerate CLAUDE.md from your project page

See the full CLI Reference for every command, or Core Concepts for how story maps, acceptance criteria, and verification fit together.