---

name: dev-spec-driven description: Spec-driven development workflow for iOS. Use when creating new features, writing requirements, design documents, implementation plans, EARS notation, user stories, acceptance criteria, property-based testing. allowed-tools: Read, Write, Grep, Glob

Spec-Driven Development

Table of Contents

• 1. Concept ........................... L20-L50
• 2. Workflow ......................... L52-L100
• 3. Requirements Format ... L102-L160
• 4. Design Format ............... L162-L250
• 5. Tasks Format ................. L252-L340
• 6. Traceability ................. L342-L380
• 7. Agents ............................. L382-L420

---

1. Concept

Spec Files

Each feature requires 3 files in .claude/specs/[feature-name]/:

Directory Structure

Copy.claude/specs/
├── user-authentication/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
├── product-catalog/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
└── shopping-cart/
    └── ...

Core Principles

1. Feature-based: Organized by feature, each feature is independent
2. Traceability: US → AC → Property → Task all have IDs and references
3. Checkpoints: User confirmation after each step
4. No code in spec: Specs describe only, no sample code

---

2. Workflow

2.1 Overview Flow

CopyIdea
    ↓
┌─────────────────┐
│ write-spec      │ → requirements.md
└────────┬────────┘
         ↓ [User Confirm]
┌─────────────────┐
│ write-design    │ → design.md
└────────┬────────┘
         ↓ [User Confirm]
┌─────────────────┐
│ write-tasks     │ → tasks.md
└────────┬────────┘
         ↓ [User Confirm]
┌─────────────────┐
│ execute-tasks   │ → Code
└─────────────────┘

2.2 User Confirmation (REQUIRED)

Prompt Format:

Copy❓ What would you like to do?
1. ✅ Continue to next step
2. ✏️ Request modifications
3. ⏸️ Stop here, continue later

2.3 Rules

• NEVER automatically create the next file without asking user
• ALWAYS wait for user confirmation before continuing
• User selects Modify → Apply changes → Ask again

---

3. Requirements Format

3.1 Template

Copy# [Feature Name] - Requirements

## Table of Contents
- [1. Overview](#1-overview)
- [2. User Stories](#2-user-stories)
- [3. Non-Functional Requirements](#3-non-functional-requirements)

## 1. Overview
[Brief feature description - 2-3 sentences]

## 2. User Stories

### US-001: [Story name]
**As a** [role]
**I want** [action]
**So that** [benefit]

#### Acceptance Criteria
- AC-001.1: WHEN [trigger] THE SYSTEM SHALL [behavior]
- AC-001.2: WHEN [trigger] THE SYSTEM SHALL [behavior]
- AC-001.3: IF [error] THEN THE SYSTEM SHALL [error handling]

### US-002: [Story name]
...

## 3. Non-Functional Requirements
- NFR-001: Performance - [requirement]
- NFR-002: Security - [requirement]

3.2 EARS Patterns

3.3 Rules

• Each User Story has ID: US-XXX
• Each Acceptance Criteria has ID: AC-XXX.Y
• EARS notation required for AC
• Must have error handling criteria (IF...THEN)

---

4. Design Format

4.1 Main Structure

Copy# [Feature Name] - Technical Design

## Table of Contents
- [1. Overview](#1-overview)
- [2. Shared](#2-shared)
- [3. Features](#3-features)
  - [3.1 Feature: List Screen](#31-feature-list-screen)
  - [3.2 Feature: Detail Screen](#32-feature-detail-screen)
  - [3.3 Feature: Form Screen](#33-feature-form-screen)
- [4. Navigation](#4-navigation)
- [5. Correctness Properties](#5-correctness-properties)

4.2 Shared Section

4.3 Feature Section (EACH FEATURE INDEPENDENT)

Each feature (3.1, 3.2, 3.3) has 6 parts:

4.4 Correctness Properties

4.5 Rules

• Each feature is an independent, complete unit
• Each feature MUST have Acceptance Checklist
• NO sample code, description only
• Table of contents has line numbers for fast AI navigation

---

5. Tasks Format

5.1 Main Structure

Copy# [Feature Name] - Implementation Plan

## Table of Contents
- [1. Overview](#1-overview)
- [2. Shared Tasks](#2-shared-tasks)
- [3. Feature Tasks](#3-feature-tasks)
  - [3.1 Feature: List Screen](#31-feature-list-screen)
  - [3.2 Feature: Detail Screen](#32-feature-detail-screen)
  - [3.3 Feature: Form Screen](#33-feature-form-screen)
- [4. Integration Tasks](#4-integration-tasks)
- [5. Progress](#5-progress)

5.2 Task Sections

5.3 Each Feature Has 3 Parts

5.4 Checkpoints

Each section has a Checkpoint:

Copy**Checkpoint 3.1:** ⬜ Feature List Screen complete

Checkpoint = Gate to next section:

• ⬜ = Not started
• 🔄 = In progress
• ✅ = Done (Build pass + tests pass + checklist done)

5.5 Task Format

Copy- [ ] **3.1.2.1** Create [Name]View
  - File: `Features/[Name]/Views/[Name]View.swift`
  - Wireframe: Design 3.1.1
  - Refs: AC-001.1, AC-001.3

5.6 Rules

• Task ID: [Section].[Subsection].[Task] (e.g., 3.1.2.1)
• MUST have: File, Design reference, Refs (AC-xxx)
• Complete each Feature before moving to next Feature
• DO NOT work on multiple Features in parallel
• DO NOT skip Checkpoints

---

6. Traceability

6.1 Traceability Chain

CopyUS-001 (User Story)
  └── AC-001.1 (Acceptance Criteria)
        └── Design 3.1 (Feature section)
              └── Property P1 (Correctness Property)
                    └── Task 3.1.1.2 [PBT] (Property-based test)

6.2 Traceability Matrix (in tasks.md)

6.3 Rules

• Every AC MUST have a task
• Every task MUST reference AC or Design section
• Every Property MUST reference AC

---

7. Agents

7.1 Agent Chain

7.2 When to Use Which Agent

7.3 Rules

• Each agent creates 1 file
• After each file → User confirm
• DO NOT skip agents in chain