Feature Specs

Specification Types

Different types of work require different specification approaches:

Type	Complexity	Workflow	Format
Bug Fix	Simple	My Kit	Quick spec
Minor Feature	Simple	My Kit	Quick spec
New Feature	Complex	Spec Kit	Full spec
API Endpoint	Complex	Spec Kit	Full spec + API section
UI Component	Complex	Spec Kit	Full spec + Component section

---

Feature Specifications

When to Write

Use a full feature spec when:

• Adding new functionality
• Building a new module or system
• Changes affect multiple files
• Requires design decisions

Key Sections

Problem Statement

Define the problem clearly:

## Problem Statement

The current documentation lacks guidance on workflow selection.
Developers waste time over-planning simple tasks or under-specifying
complex features, leading to inconsistent quality.

Goals and Non-Goals

Scope the work explicitly:

## Goals

1. Define clear criteria for My Kit vs Spec Kit
2. Document both workflows with commands
3. Provide decision guidance

## Non-Goals

- Creating new commands
- Changing existing behavior
- Documenting internal implementation

User Stories

Frame requirements from user perspective:

### US-1: Choose Workflow
**As a** developer starting a task
**I want** clear criteria for choosing a workflow
**So that** I use appropriate planning

**Acceptance Criteria**:
- Decision tree provided
- Complexity thresholds defined
- Examples for each workflow

---

API Specifications

When your feature includes API endpoints, add an API section to your spec.

Endpoint Format

## API Endpoints

### `POST /api/resource`

**Description**: Create a new resource.
**Authentication**: Required

#### Request

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | Resource name |
| type | string | No | Resource type |

#### Response

**Success (201)**:
```json
{
  "id": "abc123",
  "name": "Example",
  "createdAt": "2024-01-15T10:00:00Z"
}

Errors

Status	Code	When
400	VALIDATION_ERROR	Invalid input
401	UNAUTHORIZED	Missing auth
409	CONFLICT	Already exists

### API Spec Checklist

- [ ] All endpoints documented
- [ ] Request/response formats defined
- [ ] Error codes specified
- [ ] Authentication noted
- [ ] Examples provided

---

## Component Specifications

When building UI components, add a component section to your spec.

### Component Format

```markdown
## Component: Button

**Purpose**: Trigger actions
**Category**: Atom

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | string | "primary" | Visual style |
| size | string | "md" | Size variant |
| disabled | boolean | false | Disabled state |

### Variants

| Variant | Use Case |
|---------|----------|
| primary | Main actions |
| secondary | Secondary actions |
| danger | Destructive actions |

### Accessibility

- Keyboard: Enter/Space to activate
- Focus: Visible focus ring
- ARIA: Native button semantics

Component Spec Checklist

• Purpose defined
• Props documented
• Variants listed
• States covered (hover, focus, disabled)
• Accessibility requirements noted

---

Quick Spec Examples

Bug Fix

## What
Fix menu staying open after navigation on mobile.

## Why
Poor UX—users must manually close menu.

## How
Add onClick handler to close menu state.

## Test
Navigate on mobile, verify menu closes.

Minor Feature

## What
Add dark mode toggle to settings.

## Why
Users requested theme preference.

## How
Add toggle component, persist to localStorage.

## Test
Toggle works, preference persists across sessions.

---

Full Spec Example

# Spec: User Authentication

**Issue**: #42
**Branch**: `42-user-auth`
**Status**: Draft
**Type**: Feature

## Problem Statement

The application lacks user authentication, preventing
personalized features and secure access.

## Goals

1. Implement login/register endpoints
2. Add JWT-based session management
3. Protect authenticated routes

## Non-Goals

- Social login (OAuth)
- Password reset flow
- Admin user management

## User Stories

### US-1: Register Account
**As a** new user
**I want** to create an account
**So that** I can access personalized features

**Acceptance Criteria**:
- Register with email/password
- Receive confirmation
- Can login immediately

## API Endpoints

### `POST /api/auth/register`
[Request/response details...]

### `POST /api/auth/login`
[Request/response details...]

## Acceptance Criteria

### Functional
- [ ] Register creates user
- [ ] Login returns JWT
- [ ] Protected routes require auth

### Quality
- [ ] Passwords hashed
- [ ] Input validated
- [ ] Rate limiting applied

## Implementation Checklist

- [ ] Create spec
- [ ] Implement register endpoint
- [ ] Implement login endpoint
- [ ] Add auth middleware
- [ ] Test all flows
- [ ] Create PR

---

Choosing Spec Depth

Situation	Spec Type	Detail Level
Obvious fix	Quick spec	Minimal
Clear feature	Quick spec	Brief
New capability	Full spec	Standard
API changes	Full spec	+ API section
New component	Full spec	+ Component section
System design	Full spec	Comprehensive