Complete Guide to GitHub* Spec Kit

Version 1.6.0 • Last Updated: January 2025 • Total Video Content: 8 videos (189 minutes)

📖 Table of Contents

• Quick Links
• What is Spec Kit?
• Installation
• Core Concepts
• Complete Workflow
• Available Commands
• Best Practices
• Tips & Tricks
• FAQ
• Video Resources

Quick Links

For specific use cases:

• New to Spec Kit? - Start here with the new project quick start
• Existing Project? - Learn how to add features to your codebase
• Need Command Help? - Complete command reference

What is Spec Kit?

GitHub* Spec Kit is an experimental open-source toolkit that enables spec-driven development - a structured approach to building software that separates requirements from implementation.

Why Use Spec Kit?

✅ Better than "vibe coding" - Structured, reproducible development ✅ Implementation-agnostic - Same spec works across different tech stacks ✅ Git-based - Safe experimentation with branches ✅ Team collaboration - Shareable markdown documentation ✅ AI-powered - Works with Claude, GPT*-4, Gemini, Cursor, and more

Supported AI Agents

• GitHub Copilot (VS Code)
• Claude Code
• Cursor
• Gemini CLI
• Qwen, OpenCode, Windsurf
• CodeBuddy, Amazon* Q*, Roo

Installation

Option 1: Persistent Installation (Recommended)

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

# Use anywhere
specify init my-project --ai copilot --script bash

# Or 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

Option 3: Manual Template

Download templates directly from GitHub Releases.

Core Concepts

1. Constitution

Non-negotiable principles that guide ALL development decisions.

Examples:

• "Must have tests for all features"
• "Always use Next.js 14+"
• "Accessibility baseline: WCAG AA"

File: .speckit/memory/constitution.md

2. Specification (Spec)

What to build and why - completely detached from implementation.

Focus on:

• User needs and motivation
• Functional requirements
• User stories and scenarios

Avoid:

• Technology choices
• Implementation details

File: .speckit/specs/[feature]/spec.md

3. Plan

How to build it - technical implementation details.

Includes:

• Framework choices
• Architecture decisions
• Dependencies
• Data models

File: .speckit/specs/[feature]/plan.md

4. Tasks

Actionable breakdown organized by MVP phases.

NEW Structure:

• Phase 1: Setup & Shared Infrastructure
• Phase 2: Foundational Prerequisites
• Phase 3: MVP Implementation
• Phase 4+: Iterations & Improvements

File: .speckit/specs/[feature]/tasks.md

Complete Workflow

The 8-Step Process

1. /speckit.constitution  → Establish guardrails
2. /speckit.specify       → Define what & why
3. /speckit.clarify       → Fix under-specification (Q&A)
4. /speckit.checklist     → Validate completeness (NEW!)
5. /speckit.plan          → Technical how
6. /speckit.tasks         → Break into MVP phases
7. /speckit.analyze       → Validate consistency
8. /speckit.implement     → Build it!

See detailed guides:

• New Project Workflow
• Existing Project Workflow
• Command Reference

Available Commands

View detailed command reference →

Best Practices

✅ DO

1. Be specific in your specs - Detailed requirements = better output
2. Manually edit when needed - All files are markdown
3. Use the constitution wisely - Encode critical requirements
4. Experiment with different models - GPT*-4 vs Claude* Sonnet 4
5. Leverage git branches - Spec Kit creates them automatically
6. Use checklists to validate specs ✨ NEW!
7. Commit often with git - Only commit working code

❌ DON'T

1. Don't mix concerns - Spec = WHAT, Plan = HOW
2. Don't skip the constitution
3. Don't trust AI blindly - Always verify
4. Don't let AI guess on existing projects
5. Don't skip TDD if you need it

Tips & Tricks

Tip 1: Reuse Specs Across Tech Stacks

Since specs are implementation-agnostic, you can experiment with multiple implementations!

Same spec → Different plans → Different implementations

Tip 2: Model Selection Strategy

For Spec Creation:

• GPT-4:* Thoughtful, literal, complete sections at once
• Claude Sonnet 4:* Creative, iterative, fills gaps

For Implementation:

