Spec-Driven Development

Spec-Driven Development creates comprehensive specifications before writing code. The /spec command transforms natural language requirements into technical specifications with API contracts, types, and test scenarios.

Core Command

/spec "user profile feature" --full

This command analyzes requirements and generates a complete specification package.

Generated Artifacts

The command creates structured specifications:

• openapi.yaml - API contract definition
• types.ts - TypeScript interfaces
• schemas.ts - Zod validation schemas
• tests.spec.ts - Test scenarios
• implementation-plan.md - Task breakdown

API Contracts

OpenAPI specifications define endpoints:

paths:
  /api/users/{id}/profile:
    get:
      summary: Get user profile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string

Type Definitions

TypeScript interfaces ensure type safety:

export interface UserProfile {
  id: string;
  displayName: string;
  avatar?: string;
  bio?: string;
  preferences: UserPreferences;
}

Validation Schemas

Zod schemas provide runtime validation:

export const UserProfileSchema = z.object({
  id: z.string(),
  displayName: z.string().min(1).max(50),
  avatar: z.string().url().optional(),
  bio: z.string().max(500).optional(),
  preferences: UserPreferencesSchema,
});

Test Scenarios

Generated tests cover key behaviors:

describe('User Profile', () => {
  test('retrieves profile by id', async () => {
    const profile = await getProfile('user-123');
    expect(profile).toMatchSchema(UserProfileSchema);
  });
});

Command Options

Output Control

--openapi  # Generate only OpenAPI spec
--tests    # Generate only test scenarios
--full     # Generate all artifacts (default)
--prp      # Also create PRP for implementation

Specification Scope

The command analyzes existing patterns to maintain consistency:

1. Pattern Recognition - Identifies similar features in codebase
2. Schema Generation - Creates validation matching existing patterns
3. API Design - Follows established endpoint conventions
4. Test Coverage - Mirrors existing test approaches

Workflow Integration

From Spec to Implementation

1. Generate specification:

/spec "notification system" --full

2. Review generated artifacts in specs/notification-system/

3. Create PRP from specification:

/generate-prp --from-spec specs/notification-system/

4. Implement using PRP:

/execute-prp llms/PRPs/notification-system.md

Validation Steps

The command includes built-in validation:

pnpm typecheck              # Verify TypeScript types
pnpm test specs/<feature>   # Run generated tests
npx @apidevtools/swagger-cli validate specs/<feature>/openapi.yaml

Limitations

This implementation focuses on specification generation:

• No multi-phase workflow (Spec Kit's Specify → Plan → Tasks → Implement)
• No built-in phase gates between steps
• Manual progression from spec to implementation
• No team coordination features

The command excels at creating comprehensive specifications but requires manual orchestration for full development flow.

When to Use

The /spec command suits:

• Clear feature requirements needing technical translation
• API-first development approaches
• Type-safe implementation requirements
• Test-driven development workflows

Complex multi-team projects may need additional coordination beyond what this command provides.

Benefits

Despite being focused on specification generation, the command provides:

• Complete technical specifications from natural language
• Type safety through generated interfaces and schemas
• API contracts for frontend/backend alignment
• Test scenarios for validation
• Implementation guidance through task plans

Example Usage

Creating a user notification system:

/spec "email and SMS notifications for order updates" --full --prp

Generates complete specification package:

• API endpoints for notification preferences
• Type definitions for notification objects
• Validation schemas for notification payloads
• Test scenarios for delivery logic
• Implementation plan with tasks
• Optional PRP for AI implementation

The specification becomes the foundation for development, ensuring alignment between requirements and implementation.

Related Documentation