SpecVerse Language


The Revolutionary Application Specification Language for Human-AI Collaboration

🌟 What is SpecVerse?

SpecVerse is a specification language designed for seamless communication between humans and AI systems. It enables you to describe applications at three architectural layers—Components, Deployments, and Manifests—using a human-readable YAML syntax enhanced with powerful conventions and AI-powered inference.

$3

1. 📦 Components Layer
- Define your application's logical structure: models, controllers, services, events, and views
- Specify business logic, data relationships, and system boundaries
- Use lifecycle state machines and CURVED operations (Create, Update, Retrieve, Retrieve_many, Validate, Evolve, Delete)

2. 🚀 Deployments Layer
- Configure production-ready deployment topologies with logical instances
- Define storage, security, infrastructure, and monitoring capabilities
- Scale from personal projects to enterprise multi-tenant architectures

3. 🛠️ Manifests Layer
- Generate concrete deployment artifacts (Kubernetes, Docker, cloud configurations)
- Bridge the gap between specification and executable infrastructure
- Maintain perfect alignment between design intent and deployed reality

$3

SpecVerse implements a distributed Model-View-Controller pattern enhanced with:

- 📊 Models: Rich data definitions with relationships, attributes, and constraints
- 🎮 Controllers: CURVED operations (Create, Update, Retrieve, Retrieve_many, Validate, Evolve, Delete) for complete lifecycle management
- ⚙️ Services: Business logic components with event subscription capabilities
- 📱 Views: User interface specifications with state binding and interaction patterns
- 🔄 Lifecycles: State machines that govern entity transitions across all architectural layers
- 🎯 Conventions: Smart defaults and shorthand syntax that reduce boilerplate by 90%
- 👤 Profiles: Reusable component patterns for rapid composition

$3

The heart of SpecVerse: 21+ intelligent inference rules that transform your minimal specifications into complete architectures:

- Context-Aware Generation: Understands relationships and generates appropriate controllers, services, and events
- Scale Intelligence: Automatically recognizes project complexity and generates appropriate enterprise features
- Type Inference: Complete type system generation from model definitions
- Cascade Handling: Smart relationship processing with eager loading and validation

$3

- @specverse/primitives: Core reusable types (Address, Money, PhoneNumber, PersonName, ContactInfo, AuditFields)
- @specverse/business: Business domain types (Organization, Employee)
- @specverse/system: System and technical types (Configuration, LogEntry)
- @specverse/deployments: Production deployment patterns (monolith, microservices, enterprise, jamstack)
- Component Libraries: Reusable architectural patterns (authentication, user management, notifications)
- Deployment Libraries: Production-ready deployment templates (monolith, microservices, serverless)
- Domain Libraries: Industry-specific models and patterns (e-commerce, healthcare, finance)

$3

Modern Grouped Commands:
- specverse gen - Generate YAML, UML diagrams, documentation, and AI-optimized views
- specverse dev - Development workflow (validation, formatting, quick checks)
- specverse test - Testing workflows and validation cycles
- specverse ai - AI-assisted specification development (config, templates, suggestions)
- specverse infer - AI-powered architecture expansion and inference
- specverse init - Project initialization with intelligent templates

Legacy Support: Full backward compatibility with traditional commands (validate, process, check)

$3

Development Tools:
- 🎨 VSCode Extension: Full syntax highlighting, IntelliSense, real-time validation, and diagram preview
- 📊 Diagram Generator: Mermaid-based UML diagrams (ER, sequence, architecture, lifecycle, deployment)
- 📝 Documentation Generator: Auto-generated comprehensive documentation with cross-references
- 🤖 AI Orchestrator: Interactive AI workflow system for collaborative specification development

Integration Tools:
- 🔌 MCP Server: Universal AI assistant integration across all environments (Claude Desktop, web interfaces, enterprise)
- 📦 TypeScript/JavaScript API: Complete programmatic access for custom applications and build tools
- 🐳 Docker Support: Containerized deployment for enterprise environments
- ☁️ Multi-Cloud: Generate deployment artifacts for AWS, Azure, GCP, and Kubernetes

