# SpecPilot

[![npm version](https://img.shields.io/npm/v/specpilot.svg)](https://www.npmjs.com/package/specpilot)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![smithery badge](https://smithery.ai/badge/specpilot/specpilot)](https://smithery.ai/servers/specpilot/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.

![SpecPilot CLI demo](docs/demo.gif)

## MCP server

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.

```bash
claude mcp add --transport http specpilot https://init.specpilot.dev/mcp
```

Then ask your agent: *"Onboard this project with SpecPilot"*.

For Cursor, VS Code and other clients, add it as an HTTP (streamable) server:

```json
{
  "mcpServers": {
    "specpilot": {
      "type": "http",
      "url": "https://init.specpilot.dev/mcp"
    }
  }
}
```

No install, no API key. Full setup notes: <https://specpilot.dev/mcp-setup>

## Quick Start

```bash
# 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` &nbsp;·&nbsp; `validate` → `v` &nbsp;·&nbsp; `migrate` → `m` &nbsp;·&nbsp; `list` → `ls` &nbsp;·&nbsp; `refine` → `ref` &nbsp;·&nbsp; `archive` → `ar` &nbsp;·&nbsp; `add-specs` → `add` &nbsp;·&nbsp; `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

```bash
# 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](docs/GUIDE.md#generated-slash-commands) 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:**

```bash
# 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

```bash
sudo chown -R $USER ~/.npm-global
npm config set prefix '~/.npm-global'
```

#### Template Not Found

```bash
specpilot list --verbose
```

#### Validation Failures

```bash
specpilot validate --verbose --fix
```

#### Migration Issues

**Error: "Source structure 'complex' not found"**

```bash
# 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

```bash
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/`](.specs/) for contribution guidelines.

### Development Setup

```bash
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`](.specs/project/requirements.md)
2. Check [`.specs/planning/tasks.md`](.specs/planning/tasks.md)
3. Update specs when making changes
4. Run `specpilot validate` before committing

## Documentation

- **[Full Guide](docs/GUIDE.md)**: Comprehensive documentation
- **[SpecPilot vs GitHub Spec Kit](docs/comparison.md)**: Side-by-side comparison to help you choose the right tool
- **[CHANGELOG](CHANGELOG.md)**: Version history
- **[Issues](https://github.com/girishr/SpecPilot/issues)**: Bug reports & feature requests

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

_Built with specification-driven development principles for serious production projects._