specstocode

Write structured specs, map your user stories, and let your AI coding agent do the rest.

Install

npm install -g specstocode

Installs three aliases: stc (short, daily use), specstocode, and productbuilders.

Or use without installing:

npx specstocode init

How it works

1. Plan on the web — create a project on specstocode.com, map your user stories, and write Gherkin specs for each one
2. Connect your codebase — run npx specstocode init in your project directory
3. Build with AI — your AI coding agent reads SPECSTOCODE.md for full product context: stories, acceptance criteria, decisions, and notes

specstocode.com                        Your project
┌─────────────────┐                   ┌─────────────────┐
│  Story map UI   │◄── sync API ─────►│  CLI / MCP      │
│  Specs editor   │                   │  SPECSTOCODE.md │
│  (plan here)    │  GET /context     │  (build here)   │
│                 │──────────────────►│                 │
│  Stories        │  PATCH /stories   │  Claude Code    │
│  Acceptance     │◄──────────────────│  Cursor / etc   │
│  criteria       │                   │                 │
└─────────────────┘                   └─────────────────┘

Getting Started

1. Log in

stc login

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

2. Connect your codebase

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

npx specstocode init

This creates:

• SPECSTOCODE.md — product context file (stories, acceptance criteria, personas, decisions)
• .specstocode/config.json — sync config (auto-gitignored)

3. Set up your AI tool

stc setup

Configures Claude Code or Cursor with:

• CLAUDE.md / .cursorrules pointing to your specs
• ARCHITECTURE.md and CONVENTIONS.md scaffolding

4. Build

stc next          # What to build next (highest priority story + acceptance criteria)
stc done <id>     # Mark a story complete
stc stories       # List all stories
stc status        # Progress dashboard

All Commands

Setup

| Command | Description | |---------|-------------| | stc login | Authenticate (opens browser) | | stc logout | Log out | | stc init | Connect project directory to a story map | | stc sync | Refresh SPECSTOCODE.md with latest from the web | | stc setup | Configure Claude Code / Cursor |

Story management

| Command | Description | |---------|-------------| | stc status | Progress dashboard | | stc stories [-f filter] | List stories (filter: todo / done / keyword) | | stc next | Next priority story with acceptance criteria | | stc done <id> | Mark a story done (accepts ID prefix) | | stc add <title> | Create a new story | | stc decide [title] | Log an architectural decision | | stc note <id> [text] | Add implementation notes to a story |

MCP server

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

MCP Server

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

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

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

Tool modes

Control token usage with --mode:

| Mode | Tools | Use case | |------|-------|----------| | core | 5 | Day-to-day dev — list, mark done, status, notes | | standard | 8 | Active dev — + create, context, decisions | | all | 11 | Full access — + complexity, research, import |

Available tools

| Tool | Mode | Description | |------|------|-------------| | list_stories | core | List stories with optional filter | | mark_done | core | Mark a story complete | | mark_in_progress | core | Mark a story in progress | | get_status | core | Progress summary | | add_note | core | Add implementation notes | | create_story | standard | Create a new story | | get_context | standard | Fetch full product context | | log_decision | standard | Log an architectural decision | | analyze_complexity | all | AI complexity scoring | | research | all | AI research with project context | | import_prd | all | Parse a PRD into stories |

AI Features & Pricing

Most commands work on every plan. These three are AI-powered and gated:

| Command | What it does | |---------|--------------| | stc complexity | AI complexity scoring — 1-10 score, risks, suggested effort per story | | stc research | AI research with your project context — findings, recommendations, next steps | | stc import | Parse a PRD or spec document into structured user stories |

(The same applies to the matching MCP tools: analyze_complexity, research, import_prd.)

You can unlock them two ways:

1. Upgrade your plan — see specstocode.com/pricing
2. Bring your own Anthropic key — works on any plan, AI commands run on your key:

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

Links

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