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)

1. Draft Constitution

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

1. 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]

1. 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

1. Generate Questions (Maximum 5)

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

1. 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]

1. 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

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)

# Data Model

## Entity Relationship

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

## Schemas

### User

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:

# 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

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

# 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

1. Read All Documents

• Constitution
• Specification
• Plan
• Data model
• Tasks

1. Coverage Check

# 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

1. 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?

1. Report Findings

# 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

1. Phase-by-Phase Execution

• Complete all Phase 1 tasks before Phase 2
• Respect task dependencies
• Leverage parallel markers [P]

1. Task Execution Pattern

# 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

1. 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

1. 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:

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

Progress Tracking

Update tasks.md as you go:

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

1. Sequential Phases: Must complete phases in order
2. Constitution First: Always establish constitution before features
3. Branch per Feature: Each feature gets its own Git branch
4. Numbered Features: Use sequential numbering (001, 002, 003)
5. Script Integration: Use provided bash scripts for consistency
6. 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