@vfarcic/dot-ai 0.1.0

package/prompts/question-generation.md

@@ -0,0 +1,128 @@
+# Question Generation for Kubernetes Resource Configuration
+
+## User Intent
+{intent}
+
+## Recommended Solution
+{solution_description}
+
+## Resources in Solution
+{resource_details}
+
+## Available Cluster Options
+{cluster_options}
+
+## Instructions
+
+Based on the user's intent and the Kubernetes resources in this solution, generate appropriate questions to gather the information needed to create working manifests.
+
+**IMPORTANT**: Only ask questions about properties that are explicitly listed in the "Resources in Solution" section below. Do not ask about common Kubernetes properties unless they appear in the actual resource schema.
+
+Use the provided cluster options to populate dynamic select questions with real values from the user's cluster.
+
+Organize questions into three categories based on their importance and impact:
+
+### REQUIRED Questions
+Essential information needed for basic functionality. These are mandatory fields or critical configuration that makes the difference between working and non-working deployments. Without answers to these questions, the manifests cannot be generated or will fail to deploy.
+
+**MANDATORY QUESTIONS**: You MUST always include these questions in the REQUIRED section:
+- `name`: Resource name (applies to metadata.name across all resources)
+- `namespace`: Target namespace (ONLY if any resource in the solution is namespace-scoped - check resource scope information)
+
+### BASIC Questions  
+Common configuration options most users will want to set. These improve the deployment but aren't strictly required for basic functionality. They represent sensible customizations that enhance the deployment.
+
+### ADVANCED Questions
+Optional advanced configuration for power users. These are for optimization, security hardening, complex networking, resource management, or specialized scenarios that most users won't need initially.
+
+## Guidelines
+
+**CRITICAL CONSTRAINT**: Only ask questions about properties that actually exist in the provided resource schemas. Do not invent or assume properties that are not explicitly listed in the resource details.
+
+For each question, consider:
+- **ONLY the resource schema properties and their actual constraints** - never ask about properties not in the schema
+- What information is truly needed to generate a working manifest from the actual schema fields
+- **Resource capabilities and configuration richness** - expose meaningful configuration options available in the schema
+- User-friendly question wording (avoid Kubernetes jargon where possible)
+- Practical defaults that work in most environments
+- **Comprehensive coverage** - generate questions for all significant configurable properties, not just the minimum required
+- Use cluster-discovered options when available for select questions
+
+**VALIDATION RULE**: Before creating any question, verify that the property exists in the provided resource schema. If a property like "storageClass" is not listed in the schema, do not ask about it.
+
+Question types available:
+- `text`: Free text input
+- `select`: Single choice from options (use cluster-discovered options when possible)
+- `multiselect`: Multiple choices from options  
+- `boolean`: Yes/no question
+- `number`: Numeric input
+
+## Question Design for Manifest Generation
+
+**IMPORTANT**: Questions should be designed to collect semantic answers that the manifest generator can intelligently apply to the appropriate resource fields. Focus on user-friendly question IDs and clear descriptions.
+
+### Question ID Guidelines
+- Use semantic IDs that describe what the answer represents: `name`, `port`, `namespace`, `replicas`
+- Avoid resource-specific IDs like `deployment-name` or `service-port` 
+- Use consolidation-friendly IDs when the same answer applies to multiple resources
+- Examples:
+  - `name` (applies to metadata.name across all resources)
+  - `port` (applies to containerPort, service port, ingress port)
+  - `namespace` (applies to metadata.namespace across all resources)
+  - `replicas` (applies to spec.replicas in Deployment)
+
+### Semantic Consolidation
+When multiple resources need the same information, create a single question with a consolidated ID:
+- **Instead of**: `deployment-port`, `service-port`, `ingress-port`
+- **Use**: `port` (manifest generator will apply to all relevant port fields)
+
+- **Instead of**: `deployment-name`, `service-name` 
+- **Use**: `name` (manifest generator will apply to all resource names)
+
+## Response Format
+
+Return your response as JSON in this exact format:
+
+```json
+{
+  "required": [
+    {
+      "id": "unique-kebab-case-id",
+      "question": "User-friendly question text?",
+      "type": "text|select|multiselect|boolean|number",
+      "options": ["option1", "option2"],
+      "placeholder": "example value or helpful hint",
+      "validation": {
+        "required": true,
+        "min": 1,
+        "max": 100,
+        "pattern": "^[a-z0-9-]+$"
+      },
+    }
+  ],
+  "basic": [
+    // same format as required
+  ],
+  "advanced": [
+    // same format as required  
+  ],
+  "open": {
+    "question": "Is there anything else about your requirements or constraints that would help us provide better recommendations?",
+    "placeholder": "e.g., specific security requirements, performance needs, existing infrastructure constraints..."
+  }
+}
+```
+
+## Important Notes
+
+- **CRITICAL**: Only ask questions about properties explicitly defined in the provided resource schemas
+- **Generate comprehensive questions** covering all meaningful configuration options available in the resource schemas
+- Focus on questions that actually affect the generated manifests based on the actual schema
+- **Prefer explicit configuration over defaults** - give users control over important settings even if reasonable defaults exist
+- **DO NOT** ask about storage classes, node selectors, or other properties unless they appear in the resource schema
+- **DO NOT** make assumptions about what properties are configurable - stick strictly to the provided schema
+- Use the provided cluster options to populate select questions with real values
+- Consider real-world usage patterns and common configurations
+- Ensure question IDs are unique and descriptive
+- Use semantic question IDs that consolidate related fields (e.g., `port` instead of separate port questions)
+- Validation rules should match Kubernetes constraints where applicable

