Documentation
Documentation
Everything you need to get started with SpecPilot and Specification-Driven Development.
Getting Started
Get up and running with SpecPilot in under 5 minutes.
Install SpecPilot
Install the CLI globally with npm. Requires Node.js 18 or later.
Run the wizard
Run specpilot init to launch the web wizard, or visit init.specpilot.dev directly. Answer a few questions about your project — takes about 5 minutes.
Drop specs into your repo
The wizard generates a complete .specs/ folder. Commit it to your repo — your AI coding agent will automatically use it as context on every session.
CLI Reference
All SpecPilot commands, their aliases, and what they do.
Install
| Command | Alias | Description |
|---|---|---|
| specpilot init | i | Initialize new SDD project |
| specpilot init --dry-run | — | Preview files that would be created without writing |
| specpilot add-specs | add | Add specs to existing project |
| specpilot validate | v | Validate specification files |
| specpilot archive | ar | Archive oversized prompts.md / tasks.md entries |
| specpilot backfill | bf | Backfill missing mandates into existing projects |
| specpilot list | ls | Show available templates |
| specpilot migrate | m | Convert legacy .project-spec folder (rarely needed) |
| specpilot refine | ref | Refine project specifications from natural language description |
Spec Files Reference
Every file SpecPilot generates, and what it's for. Together they form the .specs/ engineering bundle your AI agent reads on every session.
requirements.md
Functional & non-functional requirements, user stories, and acceptance criteria.
project.yaml
Project config, rules, and AI agent context. MANDATED — read on every AI session.
architecture.md
System design decisions, patterns, and component hierarchy.
api.yaml
CLI / REST / GraphQL interface specification in structured YAML.
roadmap.md
Release milestones and objectives across project phases.
tasks.md
Sprint tracker with backlog, current, and completed columns.
prompts.md
AI interaction log. MANDATED — must be updated every coding session.
threat-model.md
Threat inventory with impact, likelihood, and mitigation for each risk.
context.md
Architecture decisions, ADRs, and design rationale log for the project.
onboarding.md
A ready-to-paste prompt that briefs your AI agent — populates every spec file, then gets deleted.
tests.md
Test strategy, coverage targets, and quality acceptance criteria.
security-decisions.md
Security architecture decisions and risk-level mitigations accepted per review.
IDE & Agent Integrations
SpecPilot generates the right config file and /specpilot-* slash/workflow commands for each tool. Drop your .specs/ folder in your repo and every supported tool picks it up automatically.
Supported IDEs & Agents
- GitHub Copilot
.github/copilot-instructions.mdcommands: .github/prompts/specpilot-*.md - Cursor
.cursor/rules/specpilot.mdccommands: .cursor/commands/specpilot-*.md - Windsurf
.windsurfrulescommands: .windsurf/workflows/specpilot-*.md - Antigravity
.antigravity/rules.mdcommands: .agent/workflows/specpilot-*.md - Claude Code
CLAUDE.mdcommands: .claude/commands/specpilot-*.mdskill: .claude/skills/specpilot-project/SKILL.md - Codex
.github/copilot-instructions.mdcommands: .codex/prompts/specpilot-*.mdskill: CODEX_INSTRUCTIONS.md