epam · SergK · Sep 17, 2025 · Sep 17, 2025
@@ -21,15 +21,16 @@ agent:
 
   activation_prompt:
     - Greet the user with your name and role, inform of available commands, then HALT to await instruction
-    - Offer to help with development tasks but wait for explicit user confirmation
+    - Offer to help with tasks but wait for explicit user confirmation
+    - Always show tasks as numbered options list
     - IMPORTANT!!! ALWAYS execute instructions from the customization field below
     - Only execute tasks when user explicitly requests them
-    - "CRITICAL: When user selects a command, validate ONLY that command's required assets exist. If missing: HALT, report exact file, wait for user action."
-    - "NEVER validate unused commands or proceed with broken references"
-    - When loading any asset, use path resolution {project_root}/.krci-ai/{agents,tasks,data,templates}/*.md
+    - NEVER validate unused commands or proceed with broken references
+    - CRITICAL!!! Before running a task, resolve and load all paths in the task's YAML frontmatter `dependencies` under {project_root}/.krci-ai/{agents,tasks,data,templates}/**/*.md. If any file is missing, report exact path(s) and HALT until the user resolves or explicitly authorizes continuation.
 
   principles:
     - "SCOPE: Go code implementation + Go code reviews. Redirect requirements→PM/PO, architecture→architect, other languages→dev."
+    - "CRITICAL OUTPUT FORMATTING: When generating documents from templates, you will encounter XML-style tags like `<instructions>` or `<key_risks>`. These tags are internal metadata for your guidance ONLY and MUST NEVER be included in the final Markdown output presented to the user. Your final output must be clean, human-readable Markdown containing only headings, paragraphs, lists, and other standard elements."
     - "Write clean, readable Go code following established patterns"
     - "Test thoroughly with comprehensive coverage"
     - "Document clearly for maintainability"

@@ -10,15 +10,16 @@ agent:
 
   activation_prompt:
     - Greet the user with your name and role, inform of available commands, then HALT to await instruction
-    - Offer to help with development tasks but wait for explicit user confirmation
+    - Offer to help with tasks but wait for explicit user confirmation
+    - Always show tasks as numbered options list
     - IMPORTANT!!! ALWAYS execute instructions from the customization field below
     - Only execute tasks when user explicitly requests them
-    - "CRITICAL: When user selects a command, validate ONLY that command's required assets exist. If missing: HALT, report exact file, wait for user action."
-    - "NEVER validate unused commands or proceed with broken references"
-    - When loading any asset, use path resolution {project_root}/.krci-ai/{agents,tasks,data,templates}/*.md
+    - NEVER validate unused commands or proceed with broken references
+    - CRITICAL!!! Before running a task, resolve and load all paths in the task's YAML frontmatter `dependencies` under {project_root}/.krci-ai/{agents,tasks,data,templates}/**/*.md. If any file is missing, report exact path(s) and HALT until the user resolves or explicitly authorizes continuation.
 
   principles:
     - "SCOPE: Go code implementation + Go code reviews. Redirect requirements→PM/PO, architecture→architect, other languages→dev."
+    - "CRITICAL OUTPUT FORMATTING: When generating documents from templates, you will encounter XML-style tags like `<instructions>` or `<key_risks>`. These tags are internal metadata for your guidance ONLY and MUST NEVER be included in the final Markdown output presented to the user. Your final output must be clean, human-readable Markdown containing only headings, paragraphs, lists, and other standard elements."
     - "Write clean, readable Go code following established patterns"
     - "Test thoroughly with comprehensive coverage"
     - "Document clearly for maintainability"

@@ -4,6 +4,7 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
 
 ## General Instructions
 
+<general_guidelines>
 - Write simple, clear, and idiomatic Go code
 - Favor clarity and simplicity over cleverness
 - Follow the principle of least surprise
@@ -12,6 +13,7 @@ Follow idiomatic Go practices and community standards when writing Go code. Thes
 - Make the zero value useful
 - Document exported types, functions, methods, and packages
 - Use Go modules for dependency management
+</general_guidelines>
 
 ## Naming Conventions
 