package/prompts/resource-analysis.md

@@ -0,0 +1,127 @@
+# Resource Analysis for Enhancement
+
+## Current Solution
+{current_solution}
+
+## User Request
+{user_request}
+
+## Available Resource Types
+{available_resource_types}
+
+## Instructions
+
+Analyze the user's request and determine if the current solution can fulfill it or if additional resources are needed.
+
+### STEP 0: Handle No-Requirements Cases
+If the user request is any of: "N/A", "no requirements", "none", "nothing", "no", or similar variations:
+- This indicates the user has no additional requirements beyond current configuration
+- ALWAYS respond with: `{"canHandle": true, "approach": "complete_existing_questions", "reasoning": "User specified no additional requirements beyond current configuration"}`
+- Do NOT proceed to capability gap analysis in these cases
+- Skip all other steps and return the success response immediately
+
+### STEP 1: Analyze Current Solution Capabilities
+- Review the current solution's resources and their capabilities
+- Check if missing question answers can fulfill the user's request
+- Determine if the current resources support the requested functionality
+- **IMPORTANT**: Note which resources control deployment/pod creation and management
+
+### STEP 2: Determine Resource Needs
+If the current solution CANNOT fulfill the request:
+- Identify what type of capability is needed (storage, networking, database, etc.)
+- **CRITICAL**: Check if suggested resources can actually integrate with current solution
+- Consider resource control relationships and dependencies
+- Verify that new resources can be meaningfully connected to existing resources
+- Only suggest resources if they can functionally integrate with the current solution
+- If no meaningful integration is possible, classify as capability gap
+
+### STEP 3: Integration Analysis
+Before suggesting additional resources, perform these specific checks:
+
+#### A. Controller Resource Detection
+- **Check if current resources are high-level controllers** (Custom Resources, Operators, Helm Charts, etc.)
+- **Identify what they control**: Do they manage Deployment, Pod, Service, or Ingress creation?
+- **Determine autonomy level**: Do they fully control the application lifecycle?
+
+#### B. Integration Feasibility 
+- **Volume Mounting**: If user needs storage, can volumes be mounted to pods controlled by existing resources?
+- **Networking**: If user needs networking, can traffic be routed to pods managed by existing resources?  
+- **Environment Variables**: Can configuration be injected into pods controlled by existing resources?
+- **Resource Limits**: Can compute/memory limits be set on pods managed by existing resources?
+
+#### C. Capability Gap Detection
+If existing resources are high-level controllers that fully manage pod/deployment lifecycle:
+- **No volume mount points**: Cannot attach external storage volumes
+- **No network customization**: Cannot modify networking beyond controller's scope  
+- **No direct pod access**: Cannot inject custom configuration
+- **Classify as CAPABILITY_GAP**: Adding standalone resources won't actually provide functionality
+
+### STEP 4: Provide Analysis Result
+
+## Response Format (JSON ONLY)
+
+### If current solution CAN handle the request:
+```json
+{
+  "canHandle": true,
+  "approach": "complete_existing_questions",
+  "reasoning": "AppClaim supports scaling via spec.scaling.enabled/min/max fields"
+}
+```
+
+### If user has no additional requirements ("N/A", "none", etc.):
+```json
+{
+  "canHandle": true,
+  "approach": "complete_existing_questions",
+  "reasoning": "User specified no additional requirements beyond current configuration"
+}
+```
+
+### If additional resources are needed:
+```json
+{
+  "canHandle": false,
+  "approach": "add_resources",
+  "reasoning": "AppClaim does not support persistent storage",
+  "requiredCapability": "persistent storage",
+  "suggestedResources": ["PersistentVolumeClaim", "StorageClass"],
+  "resourceJustification": "PersistentVolumeClaim provides pod-independent storage, StorageClass defines storage parameters"
+}
+```
+
+### If request cannot be fulfilled:
+```json
+{
+  "canHandle": false,
+  "approach": "capability_gap",
+  "reasoning": "Current solution uses high-level controller that fully manages application lifecycle",
+  "integrationIssue": "Controller resource manages pod/deployment creation, preventing integration with external resources that require pod-level access",
+  "controllerType": "Custom Resource/Operator/High-level abstraction",
+  "requestedCapability": "User's requested functionality",
+  "suggestedAction": "Start over with intent that includes these requirements from the beginning"
+}
+```
+
+## Integration Analysis Examples:
+
+**Example 1 - Database with High-Level Controller:**
+- Current: High-level resource that manages application lifecycle
+- Request: External database connectivity  
+- Analysis: High-level resource controls networking/service creation, cannot connect to external databases
+- Result: capability_gap
+
+**Example 2 - Compatible Resources:**
+- Current: Standard Deployment
+- Request: Load balancing
+- Analysis: Service can route traffic to Deployment pods via label selectors
+- Result: add_resources (Service)
+
+## Critical Requirements:
+1. **RESPOND ONLY WITH JSON** - No explanations, no text, only the JSON object
+2. **Only suggest resources from Available Resource Types list**
+3. **Be specific about capability gaps**
+4. **Provide clear reasoning for decisions**
+5. **Always check resource integration feasibility**
+
+**YOU MUST RESPOND WITH ONLY THE JSON OBJECT - NO OTHER TEXT**

