- enforce strict isolation of scratch work into categorized subfolders
to prevent pollution of the project root and temporary root
- prohibit obfuscating Helm resource names behind complex logic
functions to prioritize readability in internal deployment manifests
Implement a mandatory State Machine model (PLAN and IMPLEMENTATION states)
in root instructions to prevent the AI from generating code prematurely.
The rules require mechanical reloading of skill files during execution
to combat context-window memory loss.
Also update Mermaid diagram instructions to explicitly ban <br> tags for
newlines and prohibit raw angle brackets (<, >) in nodes, enforcing
real newlines and HTML entities (<, >) to fix rendering issues.
The \n literal often fails to render correctly in Mermaid nodes. The
guidelines now require using actual newlines inside quoted text to
ensure multiline content displays reliably.
Update commit message guidelines to strictly forbid listing filenames or
technical code edits in the body. The revised rules require describing the
high-level topics and accomplished goals to ensure messages remain abstract
and easily readable.
- Lisätty Sääntö 0: Oletuksena Read-Only (Proposal Mode), jotta AI ei muokkaa tiedostoja ilman suoraa lupaa.
- Painotettu laatua, kontrollia ja oppimista nopeuden sijaan hätäilyn estämiseksi.
- Tiukennettu suoritussääntöjä: vaaditaan suostumus kaikkiin muutoksiin, ei vain "tuhoisiin".
- Lisätty Systems Thinking -sääntö putkinäön estämiseksi (huomioi infatason ongelmat kuten levytila, proxyt).
- Lisätty Constructive Pushback -sääntö: AI sparraa ja perustelee, eikä "jankuta" tai myötäile sokeasti.
- Siirretty aktiivisen verkkodebuggauksen (curl, port-forward) ohjeet helm-skilliin.
- enforce one code block with only message content for copy/paste
- disallow prose or labels outside the code block
- add explicit correct and wrong output examples
- read diff before writing, only include what's in the diff
- no CHANGES: headers, no speculative outcome sections
- bullet points state what changed, not why or how
New subsection "Multiple Files in ConfigMap data":
- start with inline range for few files (readable in template)
- shift to files/ + .AsConfig + tpl when >3 files (readability suffers)
- explains threshold for when to switch patterns
- shows both inline and file-based examples
- enables template variables in file-based approach
Audit checklist should only check hardcoded namespaces and required+default conflicts.
Resource names are not violations — they depend on subchart implementation and must be
tested via helm template, not audited via grep.
Testing Templates section rewritten:
- require testing with at least 2 different release names and namespaces
- verify resource names, labels, selectors linkage works correctly in both
- verify manifest links (Service → Deployment) use correct names/namespaces
- this is how you validate chart portability, not via code inspection
IaC principle clarified:
- chart must be deployable to any cluster/namespace without editing
- deployment discipline prevents two instances in same cluster/namespace
- not a chart constraint, a deployment constraint
Audit checklist:
- add explicit grep-based checks for hardcoded namespaces, names, required+default conflicts, unused values keys
- scope name checks to templates/ only — hardcoded names in values.yaml are legitimate
- fix required error message example to include what to set and where
New sections:
- values.yaml Is Not Rendered — fixed names in values.yaml for subchart coordination are correct
- Never Hardcode Namespace / Release Name — hard rule with IaC principle rationale
- Glue Configuration pattern — documented exception for subchart coordination (e.g. Tempo + MinIO)
values.yaml hygiene rewrite:
- two purposes: static baseline + umbrella glue (wiring subcharts into one unit)
- goal is a short, minimal file identical across all installations
- installation-specific values belong exclusively in values.<instance>.yaml
- forbidden: empty placeholders, defaults for rarely-changed values, required-value entries
required vs defaults rewrite:
- sensible default → hardcode in template, not in values.yaml
- must-vary value → required with descriptive message, no entry in values.yaml
- | default forbidden
- required error messages must say exactly what to set and where
KISS addition:
- hardcoded values are the starting point, not a compromise
- parameterize only when developer asks, and into values.<instance>.yaml
Add hard rule: charts must be fully agnostic about installation target.
- Never hardcode namespace in any template — use .Release.Namespace or omit
- Never hardcode release name — use .Release.Name / fullname helper
- Enforce IaC principle: deployer decides where, chart describes what
New skill files:
- clean-code.instructions.md — naming, functions, classes, error handling,
formatting, DRY/KISS/SOLID, Helm YAML conventions
- clean-architecture.instructions.md — dependency rule, layers, boundaries,
SOLID foundation, Helm as outermost layer
- helm.instructions.md — resource ownership, values hygiene, required vs
defaults, umbrella chart pattern, two-file values layering, KISS principle,
hook ordering, config files pattern, dependency caching, template testing
Register all three in ai-root-instructions.md skills list and routing table.
Remove .ai from .gitignore — .ai/ is the product in this repo and must be
tracked; the apply.sh skip-by-marker mechanism prevents changes to other repos.
