SpecKit: Spec-Driven Development Workflow

Guide users through structured specification-driven development from feature description to implementation tasks. This skill implements the complete SpecKit methodology for turning natural language feature descriptions into actionable development work.

Triggers

Use this skill when:

• Starting a new feature development
• Writing feature specifications
• Clarifying ambiguous requirements
• Creating technical implementation plans
• Breaking down work into actionable tasks
• Generating user stories and acceptance criteria
• Keywords: speckit, specification, spec, feature, requirements, user story, acceptance criteria, implementation plan, task breakdown

Workflow Overview

SPECKIT PIPELINE

  /speckit-specify     Create specification from description
        |
        v
  /speckit-clarify     Identify and resolve ambiguities (optional)
        |
        v
  /speckit-plan        Generate technical implementation plan
        |
        v
  /speckit-tasks       Break plan into actionable tasks
        |
        v
  /speckit-implement   Execute implementation (iterative)

Phase 1: Specify - Create Feature Specification

Purpose

Transform natural language feature descriptions into structured specifications. Focus on WHAT users need and WHY - avoid implementation details.

Process

1. Analyze Description: Extract key concepts (actors, actions, data, constraints)
2. Generate Branch Name: Create 2-4 word short name (action-noun format)
3. Create Spec Directory: specs/<NNN-feature-name>/
4. Fill Required Sections:
   • User Scenarios with priorities (P1, P2, P3)
   • Functional Requirements (FR-001, FR-002, etc.)
   • Success Criteria (measurable, technology-agnostic)
5. Mark Ambiguities: Maximum 3 [NEEDS CLARIFICATION] markers

Specification Template

# Feature: [Feature Name]

## Overview
[1-2 paragraph summary of the feature]

## User Scenarios

### P1: [Primary User Journey] (MVP)
**As a** [user type]
**I want to** [action]
**So that** [benefit]

**Acceptance Criteria:**
- Given [context], when [action], then [outcome]
- Given [context], when [action], then [outcome]

### P2: [Secondary Journey]
[Same format as P1]

## Functional Requirements

- **FR-001**: System MUST [specific capability]
- **FR-002**: System MUST [specific capability]
- **FR-003**: System SHOULD [optional capability]

## Success Criteria

- Users can complete [journey] in under [time]
- System supports [scale metric]
- [Measurable outcome]

## Out of Scope
- [Explicitly excluded items]

## Clarifications
[This section populated during clarify phase]

Key Rules

• Focus on user value and business needs
• Write for non-technical stakeholders
• No implementation details (languages, frameworks, APIs)
• Requirements must be testable and unambiguous

Phase 2: Clarify - Resolve Ambiguities

Purpose

Detect and reduce ambiguity in the specification by asking targeted clarification questions and encoding answers back into the spec.

Process

1. Load Specification: Read current spec file
2. Scan for Ambiguities: Check coverage across categories
3. Generate Questions: Maximum 5 questions, prioritized by impact
4. Sequential Questioning: Present ONE question at a time
5. Integrate Answers: Update spec immediately after each answer

Ambiguity Categories

Question Format

For Multiple-Choice:

**Recommended:** Option [X] - [1-2 sentence reasoning]

| Option | Description |
|--------|-------------|
| A | Option A description |
| B | Option B description |
| C | Option C description |

Reply with option letter, accept recommendation with "yes", or provide your own answer.

For Short-Answer:

**Suggested:** [proposed answer] - [brief reasoning]

Format: Short answer (5 words max). Accept with "yes" or provide your own.

Integration Rules

After each answer:

1. Add to ## Clarifications section with session date
2. Apply to appropriate spec section
3. Replace conflicting earlier statements
4. Save immediately

Phase 3: Plan - Create Implementation Plan

Purpose

Create a technical implementation plan from the feature specification. Generate design artifacts including research, data models, and API contracts.

Process

