@specverse/engines 4.1.0

package/assets/prompts/core/CHANGELOG.md

@@ -0,0 +1,158 @@
+# SpecVerse Standard Prompts - Changelog
+
+## Version 7.0.0 (2025-01-XX)
+
+### 🚀 Major Enhancements
+
+#### Enhanced Data Consistency & Validation
+- **Data mapping fixes**: Comprehensive snake_case ↔ camelCase handling
+- **Multi-layer validation**: Database, API, and frontend validation patterns
+- **Type safety**: End-to-end type consistency across all layers
+- **Conflict detection**: Database-level conflict resolution functions
+
+#### Environment-Adaptive Generation
+- **Adaptive complexity**: Output scales based on target environment
+- **Progressive enhancement**: Dev → Test → Prod → Enterprise scaling
+- **Local dev focus**: Quick start scripts (start.sh) and Docker Compose
+- **Production readiness**: Zero-downtime deployments and monitoring
+
+#### Enhanced Automation
+- **Automated setup**: Complete database initialization and seeding
+- **Deployment scripts**: Environment-specific automation
+- **Health checks**: Comprehensive monitoring and debugging
+- **Error handling**: Robust error patterns with recovery
+
+### 📝 Prompt Updates
+
+#### `materialise.prompt.yaml` v7.0.0
+**NEW FEATURES:**
+- Data consistency level configuration (`strict`, `basic`, `paranoid`)
+- Multi-layer validation strategy options
+- Comprehensive error handling patterns
+- Automated setup script generation (start.sh style)
+- Database-level constraint and validation functions
+
+**BREAKING CHANGES:**
+- Now requires specification analysis phase before implementation
+- Enhanced variable set with data consistency options
+- Comprehensive quality standards for production readiness
+
+#### `realize.prompt.yaml` v7.0.0
+**NEW FEATURES:**
+- Environment-adaptive generation (development/test/production/enterprise)
+- Progressive complexity scaling based on environment needs
+- Local development environment support with Docker Compose
+- Zero-downtime deployment strategies (blue-green, canary)
+- Comprehensive monitoring and observability configurations
+
+**BREAKING CHANGES:**
+- Environment-specific output (no more one-size-fits-all)
+- New variables: `deploymentStrategy`, `databaseStrategy`, `localDevSupport`
+- Conditional template logic based on environment type
+
+#### Updated `base-terminal-prompt.md`
+**NEW FEATURES:**
+- Complete workflow examples using real guesthouse system
+- Troubleshooting section with actual issues and solutions
+- Environment-specific guidance
+- v7 prompt paths and syntax updates
+
+### 🛠️ Technical Improvements
+
+#### Quality Standards
+- **Data integrity**: Multi-layer validation with database constraints
+- **Error resilience**: Graceful degradation and recovery patterns
+- **Type mapping**: Consistent data types across boundaries
+- **Performance**: Optimized queries with proper indexing
+- **Security**: Production-grade security patterns
+
+#### Framework Support
+- **Enhanced Next.js**: Type-safe API routes, validated forms
+- **NestJS**: DTOs with class-validator, TypeORM patterns
+- **Express**: Middleware validation, centralized error handling
+- **Modern platforms**: Vercel, Netlify, serverless support
+
+### 📚 Documentation Updates
+
+#### New Guides
+- **Complete workflow**: Requirements → Specification → Implementation → Deployment
+- **Troubleshooting**: Real-world issues and solutions
+- **Best practices**: Environment-specific development patterns
+- **Migration guide**: v6 → v7 upgrade path
+
+#### Enhanced Examples
+- **Guesthouse booking system**: Complete working example
+- **Data consistency patterns**: snake_case/camelCase mapping
+- **Error handling**: Comprehensive error scenarios
+- **Environment scaling**: Dev/Prod configuration differences
+
+### 🔄 Migration from v6
+
+#### Breaking Changes
+1. **Materialise prompt**: New data consistency variables required
+2. **Realize prompt**: Environment-specific template logic
+3. **File paths**: Updated to `prompts/core/standard/v7/`
+
+#### Upgrade Steps
+1. Update prompt file paths to v7 directory
+2. Add new variables for data consistency and environment type
+3. Review generated output for enhanced error handling
+4. Test environment-adaptive deployment configurations
+
+### 🐛 Bug Fixes from Real Implementation
+
+#### Data Layer Issues (Fixed in v7)
+- **Fixed**: Database column mapping (room_id vs roomId)
+- **Fixed**: Date format conversion (ISO strings vs YYYY-MM-DD)
+- **Fixed**: API response transformation consistency
+- **Fixed**: Missing data validation at model boundaries
+
+#### Deployment Issues (Fixed in v7)
+- **Fixed**: Environment variable loading in setup scripts
+- **Fixed**: Database connection handling in development
+- **Fixed**: Missing health checks and monitoring
+- **Fixed**: Over-engineering for simple development environments
+
+#### Developer Experience (Enhanced in v7)
+- **Added**: Quick start scripts (start.sh) for immediate productivity
+- **Added**: Comprehensive error messages and debugging
+- **Added**: Environment-specific documentation
+- **Added**: Real troubleshooting scenarios
+
+### 🎯 Key Lessons Learned
+
+1. **Data consistency is critical**: v7 emphasizes proper data mapping
+2. **Environment matters**: Different environments need different complexity
+3. **Automation saves time**: Setup scripts reduce friction significantly
+4. **Error handling is essential**: Comprehensive patterns prevent issues
+5. **Local dev parity**: Development should match production patterns
+
+### 🚀 What's Next
+
+- Integration with SpecVerse inference engine v3.2.0
+- Enhanced cloud platform support (AWS, Azure, GCP)
+- Advanced monitoring and observability patterns
+- AI-powered troubleshooting assistance
+- Community-contributed prompt extensions
+
+---
+
+## Version 6.0.0 (Previous Release)
+
+### Features
+- Streamlined prompt system with YAML configuration
+- Basic framework support (Next.js, NestJS, Express)
+- Infrastructure as Code generation
+- CI/CD pipeline templates
+- Security and compliance configurations
+
+### Known Issues (Resolved in v7)
+- Data mapping inconsistencies
+- Over-engineered development environments
+- Limited error handling patterns
+- Manual setup processes
+- Environment-agnostic generation
+
+---
+
+*For complete documentation, see [base-terminal-prompt.md](base-terminal-prompt.md)*