package/prompts/resource-selection.md

@@ -0,0 +1,55 @@
+# Resource Selection Prompt
+
+You are a Kubernetes expert. Given this user intent and available resources, select the resources that could be relevant for detailed analysis.
+
+## User Intent
+{intent}
+
+## Available Resources
+{resources}
+
+## Instructions
+
+Select all resources that could be relevant for this intent. Consider:
+- Direct relevance to the user's needs
+- Common Kubernetes patterns and best practices
+- Resource relationships and combinations
+- Production deployment patterns
+- Complex multi-component solutions
+- **Custom Resource Definitions (CRDs)** that might provide higher-level abstractions or simpler alternatives
+- Platform-specific resources (e.g., Crossplane, Knative, Istio, ArgoCD) that could simplify the deployment
+- **CRD Selection Priority**: If you see multiple CRDs from the same group with similar purposes (like "App" and "AppClaim"), include the namespace-scoped ones (marked as "Namespaced: true") rather than cluster-scoped ones, as they're more appropriate for application deployments
+
+Don't limit yourself - if the intent is complex, select as many resources as needed.
+
+## Response Format
+
+Respond with ONLY a JSON array of resource objects with full identifiers. Do NOT wrap in an object - just return the array:
+
+```json
+[
+  {
+    "kind": "Deployment",
+    "apiVersion": "apps/v1",
+    "group": "apps"
+  },
+  {
+    "kind": "Service", 
+    "apiVersion": "v1",
+    "group": ""
+  }
+]
+```
+
+IMPORTANT: Your response must be ONLY the JSON array, nothing else.
+
+## Selection Philosophy
+
+- **Be inclusive** - It's better to analyze too many than miss important ones
+- **Think holistically** - Consider complete solutions, not just individual components
+- **Consider dependencies** - If you select one resource, include its typical dependencies
+- **Include supporting resources** - ConfigMaps, Secrets, ServiceAccounts often needed
+- **Evaluate custom resources** - CRDs often provide simpler, higher-level interfaces than raw Kubernetes resources
+- **Prefer namespace-scoped CRDs** - When multiple similar CRDs exist from the same group (e.g., "App" vs "AppClaim"), prefer namespace-scoped ones as they're more user-friendly and require fewer permissions
+- **Don't assume user knowledge** - Users may not know about available platforms/operators in their cluster
+- **Use exact identifiers** - Include full apiVersion and group to avoid ambiguity

