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.

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 |

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 |

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

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