SpecVerse combines YAML + Conventions with AI-powered inference to transform minimal specifications (.specly files) into complete system architectures. Write 90% less code while maintaining perfect alignment between design and implementation.

📈 Recent Releases

$3

Latest stable release with comprehensive code generation improvements:

- 🐛 Debug Enhancements: Enhanced path resolution logging (enable with SPECVERSE_DEBUG=true)
- 🔧 Build Fixes: Fixed TypeScript compilation for libs/ directory
- 📦 Package Reliability: Resolved tsx node_modules restrictions
- 🎨 Pattern Adapters: Complete pattern adapter bundling for generated projects
- ✨ View Rendering: Pattern-based architecture with 49 atomic component types

Current View Syntax (as of v3.4.x):
``yaml
views:
TaskListView:
uiComponents: # ✅ Current standard property name
taskTable:
type: table
properties:
columns: [title, status, priority]
`

$3

Complete project generation with technology-agnostic scaffolding:

- 🏗️ Complete Projects: Single command generates entire runnable applications
- ⚙️ Framework Agnostic: Works with any ORM/framework combination
- 📦 Smart Dependencies: Auto-aggregates requirements, scripts, and environment variables
- 🚀 Production Ready: From specverse realize all to npm run dev in seconds

$3

For detailed release notes, migration guides, and breaking changes, see:
📖 CHANGELOG.md - Complete version history with all features and fixes

---

🔮 Roadmap

$3

#### Registry Linter (Future Release)
Optional validation of implementation manifests before code generation with typo detection and deprecation warnings.

📖 See: docs/specs/registry-linter-specification.md for complete specification




🚀 Quick Start

$3

Option 1: From npm (recommended for new projects)
`bash
npm install -g @specverse/lang
`

Option 2: From source (for development)
`bash
git clone https://github.com/SpecVerse/specverse-lang.git
cd specverse-lang
npm run setup && npm run build
`

$3

SpecVerse includes enhanced AI prompts for terminal/chat-based development:

`bash


View the complete prompt collection

ls prompts/core/standard/default/

create.prompt.yaml - Generate specs from requirements

analyse.prompt.yaml - Extract specs from existing code

materialise.prompt.yaml - Generate implementations

realize.prompt.yaml - Generate deployments (environment-adaptive)

`

Quick Terminal Usage:
`bash


Get ready-to-use terminal prompts


cat prompts/core/base-terminal-prompt.md
`

Complete Workflow:
1. Create specification from natural language
2. Materialise into production-ready code
3. Realize deployment configurations
4. Deploy with generated automation scripts

📖 Complete Terminal Guide

$3

SpecVerse provides a unified CLI for AI-assisted specification development:

#### Quick Start with AI Config

`bash


Generate a default AI configuration template

specverse ai config --output my-project-config.yaml

Edit the config file with your requirements

Then use it to generate prompts with auto-enhancement

specverse ai template create --config my-project-config.yaml
`

#### Available Commands

📚 ai docs - Show AI documentation paths
`bash
specverse ai docs


Displays paths to: AI schema, reference examples, prompt templates


`

⚙️ ai config - Generate default configuration template
`bash
specverse ai config # Display to console
specverse ai config --output ai-config.yaml # Save to file
`

📝 ai template - Get/fill AI prompt templates (unified command)
`bash


Get raw template

specverse ai template create

Create from requirements

specverse ai template create "patient management system"

Analyse existing code

specverse ai template analyse "FastAPI application at ./src"

Materialise implementation

specverse ai template materialise --config ai-config.yaml

Realize deployment

specverse ai template realize --config ai-config.yaml
`

🔍 ai suggest - Get SpecVerse library recommendations
`bash


Suggest from inline requirements

specverse ai suggest --requirements "ecommerce platform with payments"

Suggest from config file

specverse ai suggest --config ai-config.yaml
`

#### AI Config File Format

The config file supports comprehensive project specification:

`yaml


