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

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 - 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             → 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