spec-kit-skill

Spec-Kit: Constitution-Based Spec-Driven Development

Official GitHub Spec-Kit integration providing a 7-phase constitution-driven workflow for feature development.

Quick Start

This skill works with the GitHub Spec-Kit CLI to guide you through structured feature development:

1. Constitution → Establish governing principles
2. Specify → Define functional requirements
3. Clarify → Resolve ambiguities
4. Plan → Create technical strategy
5. Tasks → Generate actionable breakdown
6. Analyze → Validate consistency
7. Implement → Execute implementation

Storage: Creates files in .specify/specs/NNN-feature-name/ directory with numbered features

When to Use

• Setting up spec-kit in a project
• Creating constitution-based feature specifications
• Working with .specify/ directory
• Following GitHub spec-kit workflow
• Constitution-driven development

---

Prerequisites & Setup

Check CLI Installation

First, verify if spec-kit CLI is installed:

command -v specify || echo "Not installed"

Installation

If not installed:

# Persistent installation (recommended)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# One-time usage
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Requirements:

• Python 3.11+
• Git
• uv package manager (install uv)

Project Initialization

If CLI is installed but project not initialized:

# Initialize in current directory
specify init . --ai claude

# Initialize new project
specify init <project-name> --ai claude

# Options:
# --force: Overwrite non-empty directories
# --script ps: Generate PowerShell scripts (Windows)
# --no-git: Skip Git initialization

---

<details> <summary>🔍 Phase Detection Logic</summary>

Detecting Project State

Before proceeding, always detect the current state:

1. CLI Installed?

if command -v specify &> /dev/null || [ -x "$HOME/.local/bin/specify" ]; then
  echo "CLI installed"
else
  echo "CLI not installed - guide user through installation"
fi

2. Project Initialized?

if [ -d ".specify" ] && [ -f ".specify/memory/constitution.md" ]; then
  echo "Project initialized"
else
  echo "Project not initialized - guide user through 'specify init'"
fi

3. Current Feature

# Get latest feature directory
LATEST=$(ls -d .specify/specs/[0-9]* 2>/dev/null | sort -V | tail -1)
echo "Latest feature: $LATEST"

4. Current Phase

Detect phase by checking file existence in latest feature:

FEATURE_DIR=".specify/specs/001-feature-name"

if [ ! -f ".specify/memory/constitution.md" ]; then
  echo "Phase: constitution"
elif [ ! -d "$FEATURE_DIR" ]; then
  echo "Phase: specify"
elif [ -f "$FEATURE_DIR/spec.md" ] && ! grep -q "## Clarifications" "$FEATURE_DIR/spec.md"; then
  echo "Phase: clarify"
elif [ ! -f "$FEATURE_DIR/plan.md" ]; then
  echo "Phase: plan"
elif [ ! -f "$FEATURE_DIR/tasks.md" ]; then
  echo "Phase: tasks"
elif [ -f "$FEATURE_DIR/tasks.md" ] && grep -q "\\- \\[ \\]" "$FEATURE_DIR/tasks.md"; then
  echo "Phase: implement"
else
  echo "Phase: complete"
fi

</details> <details> <summary>📜 Phase 1: Constitution</summary>

Constitution Phase

Establish foundational principles that govern all development decisions.

Purpose

Create .specify/memory/constitution.md with:

• Project values and principles
• Technical standards
• Decision-making frameworks
• Code quality expectations
• Architecture guidelines

Process

1. Gather Context

   • Understand project domain
   • Identify key stakeholders
   • Review existing standards (if any)

2. Draft Constitution

   • Core values and principles
   • Technical standards
   • Quality expectations
   • Decision criteria

3. Structure

# Project Constitution

## Core Values

1. **[Value Name]**: [Description and implications]
2. **[Value Name]**: [Description and implications]

## Technical Principles

### Architecture
- [Principle with rationale]

### Code Quality
- [Standards and expectations]

### Performance
- [Performance criteria]

## Decision Framework

When making technical decisions, consider:
1. [Criterion with priority]
2. [Criterion with priority]

4. Versioning
   • Constitution can evolve
   • Track changes for governance
   • Review periodically

Example Content

# Project Constitution

## Core Values

1. **Simplicity Over Cleverness**: Favor straightforward solutions that are easy to understand and maintain over clever optimizations.

2. **User Experience First**: Every technical decision should improve or maintain user experience.

## Technical Principles

### Architecture
- Prefer composition over inheritance
- Keep components loosely coupled
- Design for testability

### Code Quality
- Code reviews required for all changes
- Unit test coverage > 80%
- Documentation for public APIs

