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

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

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

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

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

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

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] 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 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 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]
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? Tasks Phase Generate dependency-ordered, actionable implementation tasks. Prerequisites Script

Check prerequisites

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

Output:

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

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

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

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:

-

[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

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

安装

Persistent installation (recommended)

One-time usage

Initialize in current directory

Initialize new project

Options:

--force: Overwrite non-empty directories

--script ps: Generate PowerShell scripts (Windows)

--no-git: Skip Git initialization

Get latest feature directory

LATEST

Architecture

Code Quality

Performance

Architecture

Prefer composition over inheritance

Keep components loosely coupled

Code Quality

Code reviews required for all changes

Unit test coverage > 80%

Performance

Page load < 3 seconds

API response < 200ms

Create new feature

Expected JSON output:

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

Non-Functional Requirements

Performance: [Specific metrics]

Security: [Requirements]

Accessibility: [Standards]

Success Metrics

[Measurable outcome]

Setup plan phase

Expected JSON output:

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

Frontend

Framework: [Choice with rationale]

State Management: [Choice with rationale]

Backend

Language/Framework: [Choice with rationale]

Database: [Choice with rationale]

2. Data Model (data-model.md)

Data Model

Entity Relationship

3. API Contracts (contracts/)

4. Research (research.md) - Optional

Research: [Topic]

Options Evaluated

Option 1: [Technology]

Option 2: [Technology]

Recommendation

References

Check prerequisites

Output:

Phase 1: Foundation

[ ] 1.1 Set up project structure

Create directory layout per architecture doc

Configure build tools

Initialize testing framework

None

R1.1

[ ] 1.2 [P] Configure development environment

Set up linters and formatters

Configure CI/CD pipeline basics

1.1

Phase 2: Core Implementation

[ ] 2.1 Implement User model and persistence

Create User entity with validation

Implement repository pattern

Write unit tests

1.1

R2.1, R2.3

[ ] 2.2 [P] Implement Document model

Create Document entity

Define relationships with User

Write unit tests

1.1

R2.2

[ ] 2.3 Implement API endpoints

Create REST controllers

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

3. API Contracts (`contracts/`)

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