SpecPilot

SpecPilot

SpecPilot is a spec-driven development (SDD) CLI for AI coding agents like Claude Code, Cursor, and ChatGPT. It initializes, validates, and syncs a .specs/ directory so AI-assisted coding stays grounded in living requirements, architecture, and task specs instead of drifting from the codebase.

MCP server

Prefer to stay inside your editor? SpecPilot also runs as a remote MCP server, so Claude Code, Cursor or Copilot can run the whole onboarding itself - answering what it can infer from your repo and asking you only the rest.

claude mcp add --transport http specpilot https://init.specpilot.dev/mcp

Then ask your agent: "Onboard this project with SpecPilot".

For Cursor, VS Code and other clients, add it as an HTTP (streamable) server:

{
  "mcpServers": {
    "specpilot": {
      "type": "http",
      "url": "https://init.specpilot.dev/mcp"
    }
  }
}

No install, no API key. Full setup notes: https://specpilot.dev/mcp-setup

specpilot serve also serves a local MCP endpoint, so your AI IDE can read this machine's specs, add or move tasks and set up a folder: see Local MCP endpoint below.

Quick Start

# Install globally
npm install -g specpilot

# Create a new project
specpilot init my-project --lang typescript --framework react

# Add specs to existing project
cd existing-project
specpilot add-specs

# Validate specifications
specpilot validate

🚀 Next Steps to Populate Your Specs with AI

After creating a project, follow these steps to populate your specifications using AI:

1. Open the generated guide: Check .specs/README.md for full guidance
2. Copy the onboarding prompt: Use the prompt from .specs/development/onboarding.md
3. Paste into your AI agent: ChatGPT, Claude, or other AI assistants
4. Review generated spec files: Examine the AI-generated requirements and architecture

This AI-assisted approach ensures comprehensive, high-quality specifications tailored to your project needs.

Commands

Tip — command aliases: All commands have a short alias you can use instead of the full name. init → i  ·  validate → v  ·  migrate → m  ·  list → ls  ·  refine → ref  ·  archive → ar  ·  add-specs → add  ·  backfill → bf Example: specpilot i my-app is identical to specpilot init my-app.

Per-Command Options

Run specpilot <command> --help for full flag descriptions and default values.

Examples

# Initialize with specific language/framework
specpilot init api --lang python --framework fastapi

# Preview files that would be created without writing anything
specpilot init api --dry-run

# Refine specifications
specpilot refine "REST API for user management" --update

# Validate with auto-fix
specpilot validate --fix

specpilot serve

Serve a local web UI over a project's .specs/, where you can also move tasks between Backlog and Current Sprint, add new ones, bring SpecPilot's command files up to date, set up .specs/ in a folder that has none yet, and open more projects. With no folders it serves the project you run it from (the folder that contains .specs/); name one or more folders to serve those instead, all from one server, or open them later from the page. Press Ctrl+C to stop.

specpilot serve                  # this project, at http://127.0.0.1:4321
specpilot serve --port 5000 --open
specpilot serve ../api ../web    # two projects on one server; switch in the left rail
specpilot serve ../new-project   # no .specs/ there yet: the page sets it up (or `specpilot serve .`)
specpilot serve --stop           # stop the server on port 4321 from another terminal (--port for another)