package/assets/prompts/core/MIGRATION-v6-to-v7.md

@@ -0,0 +1,379 @@
+# Migration Guide: SpecVerse Prompts v6 → v7
+
+**Upgrade your AI workflows to the enhanced v7 prompts with data consistency and environment-adaptive generation**
+
+## 🎯 Overview
+
+SpecVerse v7 prompts represent a major upgrade focused on:
+- **Data consistency**: Multi-layer validation and type mapping
+- **Environment adaptation**: Output that scales with your needs
+- **Production readiness**: Battle-tested patterns and automation
+- **Real-world reliability**: Based on actual implementation experience
+
+## 📊 What's New in v7
+
+### Key Enhancements
+
+| Area | v6 | v7 |
+|------|----|----|
+| **Data Handling** | Basic column mapping | ✅ Snake_case ↔ CamelCase automation |
+| **Validation** | Client-side only | ✅ Database + API + Frontend |
+| **Error Handling** | Manual patterns | ✅ Comprehensive recovery patterns |
+| **Environments** | One-size-fits-all | ✅ Adaptive (dev/test/prod/enterprise) |
+| **Setup** | Manual configuration | ✅ Automated scripts (start.sh) |
+| **Testing** | Limited examples | ✅ Battle-tested with real applications |
+
+### New Features
+- **Database-level validation functions** for conflict detection
+- **Environment-aware deployment** configurations
+- **Comprehensive error handling** with recovery patterns
+- **Automated setup scripts** for instant productivity
+- **Multi-layer type safety** across all application layers
+
+## 🔄 Migration Steps
+
+### Step 1: Update File Paths
+
+**Before (v6):**
+```bash
+prompts/core/standard/v6/create.prompt.yaml
+prompts/core/standard/v6/materialise.prompt.yaml
+prompts/core/standard/v6/realize.prompt.yaml
+```
+
+**After (v7):**
+```bash
+prompts/core/standard/v7/create.prompt.yaml
+prompts/core/standard/v7/materialise.prompt.yaml
+prompts/core/standard/v7/realize.prompt.yaml
+```
+
+### Step 2: Update Variable Sets
+
+#### Materialise Prompt Variables
+
+**v6 Variables:**
+```yaml
+specificationFile: "spec.specly"
+targetFramework: "nextjs"
+implementationStyle: "modern"
+developmentEnvironment: "local"
+```
+
+**v7 Variables (Enhanced):**
+```yaml
+specificationFile: "spec.specly"
+targetFramework: "nextjs"
+implementationStyle: "modern"
+developmentEnvironment: "local"
+# NEW in v7:
+dataConsistencyLevel: "strict"          # basic/strict/paranoid
+errorHandlingStrategy: "comprehensive"  # minimal/standard/comprehensive
+validationDepth: "multi-layer"         # client-only/api-level/multi-layer/database-enforced
+setupAutomation: "full"                # manual/semi-automated/full
+```
+
+#### Realize Prompt Variables
+
+**v6 Variables:**
+```yaml
+cloudProvider: "aws"
+environmentType: "production"
+scaleRequirements: "standard"
+```
+
+**v7 Variables (Enhanced):**
+```yaml
+cloudProvider: "vercel"                 # Added vercel, netlify, local
+environmentType: "production"           # Now drives output complexity
+scaleRequirements: "auto"              # auto adjusts based on environment
+# NEW in v7:
+deploymentStrategy: "rolling"          # rolling/blue-green/canary/recreate
+databaseStrategy: "managed"            # managed/self-hosted/serverless/local
+localDevSupport: "full"               # none/basic/full
+automationLevel: "comprehensive"       # manual/basic/comprehensive
+```
+
+### Step 3: Update Prompt Templates
+
+#### Terminal Usage
+
+**v6 Terminal Prompt:**
+```
+Generate a complete implementation from this SpecVerse specification:
+
+[SPECIFICATION]
+
+Target Framework: nextjs
+Implementation Style: modern
+
+Please generate complete project structure and code.
+```
+
+**v7 Terminal Prompt (Enhanced):**
+```
+Generate a complete implementation from this SpecVerse specification:
+
+[SPECIFICATION]
+
+Target Framework: nextjs
+Implementation Style: modern
+Data Consistency Level: strict
+Error Handling Strategy: comprehensive
+Validation Depth: multi-layer
+Setup Automation: full
+
+Generate:
+1. Complete project structure with automated setup
+2. Database schema with multi-layer validation
+3. API routes with comprehensive error handling
+4. React components with type-safe data handling
+5. Setup scripts (start.sh) for instant development
+6. Production-ready configurations
+```
+
+### Step 4: Review Generated Output
+
+#### Enhanced Database Layer
+
+**v7 Generates:**
+```typescript
+// Enhanced with type mapping
+export async function getBookings(): Promise<Booking[]> {
+  const result = await query('SELECT * FROM bookings ORDER BY check_in')
+  // v7: Automatic snake_case to camelCase mapping
+  return result.rows.map(row => ({
+    id: row.id,
+    roomId: row.room_id,           // ← Automatic mapping
+    guestName: row.guest_name,     // ← Automatic mapping
+    checkIn: row.check_in,         // ← Automatic mapping
+    checkOut: row.check_out,       // ← Automatic mapping
+    notes: row.notes,
+    createdAt: row.created_at
+  }))
+}
+```
+
+#### Enhanced Error Handling
+
+**v7 Generates:**
+```typescript
+// Comprehensive error handling with recovery
+try {
+  const bookings = await getBookings()
+  return NextResponse.json(bookings)
+} catch (error) {
+  console.error('Error fetching bookings:', error)
+
+  // v7: Detailed error classification and recovery
+  if (error.code === 'ECONNREFUSED') {
+    return NextResponse.json(
+      { error: 'Database connection failed', retry: true },
+      { status: 503 }
+    )
+  }
+
+  return NextResponse.json(
+    { error: 'Internal server error', details: error.message },
+    { status: 500 }
+  )
+}
+```
+
+#### Environment-Adaptive Deployment
+
+**v7 Development Environment:**
+```yaml
+# Simple Docker Compose for development
+version: '3.8'
+services:
+  postgres:
+    image: postgres:15
+    environment:
+      POSTGRES_DB: guesthouse_dev
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    ports:
+      - "5432:5432"
+
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    depends_on:
+      - postgres
+```
+
+**v7 Production Environment:**
+```yaml
+# Full infrastructure with monitoring
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: guesthouse-app
+spec:
+  replicas: 3
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxUnavailable: 1
+      maxSurge: 1
+  template:
+    spec:
+      containers:
+      - name: app
+        image: guesthouse:latest
+        ports:
+        - containerPort: 3000
+        livenessProbe:
+          httpGet:
+            path: /api/health
+            port: 3000
+        readinessProbe:
+          httpGet:
+            path: /api/ready
+            port: 3000
+```
+
+## ⚠️ Breaking Changes
+
+### 1. Materialise Prompt Structure
+
+**Breaking Change:** Multi-phase template with data analysis
+```yaml
+# v7 requires analysis phase before implementation
+## PHASE 1: DATA ANALYSIS
+Analyze the specification for:
+- Data models and their relationships
+- Validation rules and constraints
+- Potential conflict scenarios
+
+## PHASE 2: IMPLEMENTATION GENERATION
+Generate implementation with data consistency focus
+```
+
+### 2. Realize Prompt Environment Logic
+
+**Breaking Change:** Conditional template based on environment
+```yaml
+# v7 uses conditional logic
+{% if environmentType == "development" %}
+Generate simple Docker Compose setup
+{% elif environmentType == "production" %}
+Generate production infrastructure
+{% endif %}
+```
+
+### 3. Enhanced Variable Requirements
+
+**Breaking Change:** New required variables for consistency
+- `dataConsistencyLevel` - Controls validation depth
+- `errorHandlingStrategy` - Defines error handling approach
+- `environmentType` - Drives output complexity
+
+## 🛠️ Troubleshooting Common Migration Issues
+
+### Issue: Data Not Displaying After Migration
+
+**Symptoms:**
+- API returns data but frontend shows empty
+- Database queries work but components don't render
+
+**v7 Solution:**
+```yaml
+# Use strict data consistency in materialise
+dataConsistencyLevel: "strict"
+validationDepth: "multi-layer"
+```
+
+**Result:** Automatic snake_case/camelCase mapping generated
+
+### Issue: Over-Engineered Development Environment
+
+**Symptoms:**
+- Complex infrastructure for local development
+- Unnecessary monitoring and compliance features
+
+**v7 Solution:**
+```yaml
+# Use development environment type
+environmentType: "development"
+localDevSupport: "full"
+```
+
+**Result:** Simple Docker Compose + start.sh script
+
+### Issue: Missing Error Handling
+
+**Symptoms:**
+- Application crashes on errors
+- No recovery mechanisms
+- Poor error messages
+
+**v7 Solution:**
+```yaml
+# Use comprehensive error handling
+errorHandlingStrategy: "comprehensive"
+```
+
+**Result:** Complete error handling with recovery patterns
+
+## ✅ Validation Checklist
+
+After migration, verify:
+
+- [ ] **File paths updated** to v7 directories
+- [ ] **New variables added** for data consistency and environment
+- [ ] **Generated code includes** type mapping functions
+- [ ] **Error handling is comprehensive** with recovery patterns
+- [ ] **Setup scripts work** (start.sh can launch application)
+- [ ] **Environment-appropriate complexity** (dev ≠ prod features)
+- [ ] **Database validation** functions are generated
+- [ ] **Multi-layer validation** across all boundaries
+
+## 📚 Learning Resources
+
+### Example Migration
+
+See the complete guesthouse booking system example that validated v7:
+- **Before**: Manual setup, data mapping issues, basic error handling
+- **After**: Automated setup, consistent data flow, comprehensive error handling
+
+### Key Files to Review
+
+1. **`lib/db.ts`** - Data mapping functions
+2. **`start.sh`** - Automated setup script
+3. **`schema.sql`** - Database constraints and functions
+4. **API routes** - Error handling patterns
+5. **Components** - Type-safe data handling
+
+## 🎯 Best Practices for v7
+
+### 1. Choose Appropriate Data Consistency
+- **Basic**: Simple applications, minimal validation
+- **Strict**: Business applications (recommended)
+- **Paranoid**: Financial/healthcare applications
+
+### 2. Environment-Specific Configuration
+- **Development**: Focus on speed and debugging
+- **Production**: Include monitoring and security
+- **Enterprise**: Full compliance and disaster recovery
+
+### 3. Gradual Migration Strategy
+1. Start with development environment
+2. Validate data consistency patterns
+3. Test error handling scenarios
+4. Migrate production configurations
+5. Update team documentation
+
+## 🚀 Next Steps
+
+1. **Update your prompts** to v7 syntax
+2. **Test with a small project** to validate migration
+3. **Review generated code** for quality improvements
+4. **Update team documentation** with v7 patterns
+5. **Enjoy enhanced productivity** with automated setup!
+
+---
+
+**Need help?** Check the [troubleshooting section](README.md#troubleshooting) in the main README or review the [CHANGELOG](CHANGELOG.md) for detailed changes.