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

Analyze Description: Extract key concepts (actors, actions, data, constraints)
Generate Branch Name: Create 2-4 word short name (action-noun format)
Create Spec Directory: specs/<NNN-feature-name>/
Fill Required Sections:
- User Scenarios with priorities (P1, P2, P3)
- Functional Requirements (FR-001, FR-002, etc.)
- Success Criteria (measurable, technology-agnostic)
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

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

Ambiguity Categories

| Category | What to Check | |----------|---------------| | Functional Scope | User goals, out-of-scope declarations | | Domain & Data Model | Entities, relationships, state transitions | | Interaction & UX | User journeys, error states, accessibility | | Non-Functional | Performance, scalability, security | | Integration | External services, APIs, failure modes | | Edge Cases | Negative scenarios, conflict resolution | | Constraints | Technical constraints, tradeoffs | | Terminology | Glossary consistency | | Completion Signals | Testable acceptance criteria |

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:

Add to ## Clarifications section with session date
Apply to appropriate spec section
Replace conflicting earlier statements
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

Load Context: Read spec and any existing research
Fill Technical Context: Tech stack, dependencies, constraints
Research Phase: Resolve any NEEDS CLARIFICATION items
Design Phase: Generate data models and contracts
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

Complete Setup + Foundational
Complete User Story 1 (P1)
STOP and VALIDATE
Deploy/demo if ready
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

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

Command Reference

| Command | Description | |---------|-------------| | /speckit-specify <description> | Create spec from description | | /speckit-clarify | Run clarification on current spec | | /speckit-plan <tech-stack> | Generate implementation plan | | /speckit-tasks | Generate task breakdown | | /speckit-status | Show current spec status |

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

speckit-workflow

SpecKit: Spec-Driven Development Workflow

Triggers

Workflow Overview

Phase 1: Specify - Create Feature Specification

Purpose

Process

Specification Template

Key Rules

Phase 2: Clarify - Resolve Ambiguities

Purpose

Process

Ambiguity Categories

Question Format

Integration Rules

Phase 3: Plan - Create Implementation Plan

Purpose

Process

Generated Artifacts

Implementation Plan Template

Phase 4: Tasks - Generate Actionable Tasks

Purpose

Task Format (Required)

Phase Structure

MVP Strategy

Integration with Archon

Create Tasks in Archon

Task Status Flow

Best Practices

Command Reference

Notes