- 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
- introduce active skill echoing to prevent context window forgetting during execution
- enforce strict state machine transitions back to planning mode after execution
- replace AI apologies and empty promises with mandatory post-mortem rule updates
- emphasize quality over speed as a core behavioral principle
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
-root relied on AI already having read the instructions — useless for
session start. Replaced with a direct read instruction at the top of
README that works regardless of prior context.
apply.sh was scanning its own directory and creating a recursive .ai
symlink inside .ai/, causing infinite folder nesting in VS Code.
- Skip $SCRIPT_DIR in scan_projects() to prevent self-symlinking
- Remove incorrectly created .ai/.ai symlink and .ai/.gitignore
- Add -root session reset command to ai-root-instructions.md
- Document -root command in README
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
config.yaml: new repo-root config file with docs_folders list
(docs, documentation, doc). apply.sh reads this list and picks the
first existing folder per project instead of hardcoding docs/.
Instructions:
- core-principles: add No Vibe Coding and No Touching .ai/ sections
- ai-root-instructions: add mandatory instructions block — rules stay
active for the whole session, not just at start; AI must stop and
announce if instructions were not loaded
- project-context, docs: updated to list all docs folder alternatives
and reference config.yaml as the source of truth
FR-5.0 added to apply-requirements.md. README step 4 updated.
curl ... | bash -s -- --update pulls the latest .ai/ files and exits
without scanning projects or touching docs templates.
Bootstrap captures the pre-pull commit hash and forwards it to local
mode; local mode compares with HEAD and either reports "already up to
date" or prints new commit messages with git log --oneline.
FR-1.5 added to apply-requirements.md. README and apply.md updated.
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.
Remove QUICK-REFERENCE.md from .ai/ — it contained kube-log project-specific
content (hardcoded paths, OpenShift/ArgoCD config) that was leaking into all
projects via the symlink.
Update docs to match the actual apply.sh implementation:
- apply.md: rewrite to reflect curl-only invocation, bootstrap/local phases,
factory-reset marker behaviour; remove .ai-instructions.conf and interactive
checklist references
- architecture.md: remove scripts/ subdirectory and .ai-instructions.conf that
were never implemented
- apply-usecases.md: remove INSTALL subgraph (rm -rf + cp -r was never done),
fix symlink targets to SCRIPT_DIR/.ai
- apply-requirements.md: NFR-1 corrected (TTY-gated prompt exists), NFR-4
updated to <150 lines, .ai-instructions.conf removed from out-of-scope list
- ask [y/N] per project when docs/ folder is missing
- bootstrap reopens stdin from /dev/tty so prompts work through curl | bash
- fallback to silent skip when stdin is not a TTY (non-interactive)
- docs/apply-requirements.md: FR-1.4 and FR-5.1 updated
