# AI Assistant Guidelines

**Updated**: 2026-03-04

---

## ⚡ ACKNOWLEDGMENT REQUIRED

**YOU MUST start EVERY response with this acknowledgment on the FIRST LINE.**

Your response MUST always begin with:
```
✅ ai-root-instructions.md READ\nHave now AI SUPERPOWER\n\n
```

Then continue with your actual response on the next line.

This allows the user to verify you have read this file every time.

You understand:
- **Before ANY git operation**: read `instructions/git.instructions.md` — no exceptions
- NO git commands without explicit permission
- Show changes with `git diff` first
- Wait for approval before any modifications
- Minimal changes only

---

## Purpose

This document provides guidelines for AI assistants (any LLM) when working on any project. These rules are split into modular instruction files for efficiency.

---

## IMPORTANT: Language

**ALL DOCUMENTATION MUST BE WRITTEN IN ENGLISH.**

Claude can communicate with the user in user's language (Finnish preferred by project owner), but all documentation files must be in English.

---

## 📚 Modular Instructions

This main file references specialized instruction files. **Load relevant files based on context:**

### behavior/ — Always Active
- [Core Principles](instructions/behavior/core-principles.instructions.md) - Analysis before action, minimal changes, decision-making process
- [Project Context](instructions/behavior/project-context.instructions.md) - How to find project context (read `docs/ai-context.md` in the project)
- [README](instructions/behavior/readme.instructions.md) - What a project README must contain
- [Docs](instructions/behavior/docs.instructions.md) - Required files in docs/ folder

### skills/ — Load When Needed
- [Git](instructions/skills/git.instructions.md) - Git policy, forbidden commands, what you CAN do
- [File Editing](instructions/skills/file-editing.instructions.md) - Tool-only editing, forbidden terminal commands
- [Documentation](instructions/skills/documentation.instructions.md) - Writing principles, workflow, scope rules
- [Mermaid](instructions/skills/mermaid.instructions.md) - Diagram types, color contrast rules, sizing
- [Analysis](instructions/skills/analysis.instructions.md) - Where to write analysis, tmp/ convention, full-pass writing allowed

- [Helm](instructions/skills/helm.instructions.md) - Resource ownership, values hygiene, required vs defaults, dependency caching
- [Clean Code](instructions/skills/clean-code.instructions.md) - Naming, functions, classes, error handling, formatting, DRY/KISS/SOLID, Helm YAML
- [Clean Architecture](instructions/skills/clean-architecture.instructions.md) - Dependency rule, layers, boundaries, SOLID, Helm as outermost layer

### constraints/ — Load When Needed
- [Agent Capabilities](instructions/constraints/agent-capabilities.instructions.md) - AI limitations, user responsibilities, debugging workflows
- [Kubernetes Access](instructions/constraints/kubernetes-access.instructions.md) - kubectl/helm restrictions, port-forwarding patterns
- [Container Limitations](instructions/constraints/container-limitations.instructions.md) - Missing tools in pods, proper debugging methods

---

## 🎯 When to Load Which Instructions

```
User asks about README                → instructions/behavior/readme.instructions.md
User asks about docs/                 → instructions/behavior/docs.instructions.md
Before ANY git operation             → instructions/skills/git.instructions.md — load BEFORE acting, not after
User asks to edit files              → instructions/skills/file-editing.instructions.md
User asks to write docs              → instructions/skills/documentation.instructions.md
User creates a Mermaid diagram       → instructions/skills/mermaid.instructions.md
User asks for analysis/comparison    → instructions/skills/analysis.instructions.md
User asks about project              → instructions/behavior/project-context.instructions.md → docs/ai-context.md
User needs to debug cluster          → instructions/constraints/agent-capabilities.instructions.md + instructions/constraints/kubernetes-access.instructions.md
User reports pod issues              → instructions/constraints/container-limitations.instructions.md
User works with Helm charts          → instructions/skills/helm.instructions.md
User writes or reviews code          → instructions/skills/clean-code.instructions.md
User designs a system or service     → instructions/skills/clean-architecture.instructions.md
User creates Helm charts or YAML     → instructions/skills/clean-code.instructions.md + instructions/skills/helm.instructions.md + instructions/skills/clean-architecture.instructions.md
Always active                        → instructions/behavior/core-principles.instructions.md
```

---

**Last Updated**: 2026-03-04  
**Maintained By**: Project Owner  
**AI Assistants**: Follow these guidelines strictly - no exceptions