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:

Constitution → Establish governing principles
Specify → Define functional requirements
Clarify → Resolve ambiguities
Plan → Create technical strategy
Tasks → Generate actionable breakdown
Analyze → Validate consistency
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:

bash

command -v specify || echo "Not installed"

Installation

If not installed:

bash

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

bash

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

bash

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?

bash

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

bash

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

bash

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

Gather Context
- Understand project domain
- Identify key stakeholders
- Review existing standards (if any)
Draft Constitution
- Core values and principles
- Technical standards
- Quality expectations
- Decision criteria
Structure

markdown

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

Versioning
- Constitution can evolve
- Track changes for governance
- Review periodically

Example Content

markdown

# 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

bash

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

markdown

# 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

Analyze Specification
- Read spec.md thoroughly
- Identify ambiguities, gaps, assumptions
- Note areas with multiple valid interpretations
Generate Questions (Maximum 5)
- Prioritize high-impact areas
- Focus on decisions that affect architecture
- Ask about edge cases and error handling
Question Format

markdown

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

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

markdown

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

bash

# 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

)

markdown

# 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 Layer]

Component Design

Component 1: [Name]

Responsibility: [What it does]
Interfaces: [APIs it exposes]
Dependencies: [What it needs]

[Continue for all components...]

Design Patterns

[Pattern]: [Where and why used]

Security Considerations

Authentication: [Approach]
Authorization: [Approach]
Data Protection: [Approach]

Performance Strategy

Caching: [Strategy]
Optimization: [Key areas]

Error Handling

Error types and handling strategies
Logging and monitoring approach


#### 2. Data Model (`data-model.md`)