Project requirements (multi-line support)

requirements: |
A patient management system for a small clinic with:
- Appointment scheduling
- Patient records and medical history
- HIPAA compliance

Project scale

scale: business # personal|business|enterprise

Framework and domain

framework: fastapi
domain: healthcare

Compliance and technology

compliance:
- HIPAA
- SOC2
technology:
- postgresql
- redis

SpecVerse libraries (enables auto-enhancement)

libraries:
- "@specverse/domains/healthcare"
- "@specverse/deployments/enterprise"
- "@specverse/manifests/postgresql"
`

Key Features:
- 🎯 Auto-Enhancement: When libraries are specified in config, prompts automatically include library context
- 📦 90% Code Reduction: Libraries provide pre-built domain models and deployment patterns
- 🔒 Compliance-Ready: Built-in HIPAA, SOC2, GDPR patterns in domain libraries
- 💰 Cost Estimates: Token counts and cost estimates for different LLM providers

#### Operations Available

All ai template commands support these operations:

- analyse - Extract specifications from existing codebases
- create - Generate specifications from requirements
- materialise - Generate implementation code from specs
- realize - Generate deployment configurations

$3

SpecVerse includes a universal MCP server for AI assistant integration:

`bash


Install the MCP server

npm install -g @specverse/mcp

Local development with Claude Desktop, Cline, etc.

specverse-mcp --mode local

Web deployment (with orchestrator support)

specverse-mcp --mode local --enable-orchestrator
`

Live Demo: https://specverse-crezbwpnl-specverse.vercel.app

The MCP server provides:
- 🤖 Prompt Generation: AI-optimized prompts for specification creation
- 📚 Library Suggestions: Contextual SpecVerse library recommendations
- ✅ Validation Tools: Real-time specification validation
- 🔄 Orchestrator Integration: Full workflow automation (optional)

$3

The fastest way to get started is with the project initializer:

`bash


Create new project with working examples

specverse init my-project
cd my-project

The generated specs/main.specly includes:

- Working model definitions

- Multiple deployment scale examples

- Comprehensive comments and guidance

`

$3

SpecVerse includes three production-ready templates for different project types:

#### 1. Default Template (Fullstack Monorepo)
Full-stack applications with frontend and backend in a monorepo structure.

`bash
specverse init MyApp


or explicitly


specverse init MyApp --template default
`

Stack: Fastify + Prisma + PostgreSQL (backend) + React + Vite + React Router (frontend)
Structure: npm workspaces with backend/ and frontend/ directories
Best for: Integrated full-stack applications, MVPs, startups

#### 2. Backend-Only Template
API-only services, microservices, or when frontend is a separate project.

`bash
specverse init MyAPI --template backend-only
`

Stack: Fastify + Prisma + PostgreSQL
Structure: Standalone (no subdirectories)
Best for: Microservices, API services, mobile backends, data services

#### 3. Frontend-Only Template
JAMstack applications and SPAs connecting to external APIs.

`bash
specverse init MyFrontend --template frontend-only
`

Stack: React + Vite + React Router + React Query
Structure: Standalone (no backend)
Best for: JAMstack apps, static sites, frontends for existing APIs, PWAs

📖 Complete template documentation: templates/README.md

$3

`bash


Test the generated specification

specverse validate specs/main.specly

Generate documentation

specverse gen docs specs/main.specly

Generate UML diagrams

specverse gen uml specs/main.specly
`

$3

Create a simple blog-system.specly file:

`yaml
components:
BlogSystem:
version: "3.4.0"
description: "Simple blog with posts and authors"

models:
Author:
attributes:
name: String required
email: String required unique

Post:
attributes:
title: String required
content: String required
publishedAt: String optional
relationships:
author: belongsTo Author

Optional: Add deployment (see generated examples for patterns)


deployments:
development:
version: "3.4.0"
environment: development
instances:
controllers:
blog-api:
component: "BlogSystem"
scale: 1
`

$3

`bash


