@specverse/engines 4.1.0

package/assets/prompts/core/standard/archive/v3/README.md

@@ -0,0 +1,279 @@
+# SpecVerse Core Prompts v3.0
+
+## Three-Layer Architecture
+
+Version 3.0 introduces a fundamental architectural improvement: **complete separation of concerns through three distinct specification layers**. This addresses the critical gap identified in v2 where implementation details were conflated with logical architecture.
+
+### The Three Layers
+
+#### 1. Component Specification (WHAT)
+**File**: `.specly`
+**Purpose**: Defines the logical architecture - what the system does
+**Contains**:
+- Models with attributes and relationships
+  - Supports array types: `String[]`, `Integer[]`, `Boolean[]` etc.
+- Controllers with CURED operations
+- Services with business operations
+- Behaviors with **detailed algorithmic steps**
+- Events and their payloads
+- Views and UI structure
+
+#### 2. Manifest Specification (HOW)
+**File**: `.yaml`
+**Purpose**: Defines implementation details - how to build the system
+**Contains**:
+- Technology stack selections
+- Database schema mappings
+- API patterns and formats
+- File structure and organization
+- Implementation-specific algorithms (SQL queries, etc.)
+- Error handling patterns
+- External service integrations
+
+#### 3. Deployment Specification (WHERE)
+**File**: `.specly` (deployments section)
+**Purpose**: Defines runtime topology - where and how the system runs
+**Contains**:
+- Runtime instances configuration
+- Environment-specific settings
+- Scaling parameters
+- Infrastructure components
+- Monitoring and logging setup
+
+## Prompt Improvements in v3
+
+### Key Innovation: Behavior Steps as Implementation Guide
+
+The most significant improvement in v3 is the use of **behavior steps** as a bridge between logical design and technical implementation:
+
+```yaml
+# In Component Spec (WHAT):
+behaviors:
+  checkBookingConflict:
+    steps:
+      - "Query bookings for same room"
+      - "Check if new.check_in < existing.check_out"
+      - "Check if new.check_out > existing.check_in"
+      - "Return true if both conditions match"
+
+# In Manifest (HOW):
+business_logic_implementation:
+  booking_conflict_detection:
+    sql: "SELECT * FROM bookings WHERE room_id = $1 AND check_in < $3 AND check_out > $2"
+
+# In Generated Code:
+async function checkBookingConflict(roomId, checkIn, checkOut) {
+  // Step 1: Query bookings for same room
+  const result = await db.query(
+    // Step 2 & 3: Check if dates overlap (from manifest SQL)
+    'SELECT * FROM bookings WHERE room_id = $1 AND check_in < $3 AND check_out > $2',
+    [roomId, checkIn, checkOut]
+  );
+
+  // Step 4: Return true if both conditions match
+  return result.rows.length > 0;
+}
+```
+
+## Prompt Usage Guide
+
+### 1. `analyse.prompt.yaml` - Extract from Existing Code
+
+**Purpose**: Reverse-engineer existing applications into three-layer specifications
+
+**Workflow**:
+```
+Existing Code → analyse → Component + Manifest + Deployment Specs
+```
+
+**Key Features**:
+- Extracts actual algorithms into behavior steps
+- Captures SQL queries and technical patterns in manifest
+- Preserves existing technology choices
+- Documents actual implementation details
+
+### 2. `create.prompt.yaml` - Generate from Requirements
+
+**Purpose**: Create new specifications from natural language requirements
+
+**Workflow**:
+```
+Requirements → create → Component + Manifest + Deployment Specs
+```
+
+**Key Features**:
+- Generates detailed behavior steps for business logic
+- Recommends appropriate technology stack in manifest
+- Scales architecture to requirements (personal/business/enterprise)
+- Includes implementation guidance
+
+### 3. `materialise.prompt.yaml` - Clean Implementation from Extracted Specs
+
+**Purpose**: Generate fresh implementation from extracted specs for comparison
+
+**Workflow**:
+```
+Extracted Specs → materialise → Clean Implementation + Comparison Report
+```
+
+**Key Features**:
+- Uses behavior steps as implementation blueprint
+- Follows manifest patterns exactly
+- Generates comparison report with original
+- Identifies technical debt and improvements
+
+### 4. `realize.prompt.yaml` - Full Implementation from Created Specs
+
+**Purpose**: Generate complete application from created specifications
+
+**Workflow**:
+```
+Created Specs → realize → Complete Application + Documentation
+```
+
+**Key Features**:
+- Generates manifest if not provided
+- Transforms behavior steps into commented code
+- Creates full application scaffolding
+- Includes tests based on behavior specs
+
+## Migration from v2
+
+### For Existing v2 Users
+
+The main changes when migrating from v2 to v3:
+
+1. **Behavior Steps are Required**: All behaviors, operations, and actions must include detailed `steps` arrays
+2. **Manifest is Mandatory**: Technical details must be in a separate manifest, not mixed with components
+3. **Clear Layer Separation**: Keep logical, technical, and operational concerns strictly separated
+
+### Breaking Changes
+
+- Component specs no longer contain technical implementation details
+- Manifests are now required (not optional)
+- Behavior steps must be detailed algorithms, not high-level descriptions
+
+## Examples
+
+### Complete Three-Layer Specification
+
+```yaml
+# component.specly
+components:
+  MySystem:
+    models:
+      User:
+        attributes:
+          email: Email required unique
+          roles: String[] optional
+          tags: String[] optional
+        behaviors:
+          authenticate:
+            steps:
+              - "Hash provided password"
+              - "Query user by email"
+              - "Compare hashed passwords"
+              - "Generate JWT if match"
+              - "Return token or error"
+
+# manifest.yaml
+manifest:
+  technology_stack:
+    backend:
+      framework: "Express"
+      auth: "JWT with bcrypt"
+
+  business_logic_implementation:
+    password_hashing:
+      algorithm: "bcrypt"
+      rounds: 10
+    token_generation:
+      secret: "from environment"
+      expiry: "24h"
+
+# deployment in component.specly
+deployments:
+  production:
+    instances:
+      controllers:
+        apiServer:
+          component: "MySystem"
+          scale: 3
+```
+
+## Best Practices
+
+### 1. Writing Behavior Steps
+
+**Good**:
+```yaml
+steps:
+  - "Query database for user with email"
+  - "If user not found, return error 404"
+  - "Compare provided password with stored hash"
+  - "If passwords don't match, return error 401"
+  - "Generate JWT with user ID and roles"
+  - "Return token with 200 status"
+```
+
+**Bad**:
+```yaml
+steps:
+  - "Authenticate user"
+  - "Return result"
+```
+
+### 2. Manifest Completeness
+
+Always include in manifests:
+- Complete technology stack
+- Database schema mappings
+- API response formats
+- Error handling patterns
+- File structure organization
+- Environment configurations
+
+### 3. Layer Separation
+
+**Component**: Business logic only (no SQL, no framework specifics)
+**Manifest**: All technical details (SQL, frameworks, libraries)
+**Deployment**: Runtime only (scaling, monitoring, infrastructure)
+
+## Validation
+
+All v3 prompts include validation to ensure:
+
+1. **Component specs** validate against SpecVerse v3.1 schema
+2. **Manifests** include all required sections
+3. **Behavior steps** are detailed and actionable
+4. **Generated code** traces back to specification steps
+
+## Performance Considerations
+
+v3 prompts are configured for:
+- **Higher token limits** (12000-15000) to handle three layers
+- **Lower temperature** (0.2-0.4) for consistent generation
+- **Structured outputs** for reliable parsing
+
+## Future Roadmap
+
+Planned improvements for v3.x:
+- Automated manifest library management
+- Behavior step validation and linting
+- Cross-layer consistency checking
+- Test generation from behavior specs
+- Migration path automation from v2
+
+## Support
+
+For issues or questions about v3 prompts:
+- Review examples in each prompt file
+- Check validation errors carefully
+- Ensure proper layer separation
+- Verify behavior steps are detailed
+
+## Version History
+
+- **v3.0.0** (2024-01-XX): Three-layer architecture, behavior steps as code
+- **v2.0.0** (2024-01-01): Consolidated prompts, reference-based
+- **v1.0.0** (2023-12-01): Initial prompt structure