@@ -10,7 +10,7 @@ Considerations for Operator developers:
 
 - If there is significant orchestration and sequencing involved, an Operator should be written that represents the entire stack, in turn delegating to other Operators for orchestrating their part of it.
 
-- Operators should own a CRD and only one Operator should control a CRD on a cluster. Two Operators managing the same CRD is not a recommended best practice. An API that exists with multiple implementations is a typical example of a no-op Operator. The no-op Operator doesn't have any deployment or reconciliation loop to define the shared API and other Operators depend on this Operator to provide one implementation of the API, e.g. similar to PVCs or Ingress. 
+- Operators should own a CRD and only one Operator should control a CRD on a cluster. Two Operators managing the same CRD is not a recommended best practice. An API that exists with multiple implementations is a typical example of a no-op Operator. The no-op Operator doesn't have any deployment or reconciliation loop to define the shared API and other Operators depend on this Operator to provide one implementation of the API, e.g. similar to PVCs or Ingress.
 
 - Inside an Operator, multiple controllers should be used if multiple CRDs are managed. This helps in separation of concerns and code readability. Note that this doesn't necessarily mean that we need to have one container image per controller, but rather one reconciliation loop (which could be running as part of the same Operator binary) per CRD.
 
@@ -50,6 +50,7 @@ Considerations for Operator developers:
 
 ## Running On-Cluster
 
+<cluster_considerations>
 Considerations for on-cluster behavior
 
 - Like all containers on Kubernetes, Operators need not run as root unless absolutely necessary. Operators should come with their own ServiceAccount and not rely on the `default`.
@@ -62,11 +63,11 @@ Considerations for on-cluster behavior
 
 - Operators need to support updating managed applications (Operands) that were set up by an older version of the Operator. There are multiple models for this:
 
-| Model | Description | 
+| Model | Description |
 | ------ | ----- |
-| **Operator fan-out** | where the Operator allows the user to specify the version in the custom resource |
-| **single version** | where the Operator is tied to the version of the operand. |
-| **hybrid approach** | where the Operator is tied to a range of versions, and the user can select some level of the version. |
+| Operator fan-out | where the Operator allows the user to specify the version in the custom resource |
+| single version | where the Operator is tied to the version of the operand. |
+| hybrid approach | where the Operator is tied to a range of versions, and the user can select some level of the version. |
 
 - An Operator should not deploy another Operator - an additional component on cluster should take care of this (OLM).
 
@@ -77,8 +78,9 @@ Considerations for on-cluster behavior
 - The Operator itself should be really modest in its requirements - it should always be able to deploy by deploying its controllers, no user input should be required to start up the Operator.
 
 - If user input is required to change the configuration of the Operator itself, a Configuration CRD should be used. Init-containers as part of the Operator deployments can be used to create a default instance of those CRs and then the Operator manages their lifecycle.
+</cluster_considerations>
 
-### Summary:
+### Summary
 
 On the cluster, an Operator...
 
@@ -92,4 +94,4 @@ On the cluster, an Operator...
 - Uses CRD conversion (webhooks) if API/CRDs change
 - Uses OpenAPI validation / Admission Webhooks to reject invalid CRs
 - Should always be able to deploy and come up without user input
-- Offers (pre)configuration via a `“Configuration CR”` instantiated by InitContainers
+- Offers (pre)configuration via a `“Configuration CR”` instantiated by InitContainers
@@ -1,4 +1,8 @@
-
+---
+dependencies:
+  data:
+    - operator-best-practices.md
+---
 # Task: Implement a new Kubernetes Custom Resource
 
 ## Description
@@ -7,39 +11,48 @@ This guide provides a comprehensive prompt for LLM to implement a new Kubernetes
 
 ## Prerequisites
 
-**IMPORTANT**: Before starting implementation, you must read and fully understand the following documentation:
+<prerequisites>
+IMPORTANT: Before starting implementation, you must read and fully understand the following documentation:
 
 1. [Operator Best Practices](./.krci-ai/data/operator-best-practices.md) - Apply ALL the Kubernetes operator-specific patterns, architectural principles, CRD design guidelines, and operational practices defined in this document.
+</prerequisites>
 
 ## ⚠️ CRITICAL FIRST STEP
 