• Several projects: name any folders; one without .specs/ is served too and shows the Setup view (below). They are numbered in command-line order from 0 (../api is project 0, ../web is project 1), and that number is the ?project=<n> on the server's /api/ routes and the #1/... at the start of a page link for any project after the first (no number means project 0). Each project keeps its own tasks, files and live reload; a move changes only that project's tasks.md. Folders opened from the page (below) get the next numbers; a number never changes while the server runs, and one server holds at most 20 projects.
• Quit: the power button at the foot of the left rail stops the server after you confirm, as Ctrl+C or specpilot serve --stop would (a running clone is stopped and cleaned up first). The page then says SpecPilot has stopped; other open pages simply stop updating. Not shown with --read-only.
• Task moves: drag a row, use Alt+Up/Down to reorder and Alt+Left/Right to move between Backlog and Current Sprint, or open a card's menu (right-click, the ⋯ button on the card, or Shift+F10) and pick Move to <lane> (its end, or <lane>, top), Move up or Move down; the menu also has Open details and Copy ID. A move changes exactly one line of .specs/planning/tasks.md and nothing else, and offers Undo; Completed rows do not move. If the file changed on disk since the page loaded, the move is refused and the page redraws. Start with --read-only to turn moves off.
• Section headings: when .specs/planning/tasks.md lacks ## Backlog, ## Current Sprint or ## Completed, a warning above the lanes names the empty lane, what the file has instead and the fix (edit the file; best ask your AI IDE, so anything that refers to the section follows), with Open tasks.md in VS Code and Copy prompt; a ## heading the board does not know gets a note that its rows are not shown here; a known section that holds its tasks as plain lines or a list instead of a table gets a warning saying the lane shows none of them and how to turn them into a table. Warnings hide for the session into a one-line strip, notes until the headings change. specpilot validate warns on the missing ones and --fix renames an unambiguous variant.
• Commands and Skills: each view lists its files in two groups. Under From SpecPilot are the commands whose bytes match a version SpecPilot released (in and ) and the skill while it is still SpecPilot's own render of your ; everything else is under Yours, including a command you edited. Regenerate All, in the From SpecPilot header of Commands, runs what runs for command files, and nothing else: for each IDE whose instruction file is in the project it adds the missing commands and updates the unedited ones to the current version, in every IDE's command folder, also the ones the page does not list (, , , ). It also refreshes from (name, language, framework, platforms, package manager, test framework, repository URL, license) when the skill is still SpecPilot's own, and adds it when missing; a skill you edited, or one rendered from values no longer holds, is kept with the reason . Edited files, links, files under a linked folder, your own commands and skills, instruction files and are never written. What it did is shown above the groups as it happened: updated, added, kept with the reason, and the folders the page does not list.

Local MCP endpoint (specpilot serve)

The server also answers MCP at http://127.0.0.1:<port>/mcp, so Claude Code, Cursor and other AI IDEs on this machine can read the specs and add or move tasks through the same checks as the page. It is on by default; start with --no-mcp to leave it out (the Setup view then says how to restart). --mcp is still accepted and changes nothing.

specpilot serve
# MCP endpoint: http://127.0.0.1:4321/mcp
# Add to your IDE's MCP settings: {"mcpServers":{"specpilot-local":{"type":"http","url":"http://127.0.0.1:4321/mcp","headers":{"X-SpecPilot-Token":"<token>"}}}}

Copy that line from the terminal, from the Connect Your AI IDE card on Home, or from step 1 of the Setup view (Copy button) into your IDE's MCP settings, or into .mcp.json in your project and add .mcp.json to .gitignore.

