@vfarcic/dot-ai 0.151.0 → 0.153.0

package/prompts/helm-generation.md

@@ -0,0 +1,85 @@
+# Helm Values Generation
+
+## Solution Configuration
+{{solution}}
+
+## Chart Values Structure
+The following is the chart's default values.yaml that defines available configuration options:
+{{chart_values}}
+
+## Previous Attempt (if retry)
+{{previous_attempt}}
+
+## Validation Error Details (if retry)
+{{error_details}}
+
+## Instructions
+
+Generate a values.yaml file for Helm chart installation based on the user's configuration answers. The solution contains the chart information, user intent, and all answered questions.
+
+### Core Strategy:
+
+1. **Identify CLI Arguments vs Values**:
+   - `name` answer → Helm release name (CLI argument, NOT a value)
+   - `namespace` answer → --namespace flag (CLI argument, NOT a value)
+   - All other answers → values.yaml content
+
+2. **Map Answers to Values Structure**:
+   - Use the chart's values.yaml structure above as your guide
+   - Match answer semantics to the appropriate value paths
+   - Common mappings:
+     * "replicas" → `replicaCount`
+     * "enable ingress" → `ingress.enabled`
+     * "ingress class" → `ingress.className` or `ingress.ingressClassName`
+     * "service type" → `service.type`
+     * "storage size" → `persistence.size`
+   - Use the actual field names from the chart's values.yaml, not generic assumptions
+
+3. **Handle Value Types Correctly**:
+   - Booleans: `true` or `false` (not strings "true"/"false")
+   - Numbers: numeric values without quotes
+   - Strings: use quotes only when necessary (values with special chars)
+   - Arrays/Lists: proper YAML list format
+   - Nested objects: proper YAML indentation
+
+4. **Include Only Values That Differ From Defaults**:
+   - Compare each user answer to the chart's default values above
+   - Only include values that DIFFER from the chart's defaults
+   - If user's answer matches the default value, do NOT include it in values.yaml
+   - Do NOT include `name` or `namespace` in the values (they're CLI args)
+   - This keeps the values file minimal and intentional - only showing what's changed
+
+5. **Process Open Requirements**:
+   - If the user provided open-ended requirements, translate them to appropriate values
+   - Reference the chart's values.yaml to find relevant configuration options
+
+### For Retry Attempts:
+If this is a retry (previous attempt and error details provided above):
+- Analyze the previous values.yaml to understand what was generated
+- Study the Helm error to identify the specific problem
+- Common issues:
+  * Invalid value type (string vs boolean vs number)
+  * Non-existent value path in the chart
+  * Invalid YAML syntax
+  * Template rendering errors from invalid combinations
+- Make targeted corrections to fix the identified issues
+
+### Response Requirements:
+
+1. **Valid YAML**: Generate syntactically correct YAML
+2. **Correct Structure**: Match the chart's expected values.yaml structure exactly
+3. **Proper Types**: Use correct data types for each value
+4. **Exclude CLI Args**: Do NOT include `name` or `namespace` - they are handled separately
+
+## Response Format
+
+**CRITICAL**: Return ONLY valid YAML content. NO explanations, NO markdown code blocks, NO additional text.
+
+If no values need to be overridden (user accepted all defaults for non-CLI options), return:
+```
+# Default values - no overrides needed
+```
+
+Otherwise, return only the YAML values content.
+
+**RETURN ONLY THE YAML VALUES**

package/prompts/intent-analysis.md

@@ -8,6 +8,23 @@ You are an expert Kubernetes deployment consultant analyzing user intents to ide
 ## Organizational Patterns Context
 {{organizational_patterns}}
 
+## Third-Party Tool Installation Detection
+
+**IMPORTANT**: First, determine if this intent is for installing a well-known third-party tool (Argo CD, Prometheus, Grafana, Crossplane, Cert-Manager, Jaeger, Vault, etc.).
+
+**If YES (third-party tool installation)**:
+- **Installation method is Helm** - DO NOT ask about Helm vs Kustomize vs manual
+- **Detailed configuration will come later** - DO NOT ask about HA mode, authentication, storage, resource limits, monitoring integration, secrets management, backup strategies, etc. These questions will be asked in the Helm configuration phase
+- **Keep clarification minimal** - only ask 1-3 questions that affect CHART SELECTION:
+  - "Do you want the full stack (e.g., kube-prometheus-stack) or just the base tool?"
+  - "Single cluster or multi-cluster setup?" (only if it affects which chart to use)
+  - Open-ended: "Any specific requirements that would affect the installation?"
+- **Set enhancementPotential to LOW** for clear tool installation intents
+- **Return minimal clarificationOpportunities** (1-3 max)
+
+**If NO (custom application deployment)**:
+- Proceed with comprehensive analysis below
+
 ## Analysis Framework
 
 Analyze the user's intent comprehensively to identify **every piece of missing context** that could improve the quality and relevance of deployment recommendations. Be thorough - explore all aspects that could influence the deployment, regardless of traditional categories.

package/prompts/question-generation.md

@@ -1,4 +1,4 @@
-# Question Generation for Kubernetes Resource Configuration
+# Question Generation for Kubernetes Configuration
 
 ## User Intent
 {{intent}}
@@ -6,10 +6,9 @@
 ## Recommended Solution
 {{solution_description}}
 
-## Resources in Solution
-{{resource_details}}
+{{{source_material}}}
 
-## Available Cluster Options
+## Cluster Context
 {{cluster_options}}
 
 ## Organizational Policies
@@ -19,35 +18,35 @@
 
 ## ⚠️ CRITICAL: MANDATORY "name" FIELD REQUIREMENT
 
-**BEFORE GENERATING ANY QUESTIONS**: The REQUIRED section MUST include a question with `id: "name"`. This is non-negotiable and your response will be rejected if this field is missing or renamed to any variation like "cluster-name", "deployment-name", or "app-name".
+**BEFORE GENERATING ANY QUESTIONS**: The REQUIRED section MUST include a question with `id: "name"`. This is non-negotiable and your response will be rejected if this field is missing or renamed to any variation like "cluster-name", "deployment-name", "app-name", or "release-name".
 
 ## 🛡️ POLICY-AWARE QUESTION GENERATION (HIGHEST PRIORITY)
 
 **Policy Requirements Integration:**
 - **Policy-driven questions** represent organizational governance requirements and must be enforced through configuration
-- **Conditional applicability** - Only apply policies when their rationale matches the selected resources
+- **Conditional applicability** - Only apply policies when their rationale matches the solution
 - **REQUIRED question promotion** - Applicable policy requirements should become REQUIRED questions with helpful defaults
 - **Compliance indicators** - Mark policy-driven questions with "⚠️ required by [policy description]" in question text
 - **Policy rationale** - Include policy rationale as question hints to help users understand WHY they're required
 
 **POLICY APPLICATION APPROACH:**
 
-1. **Analyze Resource Match**: Review each policy's rationale to determine if it applies to the selected resources
+1. **Analyze Match**: Review each policy's rationale to determine if it applies to the solution
 2. **Extract Requirements**: Identify what configuration properties the policy requires
 3. **Create REQUIRED Questions**: Convert applicable policy requirements into REQUIRED questions
 4. **Add Compliance Context**: Include policy context in question text and hints
 5. **Set Sensible Defaults**: Provide policy-compliant defaults when possible
 
 **CRITICAL: Policy Conditional Logic**
-- **Read each policy's "Rationale" field carefully** - it specifies WHEN and TO WHAT the policy applies  
-- **Apply policies selectively** - only convert policy requirements to questions when the policy technically applies to the selected resource types
-- **Resource type matching** - If a policy rationale mentions specific resource types (e.g., "All Deployments must..."), only apply when Deployment resources are selected
-- **Field-specific requirements** - Match policy requirements to actual resource schema fields available in the "Resources in Solution" section
+- **Read each policy's "Rationale" field carefully** - it specifies WHEN and TO WHAT the policy applies
+- **Apply policies selectively** - only convert policy requirements to questions when the policy technically applies
+- **Configuration matching** - If a policy rationale mentions specific configurations (e.g., "All Deployments must..."), only apply when relevant
+- **Field-specific requirements** - Match policy requirements to configuration options available in the source material above
 - **Policy compliance increases user success** - policy-driven questions help users create compliant configurations from the start
 
-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.
+Based on the user's intent and the configuration options in the source material above, generate appropriate questions to gather the information needed.
 
-**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.
+**IMPORTANT**: Only ask questions about properties that are explicitly listed in the source material above. Do not ask about properties unless they appear in the provided configuration options.
 
 Use the provided cluster options to populate dynamic select questions with real values from the user's cluster.
 
@@ -69,6 +68,8 @@ You MUST include these EXACT questions with these EXACT IDs in the REQUIRED sect
 2. **REQUIRED: `namespace` question (id: "namespace")**
    - ONLY if any resource in the solution is namespace-scoped - check resource scope information
    - Question ID MUST be exactly: `"id": "namespace"`
+   - **For Helm chart installations**: Use `type: "text"` (NOT `select`) because users typically want to create NEW namespaces for third-party tools (e.g., "monitoring", "argocd", "cert-manager"). Mention existing namespaces in the placeholder as suggestions.
+   - **For capability-based solutions**: Use `type: "select"` with existing namespaces as options.
 
 **VALIDATION**: Your response will fail if the REQUIRED section does not contain a question with `"id": "name"`
 
@@ -80,18 +81,27 @@ Optional advanced configuration for power users. These are for optimization, sec
 
 ## 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.
+**CRITICAL CONSTRAINT**: Only ask questions about properties that actually exist in the provided source material. Do not invent or assume properties that are not explicitly listed.
 
 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
+- **ONLY the properties and their actual constraints from the source material** - never ask about properties not provided
+- What information is truly needed to generate a working configuration
+- **Configuration richness** - expose meaningful configuration options available in the source material
 - 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.
+### Determining Suggested Answers
+
+Each question MUST include a `suggestedAnswer` field. Determine appropriate values by considering:
+
+1. **Organizational policies** - If a policy specifies required values or constraints, use compliant defaults
+2. **Source material defaults** - Use defaults defined in the chart values.yaml, CRD schema, or documentation
+3. **Cluster context** - For questions about cluster resources (ingress class, storage class, etc.), prefer options actually available in the cluster, especially those marked as default
+4. **Best practices** - Apply common Kubernetes conventions and production-ready defaults
+
+**VALIDATION RULE**: Before creating any question, verify that the property exists in the provided source material. If a property like "storageClass" is not listed, do not ask about it.
 
 Question types available:
 - `text`: Free text input
@@ -178,13 +188,13 @@ Return your response as JSON in this exact format:
 ## Important Notes
 
 - **CRITICAL VALIDATION REQUIREMENT**: The REQUIRED section MUST contain a question with `"id": "name"` - responses without this will be rejected
-- **CRITICAL**: Only ask questions about properties explicitly defined in the provided resource schemas
-- **REQUIRED**: Each question must include a `suggestedAnswer` field with a valid example value that passes the validation rules
-- **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
+- **CRITICAL**: Only ask questions about properties explicitly defined in the provided source material
+- **REQUIRED**: Each question must include a `suggestedAnswer` field (see "Determining Suggested Answers" section for guidance)
+- **Generate comprehensive questions** covering all meaningful configuration options available in the source material
+- Focus on questions that actually affect the generated configuration
 - **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
+- **DO NOT** ask about storage classes, node selectors, or other properties unless they appear in the source material
+- **DO NOT** make assumptions about what properties are configurable - stick strictly to the provided source material
 - 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

package/prompts/resource-selection.md

@@ -54,11 +54,37 @@ Create multiple alternative solutions. Consider:
 
 **Generate 2-5 different solutions** that genuinely address the user intent. Prioritize relevance over quantity - it's better to provide 2-3 high-quality, relevant solutions than to include irrelevant alternatives just to reach a target number.
 
+## Helm Installation Fallback
+
+**After analyzing available capabilities, determine if they can genuinely fulfill the user's intent.**
+
+Ask yourself: "If the user applies these resources, will they get what they actually asked for?"
+
+**Evaluation principles:**
+
+1. **Don't confuse "uses X" with "is X"**
+   - ServiceMonitor CRD *uses* Prometheus but doesn't *provide* Prometheus
+   - Certificate CRD *uses* cert-manager but doesn't *provide* cert-manager
+   - Prometheus CRD *provides* Prometheus instances (operator is installed)
+   - Cluster CRD from CNPG *provides* PostgreSQL instances (operator is installed)
+
+2. **Match the actual ask:**
+   - "Install Prometheus" + Prometheus CRD exists → Capability solution (can create Prometheus instance)
+   - "Install Prometheus" + Only ServiceMonitor exists → Helm fallback (cannot install Prometheus itself)
+   - "Deploy PostgreSQL" + CNPG Cluster CRD exists → Capability solution (can create database)
+   - "Deploy PostgreSQL" + No database operators → Helm fallback (need to install something first)
+
+3. **Decision:**
+   - If capabilities CAN fulfill the intent → Return `solutions` array with capability-based solutions
+   - If capabilities CANNOT fulfill the intent → Return `helmRecommendation` with empty `solutions` array
+
 ## Response Format
 
-Respond with ONLY a JSON object containing an array of complete solutions. Each solution should include resources, description, scoring, and pattern compliance:
+Respond with ONLY a JSON object. The format depends on whether capabilities can fulfill the intent:
+
+### When capabilities CAN fulfill the intent:
 
-**CRITICAL**: For each resource in your solutions, you MUST include the `resourceName` field. This field contains the correct plural, lowercase resource name used for kubectl explain calls. Extract this from the Available Resources list - each resource shows its `resourceName` field that you should copy exactly.
+Return solutions with resources. Include the `resourceName` field for each resource (extract from Available Resources list).
 
 ```json
 {
@@ -82,17 +108,35 @@ Respond with ONLY a JSON object containing an array of complete solutions. Each
       "score": 95,
       "description": "Complete web application deployment with networking",
       "reasons": ["High capability match for web applications", "Includes essential networking"],
-      "appliedPatterns": ["High availability web application pattern", "Ingress with TLS termination"]
+      "appliedPatterns": ["High availability web application pattern"]
     }
   ]
 }
 ```
 
-**CRITICAL - Applied Patterns Field:**
-- Include `appliedPatterns` array with the **descriptions** of organizational patterns you applied to this solution
-- Use the pattern `description` field from the Organizational Patterns section provided above
-- Only include patterns that directly influenced this solution's resource selection or configuration
-- Use empty array `[]` if no organizational patterns were applied
+**Applied Patterns:** Include pattern descriptions that influenced the solution. Use empty array `[]` if none applied.
+
+### When capabilities CANNOT fulfill the intent (Helm fallback):
+
+Return empty solutions with Helm recommendation. Patterns do not apply to Helm installations.
+
+```json
+{
+  "solutions": [],
+  "helmRecommendation": {
+    "reason": "No capabilities can install Prometheus. ServiceMonitor CRD configures monitoring targets but cannot install Prometheus itself.",
+    "suggestedTool": "Prometheus",
+    "searchQuery": "prometheus"
+  }
+}
+```
+
+**searchQuery construction rules:**
+- Use the primary tool name only (e.g., "prometheus", "argo cd", "cert-manager")
+- Do NOT include generic terms like "helm", "chart", "kubernetes", "install"
+- Do NOT include compound queries - pick the main tool (e.g., "prometheus with alertmanager" → searchQuery: "prometheus")
+- Keep it simple - ArtifactHub search works best with short, focused queries
+- The full intent will be used later when selecting the best chart from search results
 
 IMPORTANT: Your response must be ONLY the JSON object, nothing else.
 

package/shared-prompts/prd-start.md

@@ -132,23 +132,33 @@ For documentation-first PRDs:
 
 ## Step 3: Implementation Context Setup
 
+**⚠️ MANDATORY: Complete this step BEFORE proceeding to Step 4**
+
 ### Git Branch Management
-**If not already on a feature branch:**
-```bash
-# Create feature branch for PRD implementation
-git checkout -b feature/prd-[issue-id]-[feature-name]
-git push -u origin feature/prd-[issue-id]-[feature-name]
-```
+
+1. **Check current branch**: Run `git branch --show-current`
+2. **If on `main` or `master`**: Create and switch to feature branch:
+   ```bash
+   git checkout -b feature/prd-[issue-id]-[feature-name]
+   ```
+3. **If already on a feature branch**: Verify it's the correct branch for this PRD
 
 ### Development Environment Setup
 - **Dependencies**: Install any new dependencies required by the PRD
 - **Configuration**: Set up any configuration needed for development
 - **Test data**: Prepare test data or mock services
-- **Documentation tools**: Ensure documentation generation tools are available
 
-### Implementation Tracking Setup
-- **Identify key milestones**: Review the PRD milestones for progress tracking
-- **Plan progress checkpoints**: Determine when to update progress during implementation
+### Step 3 Checkpoint (REQUIRED)
+
+**You MUST display this confirmation before proceeding to Step 4:**
+
+```markdown
+## Environment Setup ✅
+- **Branch**: `[current-branch-name]` ✅
+- **Status**: [Created new branch / Already on correct branch / Staying on main (reason)]
+```
+
+**DO NOT proceed to Step 4 until branch setup is confirmed.**
 
 ## Step 4: Identify Implementation Starting Point