### Performance
- Page load < 3 seconds
- API response < 200ms
- Progressive enhancement for slower connections

## Decision Framework

When choosing between approaches:
1. Does it align with our core values?
2. Is it maintainable by the team?
3. Does it scale with our growth?
4. What's the long-term cost?

</details> <details> <summary>📝 Phase 2: Specify</summary>

Specify Phase

Define what needs building and why, avoiding technology specifics.

Script Usage

# Create new feature
.specify/scripts/bash/create-new-feature.sh --json "feature-name"

# Expected JSON output:
# {"BRANCH_NAME": "001-feature-name", "SPEC_FILE": "/path/to/.specify/specs/001-feature-name/spec.md"}

Parse JSON: Extract BRANCH_NAME and SPEC_FILE for subsequent operations.

Template Structure

Load .specify/templates/spec-template.md to understand required sections, then create specification at SPEC_FILE location.

Specification Content

Focus on functional requirements:

# Feature Specification: [Feature Name]

## Problem Statement

[What problem are we solving?]

## User Stories

### Story 1: [Title]

As a [role]
I want [capability]
So that [benefit]

**Acceptance Criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]

### Story 2: [Title]

[Continue...]

## Non-Functional Requirements

- Performance: [Specific metrics]
- Security: [Requirements]
- Accessibility: [Standards]
- Scalability: [Expectations]

## Success Metrics

- [Measurable outcome]
- [Measurable outcome]

## Out of Scope

[Explicitly state what's NOT included]

Key Principles

• Technology-agnostic: Don't specify "use React" or "MySQL"
• Outcome-focused: Describe what user achieves, not how
• Testable: Acceptance criteria must be verifiable
• Complete: Address edge cases and error scenarios

Git Integration

The script automatically:

• Creates new feature branch (e.g., 001-feature-name)
• Checks out the branch
• Initializes spec file

</details> <details> <summary>❓ Phase 3: Clarify</summary>

Clarify Phase

Resolve underspecified areas through targeted questioning.

Purpose

Before planning implementation, ensure specification is complete and unambiguous.

Process

1. Analyze Specification

   • Read spec.md thoroughly
   • Identify ambiguities, gaps, assumptions
   • Note areas with multiple valid interpretations

2. Generate Questions (Maximum 5)

   • Prioritize high-impact areas
   • Focus on decisions that affect architecture
   • Ask about edge cases and error handling

3. Question Format

## Clarifications

### Q1: [Clear, specific question]

**Context**: [Why this matters]
**Options**: [If multiple approaches exist]

### Q2: [Clear, specific question]

**Context**: [Why this matters]
**Impact**: [What decisions depend on this]

4. Update Specification
   • Add "## Clarifications" section to spec.md
   • Document questions and answers
   • Update relevant sections based on answers
   • Iterate until all critical questions answered

Guidelines

• Maximum 5 questions per round
• Specific, not general: "How should we handle concurrent edits?" not "How should it work?"
• Decision-focused: Questions that inform technical choices
• Incremental: Can run multiple clarification rounds

Example Questions

## Clarifications

### Q1: How should the system handle conflicts when two users edit the same document simultaneously?

**Context**: This affects data model design and user experience.
**Options**:
- Last-write-wins (simple, may lose data)
- Operational transforms (complex, preserves all edits)
- Locked editing (simple, limits collaboration)

**Answer**: [User provides answer]

### Q2: What's the maximum number of concurrent users we need to support?

**Context**: Affects infrastructure planning and architecture decisions.
**Impact**: Determines caching strategy, database choices, and scaling approach.

**Answer**: [User provides answer]

</details> <details> <summary>🏗️ Phase 4: Plan</summary>

Plan Phase

Create technical implementation strategy based on clarified specification.

Script Usage

# Setup plan phase
.specify/scripts/bash/setup-plan.sh --json

# Expected JSON output:
# {"FEATURE_SPEC": "/path/spec.md", "IMPL_PLAN": "/path/plan.md", "SPECS_DIR": "/path/specs", "BRANCH": "001-feature"}

Documents to Create

1. Main Plan (plan.md)

# Implementation Plan: [Feature Name]

## Technology Stack

### Frontend
- Framework: [Choice with rationale]
- State Management: [Choice with rationale]
- Styling: [Choice with rationale]

### Backend
- Language/Framework: [Choice with rationale]
- Database: [Choice with rationale]
- API Style: [REST/GraphQL/etc with rationale]

## Architecture

### System Overview

```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service Layer]
    C --> D[Data

---

*Content truncated.*