package/prompts/resource-solution-ranking.md

@@ -0,0 +1,77 @@
+# Resource Solution Ranking Prompt
+
+You are a Kubernetes expert helping to determine which resource(s) best meet a user's needs.
+
+## User Intent
+{intent}
+
+## Available Resources
+{resources}
+
+## Instructions
+
+Analyze the user's intent and determine the best solution(s). This could be:
+- A single resource that fully addresses the need
+- A combination of resources that work together to create a complete solution
+- Multiple alternative approaches ranked by effectiveness
+
+For each solution, provide:
+1. A score from 0-100 for how well it meets the user's needs
+2. Specific reasons why this solution addresses the intent
+3. Whether it's a single resource or combination, and why
+4. Production readiness and best practices
+
+Consider:
+- Semantic meaning and typical use cases
+- Resource relationships and orchestration patterns
+- Complete end-to-end solutions vs partial solutions
+- Production patterns and best practices
+- **Custom Resource Definitions (CRDs)** that may provide simpler, higher-level abstractions
+- Platform operators (Crossplane, Knative, etc.) that might offer better user experience
+- User experience - simpler declarative approaches often score higher than complex multi-resource solutions
+
+## CRD Preference Guidelines
+
+When evaluating CRDs vs standard Kubernetes resources:
+- **Prefer CRDs with matching capabilities**: If a CRD's listed capabilities directly address the user's specific needs, it should score higher than manually combining multiple standard resources
+- **Favor purpose-built solutions**: CRDs designed for specific use cases should score higher than generic resource combinations when the use case aligns
+- **Value comprehensive functionality**: A single CRD that handles multiple related concerns (deployment + networking + scaling) should score higher than manually orchestrating separate resources for the same outcome
+- **Consider operational simplicity**: CRDs that provide intuitive, domain-specific interfaces should be preferred over complex multi-resource configurations
+- **Give preference to platform abstractions**: For application deployment scenarios, purpose-built CRDs with comprehensive application platform features should be weighted more favorably than basic resources requiring manual orchestration
+- **Match scope to intent**: Only prefer CRDs when their documented capabilities genuinely align with what the user is trying to achieve
+
+## Response Format
+
+```json
+{
+  "solutions": [
+    {
+      "type": "single|combination",
+      "resources": [
+        {
+          "kind": "Deployment",
+          "apiVersion": "apps/v1",
+          "group": "apps"
+        }
+      ],
+      "score": 85,
+      "description": "Brief description of this solution",
+      "reasons": ["reason1", "reason2"],
+      "analysis": "Detailed explanation of why this solution meets the user's needs"
+    }
+  ]
+}
+```
+
+For each resource in the `resources` array, provide:
+- `kind`: The resource type (e.g., "Deployment", "Service", "AppClaim")
+- `apiVersion`: The API version (e.g., "apps/v1", "v1")
+- `group`: The API group (empty string for core resources, e.g., "apps", "devopstoolkit.live")
+
+## Scoring Guidelines
+
+- **90-100**: Complete solution, fully addresses user needs
+- **70-89**: Good solution, addresses most needs with minor gaps
+- **50-69**: Partial solution, addresses some needs but requires additional work
+- **30-49**: Incomplete solution, only peripherally addresses needs
+- **0-29**: Poor fit, doesn't meaningfully address the user's intent

package/prompts/solution-enhancement.md