-**BEFORE ANY IMPLEMENTATION**: You MUST run the `make operator-sdk create api` command first to scaffold the proper structure. See Step 1.0 below for detailed instructions on how to do this.
+<critical_first_step>
+BEFORE ANY IMPLEMENTATION: You MUST run the `make operator-sdk create api` command first to scaffold the proper structure. See Step 1.0 below for detailed instructions on how to do this.
 
-**DO NOT** manually create files before running this command!
+DO NOT manually create files before running this command!
+</critical_first_step>
 
 ## Overview
 
+<overview>
 You are tasked with implementing a new Kubernetes Custom Resource for the `your-operator` project. This operator follows the chain of responsibility pattern for handling reconciliation logic.
+</overview>
 
 ## Implementation Steps
 
+<implementation_steps>
 Follow the [Operator SDK Tutorial](https://sdk.operatorframework.io/docs/building-operators/golang/tutorial/) as the foundation for implementing your controller.
+</implementation_steps>
 
-#### 1 Scaffold API and Controller
+### 1 Scaffold API and Controller
 
-**Before implementing the controller, ask the user for the CustomResource details:**
+<scaffold_api_controller>
+Before implementing the controller, ask the user for the CustomResource details:
 
-1. **Group**: The API group (typically use `v1` for this project)
-2. **Version**: The API version (typically `v1alpha1`)
-3. **Kind**: The CustomResource kind name (e.g., `KeycloakClient`, `KeycloakUser`, etc.)
+1. Group: The API group (typically use `v1` for this project)
+2. Version: The API version (typically `v1alpha1`)
+3. Kind: The CustomResource kind name (e.g., `KeycloakClient`, `KeycloakUser`, etc.)
 
 Once you have these details, use the Operator SDK to scaffold the basic API and controller structure:
 
 ```bash
 make operator-sdk create api --group <group> --version <version> --kind <kind> --resource --controller
 ```
 
-**Example**: If the user wants to create a `KeycloakClient` CustomResource:
+Example: If the user wants to create a `KeycloakClient` CustomResource:
 
 ```bash
 make operator-sdk create api --group v1 --version v1alpha1 --kind KeycloakClient --resource --controller
@@ -52,12 +65,14 @@ This command will create:
 - Basic RBAC markers
 
 After scaffolding, you'll need to customize the generated code to follow the project's specific patterns described in the sections below.
+</scaffold_api_controller>
 
-#### 2 Implement the API Types
+### 2 Implement the API Types
 
+<implement_api_types>
 Implement your Custom Resource Definition (CRD) spec and status, based on user requirements, in `api/v1alpha1/`:
 
-**Note**: The following examples use `YourResource` as a placeholder. Replace this with the actual resource name you specified during scaffolding.
+Note: The following examples use `YourResource` as a placeholder. Replace this with the actual resource name you specified during scaffolding.
 
 ```go
 // +kubebuilder:object:root=true
@@ -83,20 +98,26 @@ type YourResourceStatus struct {
 }
 ```
 
-#### 3 Generate Code and Manifests
+</implement_api_types>
+
+### 3 Generate Code and Manifests
 
+<generate_code_manifests>
 Run the following commands to generate the necessary code:
 
 ```bash
 make generate
 make manifests
 ```
 
-#### 4 Implement the Controller
+</generate_code_manifests>
 
+### 4 Implement the Controller
+
+<implement_controller>
 Implement your controller in `internal/controller/yourresource/` following the existing pattern:
 
-**Note**: Replace `YourResource` and `yourresource` with the actual resource name you specified during scaffolding.
+Note: Replace `YourResource` and `yourresource` with the actual resource name you specified during scaffolding.
 
 ```go
 package yourresource
@@ -231,15 +252,18 @@ func (r *ReconcileYourResource) updateYourResourceStatus(
 }
 ```
 
-#### 5 Implement the Chain of Responsibility
+</implement_controller>
+
+### 5 Implement the Chain of Responsibility
 
+<implement_chain>
 Create a chain package in `internal/controller/yourresource/chain/` with the following structure:
 
 1. `chain.go` - Main chain implementation
 2. `factory.go` - Chain factory
 3. Individual handler files for each step in the chain
 
-**Note**: Replace `yourresource` and `YourResource` with the actual resource name you specified during scaffolding.
+Note: Replace `yourresource` and `YourResource` with the actual resource name you specified during scaffolding.
 
 Example `chain.go`:
 
@@ -284,9 +308,11 @@ func MakeChain(k8sClient client.Client) Chain {
 ```
 
 Example handler implementations should follow the pattern of existing handlers in your chain.
+</implement_chain>
 
-#### 6 Register the Controller
+### 6 Register the Controller
 
+<register_controller>
 Add your controller to `cmd/main.go`:
 
 ```go
@@ -301,4 +327,5 @@ if err = yourresourcecontroller.NewReconcileYourResource(mgr.GetClient()).SetupW
 }
 ```
 
-**Note**: Replace `YourResource` with the actual resource name you specified during scaffolding.
+Note: Replace `YourResource` with the actual resource name you specified during scaffolding.
+</register_controller>
@@ -1,25 +1,38 @@
+---
+dependencies:
+  data:
+    - go-coding-standards.md
+    - operator-best-practices.md
+---
+
 # Task: Review Go code
 
 You are an expert Go developer and Kubernetes operator specialist tasked with reviewing Go code for quality, best practices, and adherence to standards.
 
 ## Prerequisites
 
-**IMPORTANT**: Before starting your review, you must read and fully understand the following documentation:
+<prerequisites>
+IMPORTANT: Before starting your review, you must read and fully understand the following documentation:
 
-1. **Read** [Go Coding Standards](./.krci-ai/data/go-coding-standards.md) - Apply ALL the Go development standards, best practices, naming conventions, error handling patterns, testing guidelines, and security practices defined in this document.
+1. Read [Go Coding Standards](./.krci-ai/data/go-coding-standards.md) - Apply ALL the Go development standards, best practices, naming conventions, error handling patterns, testing guidelines, and security practices defined in this document.
 
-2. **Read** [Operator Best Practices](./.krci-ai/data/operator-best-practices.md) - Apply ALL the Kubernetes operator-specific patterns, architectural principles, CRD design guidelines, and operational practices defined in this document.
+2. Read [Operator Best Practices](./.krci-ai/data/operator-best-practices.md) - Apply ALL the Kubernetes operator-specific patterns, architectural principles, CRD design guidelines, and operational practices defined in this document.
 
 Your review must be based on the standards and practices outlined in these documents. Do not proceed without reading them first.
+</prerequisites>
 
 ## Review Approach
 
-1. **Analyze the code** against all standards and practices from the required documentation
-2. **Identify violations** of the established guidelines
-3. **Provide specific, actionable feedback** with clear examples and references to the documentation
+<review_approach>
+1. Analyze the code against all standards and practices from the required documentation
+2. Identify violations of the established guidelines
+3. Provide specific, actionable feedback with clear examples and references to the documentation
+</review_approach>
 
 ## Review Output Format
 
+<review_output_format>
+
 ### Summary
 
 Brief overall assessment of code quality and adherence to standards.
@@ -28,11 +41,11 @@ Brief overall assessment of code quality and adherence to standards.
 
 For each issue found, provide:
 
-- **Category**: (e.g., "Go Standards Violation", "Operator Best Practice", "Security", etc.)
-- **Severity**: Critical | High | Medium | Low
-- **Description**: Clear explanation with reference to specific guideline from the documentation
-- **Location**: File and line number references
-- **Recommendation**: Specific fix with code example if helpful
+- Category: (e.g., "Go Standards Violation", "Operator Best Practice", "Security", etc.)
+- Severity: Critical | High | Medium | Low
+- Description: Clear explanation with reference to specific guideline from the documentation
+- Location: File and line number references
+- Recommendation: Specific fix with code example if helpful
 
 ### Strengths
 
@@ -45,10 +58,13 @@ Prioritized list of recommended fixes:
 1. Critical issues that must be addressed
 2. Important improvements
 3. Nice-to-have enhancements
+</review_output_format>
 
 ## Review Principles
 
+<review_principles>
 - Be constructive and educational
 - Reference the specific guidelines from the documentation
 - Provide concrete examples and suggestions
 - Balance thoroughness with practicality
+</review_principles>