package/assets/prompts/core/standard/archive/v3/analyse.prompt.yaml

@@ -0,0 +1,309 @@
+name: analyse
+version: "3.0.0"
+description: Extract complete SpecVerse specifications from existing application code with three-layer architecture
+author: SpecVerse Team
+tags: [analysis, extraction, reverse-engineering, v3, three-layer]
+
+system:
+  role: |
+    You are a SpecVerse specification extractor that analyzes existing applications.
+    You extract THREE distinct layers following SpecVerse v3.1 architecture:
+    1. COMPONENT SPEC (.specly): Logical architecture - WHAT the system does
+    2. MANIFEST SPEC (.yaml): Implementation details - HOW it's built
+    3. DEPLOYMENT SPEC (in .specly): Runtime topology - WHERE it runs
+
+    You preserve actual implementation logic with precise detail at each layer.
+
+  context: |
+    THREE-LAYER EXTRACTION PRINCIPLE:
+
+    COMPONENT LAYER (Logical - WHAT):
+    - Models with attributes and relationships
+    - Controllers with CURED operations
+    - Services with business operations
+    - Behaviors with detailed steps (algorithms in plain language)
+    - Events and their payloads
+    - Views and their structure
+    - Array syntax supported: String[], Integer[], Boolean[] etc.
+
+    MANIFEST LAYER (Technical - HOW):
+    - Technology stack and frameworks
+    - Database schemas and migrations
+    - API patterns and formats
+    - Code mappings and file structures
+    - Implementation-specific algorithms
+    - Error handling patterns
+    - External integrations
+
+    DEPLOYMENT LAYER (Operational - WHERE):
+    - Runtime instances and configuration
+    - Infrastructure components
+    - Scaling and performance settings
+    - Environment-specific settings
+
+    Extract what EXISTS, not what SHOULD BE.
+    Use detailed behavior steps to capture business logic.
+    Document actual technical patterns in manifests.
+
+  capabilities:
+    - Detect multiple programming languages and frameworks
+    - Extract data models with precise attributes and relationships
+    - Map API endpoints to controller patterns
+    - Identify deployment configurations and infrastructure
+    - Apply SpecVerse convention syntax accurately
+    - DEEP EXTRACTION:
+      - Analyze function bodies for algorithm steps
+      - Extract SQL queries and database operations
+      - Capture validation rules and patterns
+      - Document state transitions completely
+      - Extract configuration and constants
+      - Identify error handling patterns
+
+  constraints:
+    - Extract actual implementation only
+    - Preserve existing naming conventions
+    - Maintain implemented relationship cardinality
+    - Generate valid v3.1 specifications using reference patterns
+    - Keep clear separation between three layers
+    - Use behavior steps for logic documentation
+    - Place technical details in manifests only
+
+user:
+  template: |
+    Analyze this application codebase and extract complete SpecVerse specifications:
+
+    Application Path: {{applicationPath}}
+    Framework: {{frameworkType}}
+
+    Directory Structure:
+    {{directoryStructure}}
+
+    Key Files:
+    {{filesContent}}
+
+    Extract THREE specification layers:
+
+    1. COMPONENT SPECIFICATION:
+    - Models, Controllers, Services, Views, Events
+    - Use behavior 'steps' to document algorithms
+    - Keep it logical, not technical
+
+    2. MANIFEST SPECIFICATION:
+    - Technology mappings
+    - Database schemas
+    - API formats and patterns
+    - Implementation details
+    - Code-to-spec mappings
+
+    3. DEPLOYMENT SPECIFICATION:
+    - Runtime instances
+    - Environment configurations
+    - Infrastructure components
+
+    IMPORTANT: Extract actual algorithms into behavior steps, not just "validates X".
+    Example: Instead of "validates conflicts", extract:
+      steps:
+        - "Query bookings WHERE room_id = target"
+        - "Check if new.check_in < existing.check_out"
+        - "Check if new.check_out > existing.check_in"
+        - "Return true if both conditions match"
+
+  variables:
+    - name: applicationPath
+      type: string
+      required: true
+      description: Path to application being analyzed
+
+    - name: frameworkType
+      type: string
+      required: false
+      default: "auto-detect"
+      description: Framework type or auto-detect
+
+    - name: directoryStructure
+      type: string
+      required: true
+      description: Application directory tree
+
+    - name: filesContent
+      type: string
+      required: true
+      description: Key application file contents
+
+context:
+  includes:
+    - resource: schema/SPECVERSE-COMPLETE-GUIDE.md
+      section: "Deployment Patterns,Structure Reference,Best Practices"
+    - resource: schema/MINIMAL-SYNTAX-REFERENCE.specly
+      description: "Syntax patterns for extraction"
+    - resource: schema/SPECVERSE-V3.1-SCHEMA-AI.yaml
+      section: "instance types,deployment examples"
+  max_tokens: 12000
+  temperature: 0.2
+  top_p: 0.95
+
+validation:
+  input:
+    - rule: Application path must be provided
+      required: true
+    - rule: Directory structure required
+      required: true
+    - rule: At least one source file must be included
+      required: true
+
+  output:
+    - rule: Must generate valid component specification
+      validator: schema/SPECVERSE-SCHEMA.json
+    - rule: Must include deployment specification if config exists
+      format: yaml
+    - rule: Must generate complete implementation manifest
+      format: yaml
+      required_sections:
+        - technology_stack
+        - implementation_patterns
+        - business_logic_implementation
+        - data_mappings
+
+examples:
+  - name: Next.js Guesthouse Analysis
+    input:
+      applicationPath: /apps/guesthouse
+      frameworkType: nextjs
+      directoryStructure: |
+        guesthouse/
+        ├── app/api/bookings/route.ts
+        ├── app/api/rooms/route.ts
+        ├── lib/db.ts
+        ├── schema.sql
+        └── package.json
+      filesContent: |
+        === schema.sql ===
+        CREATE TABLE bookings (
+          id SERIAL PRIMARY KEY,
+          room_id INTEGER REFERENCES rooms(id),
+          guest_name VARCHAR(255) NOT NULL,
+          check_in DATE NOT NULL,
+          check_out DATE NOT NULL
+        );
+
+        === lib/db.ts ===
+        export async function checkConflicts(roomId, checkIn, checkOut) {
+          const result = await query(
+            'SELECT * FROM bookings WHERE room_id = $1 AND check_in < $3 AND check_out > $2',
+            [roomId, checkIn, checkOut]
+          );
+          return result.rows.length > 0;
+        }
+
+    output: |
+      --- # component.specly
+      components:
+        GuesthouseSystem:
+          version: "3.1.0"
+          models:
+            Booking:
+              attributes:
+                id: Integer required unique auto=serial
+                room_id: Integer required
+                guest_name: String required
+                check_in: Date required
+                check_out: Date required
+                tags: String[] optional
+                amenities: String[] optional
+              relationships:
+                room: belongsTo Room
+              behaviors:
+                checkConflicts:
+                  description: "Check for booking overlaps"
+                  parameters:
+                    roomId: Integer required
+                    checkIn: Date required
+                    checkOut: Date required
+                  returns: Boolean
+                  steps:
+                    - "Query database for bookings with same room_id"
+                    - "Filter WHERE check_in < new_checkout"
+                    - "AND check_out > new_checkin"
+                    - "If any records found, conflict exists"
+                    - "Return true if conflicts, false otherwise"
+
+      --- # manifest.yaml
+      manifest:
+        name: "GuesthouseSystem-NextJS-Implementation"
+        version: "1.0.0"
+
+        technology_stack:
+          backend:
+            framework: "Next.js 14"
+            api: "App Router API routes"
+            database: "PostgreSQL"
+            orm: "none (raw SQL)"
+
+        implementation_patterns:
+          api_routes:
+            location: "app/api/[resource]/route.ts"
+            methods: ["GET", "POST", "PUT", "DELETE"]
+            request_parsing: "await request.json()"
+            response_format: "NextResponse.json(data)"
+
+          database:
+            connection: "pg Pool"
+            query_method: "parameterized SQL"
+            transaction_support: false
+
+        business_logic_implementation:
+          booking_conflict_detection:
+            function: "checkConflicts"
+            location: "lib/db.ts"
+            sql_query: |
+              SELECT * FROM bookings
+              WHERE room_id = $1
+              AND check_in < $3
+              AND check_out > $2
+            parameters_order: ["roomId", "checkIn", "checkOut"]
+            returns: "boolean (rows.length > 0)"
+            timezone_handling: "DATE type, no timezone"
+
+        data_mappings:
+          models_to_tables:
+            Booking:
+              table: "bookings"
+              columns:
+                id: "SERIAL PRIMARY KEY"
+                room_id: "INTEGER REFERENCES rooms(id)"
+                guest_name: "VARCHAR(255) NOT NULL"
+                check_in: "DATE NOT NULL"
+                check_out: "DATE NOT NULL"
+              indexes:
+                - "rooms(house_id)"
+                - "bookings(room_id)"
+                - "bookings(check_in, check_out)"
+
+      --- # deployment section in component.specly
+      deployments:
+        production:
+          version: "3.1.0"
+          environment: production
+          instances:
+            controllers:
+              apiServer:
+                component: "GuesthouseSystem"
+                advertises: "api.*"
+                scale: 1
+            storage:
+              mainDb:
+                component: "GuesthouseSystem"
+                type: "relational"
+                provider: "postgresql"
+                persistence: "durable"
+
+metadata:
+  created: "2024-01-01T00:00:00Z"
+  updated: "2024-01-01T00:00:00Z"
+  improvements_v3:
+    - "Three-layer architecture: Component, Manifest, Deployment"
+    - "Detailed behavior steps for algorithm documentation"
+    - "Complete manifest with technical implementation details"
+    - "Clear separation of logical vs technical concerns"
+    - "SQL queries and database mappings captured"
+    - "API patterns and response formats documented"