LumiSDD - Spec Driven Development Framework

About LumiSDD

LumiSDD (Lightweight Methodology for Spec-Driven Development) is a lightweight, type-safe framework for modern software engineering that brings Spec-Driven Development (SDD) to life. Built with TypeScript and designed for developers who want specification-based development with integrated PM² project management methodology.

What is Spec-Driven Development?

Spec-Driven Development (SDD) is an approach where specifications are treated as first-class citizens in the software development lifecycle:

1. Define First - Create clear specifications before implementation
2. Validate Automatically - Use schemas to validate data automatically
3. Generate Code - Auto-generate types and documentation from specs
4. Track Compliance - Monitor requirement fulfillment over time

Why LumiSDD?

Traditional Development	LumiSDD Approach
Code-centric	Specification-centric
Documentation as afterthought	Documentation generated
Manual validation	Automated schema validation
Unclear requirements	Tracked, verifiable requirements
Ad-hoc processes	PM² methodology integration

Key Features

📋 Spec Management

• Create specifications with requirements, constraints, and metadata
• Support for JSON Schema and OpenAPI specifications
• Version management with semver
• Strict and flexible modes

✅ Schema Validation

• Built-in JSON Schema validation (Draft-07, 2020-12)
• OpenAPI 2.0, 3.0, 3.1 specification validation
• Custom validators extensible

💻 Code Generation

• TypeScript type definitions from specs
• Markdown documentation generation
• Customizable generators

📊 Compliance Tracking

• Track requirement status (pending, in progress, completed, verified)
• Generate compliance reports
• Identify critical pending items

🏛️ PM² Integration

• Full PM² methodology workflow support
• Project Charter, Handbook, Work Plan management
• Phase gates (Initiating → Planning → Executing → Closing)
• Stakeholder and risk management

🔒 Type Safety

• Full TypeScript support with strict typing
• Generated type definitions
• Compile-time error detection

Quick Start

Installation

npm install @xflofoxx/LumiSDD

Basic Usage

import { Spec, SpecRegistry, TypeScriptGenerator, JsonSchemaValidator, ComplianceTracker } from '@xflofoxx/LumiSDD';

// 1. Create a specification
const spec = Spec.create({
  name: 'UserService',
  version: '1.0.0',
  description: 'User management service specification',
  schema: {
    type: 'object',
    properties: {
      id: { type: 'string' },
      name: { type: 'string' },
      email: { type: 'string', format: 'email' }
    },
    required: ['id', 'name', 'email']
  },
  requirements: [{
    id: 'REQ-001',
    description: 'User can register with valid email',
    priority: 'high',
    status: 'completed',
    testable: true,
    acceptanceCriteria: ['Email is validated', 'User is persisted']
  }]
});

// 2. Register the spec
const registry = new SpecRegistry();
registry.register(spec);

// 3. Generate TypeScript types
const generator = new TypeScriptGenerator();
console.log(generator.generate(spec).code);

// 4. Validate data against schema
const validator = new JsonSchemaValidator();
const result = validator.validateJsonSchema(
  { id: '1', name: 'John', email: 'john@example.com' },
  spec.schema!
);
console.log('Valid:', result.valid);

// 5. Track compliance
const tracker = new ComplianceTracker(registry);
tracker.trackChange(spec.id, 'REQ-001', 'verified');
const report = tracker.generateReport(spec.id);
console.log(`Compliance: ${report.compliancePercentage}%`);

Use Cases

API Development

Define your API specification once, generate types and validators automatically.

Data Validation

Use JSON Schema for runtime validation with automatic type generation.

Requirements Management

Track requirements from specification to implementation with compliance reports.

Project Management

Apply PM² methodology with built-in workflow and artifact templates.

PM² Methodology

This project follows the PM² Project Management Methodology developed by the European Commission:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Initiating  │────▶│  Planning   │────▶│ Executing   │────▶│  Closing    │
│             │     │             │     │             │     │             │
│ • Charter   │     │ • Handbook  │     │ • Deliver   │     │ • End Report│
│ • Stakehold │     │ • Work Plan │     │ • Monitor   │     │ • Lessons   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

PM² Resources

• Project Initiation Canvas
• RAID Log
• Traceability Matrix
• PM² Guide PDF

Documentation

• Getting Started
• Contributing Guide
• Code of Conduct
• Security Policy

Examples

LumiSDD includes practical examples to help you get started:

Example	Description	Complexity
Hello Spec	Basic specification and code generation	Beginner ⭐
User CRUD	Complete REST API specification	Intermediate ⭐⭐
E2E Workflow	Full SDD workflow demonstration	Advanced ⭐⭐⭐

Quick Start with Examples:

# Clone the repository
git clone https://github.com/Xflofoxx/LumiSDD.git
cd LumiSDD

# Install dependencies
npm install

# Build
npm run build

# Run the E2E example (recommended for first-time users)
npm run example:e2e

For a complete overview of all examples, see examples/README.md.

Free Tier Compatible

This project is designed to work within free tier limits:

• CI/CD: Optimized GitHub Actions workflow (~10 min/job)
• No external paid services: Uses local coverage reporting
• Open source dependencies: All packages are MIT/Apache licensed
• Self-hosted runners: Can run locally with Docker if needed

Development

# Install dependencies
npm install

# Run tests
npm test

# Run typecheck
npm run typecheck

# Run lint
npm run lint

# Build
npm run build

# Run examples
cd examples/hello-spec && ./generate.sh

Architecture

src/
├── core/           # Core specification classes
│   ├── Spec.ts    # Specification class with requirements/constraints
│   ├── SpecRegistry.ts  # Registry for managing multiple specs
│   └── types.ts   # TypeScript interfaces
├── validators/     # Schema validators
│   ├── SpecValidator.ts    # Base validator using Ajv
│   ├── JsonSchemaValidator.ts  # JSON Schema validation
│   └── OpenApiValidator.ts    # OpenAPI validation
├── generators/     # Code generators
│   ├── CodeGenerator.ts      # Base generator class
│   ├── TypeScriptGenerator.ts  # TypeScript type generation
│   └── MarkdownGenerator.ts   # Markdown documentation
├── trackers/      # Compliance tracking
│   └── ComplianceTracker.ts  # Track requirement compliance
└── pm2/          # PM² methodology integration
    ├── PM2Workflow.ts  # PM² workflow implementation
    └── types.ts       # PM² types (phases, roles, deliverables)

Philosophy

→ lightweight not complex
→ iterative not waterfall  
→ type-safe not loose
→ standards-compliant not proprietary
→ extensible not rigid

License

MIT License - see LICENSE for details.

Author

Xflofoxx - Creator and maintainer

Acknowledgments

• Inspired by OpenSpec
• Built with Ajv for JSON Schema validation
• Follows PM² Methodology by European Commission