Documentation

Everything you need to get started with SpecPilot and Specification-Driven Development.

Getting Started CLI Reference Spec Files IDE & Agents

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.

npm install -g specpilotcopy

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.

$specpilot initcopy

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

npm install -g specpilotcopy

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.

project/

requirements.md

Functional & non-functional requirements, user stories, and acceptance criteria.

project/

project.yaml

Project config, rules, and AI agent context. MANDATED: read on every AI session.

architecture/

architecture.md

System design decisions, patterns, and component hierarchy.

architecture/

api.yaml

CLI / REST / GraphQL interface specification in structured YAML.

planning/

roadmap.md

Release milestones and objectives across project phases.

planning/

tasks.md

Sprint tracker with backlog, current, and completed columns.

development/

prompts.md

AI interaction log. MANDATED: must be updated every coding session.

security/

threat-model.md

Threat inventory with impact, likelihood, and mitigation for each risk.

development/

context.md

Architecture decisions, ADRs, and design rationale log for the project.

development/

onboarding.md

A ready-to-paste prompt that briefs your AI agent, populates every spec file, then gets deleted.

quality/

tests.md

Test strategy, coverage targets, and quality acceptance criteria.

security/

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.md
commands: .github/prompts/specpilot-*.md
Cursor.cursor/rules/specpilot.mdc
commands: .cursor/commands/specpilot-*.md
Windsurf.windsurfrules
commands: .windsurf/workflows/specpilot-*.md
Antigravity.antigravity/rules.md
commands: .agent/workflows/specpilot-*.md
Claude CodeCLAUDE.md
commands: .claude/commands/specpilot-*.mdskill: .claude/skills/specpilot-project/SKILL.md
Codex.github/copilot-instructions.md
commands: .codex/prompts/specpilot-*.mdskill: CODEX_INSTRUCTIONS.md