SpecPilot

A CLI tool for initializing specification-driven development projects with flexible, production-ready structures.

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/prompts.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
add-specs	Add specs to existing project
validate	Validate specification files
list	Show available templates
migrate	Migrate between spec versions
specify <desc>	Update project specifications

Examples

# Initialize with specific language/framework
specpilot init api --lang python --framework fastapi

# Update specifications
specpilot specify "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
• CLI: Command-line tools

JavaScript

• React: SPA applications
• Express: REST APIs
• Next.js: Full-stack apps
• CLI: Command-line tools

Python

• FastAPI: Modern REST APIs
• Django: Full-stack applications
• Data Science: ML/Data Science projects

Project Structure

SpecPilot generates a .specs/ folder with organized subdirectories:

.specs/
├── project/          # Project config & requirements
├── architecture/     # System design & API specs
├── planning/         # Roadmap & task tracking
├── quality/          # Testing & documentation
└── development/      # AI prompts & context

Key Files

• project.yaml: Project configuration and rules
• requirements.md: Functional/non-functional requirements
• architecture.md: System architecture decisions
• prompts.md: AI interaction tracking (MANDATED)
• tasks.md: Task management (backlog/sprint/completed)

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

• VSCode - Industry standard with Copilot integration
• Cursor - AI-first code editor with enhanced AI context
• Windsurf - Advanced AI coding assistant
• Kiro - Specialized AI development environment
• Antigravity - AI-powered IDE with context awareness

Cloud-Based AI Agents (Instruction Files):

• Cowork - Anthropic Claude agent with Skills framework
• Codex - OpenAI Codex agent with instruction context

Generated Configuration Files:

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

For cloud agents:

• Cowork: .claude/skills/specpilot-project/SKILL.md with project context and development guidelines
• Codex: CODEX_INSTRUCTIONS.md at project root with architecture overview and mandates

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, kiro, antigravity (desktop)
# - cowork, 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
• 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.