```markdown
# Data Model

## Entity Relationship

```mermaid
erDiagram
    USER ||--o{ DOCUMENT : creates
    USER {
        string id
        string email
        string role
    }
    DOCUMENT {
        string id
        string title
        string content
    }

Schemas

User

typescript

interface User {
  id: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer';
  createdAt: Date;
}

[Continue for all entities...]


#### 3. API Contracts (`contracts/`)

Create API specifications:
- `api-spec.json` (OpenAPI/Swagger)
- `signalr-spec.md` (if using SignalR)
- Other contract definitions

#### 4. Research (`research.md`) - Optional

Document technology investigations:

```markdown
# Research: [Topic]

## Options Evaluated

### Option 1: [Technology]
**Pros**: [Benefits]
**Cons**: [Drawbacks]
**Fit**: [How well it matches our needs]

### Option 2: [Technology]
[Same structure...]

## Recommendation

[Chosen option with rationale]

## References

- [Source 1]
- [Source 2]

5. Quick start (

quickstart.md

) - Optional

Setup instructions for developers.

Alignment Check

Before finalizing:

✅ Does plan address all requirements?
✅ Does it follow constitution principles?
✅ Are technical choices justified?
✅ Are dependencies identified?
✅ Is it implementable?

</details> <details> <summary>✅ Phase 5: Tasks</summary>

Tasks Phase

Generate dependency-ordered, actionable implementation tasks.

Prerequisites Script

bash

# Check prerequisites
.specify/scripts/bash/check-prerequisites.sh --json [--require-tasks] [--include-tasks]

# Output: {"FEATURE_DIR": "/path", "AVAILABLE_DOCS": ["spec.md", "plan.md", ...]}

Task Generation

Create

.specify/specs/NNN-feature/tasks.md

markdown

# Implementation Tasks: [Feature Name]

## Phase 1: Foundation

- [ ] 1.1 Set up project structure
  - Create directory layout per architecture doc
  - Configure build tools
  - Initialize testing framework
  - **Depends on**: None
  - **Requirement**: R1.1

- [ ] 1.2 [P] Configure development environment
  - Set up linters and formatters
  - Configure CI/CD pipeline basics
  - **Depends on**: 1.1
  - **Requirement**: R1.2

## Phase 2: Core Implementation

- [ ] 2.1 Implement User model and persistence
  - Create User entity with validation
  - Implement repository pattern
  - Write unit tests
  - **Depends on**: 1.1
  - **Requirement**: R2.1, R2.3

- [ ] 2.2 [P] Implement Document model
  - Create Document entity
  - Define relationships with User
  - Write unit tests
  - **Depends on**: 1.1
  - **Requirement**: R2.2

- [ ] 2.3 Implement API endpoints
  - Create REST controllers
  - Add request/response validation
  - Write integration tests
  - **Depends on**: 2.1, 2.2
  - **Requirement**: R3.1, R3.2

[Continue with all phases...]

## Phase N: Integration & Testing

- [ ] N.1 End-to-end testing
  - Write E2E test scenarios
  - Test critical user paths
  - **Depends on**: [all previous]
  - **Requirement**: All

## Notes

- `[P]` indicates tasks that can be parallelized
- Always check dependencies before starting
- Reference requirements for acceptance criteria

Task Characteristics

Each task should:

Be specific and actionable
Reference requirements (R1.1, R2.3, etc.)
List dependencies
Be completable in 1-4 hours
Have clear acceptance criteria

Task Types:

Implementation tasks (write code)
Testing tasks (write tests)
Configuration tasks (set up tools)
Integration tasks (connect components)

Exclude:

Deployment tasks
User training
Marketing activities
Non-coding work

Dependency Markers

None: Can start immediately
1.1: Must complete task 1.1 first
1.1, 2.2: Must complete both first
[P]: Can run in parallel with siblings

</details> <details> <summary>🔍 Phase 6: Analyze</summary>

Analyze Phase

Cross-artifact consistency and quality validation (read-only).

Purpose

Before implementation, verify:

All requirements covered by tasks
Plan aligns with constitution
No conflicts between documents
No missing dependencies

Analysis Process

Read All Documents
- Constitution
- Specification
- Plan
- Data model
- Tasks
Coverage Check

bash

# Extract requirements
grep -E "R[0-9]+\.[0-9]+" spec.md | sort -u > requirements.txt

# Extract referenced requirements in tasks
grep -E "Requirement.*R[0-9]+" tasks.md | sort -u > covered.txt

# Compare
comm -23 requirements.txt covered.txt

Consistency Checks

Constitution Alignment:

Does plan follow stated principles?
Are architecture choices justified per constitution?

Requirement Coverage:

Is every requirement addressed in tasks?
Are acceptance criteria testable?

Technical Coherence:

Do data models match spec needs?
Do API contracts align with plan?
Are dependencies realistic?

Task Dependencies:

Are all dependencies valid?
Is critical path identified?
Any circular dependencies?

Report Findings

markdown

# Analysis Report

## ✅ Passing Checks

- All requirements covered
- Constitution alignment verified
- No circular dependencies

## ⚠️ Warnings

- Requirement R3.4 has no corresponding task
- Task 5.2 references undefined dependency

## 🔴 Critical Issues

None found

## Recommendations

1. Add task for Requirement R3.4
2. Clarify dependency for task 5.2
3. Consider breaking task 6.1 into smaller tasks (estimated 8 hours)

Guidelines

Read-only: Don't modify documents
Objective: Report facts, not opinions
Actionable: Provide specific recommendations
Prioritized: Critical issues first

</details> <details> <summary>⚙️ Phase 7: Implement</summary>

Implement Phase

Execute tasks systematically, respecting dependencies and test-driven development.

Implementation Strategy

Phase-by-Phase Execution
- Complete all Phase 1 tasks before Phase 2
- Respect task dependencies
- Leverage parallel markers [P]
Task Execution Pattern

bash

# For each task:
# 1. Read context
cat .specify/specs/001-feature/spec.md
cat .specify/specs/001-feature/plan.md
cat .specify/specs/001-feature/data-model.md

# 2. Check dependencies
# Verify all depends-on tasks are complete

# 3. Implement
# Write code per task description

# 4. Test
# Write and run tests

# 5. Validate
# Check against requirements

# 6. Mark complete
# Update tasks.md: - [x] task completed

Test-Driven Approach

For each task:

Write tests first (when applicable)
Implement to pass tests
Refactor while maintaining green tests
Integration test when connecting components

Quality Checks

Before marking task complete:

Code follows plan architecture
Tests written and passing
Meets acceptance criteria
No obvious bugs
Integrated with previous work

Handling Errors

If implementation reveals issues:

Design Issues: Return to plan phase, update plan
Requirement Gaps: Return to specify/clarify, update spec
Technical Blockers: Document, escalate to user

Progress Tracking

Update tasks.md as you go:

markdown

- [x] 1.1 Set up project structure ✓ Complete
- [x] 1.2 [P] Configure development environment ✓ Complete
- [ ] 2.1 Implement User model ← Currently here
- [ ] 2.2 [P] Implement Document model

Completion Criteria

Feature is complete when:

All tasks marked complete
All tests passing
All requirements validated
Code reviewed (if applicable)
Documentation updated

</details>

File Structure

.specify/
├── memory/
│   └── constitution.md              # Phase 1
├── specs/
│   └── 001-feature-name/            # Numbered features
│       ├── spec.md                  # Phase 2
│       ├── plan.md                  # Phase 4
│       ├── data-model.md            # Phase 4
│       ├── contracts/               # Phase 4
│       │   ├── api-spec.json
│       │   └── signalr-spec.md
│       ├── research.md              # Phase 4 (optional)
│       ├── quickstart.md            # Phase 4 (optional)
│       └── tasks.md                 # Phase 5
├── scripts/
│   └── bash/
│       ├── check-prerequisites.sh
│       ├── create-new-feature.sh
│       ├── setup-plan.sh
│       └── common.sh
└── templates/
    ├── spec-template.md
    ├── plan-template.md
    └── tasks-template.md

Workflow Rules

Sequential Phases: Must complete phases in order
Constitution First: Always establish constitution before features
Branch per Feature: Each feature gets its own Git branch
Numbered Features: Use sequential numbering (001, 002, 003)
Script Integration: Use provided bash scripts for consistency
Principle-Driven: All decisions align with constitution

Summary

Spec-Kit provides a rigorous, constitution-based approach to feature development with clear phases, explicit dependencies, and comprehensive documentation at every step. The workflow ensures alignment from principles through implementation.

Supporting Files

For advanced detection logic and automation scripts, see:

Detection Logic - Comprehensive state detection algorithms

spec-kit-skill

NPX Install

Tags

SKILL.md Content

Spec-Kit: Constitution-Based Spec-Driven Development

Quick Start

When to Use

Prerequisites & Setup

Check CLI Installation

Installation

Project Initialization

Detecting Project State

1. CLI Installed?

2. Project Initialized?

3. Current Feature

4. Current Phase

Constitution Phase

Purpose

Process

Example Content

Specify Phase

Script Usage

Template Structure

Specification Content

Key Principles

Git Integration

Clarify Phase

Purpose

Process

Guidelines

Example Questions

Plan Phase

Script Usage

Documents to Create

1. Main Plan (plan.md)

Component Design

Component 1: [Name]

Design Patterns

Security Considerations

Performance Strategy

Error Handling

Schemas

User

5. Quick start (quickstart.md) - Optional

Alignment Check

Tasks Phase

Prerequisites Script

Task Generation

Task Characteristics

Dependency Markers

Analyze Phase

Purpose

Analysis Process

Guidelines

Implement Phase

Implementation Strategy

Handling Errors

Progress Tracking

Completion Criteria

File Structure

Workflow Rules

Summary

Supporting Files

1. Main Plan (
`plan.md`
)

5. Quick start (
`quickstart.md`
) - Optional