• Claude Sonnet 4:* Best creative code output (recommended!)
• GPT-4:* Reliable, predictable results

Tip 3: Folder Structure

my-project/
├── .github/
│   └── copilot-instructions.md  # Custom slash commands
├── .speckit/
│   ├── memory/
│   │   └── constitution.md
│   ├── scripts/
│   ├── templates/
│   └── specs/
│       └── 001-feature-name/
│           ├── spec.md
│           ├── plan.md
│           └── tasks.md
└── src/

Tip 4: Auto-Approved Scripts ✨ NEW!

VS Code + Copilot: Scripts automatically approved - no permission prompts!

Benefits:

• ✅ Faster workflow
• ✅ Still secure (only Spec Kit scripts)
• ✅ Available out of the box

Tip 5: Checklists - Unit Tests for English ✨ NEW!

Generate domain-specific checklists to validate spec completeness:

/speckit.checklist UX           # Visual hierarchy, loading states
/speckit.checklist security     # Authentication, validation
/speckit.checklist accessibility # WCAG compliance

Then cross-check:

Cross-check the UX checklist with spec.md

AI automatically updates spec to fill gaps!

FAQ

Q: Which docs should I update after iterations?

A: Priority order:

1. Spec (most important) - sole source of truth
2. Constitution - if you discover non-negotiable principles
3. Plan - if technical stack changes
4. Tasks - just regenerate with /speckit.tasks

Q: How do I handle multi-repo setups?

A: Two approaches:

Option 1: One Spec Kit per repo (recommended)

• Bootstrap independently
• Easier to manage

Option 2: Shared constitution via git submodules

• Enforces organizational consistency
• More complex

Q: Agent went off the rails. How do I unwind?

A: Use git workflow:

1. Update spec with correct requirements
2. Commit spec changes
3. Discard unwanted code in git client
4. Re-implement from updated spec

Q: Can I rebuild with different tech stack later?

A: Yes! This is the power of implementation-agnostic specs.

Process:

1. Keep original spec
2. Create new plan with different stack
3. Regenerate tasks
4. Implement with new stack

Q: Do I need TDD for everything?

A: No! Tests are now optional.

When to skip:

• Quick prototypes
• Personal projects
• Rapid iteration

How to skip:

/speckit.plan

Not writing tests for this project.

Video Resources

Essential Watching (Watch in Order)

1. Complete Guide (40 min)
2. Under the Hood (36 min)
3. Latest Updates (14 min)
4. Clarify & Analyze (12 min)
5. Existing Projects (45 min)

Supplementary Videos

6. Copilot CLI (23 min)
7. Q&A (20 min)
8. Checklists (11 min) ✨ LATEST!

What's New in Version 1.6.0

🎯 Checklists - Unit Tests for English!

• Domain-specific quality checklists (UX, security, accessibility)
• Cross-check functionality to auto-update specs
• Solves under-specification problem

🚀 Better Developer Experience

• Auto-approved scripts in VS Code (no permission prompts!)
• Better command structure with speckit. prefix
• Initialize in current directory with .

📊 Improved Task Management

• MVP-first approach with phased delivery
• User story organization
• Tests now optional (not forced)

🔧 More Agent Support

• CodeBuddy, Amazon* Q*, Roo added

Project Structure Example

Real-world example from a 10-year-old Hugo blog:

Goal: Add reading list feature

Constitution:

Static site with no frameworks.
Built with Hugo.
Use existing theme in themes/ folder.

Result: ✅ Reading list integrated seamlessly ✅ Respects existing architecture ✅ Can rebuild if migrating tech stack

See it live: den.dev/books/

Contributing

Spec Kit is experimental and open source!

Ways to contribute:

• Try it and file issues
• Share feedback
• Open pull requests (discuss big changes first!)
• Star the repo ⭐

Resources:

• GitHub Repository
• Discussions
• Issues

Next Steps

Ready to start?

• New Project Quick Start - Build from scratch
• Existing Project Quick Start - Add to existing code
• Command Reference - Master all commands

Happy spec-driven development! 🚀

This guide is based on analysis of 8 video tutorials (189 minutes) and comprehensive testing of all features. Last updated: January 2025.