• Tools: specpilot_list_projects, specpilot_read_spec, specpilot_list_tasks, specpilot_new_task, specpilot_move_task, specpilot_validate_specs (no --fix, writes nothing) and specpilot_regenerate_commands. Each takes an optional project index. The two task writes need the sha256 that specpilot_list_tasks returned; if tasks.md changed since, the write is refused ("since you last read it") and nothing is written. Open pages show the change through live reload.
• Setup tools: specpilot_setup_questions (a path) returns what was detected in the code and every question, with choices and suggestions; specpilot_setup_project (the path, the answers, and which ones the user gave) writes .specs/, the instruction files and the skill (creating a new project's folder), runs specpilot validate and returns the files written and the result. Nine tools in all. They work only on a folder the page is setting up: one you named, opened or cloned that has no .specs/, or the new project's folder you named on the Setup view. The server tells the IDE the order (questions, answer from the code, ask the user the rest, write, report). The Setup view's Progress rows follow these calls.
• Same guards as the page: loopback only, the Host check, the token (a wrong or missing X-SpecPilot-Token gets 403), JSON only, 64 KB, the page's read allowlist, the page's write allowlist and one write lock for page and IDE. A request from a web page (any other Origin) is refused with 403; IDEs send none. Clones and the project list are not tools.
• Protocol revisions: MCP 2026-07-28 (no handshake; the version, Mcp-Method and Mcp-Name headers must match the request body), and 2025-11-25 and 2025-06-18 (with initialize), on the same URL. A client that speaks both picks one; the config line is the same. Streamable HTTP, POST only, no sessions; answers are JSON, never a stream, and no change notifications are sent.
• Token: a new one each time serve starts, so the line needs copying again after a restart. To keep one line, set SPECPILOT_MCP_TOKEN (at least 32 characters, no spaces) in the environment of serve and of your IDE; the line then says ${SPECPILOT_MCP_TOKEN}, which Claude Code fills in from the environment (other IDEs: put the token in its place). SpecPilot never writes the token anywhere.

Supported Languages & Frameworks

TypeScript

• React: SPA applications
• Express: REST APIs
• Next.js: Full-stack apps
• Nest.js: Scalable server-side apps
• Vue: Progressive UI framework
• Angular: Enterprise SPA framework

JavaScript

• React: SPA applications
• Express: REST APIs

Note: no framework prompt is shown for JavaScript — pass --framework explicitly if needed.

Python

• FastAPI: Modern REST APIs
• Django: Full-stack applications
• Flask: Lightweight REST APIs
• Streamlit: Data Science / ML apps

Kotlin

• Android: Native Android apps
• Spring: Server-side REST APIs
• Ktor: Async Kotlin web framework
• Compose: Jetpack Compose UI

Swift

• iOS: Native iOS apps
• SwiftUI: Declarative Apple UI
• Vapor: Swift server-side framework

Project Structure

SpecPilot generates a .specs/ folder with organized subdirectories:

.specs/
├── architecture/
│   ├── api.yaml              # CLI / REST API / GraphQL interface spec
│   └── architecture.md       # System design decisions and patterns
├── development/
│   ├── context.md            # Development memory, decisions, learnings
│   ├── onboarding.md         # One-time AI bootstrap prompt — delete after first use
│   └── prompts.md            # AI interaction log — MANDATED, update every session
├── planning/
│   ├── roadmap.md            # Release milestones and objectives
│   └── tasks.md              # Sprint tracker (backlog / current / completed)
├── project/
│   ├── project.yaml          # Project config and AI context (MANDATED)
│   └── requirements.md       # Functional & non-functional requirements
├── quality/
│   └── tests.md              # Test strategy, coverage targets, acceptance criteria
└── security/
    ├── security-decisions.md # ADR-style security design decisions
    └── threat-model.md       # Threat inventory with impact/likelihood/mitigation

Also generated at project root: an AI context file (.github/copilot-instructions.md, CLAUDE.md, .cursor/rules/specpilot.mdc , .windsurfrules, .antigravity/rules.md etc.) based on your selected IDE/Agent

Configuration

SpecPilot requires no global configuration. Each project is self-contained with settings in project.yaml.

IDE & Agent Support

SpecPilot generates AI agent configuration files during project initialization. When you run specpilot init, you'll be prompted to select your AI IDE/Agent:

Desktop IDEs (Workspace Settings):

• GitHub Copilot - Industry standard with Copilot integration
• Cursor - AI-first code editor with enhanced AI context
• Windsurf - Advanced AI coding assistant
• Antigravity - AI-powered IDE with context awareness

Cloud-Based AI Agents (Instruction Files):

• Claude Code - Anthropic Claude Code CLI agent (CLAUDE.md)
• Codex - OpenAI Codex agent with instruction context

Generated Configuration Files:

Each IDE/Agent selection generates one AI context file at the project root:

All context files contain: project name/stack, critical mandates, Code Philosophy, Code Rules, and a Re-Anchor Prompt.

For desktop IDEs: .vscode/settings.json (or .cursor/, .windsurf/, etc.)

• IDE-specific workspace folder setup for code + .specs
• Extensions recommendations for development
• AI context configuration for better spec integration

Generated Slash Commands

Each IDE/Agent selection also generates 8 specpilot-* slash/workflow commands (status, reanchor, report, sync, refine, validate, archive, backfill) that mirror key CLI operations as in-editor commands — e.g. .claude/commands/specpilot-status.md for Claude Code, .cursor/commands/ for Cursor, .github/prompts/ for GitHub Copilot. Running backfill on an existing project fills in any commands missing for your already-configured IDE(s) and updates the ones you have not edited to the current version; edited files are kept and listed. Each command file is reported as added, updated (to the current version), or kept with its reason: kept: modified (you changed it; delete it and re-run specpilot backfill to get the latest version), kept: CRLF line endings (a known version saved with Windows line endings) kept: symbolic link (links are never written through), kept: folder is a symbolic link or not a folder (nothing is written through a linked .claude/ or similar) or kept: could not be written: <code> (the write failed; the rest still run). The specpilot serve page's Regenerate All runs the same step. See the Full Guide for the complete list and per-IDE paths.

The generated settings/instructions automatically configure your AI agent to:

• Include .specs/ folder in AI context
• Understand project structure and requirements
• Follow specification-driven development principles
• Access development guidelines and onboarding prompts

Example:

# During init, you'll be prompted to select your IDE/Agent
specpilot init my-project --lang typescript --framework react
# Respond with your preferred IDE/Agent:
# - vscode, cursor, windsurf, antigravity (desktop)
# - claude-code, codex (cloud agents)

Troubleshooting

Common Issues

Permission Errors

sudo chown -R $USER ~/.npm-global
npm config set prefix '~/.npm-global'

Template Not Found

specpilot list --verbose

Validation Failures

specpilot validate --verbose --fix

Migration Issues

Error: "Source structure 'complex' not found"

# For NEW projects, use:
specpilot init my-project

# For EXISTING projects without specs:
specpilot add-specs

# Only use migrate if you have an old .project-spec folder
specpilot migrate --from complex --to simple --backup

Debug Mode

DEBUG=specpilot specpilot <command>

Why SpecPilot?

SpecPilot implements Specification-Driven Development (SDD) where specifications come first:

Specifications → Architecture → Code → Tests → Deployment

Benefits:

• Clarity: Everyone understands what needs to be built
• Consistency: Standardized structure across projects
• Quality: Built-in validation and testing
• AI-Ready: Clear context for AI assistants
• Maintainable: Comprehensive documentation

Contributing

This project follows SDD principles. See .specs/ for contribution guidelines.

Development Setup

git clone https://github.com/girishr/SpecPilot.git
cd SpecPilot
npm install
npm run build
npm link  # For local testing

Browser tests for specpilot serve

The page's clicks, keys, focus and live reload are tested in headless Chromium, separately from npm test:

npx playwright-core install chromium-headless-shell  # once, if Playwright's Chromium is not on this machine yet
npm run test:browser                                  # builds, then runs src/__browser__/ (about 10 s)

The suite starts the built server on scratch copies of a fixture project (src/__browser__/fixture/, never this repo's own .specs/) under a temporary HOME, so it writes nothing in the repo or in ~/.specpilot/. A failing test prints the paths of its error message and stack, a screenshot and the page's HTML, kept in a temp folder.

Quick Contribution Guide

1. Review .specs/project/requirements.md
2. Check .specs/planning/tasks.md
3. Update specs when making changes
4. Run specpilot validate before committing

Releases follow the checklist in docs/RELEASING.md.

Documentation

• Full Guide: Comprehensive documentation
• SpecPilot vs GitHub Spec Kit: Side-by-side comparison to help you choose the right tool
• CHANGELOG: Version history
• Issues: Bug reports & feature requests

License

MIT License - see LICENSE file for details.

Built with specification-driven development principles for serious production projects.