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

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

Command	Description
init <name>	Initialize new SDD project
init <name> --dry-run	Preview files that would be created without writing
add-specs	Add specs to existing project
validate	Validate specification files
archive	Archive oversized prompts.md / tasks.md entries
backfill	Backfill missing mandates & slash commands into existing project files
list	Show available templates
migrate	Convert legacy .project-spec folder (rarely needed)
refine [desc]	Refine project specifications
serve [folders...]	Serve a local web UI over the .specs/ of this project, or of each folder named (task moves unless --read-only)

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

Command	Options
init	--lang · --framework · --dir · --specs-name · --no-prompts · --dry-run
validate	--fix · --verbose
migrate	--from · --to · --backup
list	--lang · --verbose
refine	--update · --no-prompts
archive	--dry-run · --force
add-specs	--no-analysis · --deep-analysis · --no-prompts
backfill	--dir · --specs-name · --dry-run · --no-prompts
serve	--port · --poll · --read-only · --open

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. 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. 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

Option	Default	Description
--port <n>	4321	Port to listen on (127.0.0.1 only)
--poll <ms>	1000	Change-detection interval in ms (minimum 250); polling runs only while a page is open
--read-only		No task moves: the UI only reads, with no drag handles and no write route
--open		Open the UI in the default browser

• Several projects: every folder you name must contain .specs/; one that does not stops startup with its name. 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. The list is fixed when the server starts: the page cannot add a folder, and nothing is saved outside your projects.
• Task moves: drag a row, or use Alt+Up/Down to reorder and Alt+Left/Right to move between Backlog and Current Sprint. 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.
• Nothing else is written: each served project's .specs/planning/tasks.md is the only file the server can change; everything else is read on every request.
• Loopback only: binds 127.0.0.1 only; rejects any Host header other than 127.0.0.1:<port> or localhost:<port> (403).
• Live reload: polls allowlisted files with stat() every --poll ms while a page is open, and pushes changed paths on /api/events; open pages update in place.
• What it shows: .specs/, CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, .claude/commands/, .claude/skills/ and .github/prompts/, as the files' own text.
• Limits: paths through symlinked folders, hidden files and node_modules are not shown. Task moves are refused, not approximated, when they cannot change exactly one line: a section with no table yet (a fresh project's [TODO]), a move involving the file's last line when it has no trailing newline, and a tasks.md that is not valid UTF-8. If an editor saves tasks.md in the same instant the server writes it, that save can be overwritten; git keeps it recoverable.

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, rules, 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:

IDE/Agent	Generated file
GitHub Copilot	.github/copilot-instructions.md
Codex	.github/copilot-instructions.md
Cursor	.cursor/rules/specpilot.mdc
Windsurf	.windsurfrules
Antigravity	.antigravity/rules.md
Claude Code	CLAUDE.md

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) or kept: symbolic link (links are never written through). 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

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

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.