intentdocs

IntentDocs is an MCP-native spec-driven development platform for Claude Code, Cursor and other AI coding agents. It captures product intent as structured specifications — a story map with acceptance criteria, data model and build order — gives agents live access to those specs over MCP or this CLI, and records implementation progress and verification against what was planned.

This package is the intent CLI: the bridge between your repository and your IntentDocs project. Learn the concepts at intentdocs.com/intent-driven-development and the file format at intentdocs.com/intent-md.

Install

npm install -g intentdocs

Installs the intent command.

Or use without installing:

npx intentdocs init

How it works

intentdocs is the context engineering harness for agentic development. It structures everything your AI coding agent needs to work reliably — not just the stories, but the full picture:

| Context type | What it holds | How to populate | |---|---|---| | Instructions | Role, goals, boundaries for this project | Project page → Instructions | | Scope | Story maps, user stories, acceptance criteria | Web UI or intent add / intent propose | | Memory | Architectural decisions, lessons learned | intent decide / intent done | | Examples | Reference patterns, before/after code | intent example | | Tools | APIs, services, MCP config | Project page → Tools | | Guardrails | Hard constraints, safety rules | Project page → Guardrails |

All of this is assembled into CLAUDE.md (or AGENTS.md / GEMINI.md) by running:

intent sync --context

intentdocs.com                        Your project
┌─────────────────────┐               ┌──────────────────────────┐
│  Project page       │               │  CLI                     │
│  ├ Instructions     │               │  ├ CLAUDE.md   ← harness │
│  ├ Story maps       │◄── sync ─────►│  ├ INTENT.md             │
│  ├ Decisions        │               │  ├ .intent/              │
│  ├ Examples         │  --context    │  │   stories/<id>.md     │
│  ├ Tools / MCP      │──────────────►│  └ mcp.json              │
│  └ Guardrails       │               │                          │
└─────────────────────┘               │  Claude Code / Cursor    │
                                      └──────────────────────────┘

Getting Started

1. Log in

intent login

Opens your browser to authenticate. One-time per machine.

2. Connect your codebase

Run inside your project directory after creating a project on intentdocs.com:

npx intentdocs init

This creates:

• CLAUDE.md — full context harness assembled from your project page (instructions, stories, decisions, examples, tools, guardrails)
• INTENT.md — story map summary (stories, ACs, status)
• ARCHITECTURE.md — pre-filled with your detected tech stack
• .intent/config.json — sync config (auto-gitignored)

3. Set up your AI tool

intent setup

Configures Claude Code or Cursor with:

• Slash commands for the full development workflow
• CONVENTIONS.md scaffolding

4. Build

intent next          # Pick up the next story
intent done <id>     # Mark complete + log a decision or lesson
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

All Commands

Setup & sync

| Command | Description | |---|---| | intent login | Authenticate (opens browser) | | intent logout | Log out | | intent init | Connect project directory to a story map + generate CLAUDE.md | | intent setup | Configure Claude Code / Cursor with slash commands | | intent sync | Refresh INTENT.md with latest stories | | intent sync --context | Regenerate CLAUDE.md from your full project page context |

Story management

| Command | Description | |---|---| | intent status | Progress dashboard + recent activity | | intent stories [-f filter] | List stories (todo / done / keyword) | | intent next | Next priority story with acceptance criteria | | intent done <id> | Mark done — prompts for a decision or lesson learned | | intent add <title> | Create a new story | | intent propose [name] | Plan a new feature — creates stories + saves a local spec | | intent note <id> [text] | Add implementation notes to a story |

Context & memory

| Command | Description | |---|---| | intent decide [title] | Log an architectural or product decision | | intent example | Log a reference pattern (before/after code) for this codebase |

AI features (Builder plan)

| Command | Description | |---|---| | intent complexity | AI complexity scoring — 1-10 score, risks, suggested effort | | intent research | AI research with your project context | | intent import | Parse a PRD into structured user stories | | intent next --stub | Generate a failing test skeleton from acceptance criteria |

MCP server

| Command | Description | |---|---| | intent mcp [--mode] | Start MCP server (core / standard / all) |

Slash Commands (Claude Code / Cursor)

Run intent setup to install these. Use inside your AI coding agent, not the terminal.

| Command | What it does | |---|---| | /intent-next | Pick up the next story | | /intent-implement | Full implementation playbook — load harness → ACs → code → done | | /intent-propose | Plan a new feature before writing code | | /intent-review | Review implementation against acceptance criteria | | /intent-document | Document what was built | | /intent-test | Generate tests from acceptance criteria | | /intent-decide | Log an architectural or product decision | | /intent-example | Log a reference pattern for this codebase | | /intent-status | Show story map progress and recent activity | | /intent-done | Mark a story done + log a decision | | /intent-sync | Refresh story map or regenerate full CLAUDE.md harness | | /intent-context | Load focused context for the current story |

MCP Server

The intentdocs MCP server exposes tools (actions your agent can take) and resources (project context your agent can read). Configure it once and your AI coding agent has native access to your full spec.

Give Claude Code or Cursor native tool and resource access to your story map.

Add to ~/.claude/settings.json (Claude Code) or your Cursor MCP config:

{
  "mcpServers": {
    "intentdocs": {
      "command": "npx",
      "args": ["intentdocs", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Available tools (19)

| Tool | Description | |---|---| | list_projects | List user's projects | | get_context | Full product context for a project | | list_stories | List stories with optional filter | | update_stories | Batch update story status/fields, including user-story text (as_a/i_want/so_that) | | create_stories | Batch create new stories | | report_criteria | Report acceptance criteria pass/fail results | | add_criteria | Append acceptance criteria to a story — returns new criterion IDs for use with report_criteria | | replace_criteria | Replace ALL acceptance criteria on a story — returns new criterion IDs | | check_release_readiness | Pre-flight scan for missing ACs and implementation plans | | start_story | Mark a story in_progress (blocks if another is already in_progress) | | complete_story | Mark a story done + returns next story in release | | get_status | Progress summary | | raise_blocker | Flag a blocker on a story | | add_note | Add implementation notes | | log_decision | Log an architectural decision | | analyze_complexity | AI complexity scoring | | research | AI research with project context | | import_prd | Parse a PRD into stories | | get_build_order | Recommended implementation order |

MCP Resources

Resources let any MCP-compatible agent (Claude Code, Cursor, Codex) discover and read your project spec without invoking commands. Unlike tools, resources are read-only and auto-discoverable — your coding agent can pull exactly the context it needs.

| Resource | URI | Description | |---|---|---| | Story Map | intentdocs://project/storymap | Full product context — personas, activities, stories, acceptance criteria | | Stories | intentdocs://project/stories | All stories with status, priority, effort, and ACs | | Status | intentdocs://project/status | Progress summary — done/in-progress/todo counts | | Decisions | intentdocs://project/decisions | Architectural and product decisions | | Data Model | intentdocs://project/data-model | Schema and data model from your spec | | Build Order | intentdocs://project/build-order | Recommended implementation order |

Resources are always available regardless of tool mode.

Example usage in Claude Code:

Your coding agent can read these directly:

Read resource: intentdocs://project/data-model

No command needed — the agent discovers available resources from the MCP server automatically.

AI Features & Pricing

AI-powered commands are gated behind the Builder plan. Unlock two ways:

1. Upgrade — intentdocs.com/pricing
2. Bring your own Anthropic key — works on any plan:

intent keys set       # add your Anthropic API key (encrypted at rest)
intent keys status    # check whether a key is configured
intent keys remove    # fall back to plan limits

Links

• intentdocs.com — web app
• npm — this package