@@ -0,0 +1,129 @@
+# Single-Pass Solution Enhancement
+
+## Current Solution
+{current_solution}
+
+## Detailed Resource Schemas
+{detailed_schemas}
+
+## Analysis Result
+{analysis_result}
+
+## User Response
+{open_response}
+
+## Instructions
+
+You are enhancing a solution in a **single-pass architecture**. Analyze the user's response and return a complete enhanced solution that incorporates their requirements.
+
+**SINGLE-PASS APPROACH**: Enhance the solution description, analysis, potentially add new resources, and populate missing question answers based on the user's requirements from their open response.
+
+### Enhancement Strategy:
+
+1. **Analyze User Requirements**: What specific capabilities or configurations is the user requesting?
+
+2. **Enhance Solution Content**: 
+   - Update the solution description to reflect the enhanced capabilities
+   - Enhance the analysis to explain how the solution addresses the user's specific needs
+   - Adjust the solution score if the enhancement significantly improves the solution
+
+3. **Populate Question Answers**: 
+   - Analyze the user's open response for specific configuration values
+   - Fill in answers for questions that can be determined from the user's requirements
+   - Only populate answers where the user provided clear information in their open response
+   - Leave questions unanswered if the user didn't provide relevant information
+
+4. **Add Resources if Needed**: 
+   - Only if the Analysis Result indicates new resources are required (approach: "add_resources")
+   - Use ONLY the schemas provided in "Detailed Resource Schemas" section
+   - Add resources that are actually needed and supported by the available schemas
+
+5. **Preserve Solution Structure**: 
+   - Keep all existing questions intact 
+   - The user's open response should remain as-is
+   - Do not add new questions - this is a single-pass system
+
+### Resource Enhancement Guidelines:
+- **SCHEMA VALIDATION**: Only add resources that exist in the "Detailed Resource Schemas" section
+- **CAPABILITY FOCUS**: Add resources only when the current solution cannot handle the user's requirements
+- **NO REDUNDANCY**: Don't add resources if existing ones already provide the needed capabilities
+
+## Response Format
+
+### For Successful Enhancement:
+Return the complete enhanced solution. Copy the entire current solution and enhance it with:
+- Updated description and analysis
+- Populated question answers based on the user's open response  
+- Additional resources if needed
+- Updated score
+
+```json
+{
+  "enhancedSolution": {
+    "type": "single",
+    "score": 85,
+    "description": "[ENHANCED_DESCRIPTION_INCORPORATING_USER_REQUIREMENTS]",
+    "reasons": ["copy from current solution"],
+    "analysis": "[ENHANCED_ANALYSIS_EXPLAINING_HOW_SOLUTION_MEETS_REQUIREMENTS]",
+    "resources": [
+      "copy all resources from current solution, plus any additionalResources if needed"
+    ],
+    "questions": {
+      "required": [
+        "copy all required questions from current solution, preserving existing answers"
+      ],
+      "basic": [
+        "copy all basic questions from current solution, adding answers where user provided info"
+      ],
+      "advanced": [
+        "copy all advanced questions from current solution, adding answers where user provided info"
+      ],
+      "open": {
+        "question": "copy from current solution",
+        "placeholder": "copy from current solution", 
+        "answer": "copy from current solution - DO NOT MODIFY"
+      }
+    }
+  }
+}
+```
+
+### For Capability Gap:
+```json
+{
+  "error": "CAPABILITY_GAP",
+  "message": "[EXPLANATION_OF_WHY_CURRENT_SOLUTION_CANNOT_HANDLE_REQUEST]",
+  "missingCapability": "[WHAT_USER_REQUESTED_THAT_CANNOT_BE_DONE]",
+  "currentSolution": "[BRIEF_DESCRIPTION_OF_CURRENT_RESOURCES]",
+  "suggestedAction": "[ADVICE_TO_START_OVER_WITH_DIFFERENT_INTENT]"
+}
+```
+
+## Enhancement Examples:
+
+### Example 1: Enhanced Description and Analysis
+**User**: "I need it to handle 10x traffic with high availability"
+**Current**: Basic Pod deployment solution
+**Enhanced**: Description mentions auto-scaling and HA capabilities, analysis explains how the solution scales and maintains availability
+
+### Example 2: Adding Resources
+**User**: "I need persistent storage for user uploads"
+**Current**: Basic application deployment
+**Analysis Result**: "add_resources" with PersistentVolumeClaim recommended
+**Enhanced**: Add PVC resource and update description to mention persistent storage capabilities
+
+### Example 3: Capability Gap
+**User**: "I need a managed database service"
+**Current**: Application deployment solution
+**Problem**: Kubernetes doesn't provide managed database services natively
+**Response**: Return capability gap error, suggest starting over with database-specific intent
+
+## Critical Requirements:
+1. **RESPOND ONLY WITH JSON** - No explanations, no text, only the JSON object
+2. **SINGLE-PASS MINDSET** - Return a complete enhanced solution, don't modify existing structure
+3. **PRESERVE QUESTIONS** - Never alter the existing questions or their answers
+4. **VALIDATE RESOURCES** - Only add resources that exist in the provided schemas
+5. **ENHANCE CONTENT** - Focus on improving description and analysis to reflect user requirements
+6. **LOGICAL ENHANCEMENTS** - Only enhance aspects that are actually improved by the user's requirements
+
+**YOU MUST RESPOND WITH ONLY THE JSON OBJECT - NO OTHER TEXT**