spec-kit-skill

name

spec-kit-skill

description

GitHub Spec-Kit integration for constitution-based spec-driven development. 7-phase workflow (constitution, specify, clarify, plan, tasks, analyze, implement). Use when working with spec-kit CLI, .specify/ directories, or creating specifications with constitution-driven development. Triggered by "spec-kit", "speckit", "constitution", "specify", references to .specify/ directory, or spec-kit commands.

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

---

🔍 Phase Detection Logic

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"
 [ -f  ] && ! grep -q  ; 
   
 [ ! -f  ]; 
   
 [ ! -f  ]; 
   
 [ -f  ] && grep -q  ; 
   

   

📜 Phase 1: Constitution

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.

 : Every technical decision should improve or maintain user experience.




 Prefer composition over inheritance
 Keep components loosely coupled
 Design for testability


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


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



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

📝 Phase 2: Specify

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

❓ Phase 3: Clarify

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)

: [User provides answer]



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

: [User provides answer]

🏗️ Phase 4: Plan

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
    }

✅ Phase 5: Tasks

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
 : 2.1, 2.2
 : R3.1, R3.2

[Continue with all phases...]



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



  indicates tasks that can be parallelized
 Always check dependencies before starting
 Reference requirements for acceptance criteria

🔍 Phase 6: Analyze

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

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

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

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



None found



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

⚙️ Phase 7: Implement

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]

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

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

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

---

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.