diff --git a/.ai/instructions/skills/analysis.instructions.md b/.ai/instructions/skills/analysis.instructions.md index 1cd876f..439ab93 100644 --- a/.ai/instructions/skills/analysis.instructions.md +++ b/.ai/instructions/skills/analysis.instructions.md @@ -5,7 +5,7 @@ Analysis documents are scratch work — comparisons, evaluations, investigations ## Where to write ``` -tmp//filename.md +tmp//.md ``` Examples: @@ -13,7 +13,9 @@ Examples: - `tmp/curl-installer/design.md` - `tmp/harness-options/analysis.md` -`TOPIC` is a short slug describing the subject area. `filename` describes what the document contains. Use lowercase and hyphens. +`TOPIC` is a short slug describing the subject area. `<title>.md` describes what the document contains. Use lowercase and hyphens. + +**CRITICAL RULE:** Do NOT create analysis files or any temporary files in the project root. Always use the `tmp/<topic>/` folder structure. ## Scope diff --git a/.ai/instructions/skills/file-editing.instructions.md b/.ai/instructions/skills/file-editing.instructions.md index 80d091d..857f882 100644 --- a/.ai/instructions/skills/file-editing.instructions.md +++ b/.ai/instructions/skills/file-editing.instructions.md @@ -45,48 +45,52 @@ --- -## 📁 Output File Management +## 📁 Scratch and Temporary Files (Testing, Terminal outputs, Work drafts) -**CRITICAL: Save all reports, test results, and temporary outputs to project's tmp/ directory** +**CRITICAL: NEVER create temporary, testing, or intermediate files in the project root or source directories.** + +All scratch work, terminal outputs, test scripts, and experimental code MUST be created in the project's `tmp/` directory using a specific structure: + +``` +tmp/<topic>/<title>.<extension> +``` + +- **`topic`**: A short, hyphenated slug describing the feature, bug, or task you are working on (e.g., `auth-flow-tests`, `db-migration`). +- **`title`**: What the file actually contains (e.g., `curl-test`, `raw-manifest`). +- **`<extension>`**: The appropriate file extension for the content (e.g., `.sh`, `.json`, `.yaml`, `.py`). ### File Output Rules: -- ✅ **ALWAYS use:** `kube-log/tmp/` for all generated files -- ❌ **NEVER use:** `/tmp/` (system temp - outside project) -- ❌ **NEVER use:** `~/` (user home - outside project) +- ✅ **ALWAYS use topic subfolders:** `tmp/<topic>/<filename>` for all generated temporary files, scripts, and logs. +- ❌ **NEVER use `tmp/` root:** Do NOT create files directly under `tmp/` (e.g., `tmp/test.sh`). The folder will bloat and become impossible to navigate. +- ❌ **NEVER use Project root:** (e.g., `./test.py`, `./output.txt`). +- ❌ **NEVER use System `/tmp/` or user home `~/`:** (They are outside project context and invisible to the user). ### Examples: **Correct:** ```bash # Helm template outputs -helm template monitoring . > kube-log/tmp/monitoring-manifests.yaml +helm template monitoring . > tmp/monitoring-setup/rendered-manifests.yaml -# Test results -cat > kube-log/tmp/test-results.md << 'EOF' -# Test Results -... -EOF +# Temporary test scripts +create_file("tmp/auth-flow/test-token.sh", "...") -# Analysis reports -cat > kube-log/tmp/analysis-report.txt << 'EOF' -... -EOF +# JSON payload for curl +create_file("tmp/payment-api/test-payload.json", "...") ``` **Wrong:** ```bash +# DON'T write to project root! +helm template monitoring . > rendered-manifests.yaml +create_file("test-token.sh", "...") + # DON'T use system /tmp helm template monitoring . > /tmp/monitoring-manifests.yaml - -# DON'T use user home -cat > ~/test-results.md << 'EOF' ``` -### Why Project tmp/ Directory: -- ✅ Keeps all project artifacts together -- ✅ Easy for user to find and review -- ✅ Can be added to .gitignore -- ✅ Preserved across sessions -- ✅ Part of project context - -**Note:** Create `kube-log/tmp/` directory if it doesn't exist before writing files. +### Why use `tmp/<topic>/`: +- ✅ Keeps the project root clean. +- ✅ Groups related investigation files together by topic. +- ✅ The entire `tmp/` folder is `.gitignore`d, preventing accidental commits of test data. +- ✅ Easy for the user to review or delete later. diff --git a/.ai/instructions/skills/helm.instructions.md b/.ai/instructions/skills/helm.instructions.md index 1cdd870..8518dfa 100644 --- a/.ai/instructions/skills/helm.instructions.md +++ b/.ai/instructions/skills/helm.instructions.md @@ -119,6 +119,16 @@ name: {{ include "mychart.fullname" . }} name: {{ .Release.Name }}-service ``` +### 🏷️ Explicit Resource Naming (Readability over Helpers) + +**❌ FORBIDDEN:** Hiding resource names behind complex `fullname`, `name`, or `chart` helper functions in umbrellas (e.g., `name: {{ include "mychart.fullname" . }}`). +**✅ REQUIRED:** Write explicit, readable resource names directly in the manifest using `.Release.Name` and the component name (e.g., `name: {{ .Release.Name }}-keycloak`). + +### Why — Clean Code Readability Principle +Helm's default `_helpers.tpl` generators are designed for publicly distributed charts that require aggressive overriding. For internal or umbrella charts, this obfuscates the codebase. A developer reading a `deployment.yaml` should instantly see the exact name of the resource without opening `_helpers.tpl` to parse logical conditionals. + +*Exception: Standardized Kubernetes labels (`app.kubernetes.io/*` and `helm.sh/chart`) MUST still be centralized in a `common` library chart using helpers (e.g., `{{ include "common.labels" . }}`) to keep the DRY principle intact across hundreds of files.* + ### Why — IaC Principle The chart is infrastructure code. It must be deployable to any cluster, any namespace, any environment, by any deployer — without editing the chart itself. Installation-specific decisions belong exclusively in `values.<installation>.yaml` in the deployment repo.