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.
Spec-Driven Development (SDD) is an approach where specifications are treated as first-class citizens in the software development lifecycle:
- Define First - Create clear specifications before implementation
- Validate Automatically - Use schemas to validate data automatically
- Generate Code - Auto-generate types and documentation from specs
- Track Compliance - Monitor requirement fulfillment over time
| 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 |
- Create specifications with requirements, constraints, and metadata
- Support for JSON Schema and OpenAPI specifications
- Version management with semver
- Strict and flexible modes
- Built-in JSON Schema validation (Draft-07, 2020-12)
- OpenAPI 2.0, 3.0, 3.1 specification validation
- Custom validators extensible
- TypeScript type definitions from specs
- Markdown documentation generation
- Customizable generators
- Track requirement status (pending, in progress, completed, verified)
- Generate compliance reports
- Identify critical pending items
- Full PM² methodology workflow support
- Project Charter, Handbook, Work Plan management
- Phase gates (Initiating → Planning → Executing → Closing)
- Stakeholder and risk management
- Full TypeScript support with strict typing
- Generated type definitions
- Compile-time error detection
npm install @xflofoxx/LumiSDDimport { 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}%`);Define your API specification once, generate types and validators automatically.
Use JSON Schema for runtime validation with automatic type generation.
Track requirements from specification to implementation with compliance reports.
Apply PM² methodology with built-in workflow and artifact templates.
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 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
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:e2eFor a complete overview of all examples, see examples/README.md.
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
# 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.shsrc/
├── 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)
→ lightweight not complex
→ iterative not waterfall
→ type-safe not loose
→ standards-compliant not proprietary
→ extensible not rigid
MIT License - see LICENSE for details.
Xflofoxx - Creator and maintainer
- Inspired by OpenSpec
- Built with Ajv for JSON Schema validation
- Follows PM² Methodology by European Commission