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 --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, Current Sprint and Review, approve or send back what an agent finished, 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= 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, Current Sprint and Review (Backlog and Current Sprint either way; Current Sprint to Review and back), or open a card's menu (right-click, the ⋯ button on the card, or Shift+F10) and pick Move to (its end, or , 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 and Won't do 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.
• Warning while work is in progress: a move from the page, and Archive, ask first when the project is on a branch other than main or master, or when a .specs/ file changed on disk in the last two minutes and not from the page (an agent or editor at work). The dialog says what could happen (the change rides on the branch's work and can conflict at the merge; an agent saving an older copy of tasks.md can undo it) and offers Cancel or Move anyway; Archive adds the check to its own list. The page knows only what it has seen since it loaded. Approve and Send back never ask.
• Review lane: ## Review in .specs/planning/tasks.md holds finished work that you check before it counts as done; the lane's header reads Review HITL (human-in-the-loop). Your AI agent moves finished work from Current Sprint to Review, never straight to Completed (the generated instruction files and the MCP server say so). Open a Review card: Approve appends Approved to the row and shows an Approved chip, and the panel says the next step (tell your agent to wrap it up; Copy prompt gives you the line); Send back opens a note box (What needs fixing? (optional), up to 200 characters, Cmd/Ctrl+Enter sends, Escape cancels), appends Sent back : and moves the row to the top of Current Sprint, so the agent picks it up next; both offer Undo, and the panel lists earlier notes under History. A drag or Alt+← out of Review is a Send back without a note, so an approved row that comes back is no longer approved. The agent writes the Completed entry (number, CD ID, commit) by hand once a row is marked Approved; SpecPilot never writes it. ## Won't do, when the file has it, is a read-only lane after Completed, folded to a strip until you open it. Off with --read-only.
• Type and Priority: when Backlog, Current Sprint and Review are | ID | Type | Priority | Description | tables (what init writes), each card shows its Priority (P1 to P3) and Type (feat, bug, chore) on its bottom line, and the task details set them with two button groups that save at once; New Task offers them too. A table that is still | ID | Description | works as bef