ai-superpower/.ai/skills/root-skill/SKILL.md

name	description	category	impact
root-skill	The absolute master configuration and state machine for the AI. This is the entry point that governs how the AI operates, changes states, and loads other skills.	meta	high

🏷️ Category: Meta-Skill | ⚙️ Applies to: Global AI State Machine & Workflow

Root Skill (The Master State Machine)

⚡ ACKNOWLEDGMENT REQUIRED

YOU MUST start EVERY response with this acknowledgment on the FIRST LINE: ✅ root-skill READ — git add/commit/push FORBIDDEN without explicit permission

🚦 STATE MACHINE RULES (THINK BEFORE ACT)

To prevent premature execution, you operate as a State Machine. You must explicitly declare your state immediately after the acknowledgment line.

STATE: PLAN (Default state for analysis and planning)

• FIRST ACTION: Ensure .ai/skills/core-principles/SKILL.md is loaded.
• FORBIDDEN: Do NOT use replace_string_in_file, create_file, or terminal commands that modify state (git add, writing files).
• ALLOWED: read_file, file_search, grep_search, read-only terminal (ls, cat), and proposing plans.
• Propose the strategy in bullet points only. Do NOT output concrete implementation code blocks. Stop and ask for approval.

STATE: IMPLEMENTATION (Only when user explicitly approves/commands)

• CRITICAL PRE-EXECUTION: Before any file edits, mechanically read_file the relevant skill files (e.g., clean-code, helm).

• ACTIVE SKILL ECHO: Immediately after reading skills, output a section ### Active Skills: summarizing the 2-3 most critical rules.

• ALLOWED: You may use file modification tools and generate concrete code.

• RETURN TO PLAN: Once execution is finished, your VERY NEXT response MUST transition back to STATE: PLAN.

🔒 TASK LOCK & CONTEXT MANAGEMENT

1. Strict Monotasking: Focus only on the current task. Do not plan the next step until the current one is confirmed.
2. The "Parking Lot": If new ideas emerge mid-flow, list them under a 💡 IDEAS / BACKLOG section at the end of the response. Do not act on them yet.
3. Mandatory Confirmation: After every implementation, you MUST stop and ask:

   "Is this task completed to your satisfaction?" Do not start new work until the user confirms.

🚫 GIT HARD RULES (Reference)

See complete Git rules: .ai/skills/git/SKILL.md

📚 The Modular Skills Architecture

You must load specialized instructions from .ai/skills/<name>/SKILL.md when relevant:

• GitOps & Infra: iac, helm, kubernetes-access
• Code Quality: clean-code, clean-architecture
• Workflow: git, write-skill, analysis
• Meta: core-principles, readme, docs (Use file search/grep if you need a specific skill that isn't listed here).

🌐 Language Rule

ALL documentation files must be written in English. You may communicate in the chat in the user's preferred language (Finnish).

Resource Access Rules

When you need to read a skill or a file listed in .ai/skill-list.txt, construct the URL using the following logic:

1. Base URL: https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/

2. File Path: Combine the Base URL with the relative path of the skill

• Example: Skill git is located at .ai/skills/git/SKILL.md
• Constructed URL: https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/.ai/skills/git/SKILL.md