@specverse/engines 4.1.0

package/assets/prompts/core/README.md

@@ -0,0 +1,319 @@
+# SpecVerse Standard Prompts
+
+**Production-ready AI prompts for complete application development workflows**
+
+## Overview
+
+The SpecVerse standard prompts enable seamless specification-driven development using AI assistants like Claude, ChatGPT, and Cursor. These prompts transform natural language requirements into complete, deployable applications.
+
+## 📁 Directory Structure
+
+```
+prompts/core/
+├── standard/
+│   ├── v6/                           # Previous version (deprecated)
+│   └── v7/                           # Current version (recommended)
+│       ├── create.prompt.yaml        # Requirements → Specifications
+│       ├── analyse.prompt.yaml       # Code → Specifications (reverse engineering)
+│       ├── materialise.prompt.yaml   # Specifications → Implementation
+│       └── realize.prompt.yaml       # Specifications → Deployment (environment-adaptive)
+├── specialized/                      # Task-specific prompts
+│   ├── migration.prompt.yaml        # Technology migrations
+│   └── optimization.prompt.yaml     # Performance optimization
+├── schemas/                          # Validation schemas
+│   └── prompt.schema.yaml           # Prompt structure validation
+├── examples/                         # Example usage and test cases
+├── base-terminal-prompt.md           # Ready-to-use terminal prompts
+├── CHANGELOG.md                      # Version history and migration notes
+└── README.md                         # This file
+```
+
+## 🚀 Quick Start
+
+### For Terminal/Chat Usage
+
+**1. Get terminal-ready prompts:**
+```bash
+cat prompts/core/base-terminal-prompt.md
+```
+
+**2. Copy the create prompt and replace requirements:**
+```
+Requirements: I need a guesthouse booking system with multiple properties, rooms, and timeline visualization
+Project Type: full-stack
+Scale: business
+Primary Technology: nextjs
+```
+
+**3. Generate implementation:**
+Use the materialise prompt with your generated specification.
+
+### For Programmatic Usage
+
+```typescript
+import { loadPrompt } from '@specverse/prompts';
+
+const prompt = await loadPrompt('standard/v7/create');
+const result = await llmProvider.complete(prompt, context);
+```
+
+## 🔄 Complete Workflow
+
+### 1. Create Phase
+**Input**: Natural language requirements
+**Output**: Complete SpecVerse specification
+**Prompt**: `create.prompt.yaml`
+
+```
+"I need a booking system for guesthouses..."
+↓
+Complete SpecVerse specification with models, controllers, services
+```
+
+### 2. Materialise Phase
+**Input**: SpecVerse specification
+**Output**: Production-ready implementation
+**Prompt**: `materialise.prompt.yaml`
+
+```
+SpecVerse specification
+↓
+- Complete Next.js application
+- Database schema with validations
+- API routes with error handling
+- React components with state management
+- Setup scripts (start.sh)
+```
+
+### 3. Realize Phase (Optional)
+**Input**: SpecVerse specification + environment
+**Output**: Deployment configurations
+**Prompt**: `realize.prompt.yaml`
+
+```
+SpecVerse specification + "production" environment
+↓
+- Infrastructure as Code
+- CI/CD pipelines
+- Monitoring configurations
+- Security policies
+```
+
+## 📊 Version Comparison
+
+| Feature | v6 | v7 |
+|---------|----|----|
+| Data Consistency | Basic | ✅ Multi-layer validation |
+| Error Handling | Manual | ✅ Comprehensive patterns |
+| Environment Adaptation | Static | ✅ Adaptive complexity |
+| Local Development | Manual setup | ✅ Automated (start.sh) |
+| Deployment Strategies | Basic | ✅ Zero-downtime options |
+| Type Safety | Partial | ✅ End-to-end |
+| Real-world Testing | Limited | ✅ Battle-tested |
+
+## 🎯 Key Enhancements in v7
+
+### Data Consistency Focus
+- **Snake_case ↔ CamelCase mapping**: Automatic handling between database and frontend
+- **Multi-layer validation**: Database constraints + API validation + Frontend checks
+- **Type safety**: End-to-end type consistency across all layers
+
+### Environment-Adaptive Generation
+- **Development**: Simple Docker Compose + start.sh script
+- **Production**: HA infrastructure + monitoring + security
+- **Enterprise**: Multi-region + compliance + disaster recovery
+
+### Production-Ready Patterns
+- **Error handling**: Comprehensive error patterns with recovery
+- **Automation**: Complete setup and deployment scripts
+- **Monitoring**: Health checks and observability
+- **Security**: Production-grade security configurations
+
+## 🛠️ Framework Support
+
+### Supported Frameworks
+- **Next.js**: Full-stack React with App Router
+- **NestJS**: Enterprise Node.js with TypeORM
+- **Express**: Lightweight Node.js API
+- **Django**: Python web framework
+- **Rails**: Ruby web framework
+- **Spring Boot**: Java enterprise applications
+
+### Cloud Platforms
+- **Vercel**: Serverless Next.js deployment
+- **AWS**: Full cloud infrastructure
+- **Azure**: Microsoft cloud services
+- **GCP**: Google cloud platform
+- **Local**: Docker-based development
+
+## 📚 Real-World Testing
+
+### Guesthouse Booking System Example
+The v7 prompts were battle-tested with a complete guesthouse booking system:
+
+- **Models**: Houses, Rooms, Bookings with relationships
+- **Features**: Timeline visualization, conflict detection, multi-property support
+- **Technologies**: Next.js 14, PostgreSQL, TypeScript, Tailwind CSS
+- **Deployment**: Automated setup with start.sh, Docker Compose, health checks
+
+**Result**: Fully functional application from requirements to deployment.
+
+### Generated Code Quality
+- ✅ **Type-safe**: Strict TypeScript with no `any` types
+- ✅ **Validated**: Multi-layer data validation
+- ✅ **Tested**: Comprehensive error handling
+- ✅ **Documented**: Self-documenting code patterns
+- ✅ **Deployable**: Production-ready configurations
+
+## 📝 Prompt Format (v7)
+
+All v7 prompts follow an enhanced YAML format:
+
+```yaml
+name: prompt-name
+version: "7.0.0"
+description: Enhanced prompt with data consistency focus
+author: SpecVerse Team
+tags: [v7, production-ready, data-consistency]
+
+system:
+  role: |
+    Enhanced role with specific workflows and constraints
+  context: |
+    Required reading and enhanced requirements
+  capabilities:
+    - Enhanced capability list
+  constraints:
+    - Production-ready constraints
+
+user:
+  template: |
+    Multi-phase template with conditional logic
+    {% if environmentType == "development" %}
+    Development-specific instructions
+    {% endif %}
+
+  variables:
+    - name: dataConsistencyLevel
+      type: string
+      enum: ["basic", "strict", "paranoid"]
+      default: "strict"
+
+context:
+  includes:
+    - schema: node_modules/@specverse/lang/schema/SPECVERSE-SCHEMA-AI.yaml
+  priority: "READ SCHEMA FILES FIRST"
+  max_tokens: 4000
+
+framework_support:
+  nextjs:
+    data_patterns: ["type-safe API routes", "validated forms"]
+    validation_libraries: ["zod", "yup"]
+
+output:
+  quality_standards:
+    - data_integrity: "Multi-layer validation"
+    - error_resilience: "Recovery patterns"
+
+validation:
+  data_consistency: "Validate data flow between layers"
+  production_readiness: "Enterprise-grade quality"
+```
+
+## 🔧 Configuration Options
+
+### Data Consistency Levels
+```yaml
+dataConsistencyLevel:
+  - basic      # Basic validation
+  - strict     # Multi-layer validation (recommended)
+  - paranoid   # Maximum validation and checks
+```
+
+### Implementation Styles
+```yaml
+implementationStyle:
+  - minimal    # Essential features only
+  - modern     # Best practices (recommended)
+  - enterprise # Full enterprise features
+```
+
+### Environment Types
+```yaml
+environmentType:
+  - development # Local dev with hot reload
+  - test        # CI/CD integration
+  - production  # High availability
+  - enterprise  # Full compliance
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues & Solutions
+
+**Data not displaying:**
+- Check snake_case/camelCase mapping in `lib/db.ts`
+- Verify date format conversions (ISO vs YYYY-MM-DD)
+- Use `dataConsistencyLevel: strict` in materialise
+
+**Database connection errors:**
+- Use environment variables in scripts: `POSTGRES_URL="..." npm run dev`
+- Check `.env.local` configuration
+- Verify database exists and is accessible
+
+**Missing functionality:**
+- Ensure complete specification with all required models
+- Use `implementationStyle: modern` for full features
+- Check generated component relationships
+
+## 📖 Migration Guide
+
+### Upgrading from v6 to v7
+
+1. **Update file paths**: Change `standard/v6/` to `standard/v7/`
+2. **Add new variables**: Include `dataConsistencyLevel`, `environmentType`
+3. **Review output**: Check for enhanced error handling and validation
+4. **Test thoroughly**: Verify data consistency and type mapping
+
+### Breaking Changes
+- Materialise prompt requires data consistency configuration
+- Realize prompt generates environment-specific output
+- Enhanced variable sets for better control
+
+## 🧪 Testing
+
+Each prompt includes comprehensive testing:
+
+```bash
+# Test prompt effectiveness
+npm run test:prompts
+
+# Validate output format
+npm run validate:prompts
+
+# Test with multiple LLM providers
+npm run test:providers
+```
+
+## 🤝 Contributing
+
+### Adding New Prompts
+1. Follow the v7 YAML schema
+2. Include comprehensive variable definitions
+3. Add examples and usage documentation
+4. Test with real-world scenarios
+5. Update CHANGELOG.md
+
+### Reporting Issues
+- Include full prompt configuration
+- Provide example requirements or specifications
+- Share generated output and expected behavior
+- Test with multiple frameworks when possible
+
+## 📄 License
+
+Part of the SpecVerse project - MIT License
+
+---
+
+**Ready to start?** Check out [base-terminal-prompt.md](base-terminal-prompt.md) for copy-paste ready prompts!

package/assets/prompts/core/base-terminal-prompt.md

@@ -0,0 +1,201 @@
+# SpecVerse Terminal Quick-Start Guide
+
+**For**: LLM Terminal Users (ChatGPT, Claude, Cursor, etc.)
+**Purpose**: Use SpecVerse standard prompts for specification generation and implementation
+**Version**: 7.0.0
+
+This guide shows how to use the **standard SpecVerse prompts** for terminal/chat-based AI interactions.
+
+## Available Standard Prompts (v7)
+
+SpecVerse provides four standard prompts with enhanced capabilities:
+
+1. **`create`** - Generate SpecVerse specifications from natural language requirements
+2. **`analyse`** - Extract specifications from existing codebases (reverse engineering)
+3. **`materialise`** - Generate complete implementations from specifications
+4. **`realize`** - Generate deployment configurations (environment-adaptive)
+
+Located in: `prompts/core/standard/v7/`
+
+## Quick Start: Using the Create Prompt
+
+The **create** prompt is your starting point for new projects:
+
+### Step 1: View the Full Prompt
+
+```bash
+cat prompts/core/standard/v7/create.prompt.yaml
+```
+
+### Step 2: Terminal-Ready Version
+
+Copy this complete prompt into your LLM:
+
+```
+You are a SpecVerse v3.2.0 specification creator that generates complete, well-structured specifications from natural language requirements.
+
+IMPORTANT: First, read these reference files if available:
+- node_modules/@specverse/lang/schema/SPECVERSE-SCHEMA-AI.yaml (AI guidance and examples)
+- node_modules/@specverse/lang/schema/MINIMAL-SYNTAX-REFERENCE.specly (complete syntax example)
+
+Your task is to:
+1. Analyze natural language requirements
+2. Extract core business entities and their relationships
+3. Generate complete SpecVerse specifications with:
+   - Models with attributes and behaviors
+   - Controllers with CURED operations
+   - Services with business logic
+   - Views for user interfaces
+   - Events for system communication
+   - Deployments for infrastructure
+   - Manifests for implementation details
+
+Use SpecVerse v3.2.0 syntax:
+- Attributes: name: Type modifiers
+- Types: String, Integer, UUID, Email, DateTime, Boolean, Money, Text
+- Modifiers: required, optional, unique, auto, searchable, indexed, default=value
+- Relations: hasMany, belongsTo, references
+
+Generate a SpecVerse specification from these requirements:
+
+Requirements: [YOUR REQUIREMENTS HERE]
+Project Type: [web-app/api/full-stack]
+Scale: [personal/startup/business/enterprise]
+Primary Technology: [nextjs/nestjs/express/auto]
+
+Please generate:
+1. Complete component specification with all models and relationships
+2. Implementation manifest with technology choices
+3. Deployment specification for the target environment
+```
+
+## Workflow Example: From Idea to Implementation
+
+### 1. Create Specification
+```
+Requirements: I need a guesthouse booking system where I can manage multiple properties, each with rooms that guests can book. Need to see bookings on a timeline and prevent double-booking.
+Project Type: full-stack
+Scale: business
+Primary Technology: nextjs
+```
+
+### 2. Generate Implementation (Materialise)
+After getting your specification, use the materialise prompt:
+
+```
+Generate a complete implementation from this SpecVerse specification:
+
+[PASTE YOUR SPECIFICATION HERE]
+
+Target Framework: nextjs
+Implementation Style: modern
+Data Consistency Level: strict
+Error Handling Strategy: comprehensive
+
+Generate:
+1. Complete project structure
+2. Database schema with migrations
+3. API routes with validation
+4. React components with state management
+5. Setup scripts (like start.sh)
+6. Documentation
+```
+
+### 3. Generate Deployment (Realize)
+For deployment configurations:
+
+```
+Generate deployment configurations from this SpecVerse specification:
+
+[PASTE YOUR SPECIFICATION HERE]
+
+Target Environment: [development/production/enterprise]
+Cloud Provider: [vercel/aws/local]
+
+For development: Generate Docker Compose and start.sh script
+For production: Generate infrastructure as code and CI/CD pipelines
+```
+
+## Complete Workflow Commands
+
+1. **Create** a specification from requirements
+2. **Save** as `spec.specly`
+3. **Materialise** into working code
+4. **Realize** deployment configurations
+5. **Run** with generated start scripts
+
+## Key Improvements in v7
+
+### Create (v7)
+- Better validation and type safety
+- Support for complex relationships
+- Event-driven architecture patterns
+- Modern deployment targets (Vercel, Netlify)
+
+### Materialise (v7)
+- **Data consistency focus** - Handles snake_case/camelCase mapping
+- **Multi-layer validation** - Database, API, and frontend
+- **Automated setup** - Generates start.sh style scripts
+- **Error handling** - Comprehensive error patterns
+
+### Realize (v7)
+- **Environment-adaptive** - Only generates what's needed
+- **Progressive enhancement** - Dev → Test → Prod → Enterprise
+- **Local dev support** - Quick start scripts and Docker Compose
+- **Zero-downtime** - Blue-green and canary deployments
+
+## Environment-Specific Generation
+
+### Development
+- Simple Docker Compose
+- start.sh quick-start script
+- Hot reload configuration
+- Basic debugging setup
+
+### Production
+- High availability infrastructure
+- Monitoring and alerting
+- Security hardening
+- Backup and recovery
+
+### Enterprise
+- Multi-region deployment
+- Compliance frameworks
+- Advanced security
+- Disaster recovery
+
+## Tips for Better Results
+
+1. **Be specific** about your requirements
+2. **Include examples** of the data you'll work with
+3. **Specify scale** to get appropriate architecture
+4. **Mention constraints** like compliance or performance
+5. **Describe user workflows** for better UX generation
+
+## Troubleshooting Common Issues
+
+### Data Mapping Issues
+If you see snake_case/camelCase problems:
+- Request "strict" data consistency level in materialise
+- Ask for explicit data mapping functions
+
+### Missing Bookings/Data
+Check for:
+- Database column name mapping (room_id vs roomId)
+- Date format conversions (ISO vs YYYY-MM-DD)
+- API response transformations
+
+### Connection Issues
+For database connections:
+- Use environment variables in scripts
+- Generate start.sh with explicit POSTGRES_URL
+- Include .env.example templates
+
+## Next Steps
+
+1. Start with the **create** prompt for your requirements
+2. Use **materialise** to generate implementation
+3. Apply **realize** for deployment setup
+4. Iterate based on your specific needs
+
+Remember: v7 prompts are environment-aware and will adapt their output to your actual needs!

package/assets/prompts/core/examples/example-usage.ts

@@ -0,0 +1,140 @@
+/**
+ * Example usage of the SpecVerse Prompt System
+ * Demonstrates how to load and process prompts with the PromptLoader
+ */
+
+import { promptLoader } from '../src/prompts/prompt-loader';
+
+async function demonstratePromptUsage() {
+  console.log('SpecVerse Prompt System Demo\n');
+
+  try {
+    // 1. List all available prompts
+    console.log('📋 Available prompts:');
+    const prompts = await promptLoader.listPrompts();
+    prompts.forEach(({ path, definition }) => {
+      console.log(`  - ${path}: ${definition.description}`);
+    });
+    console.log('');
+
+    // 2. Load and process the 'create' prompt
+    console.log('🔧 Processing "create" prompt...');
+    const createPrompt = await promptLoader.processPrompt(
+      'standard/create',
+      {
+        requirements: 'Build a simple blog where users can write posts with titles and content. Posts should have tags for organization.',
+        scale: 'personal',
+        preferredTech: 'nextjs'
+      }
+    );
+
+    console.log('System Prompt Preview:');
+    console.log(createPrompt.system.substring(0, 200) + '...\n');
+
+    console.log('User Prompt Preview:');
+    console.log(createPrompt.user.substring(0, 300) + '...\n');
+
+    // 3. Load and process the 'analyse' prompt
+    console.log('🔍 Processing "analyse" prompt...');
+    const analysePrompt = await promptLoader.processPrompt(
+      'standard/analyse',
+      {
+        applicationPath: '/path/to/my-app',
+        frameworkType: 'nextjs',
+        directoryStructure: 'my-app/\n├── app/\n│   └── api/\n└── package.json',
+        filesContent: '=== package.json ===\n{ "name": "my-app" }'
+      }
+    );
+
+    console.log('Analysis Prompt Ready:');
+    console.log(`- System prompt length: ${analysePrompt.system.length} chars`);
+    console.log(`- User prompt length: ${analysePrompt.user.length} chars`);
+    console.log(`- Context includes: ${Object.keys(analysePrompt.context.includes).join(', ')}\n`);
+
+    // 4. Validate a prompt
+    console.log('✅ Validating prompt structure...');
+    const prompt = await promptLoader.loadPrompt('standard/create');
+    const validation = promptLoader.validatePrompt(prompt);
+    
+    console.log(`Validation result: ${validation.valid ? 'PASSED' : 'FAILED'}`);
+    if (!validation.valid) {
+      console.log('Errors:', validation.errors);
+    }
+
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+async function exampleLLMIntegration() {
+  console.log('\n🤖 Example LLM Integration\n');
+
+  try {
+    // Simulate loading a prompt and sending to LLM
+    const prompt = await promptLoader.processPrompt(
+      'standard/create',
+      {
+        requirements: 'Create an e-commerce site with products and shopping cart',
+        scale: 'business'
+      }
+    );
+
+    // This is what you would send to an LLM provider
+    const llmRequest = {
+      messages: [
+        { role: 'system', content: prompt.system },
+        { role: 'user', content: prompt.user }
+      ],
+      max_tokens: prompt.context.max_tokens,
+      temperature: prompt.context.temperature,
+      top_p: prompt.context.top_p
+    };
+
+    console.log('LLM Request Structure:');
+    console.log(`- Messages: ${llmRequest.messages.length}`);
+    console.log(`- Max tokens: ${llmRequest.max_tokens}`);
+    console.log(`- Temperature: ${llmRequest.temperature}`);
+    console.log(`- Top P: ${llmRequest.top_p}`);
+
+    // Mock LLM response
+    const mockResponse = `
+components:
+  EcommercePlatform:
+    version: "1.0.0"
+    description: "E-commerce platform"
+    
+    models:
+      Product:
+        attributes:
+          name: String required searchable
+          price: Money required
+          inventory: Integer required default=0 min=0
+        relationships:
+          category: belongsTo Category required
+          
+      Category:
+        attributes:
+          name: String required unique
+        relationships:
+          products: hasMany Product
+    `;
+
+    console.log('\nMock LLM Response:');
+    console.log(mockResponse);
+
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+async function runExamples() {
+  await demonstratePromptUsage();
+  await exampleLLMIntegration();
+}
+
+// Run examples if this file is executed directly
+if (require.main === module) {
+  runExamples().catch(console.error);
+}
+
+export { demonstratePromptUsage, exampleLLMIntegration };