The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the SpecPilot listing page.
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.

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.
Then ask your agent: "Onboard this project with SpecPilot".
For Cursor, VS Code and other clients, add it as an HTTP (streamable) server:
No install, no API key. Full setup notes: https://specpilot.dev/mcp-setup
After creating a project, follow these steps to populate your specifications using AI:
.specs/README.md for full guidance.specs/development/onboarding.mdThis AI-assisted approach ensures comprehensive, high-quality specifications tailored to your project needs.
| 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 |
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→bfExample:specpilot i my-appis identical tospecpilot init my-app.
| 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 |
Run
specpilot <command> --helpfor full flag descriptions and default values.
Note: no framework prompt is shown for JavaScript — pass
--frameworkexplicitly if needed.
SpecPilot generates a .specs/ folder with organized subdirectories:
Also generated at project root: an AI context file (
.github/copilot-instructions.md,CLAUDE.md,.cursor/rules/specpilot.mdc,.windsurfrules,.antigravity/rules.mdetc.) based on your selected IDE/Agent
SpecPilot requires no global configuration. Each project is self-contained with settings in project.yaml.
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):
Cloud-Based AI Agents (Instruction Files):
CLAUDE.md)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.)
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). See the Full Guide for the complete list and per-IDE paths.
The generated settings/instructions automatically configure your AI agent to:
.specs/ folder in AI contextExample:
Error: "Source structure 'complex' not found"
SpecPilot implements Specification-Driven Development (SDD) where specifications come first:
Benefits:
This project follows SDD principles. See .specs/ for contribution guidelines.
.specs/project/requirements.md.specs/planning/tasks.mdspecpilot validate before committingMIT License - see LICENSE file for details.
Built with specification-driven development principles for serious production projects.