A Playground for Demonstrating Spec-Driven Development with GitHub Spec Kit

Spec-Driven Development (SDD) is a methodology where you first capture clear specifications of what you want to build and why, then create technical plans, break requirements into actionable tasks, and finally implement these using AI coding agents. This approach ensures alignment between intent and implementation while leveraging AI tools effectively.

GitHub Spec Kit is an open-source toolkit designed to bring clarity, structure, and AI assistance to spec-driven development. It helps teams:

• Define what to build with clear specifications
• Create detailed technical implementation plans
• Break work into manageable tasks
• Maintain living documentation that evolves with the project
• Collaborate effectively with AI coding agents

Install the Specify CLI tool using one of the following methods:

Using uv (recommended):

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

Verify installation:

specify --version

Create a new spec-driven project:

specify init <PROJECT_NAME>

Or initialize with a specific AI agent:

specify init <PROJECT_NAME> --ai copilot

OR

cd <PROJECT_NAME> && specify init --ai copilot --here

This sets up .github and .specify directories for your specification files and plans.

Define what our over archaring project principles that the AI should adhere to when making decisions about the spec, plan and tasks for your development project

/speckit.constitution
Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
Most important are concepts of secure coding and utilising test driven development (TDD)

Define what you want to build and why, focusing on goals, user scenarios, and desired outcomes. Use the /specify slash command:

/speckit.specify
Build an app to manage tasks with Kanban boards, multiple users, and real-time commenting.

Key Points:

• Focus on the "what" and "why", not the "how"
• Describe functional requirements and user scenarios
• Avoid technical implementation details at this stage

Once the specification is ready, generate the technical plan using the /plan command:

/speckit.plan
Use React with TypeScript; backend with Node.js & PostgreSQL.

This step details:

• Architectural choices
• Technology stack
• Technical approach
• Integration points

Consider using the following optional commands to further refine your spoecification:

│  Optional commands that you can use for your specs (improve quality & confidence)                                 │
│                                                                                                                   │
│  ○ /speckit.clarify (optional) - Ask structured questions to de-risk ambiguous areas before planning (run before  │
│  /speckit.plan if used)                                                                                           │
│  ○ /speckit.analyze (optional) - Cross-artifact consistency & alignment report (after /speckit.tasks, before      │
│  /speckit.implement)                                                                                              │
│  ○ /speckit.checklist (optional) - Generate quality checklists to validate requirements completeness, clarity,    │
│  and consistency (after /speckit.plan)    

Divide the spec and technical plan into concrete, actionable tasks using the /tasks command:

/speckit.tasks
# Outputs a list of development tasks, requirements, and milestones.

Each task aligns with the guiding specification and can be assigned to developers or AI agents.

Use AI coding agents (like GitHub Copilot, Claude, Cursor, or Gemini) to implement each task. The living specification and technical plan guide the implementation process.

Specifications in Spec Kit are living documents. Update them as new insights or requirements arise to ensure specifications and actual code remain aligned.

• Specify CLI: Easy project setup and scaffolding
• Constitution Files: Define non-negotiable team and project principles
• Markdown Artifacts: All specs, plans, and tasks are generated as markdown for easy sharing and version control
• Cross-Platform: Works on Windows, macOS, and Linux
• AI Agent Integration: Supports multiple AI frameworks and agents (Copilot, Claude, Cursor, Gemini, etc.)
• Slash Commands: Fast interaction for specifying, planning, and breaking down work

• Reduces Ambiguity: Clear separation of what/why vs. how
• Improves Collaboration: Everyone refers to the same living source of truth
• Better AI Results: AI agents generate code closely aligned to verified requirements and architecture
• Flexible and Scalable: Adapt to project changes without losing alignment or context
• Documentation by Default: Specs serve as up-to-date project documentation

1. Start with Why: Always begin by documenting the purpose and goals
2. Keep Specs Living: Update specifications as requirements evolve
3. Separate Concerns: Keep the specification (what/why) distinct from the technical plan (how)
4. Iterate Often: Review and refine specs based on implementation learnings
5. Use Constitution Files: Define team principles and non-negotiables upfront
6. Leverage AI Effectively: Use AI agents for implementation while humans focus on specification and review

• Official Spec Kit Documentation
• Spec Kit Quick Start Guide
• Spec Kit Installation Guide
• GitHub Spec Kit Repository
• Spec Kit Community Site
• GitHub Blog: Spec-driven development with AI
• LogRocket: Exploring spec-driven development

Here's a complete example of using Spec Kit:

# 1. Initialize project
specify init my-task-manager --ai copilot

# 2. Navigate to project
cd my-task-manager

# 3. Create specification
/speckit.specify
Build a task management system with:
- User authentication
- Project workspaces
- Kanban board view
- Real-time collaboration
- Task comments and attachments

# 4. Create technical plan
/speckit.plan
Frontend: React + TypeScript + Tailwind CSS
Backend: Node.js + Express + PostgreSQL
Authentication: JWT tokens
Real-time: Socket.io
Deployment: Docker containers on AWS

# 5. Generate tasks
/speckit.tasks
# This will create a breakdown of implementation tasks

# 6. Implement tasks iteratively
# Work through each task with your AI coding agent
# Update specs and plans as you learn and requirements evolve
/speckit.implement

This repository serves as a demonstration and playground for spec-driven development practices. Feel free to experiment with different specifications, plans, and implementation approaches.

This is a demonstration repository. See the main GitHub Spec Kit repository for licensing information.