GROUPED COMMANDS

specverse gen yaml blog-system.specly # Generate processed YAML
specverse gen uml blog-system.specly # Generate UML diagrams
specverse gen docs blog-system.specly # Generate documentation
specverse gen views blog-system.specly # Generate AI-optimized views
specverse gen all blog-system.specly # Generate everything

Development workflow commands

specverse dev quick blog-system.specly # Quick validation
specverse dev format blog-system.specly # Format specification

LEGACY COMMANDS (deprecated but supported)

specverse validate blog-system.specly # Use: specverse dev quick
specverse process blog-system.specly # Use: specverse gen yaml
`

$3

Use SpecVerse programmatically in your applications:

`typescript
import { SpecVerseParser, LogicalInferenceEngine } from '@specverse/lang';
import { readFileSync } from 'fs';

// Parse specification
const schema = JSON.parse(readFileSync('node_modules/@specverse/lang/schema/SPECVERSE-SCHEMA.json', 'utf8'));
const parser = new SpecVerseParser(schema);
const result = parser.parseFile(content, 'blog-system.specly');

// Run AI inference
const config = {
logical: { generateControllers: true, generateServices: true },
rules: {
logicalRulesPath: 'node_modules/@specverse/lang/dist/inference-engine/rules/logical'
}
};
const engine = new LogicalInferenceEngine(config);
await engine.loadRules();
const inference = await engine.inferLogicalSpecification(result.ast.components.flatMap(c => c.models), 'BlogSystem');

console.log('Generated:', inference.statistics.controllersGenerated, 'controllers');
`

✅ Fully tested examples: API Usage Guide - Working JavaScript & TypeScript examples

🛠️ CLI Commands

$3


`bash

Generate various outputs (RECOMMENDED)

specverse gen views user-spec.specly # AI-optimized implementation specs
specverse gen yaml user-spec.specly # Process .specly to .yaml
specverse gen uml user-spec.specly # Generate UML diagrams
specverse gen docs user-spec.specly # Generate documentation
specverse gen all user-spec.specly # Generate everything

Development and testing workflows

specverse dev quick # Quick validation (replaces 'check')
specverse dev format # Format specification
specverse test cycle # Full test cycle

Library management (NEW)

specverse lib search --tags auth # Search registry libraries by tags
specverse lib search auth # Search libraries by name/description
specverse lib info @specverse/auth # Get detailed library information
specverse lib list # List cached/used libraries
specverse lib tags # List available tags
specverse lib cache clear # Clear library cache
`

$3

`bash
specverse validate spec.specly # Validate specifications
specverse process spec.specly # Convert .specly to .yaml
specverse init MyProject # Initialize new project (WORKS GREAT!)
`

📖 Complete reference: CLI Documentation

📚 Registry Integration

SpecVerse includes built-in integration with the SpecVerse Community Registry for sharing and discovering reusable components:

$3

- Automatically resolves imports from the production registry
- Falls back to local files and NPM packages if needed
- Built-in caching for offline development

$3

`bash

Search by multiple criteria

specverse lib search --tags authentication,oauth
specverse lib search --tags business,healthcare
specverse lib search payments

Get detailed information

specverse lib info domains-primitives-contact-yaml-contactlibrary
`

$3

- Cache Management: Automatic caching with manual clear options
- Library Listing: View all cached and currently used libraries
- Tag Discovery: Browse available tags for semantic search
- Type Classification: Libraries organized by component, deployment, manifest types

$3

- URL: https://specverse-lang-registry-api.vercel.app
- Libraries: 20+ production-ready libraries covering primitives, business domains, deployments
- Import Format: Use actual library names from registry (e.g., domains-primitives-contact-yaml-contactlibrary)

🏗️ Architecture

SpecVerse features a clean, modular architecture with unified manifest support:

`
src/
├── parser/ # YAML + Conventions parser
├── inference-engine/ # AI-powered specification inference
├── cli/ # Command-line interface
├── generators/ # Documentation and diagram generators

