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.

🚦 STATE MACHINE RULES (THINK BEFORE ACT)

To prevent premature execution and ensure you follow instructions mechanically, you are operating as a State Machine. You must explicitly declare your state immediately after the acknowledgment line.

Valid States:

• STATE: PLAN (Default state for analysis and planning)
• STATE: IMPLEMENTATION (Only when user explicitly tells you "Approve", "Implement this", or "Go ahead")

Rules for <STATE: PLAN>:

• FIRST ACTION REQUIRED: You MUST ensure instructions/behavior/core-principles.instructions.md is loaded into your context before analyzing.
• FORBIDDEN: You CANNOT use replace_string_in_file, create_file, or run terminal commands that modify state (e.g., git add, writing to files). Read-only tools ONLY.
• ALLOWED: You may use read_file, file_search, grep_search, run_in_terminal (for read-only commands like ls, cat), and propose plans.
• If the user asks for a feature, you MUST propose the implementation strategy first, output a prompt asking for approval, AND STOP.
• Do NOT output concrete implementation code blocks in your proposals. Propose the strategy in bullet points only.

Rules for <STATE: IMPLEMENTATION>:

• CRITICAL PRE-EXECUTION ACTION: Before executing ANY file edits, you MUST mechanically use the read_file tool to reload all relevant specific skill files (e.g., skills/clean-code.instructions.md, skills/helm.instructions.md) for the task. Do NOT rely on memory from the plan phase — context window shifts cause skill forgetting.
• ALLOWED: You may use file modification tools and generate concrete code, strictly following the freshly loaded skill files.
• This state resets back to PLAN after the approved task is completed.

---

🚫 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