Quick Start: New Project

Get up and running with Spec Kit in a brand new project in under 10 minutes.

📖 Table of Contents

Prerequisites
Installation
The 8-Step Workflow
Minimum Workflow
Recommended Workflow
Quick Tips
Folder Structure
What's Next?

Prerequisites

AI Agent: GitHub* Copilot*, Claude* Code, Cursor*, or any supported agent
Python 3.11+*
Git*
Your favorite editor (VS Code* recommended)

Installation

Option 1: Persistent (Recommended)

# Install once, use everywhere
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Create your project
specify init my-project --ai copilot --script bash

# Or initialize in current directory
cd my-project
specify init . --ai copilot --script bash

Option 2: One-time Usage

uvx --from git+https://github.com/github/spec-kit.git specify init my-project

Agent options: copilot, claude, gemini, cursor, windsurf, qwen, opencode, codebuddy, amazonq, roo

Script options: bash (Linux*/macOS*) or ps (PowerShell*/Windows*)

The 8-Step Workflow

1. Establish Constitution

Command: /speckit.constitution

Define your non-negotiable project principles:

Static website with minimal dependencies,
optimized for mobile and desktop (responsive),
with accessibility standards (WCAG AA).

What it creates: .speckit/memory/constitution.md

2. Create Specification

Command: /speckit.specify

Describe WHAT you want to build (not HOW):

I am building a modern podcast website that should:
- Look sleek and professional
- Have a landing page with one featured episode
- Include episodes page, about page, and FAQ page
- Display 20 mock episodes
- Be mobile responsive

Focus on: User needs, requirements, acceptance criteria Avoid: Technology choices, implementation details

3. Clarify (Optional but Recommended)

Command: /speckit.clarify

AI asks up to 5 clarification questions with multiple choice answers:

AI: What specific episode metadata should be displayed?
A) Basic (title, date)
B) Standard (title, date, duration, description)
C) Extended (all fields + host, guests, tags)

You: C

Why use it: Catches assumptions you didn't question

4. Validate with Checklists (Optional but Powerful) ✨ NEW!

Command: /speckit.checklist UX

Generate domain-specific quality checklists:

/speckit.checklist UX          # User experience validation
/speckit.checklist security     # Security considerations
/speckit.checklist accessibility # WCAG compliance

Then cross-check with spec:

Cross-check the UX checklist with spec.md

AI automatically updates spec to fill gaps!

Domains: UX, security, accessibility, performance

5. Generate Plan

Command: /speckit.plan

Specify HOW to build it (technical details):

Use Next.js with static site configuration.
No databases needed - use mock data.
Make sure the site is responsive and mobile-ready.

What it includes: Frameworks, dependencies, architecture, testing strategy

6. Break Into Tasks

Command: /speckit.tasks

Get an MVP-first task breakdown organized by phases:

Phase 1: Setup & Shared Infrastructure
Phase 2: Foundational Prerequisites
Phase 3: MVP Implementation (User Story 1)
Phase 4+: Iterations & Improvements

Tests are optional - No longer forced unless you ask!

7. Analyze & Validate ⚠️ Critical!

Command: /speckit.analyze

Validates spec, plan, and tasks against constitution:

Severity: CRITICAL
Issue: Next.js violates "static HTML/CSS only" constitution requirement
Recommendation: Either justify or return to vanilla approach

Always run before implementing - Catches inconsistencies early!

8. Implement

Command: /speckit.implement

One command to build everything:

/speckit.implement

AI executes tasks phase by phase, creates all files, runs tests.

Pro tip: Use Claude* Sonnet 4 or GPT*-4 for best results!

Minimum Workflow (Quick Prototypes)

For fast iteration:

1. /speckit.constitution
2. /speckit.specify
3. /speckit.plan
4. /speckit.tasks
5. /speckit.implement

Recommended Workflow (Quality Projects)

For better results:

1. /speckit.constitution
2. /speckit.specify
3. /speckit.clarify         ← Eliminates assumptions
4. /speckit.checklist UX    ← Validates completeness
5. /speckit.plan
6. /speckit.tasks
7. /speckit.analyze         ← Catches inconsistencies
8. /speckit.implement

Quick Tips

✅ DO

Be specific - Detailed specs = better output
Edit manually - All files are markdown, edit them!
Use git branches - Spec Kit creates them automatically
Try different models - GPT*-4 vs Claude* Sonnet 4

❌ DON'T

Don't mix concerns - Spec = WHAT, Plan = HOW
Don't skip constitution - It guides all decisions
Don't trust AI blindly - Always verify output

Folder Structure

After initialization, you'll see:

my-project/
├── .github/
│   └── copilot-instructions.md  # Custom slash commands
├── .speckit/
│   ├── memory/
│   │   └── constitution.md      # Project principles
│   ├── scripts/                 # Helper scripts
│   ├── templates/               # Spec templates
│   └── specs/
│       └── 001-feature-name/
│           ├── spec.md          # Requirements
│           ├── plan.md          # Technical details
│           └── tasks.md         # Task breakdown
└── src/                         # Your source code

What's Next?

Command Reference - All commands explained
Complete Guide - In-depth documentation
Existing Project Guide - Add features to existing code

Need Help?

GitHub Repo*: github.com/github/spec-kit
Discussions: Community discussions
Latest Tutorial: Checklists video

Happy spec-driven development! 🚀