tools/
├── ai-orchestrator/ # AI workflow orchestration + configuration
├── diagram-generator/ # Standalone diagram generation
├── specverse-mcp/ # MCP server for AI assistants
└── vscode-extension/ # VSCode language support
`

🧠 AI-Powered Inference Engine

Transform minimal models into complete architectures with intelligent scale recognition:

Personal Scale Example (4x Expansion):
`yaml
GuestBedroom:
attributes:
roomName: String required
capacity: Integer required
`
→ 207 lines become 807 lines with guest-focused features

Enterprise Scale Example (7.6x Expansion):
`yaml
Organization:
attributes:
name: String required
contactEmail: Email required
relationships:
properties: hasMany Property cascade
users: hasMany User through=OrganizationMembership
`
→ 479 lines become 3,644 lines with multi-tenancy, RBAC, international support

📊 Features & Capabilities

$3

- YAML + Conventions: Human-readable syntax with powerful shorthand
- Model Definitions: Attributes, relationships, lifecycles, profiles
- Component Architecture: Logical components with clear boundaries
- Deployment Specifications: Production-ready deployment configs

$3

- 21 Inference Rules: Generate controllers, services, events, views
- Context-Aware: Relationship-aware generation with cascade handling
- Lifecycle Integration: State machine integration across all layers
- Type Inference: Complete type specifications for all components

$3

- CLI: Full-featured command-line interface with deployment diagram support
- VSCode Extension: Syntax highlighting, validation, intellisense with deployment and manifest keywords
- Diagram Generation: Mermaid diagrams (ER, sequence, architecture, lifecycle, deployment)
- Documentation: Auto-generated MD/MDX documentation

🧪 Testing & Quality

$3

SpecVerse maintains a comprehensive multi-tier testing infrastructure covering all components:

- Core Component Tests: Unit and integration tests via Vitest
- Inference Engine Tests: AI rule validation and regression testing
- Grammar Validation: Language syntax validation across all features
- Example Validation: Real-world specifications with expected failure handling
- Integration Tests: API, CLI, Parser, and Package integration tests
- Tool Tests: AI Orchestrator, MCP Server, and Configuration tests

📖 See CHANGELOG.md for current test counts and success rates

$3

Unified Diagram Generator: 15 diagram types across 5 architectural categories.

| Category | Diagram Type | Status | Description |
|----------|-------------|--------|-------------|
| Event Flow | event-flow-layered | ✅ Complete | 5-layer architecture with dual event bus |
| | event-flow-sequence | ✅ Complete | Temporal event sequences |
| | event-flow-swimlane | ✅ Complete | Parallel event flows |
| Model Diagrams | er-diagram | ✅ Complete | Entity-relationship diagram |
| | model-inheritance | ✅ Complete | Model inheritance hierarchy |
| | profile-attachment | ✅ Complete | Profile attachments to models |
| | lifecycle | ✅ Complete | State machine lifecycles |
| Architecture | mvc-architecture | ✅ Complete | MVC architecture overview |
| | service-architecture | ✅ Complete | Service layer architecture |
| | component-dependencies | ✅ Complete | Component dependency graph |
| Deployment | deployment-topology | ✅ Complete | Deployment instance visualization |
| | capability-flow | ✅ Complete | Capability provider/consumer flow |
| Manifest | manifest-mapping | ✅ Complete | Component → Manifest → Implementation |
| | technology-stack | ✅ Complete | Technology stack by category |
| | capability-bindings | ✅ Complete | Capability → Implementation bindings |

Progress: 15/15 fully implemented (100%) ✅ COMPLETE

`bash


Generate all diagram types

specverse gen diagram myapp.specly

Generate specific diagram type

specverse gen diagram myapp.specly -d event-flow-layered

Use different theme

