Spec-Driven Development Skill

Description

This skill enforces a spec-first development process. Before any code is written, a formal specification is created, reviewed, and approved. The 7-phase workflow ensures requirements are clear, edge cases are identified, and implementation matches the design.

Instructions

Follow these 7 phases in order. Do not skip phases.

Phase 1: Requirements Gathering

• Collect user requirements through conversation
• Identify stakeholders and their needs
• Document functional and non-functional requirements
• Output: spec/requirements.md

Copy
## Requirements

### Functional
- FR-1: Users can create accounts with email/password
- FR-2: Users can reset passwords via email link
- FR-3: Sessions expire after 24 hours of inactivity

### Non-Functional
- NFR-1: Login response time < 200ms
- NFR-2: Support 10,000 concurrent sessions
- NFR-3: OWASP Top 10 compliance

Phase 2: Architecture Design

• Define system components and their interactions
• Choose technology stack with justification
• Identify data models and API contracts
• Output: spec/architecture.md

Phase 3: Interface Specification

• Define all API endpoints with request/response schemas
• Define all UI components with props and state
• Define database schemas with relationships
• Output: spec/interfaces.md

Copy
// Example API spec
interface CreateUserRequest {
  email: string;      // RFC 5322 valid email
  password: string;   // Min 8 chars, 1 uppercase, 1 number
  name: string;       // 1-100 characters
}

interface CreateUserResponse {
  id: string;         // UUID v4
  email: string;
  name: string;
  createdAt: string;  // ISO 8601
}

Phase 4: Edge Case Analysis

• Enumerate edge cases for each feature
• Define error handling behavior
• Document failure modes and recovery
• Output: spec/edge-cases.md

Phase 5: Test Plan

• Define test cases that cover all requirements
• Map each test to a requirement (traceability)
• Include happy path, edge cases, and error scenarios
• Output: spec/test-plan.md

Phase 6: Implementation

• Write code that implements the spec exactly
• Reference spec section in code comments for traceability
• Run tests continuously during implementation
• No feature creep — only build what the spec describes

Phase 7: Verification

• Run full test suite
• Cross-check implementation against spec
• Document any deviations with justification
• Output: spec/verification-report.md

Rules

• NEVER write implementation code before Phase 5 is complete
• Each phase must be explicitly approved before proceeding
• Requirements must be testable — reject vague requirements
• Every API endpoint must have a request/response schema
• Every edge case must have a corresponding test
• Deviations from spec require documented justification
• Store all spec documents in a spec/ directory
• Use requirement IDs (FR-1, NFR-1) for traceability throughout

Examples

User: Build a payment processing module Action: Start Phase 1 — gather requirements for payment methods, currencies, error handling, compliance needs

User: I want to add search functionality Action: Phase 1 through 5 first — define what's searchable, ranking algorithm, performance requirements, then implement

User: Skip to implementation, I know what I want Action: Respectfully explain why spec-first matters, offer a lightweight spec (phases 1+3+5 only) as compromise