Project setup

These commands create a project, connect a directory to its story map, and set up your coding agent. Run them from the root of the repository you want connected.

intentdocs start

Walks you from a problem statement to a new project.

intentdocs start

No arguments or options. Needs a valid login.

The flow:

1. You describe the problem. It must be at least 10 characters.
2. The CLI asks up to three follow-up questions about the idea.
3. It writes a pitch, names the target user, and suggests product names. You pick one or type your own.
4. It creates the project and prints the start of its ID.
5. It asks whether you have validated demand. If you have not, it offers to publish the project to Explore so others can give feedback. Publishing asks you to confirm a summary first.
6. It asks whether you are ready to scope. Yes runs intentdocs scope with the new project's ID. No prints the command to run later.

If you have reached your plan's project limit, project creation fails and the CLI says so.

intentdocs scope

Generates a blueprint and story map for a project, then connects the current directory to it.

intentdocs scope [projectId]

intentdocs scope 3f9c2a1e-7b4d-4c1a-9e2f-0a8b6c5d4e3f

The CLI asks four questions: the main steps a user takes, the key personas, the smallest thing you could build to test the idea, and any technical constraints. It then generates the blueprint and prints a short summary: the hypothesis, persona names, story count and build-order steps.

After that it:

• Connects the directory the way init does: writes .intent/config.json with the project ID, map ID, map title and the project's workspace (and its app URL when it has one), then downloads INTENT.md. If the directory is already connected, it leaves .intent/config.json as it is, says so, and skips this step. To connect it to the new project instead, delete .intent/config.json and run intentdocs init.
• Offers to write MOCKUP_PROMPT.md, a prompt you hand to your coding agent to build a single-file HTML mockup. The CLI does not build the mockup itself.
• Offers to run git init and commit INTENT.md (and MOCKUP_PROMPT.md), when the directory is not already a Git repository.
• Offers to run intentdocs setup.

intentdocs templates

Lists the built-in story map templates, or previews one.

intentdocs templates [name]

intentdocs templates
intentdocs templates saas

The templates are saas, marketplace, mobile-app and ai-tool. A preview prints the template's story, activity and persona counts and the steps under each activity:

  SaaS Starter: Multi-tenant SaaS with auth, billing, and dashboards
  16 stories, 5 activities, 2 personas
 
    Sign up & Onboard: Registration → Team setup → First-run experience
    Core Workflow: Dashboard → Main feature → Data management
    ...

This command only displays templates. It does not create or change anything.

intentdocs init

Connects the current directory to an existing story map.

intentdocs init

No options. The command shows an optional [token] argument for backwards compatibility, but sync tokens are retired: passing one prints a message and exits 1.

What it does:

1. Logs you in first if you are not logged in.
2. Lists the projects your token can reach and asks you to pick one by number, then a story map in that project.
3. Makes a first call to the map as you, to confirm you have access, and prints the story counts.
4. Writes .intent/config.json: the project ID, map ID, map title and the project's workspace. It also stores the project's app URL when it has one, which intentdocs done uses for screenshots.
5. Downloads INTENT.md.
6. Adds .intent/ to .gitignore, if the file exists.
7. If CLAUDE.md exists and does not mention INTENT.md, appends an intentdocs block. The block points the agent at INTENT.md, asks it to save each test with save_tests, tells it to link each pull request with intentdocs done <story> --pr <url> or the complete_story or link_pr tool, and gives the PR footer to use when GitHub is not connected. If .cursorrules exists and does not mention INTENT.md, appends one line pointing at it.
8. If there is no ARCHITECTURE.md, detects your stack from the project files, asks you to confirm it, and writes an ARCHITECTURE.md scaffold.

Then it asks two questions:

• Allow tools without asking. It shows the IntentDocs MCP tools it would allow in the project's .claude/settings.json, and writes them only if you answer y. Allowed: the read tools list_projects, get_context, get_session_context, list_stories, get_story, get_status, get_build_order, get_vision, get_design, get_run, and the build-loop tools next_in_run, start_story, report_criteria, save_tests, complete_story, link_pr, add_note. These still ask every time: replace_criteria, update_stories, create_stories, cancel_story. The rules use the server name you gave IntentDocs in .mcp.json or ~/.claude.json, or intentdocs when it finds none. For Cursor, it prints which tools to allow in Cursor's settings.
• Set up CI test reporting. Answer y to run intentdocs ci now.

Behaviour to know:

• If the directory is already connected, init tells you to run intentdocs sync instead and exits 0. To reconnect, delete .intent/config.json first.
• If your token reaches no projects, or the project has no story maps, init says so and exits 0. Create one at intentdocs.com first.
• The workspace it records is what later commands check your token against. See Workspaces and tokens.

intentdocs sync

Refreshes local files from the live story map.

intentdocs sync [--context]

intentdocs sync
intentdocs sync --context

Without options, sync:

• Rewrites INTENT.md and prints the done count, for example ✓ INTENT.md updated (12/30 done, 40%).
• Records a sync event in the project's activity feed.
• Refreshes every .intent/stories/<id>.md file already on disk from the live story. What you wrote under Approach, Implementation notes, Decisions and Relevant files is kept. Files for stories no longer on the map are left in place and reported as orphaned.

With --context, it fetches the project's assembled agent context (instructions, scope, decisions, examples, tools and guardrails) and writes it to .claude/CLAUDE.md when a .claude/ directory exists, otherwise to CLAUDE.md at the root. Run it after you change the project's instructions, guardrails, decisions or examples.

Note: sync --context replaces the whole context file. Anything you wrote in that file by hand is lost; keep your own notes in a different file.

Note: In a story context file, the title, status, user story, criteria, design references, spec and implementation plan come from the server and are rewritten on every refresh. The Approach, Implementation notes, Decisions and Relevant files sections are yours: sync, show and implement keep what you wrote there, including any ## headings you add inside them. Anything you edit elsewhere in the file is replaced. To put a note on the story itself, use intentdocs note.

intentdocs setup

Configures Claude Code, Cursor or both to work with this project.

intentdocs setup

No arguments or options. Needs a valid login and a connected checkout. It asks which tool to configure: Claude Code, Cursor, or both.

For Claude Code, it:

• Appends an intentdocs section to CLAUDE.md, or creates the file, unless the section is already there.
• Writes twelve slash commands to .claude/commands/: intent-next, intent-implement, intent-review, intent-document, intent-test, intent-status, intent-done, intent-sync, intent-propose, intent-context, intent-decide and intent-example. They are rewritten on every run.
• Removes old pb-* command files from the same directory.
• Registers the local MCP server in the project's .mcp.json under the name intent, running npx intentdocs mcp. This is the entry claude mcp add --scope project intent -- npx intentdocs mcp writes. Other servers in the file are kept. If .mcp.json isn't valid JSON, it is left alone and setup prints that command for you to run. Restart Claude Code and approve the server when it asks.
• Removes the intent entry older versions of setup wrote to ~/.claude/settings.json, where Claude Code doesn't read MCP servers. An entry you changed is left alone.

For Cursor, it appends an intentdocs section to .cursorrules, or creates the file, and prints the mcpServers JSON to add to Cursor's MCP settings. It does not write Cursor's settings for you.

In both cases, it then writes the project's agent context the same way intentdocs sync --context does, and creates ARCHITECTURE.md and CONVENTIONS.md scaffolds if they are missing.

You can run setup again at any time. It does not duplicate the sections it appends.

For the hosted MCP server and per-client setup, see Claude Code setup and Cursor and remote setup.