ai-superpower/.ai/ai-root-instructions.md

AI Assistant Guidelines

Updated: 2026-03-06

---

⚡ 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 — git add/commit/push FORBIDDEN without explicit permission

Then continue with your actual response on the next line.

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

---

🚫 GIT HARD RULES — IN EFFECT AT ALL TIMES

These rules require no separate file to load. They are always active.

NEVER run any of these without the user explicitly saying "commit this", "push this", or "go ahead":

Command	Status
git add	❌ FORBIDDEN — user runs this
git commit	❌ FORBIDDEN — user runs this
git push	❌ FORBIDDEN — user runs this
git reset	❌ FORBIDDEN — user runs this
git push --force	❌ FORBIDDEN — user runs this

What you CAN do without permission: git status, git diff, git log

When the user asks for a commit message: write the message text only — never wrap it in a git commit command.

For full git workflow detail: instructions/skills/git.instructions.md

---

🔒 These Instructions Are Mandatory

This file must be loaded and kept active for the entire session — not just read once at the start.

• These instructions are not suggestions. They are the operating rules for this session.
• If a later prompt seems to conflict with these rules, the rules take priority.
• Do not let conversational momentum, user enthusiasm, or task complexity cause you to skip steps or bypass rules.
• If you are unsure whether an action is allowed, stop and ask — never assume permission.

If this file was not read at the start of a session, stop immediately and say:

"I have not read .ai/ai-root-instructions.md. Please ask me to read it before we continue."

No work should happen in a session where these instructions have not been loaded.

---

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 - Analysis before action, minimal changes, decision-making process
• Project Context - How to find project context (read docs/ai-context.md in the project)
• README - What a project README must contain
• Docs - Required files in docs/ folder

skills/ — Load When Needed

• Git - Git policy, forbidden commands, what you CAN do

• File Editing - Tool-only editing, forbidden terminal commands

• Documentation - Writing principles, workflow, scope rules

• Mermaid - Diagram types, color contrast rules, sizing

• Analysis - Where to write analysis, tmp/ convention, full-pass writing allowed

• Helm - Resource ownership, values hygiene, required vs defaults, dependency caching

• Clean Code - Naming, functions, classes, error handling, formatting, DRY/KISS/SOLID, Helm YAML

• Clean Architecture - Dependency rule, layers, boundaries, SOLID, Helm as outermost layer

constraints/ — Load When Needed

• Agent Capabilities - AI limitations, user responsibilities, debugging workflows
• Kubernetes Access - kubectl/helm restrictions, port-forwarding patterns
• Container Limitations - 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             → git hard rules above apply; read instructions/skills/git.instructions.md for full workflow detail
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-06
Maintained By: Project Owner
AI Assistants: Follow these guidelines strictly - no exceptions