1. Load Context: Read spec and any existing research
2. Fill Technical Context: Tech stack, dependencies, constraints
3. Research Phase: Resolve any NEEDS CLARIFICATION items
4. Design Phase: Generate data models and contracts
5. Structure Phase: Define project layout

Generated Artifacts

specs/<feature>/
├── spec.md           # Feature specification
├── plan.md           # Implementation plan
├── research.md       # Research and decisions
├── data-model.md     # Entity definitions
├── quickstart.md     # Getting started guide
└── contracts/
    └── api-spec.json # OpenAPI specification

Implementation Plan Template

# Implementation Plan: [Feature Name]

## Technical Context

**Language/Version**: [e.g., Python 3.11, TypeScript 5.x]
**Primary Dependencies**: [e.g., FastAPI, React]
**Storage**: [e.g., PostgreSQL, MongoDB]
**Testing**: [e.g., pytest, Jest]
**Target Platform**: [e.g., Linux container, AWS Lambda]

## Project Structure

src/
├── models/
├── services/
├── api/
└── lib/

tests/
├── unit/
├── integration/
└── e2e/

## Data Model Summary

[Key entities and relationships]

## API Endpoints Summary

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/v1/resource | Create resource |
| GET | /api/v1/resource/:id | Get resource |

## Implementation Phases

1. Setup & Infrastructure
2. Core Data Model
3. Business Logic
4. API Layer
5. Testing & Polish

Phase 4: Tasks - Generate Actionable Tasks

Purpose

Generate dependency-ordered task list organized by user story from the implementation plan.

Task Format (Required)

- [ ] T001 [P] [US1] Description with file path

Components:

• Checkbox: Always - [ ]
• Task ID: Sequential (T001, T002...)
• [P]: Parallelizable (different files, no dependencies)
• [Story]: User story label (US1, US2...)
• Description: Clear action with exact file path

Phase Structure

## Phase 1: Setup (Shared Infrastructure)
- Project initialization
- Dependencies

## Phase 2: Foundational (Blocking Prerequisites)
- Database schema
- Authentication
- Base models
**Checkpoint**: Foundation ready

## Phase 3: User Story 1 - [Title] (P1) MVP
**Goal**: [What this delivers]
**Independent Test**: [How to verify]

### Tests for User Story 1
- [ ] T010 [P] [US1] Contract test for endpoint

### Implementation for User Story 1
- [ ] T012 [P] [US1] Create Model in src/models/
- [ ] T013 [US1] Implement Service in src/services/
- [ ] T014 [US1] Implement endpoint in src/api/

**Checkpoint**: US1 complete

## Phase 4+: Additional User Stories
[Same pattern]

## Phase N: Polish & Cross-Cutting
- Documentation
- Performance optimization

MVP Strategy

1. Complete Setup + Foundational
2. Complete User Story 1 (P1)
3. STOP and VALIDATE
4. Deploy/demo if ready
5. Then continue with US2, US3...

Integration with Archon

Create Tasks in Archon

# For each generated task:
manage_task("create",
    project_id="<PROJECT_ID>",
    title="T001: Create User model",
    description="Create User model in src/models/user.py with fields...",
    status="todo",
    feature="User Story 1",
    task_order=10
)

Task Status Flow

todo -> doing -> review -> done

Best Practices

1. Start with Why: Understand user value before technical details
2. One Concern Per Section: Keep spec sections focused
3. Testable Everything: All requirements must be verifiable
4. Iterative Refinement: Multiple clarify passes are OK
5. Technology Agnostic Specs: Keep impl details in plan, not spec
6. MVP First: Prioritize P1 stories for initial delivery
7. Checkpoints Matter: Validate at each phase boundary

Command Reference

Notes

• Specifications should be written for stakeholders, not developers
• The plan document is where technical decisions live
• Tasks should be small enough for one session (30min-4hrs)
• Use Archon for persistent task tracking across sessions