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

References

• For detailed detection logic and status checks, see helpers/detection-logic.md.
• For a runnable status report, use scripts/detect-phase.sh.

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 codex

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

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