specverse gen diagram myapp.specly -t dark-mode
`

$3

Zero-Tolerance Documentation Quality: Every code example in documentation is automatically validated.

- 266 Documentation Snippets Validated: All code examples must pass SpecVerse validation
- Integrated Build Process: Documentation validation runs on every build and release
- Smart Classification: Automatic detection of complete specs, fragments, and configuration files
- Comprehensive Reporting: Detailed analysis of skipped content with categorization
- Auto-Fix Capabilities: Intelligent suggestions and automatic fixes for common issues

`bash


Documentation quality assurance


npm run docs:validate-snippets # Validate all documentation code examples
npm run verify # Includes documentation validation in release process
`

$3

`bash

Comprehensive specification validation

node scripts/validate-all-specly.js

Results: ✅ 50 files validated, 98.0% pass rate (49/50)

Covers: All .specly examples + Core library files + Complete specifications

`

$3

`bash

Run complete test suite

npm test

Results: ✅ 800 tests, 100% success rate (excluding expected failures)

`

📚 Examples & Documentation

$3

Start with generated examples from specverse init, then explore:

- 01-fundamentals/ - Core concepts
- 02-profiles/ - Dynamic model composition
- 03-architecture/ - System design patterns
- 04-domains/ - Real-world applications

$3

- API Usage Guide - TypeScript/JavaScript API examples and patterns
- CLI Reference - Complete command reference

$3

Comprehensive documentation organized by purpose:

- docs/guides/ - User & developer guides (installation, development, testing, troubleshooting)
- docs/specs/ - Language specifications and architecture (view system, inference engine, registry linter)
- docs/architecture/ - System architecture (parser, code generation, inference engine, schema)
- docs/implementation-plans/ - Active implementation plans and progress tracking
- docs/plans/ - Feature and enhancement plans (view renderers, frontend scaffolding, registry linter)
- docs/migration/ - Migration guides for version upgrades (v3.5.0, v3.6.0, view system)
- docs/analysis/ - Technical analysis documents (schema extensibility, registry realization)
- docs/releases/ - Release notes and version documentation
- docs/archive/ - Historical documentation and completed work

📚 See docs/README.md for complete documentation index and navigation guide.

🛠️ Development

$3

- Node.js 18+
- TypeScript 5.3+
- npm or yarn

$3

`bash
git clone https://github.com/SpecVerse/specverse-lang.git
cd specverse-lang
npm run setup # Install all dependencies (root, parser, extension, docs)
npm run build # Build all components
`

$3

`bash
npm run dev # Build and test (full development cycle + docs validation)
npm run build # Build all components (parser, core, CLI, extension)
npm run test # Run unit and integration tests
npm run verify # Complete release validation (all tests + docs validation)
npm run docs # Generate documentation (API + diagrams)

Documentation Quality Assurance

npm run docs:validate-snippets # Validate all documentation code examples
npm run docs:validate-snippets:verbose # Detailed validation output
npm run docs:validate-snippets:fix # Auto-fix common issues
`

$3

Install the SpecVerse extension for enhanced development experience:
- Syntax highlighting for .specly files with deployment and manifest keywords
- Real-time validation and error checking
- IntelliSense for conventions, keywords, and deployment properties
- Integrated diagram preview including deployment diagrams

🌟 Real-World Impact

Specification Efficiency: Write 90% less while maintaining complete system architecture

Example Comparison:
- Traditional: 1,200+ lines of manual architecture definitions
- SpecVerse: 120 lines (.specly specification)
- AI-Inferred: Complete system architecture with full type specifications

📦 Package Information

- Package: @specverse/lang
- Latest Version: See npm package
- License: MIT
- Repository: github.com/SpecVerse/specverse-lang
- Documentation: Auto-generated in docs/ directory

🤝 Contributing

We welcome contributions! Please see our contributing guidelines and:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run the test suite (npm run release-test)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🚀 Getting Started

Ready to transform your development workflow?

`bash
npm install -g @specverse/lang
specverse init my-project
cd my-project


Edit specs/main.specly with your specification


specverse validate specs/main.specly
specverse gen all specs/main.specly
``

Experience the future of specification-driven development with SpecVerse!