moilanik 191f9f4f2a refactor(ai-skills): harden control flow and reduce instruction drift

Tighten root/core control flow, add dedicated post-mortem, web, and
context-hygiene capabilities, and reduce instruction drift through clearer
ownership, conflict-priority handling, and README/docs workflow alignment.
This makes long-session AI behavior more deterministic while keeping the
instruction system compact and maintainable.

2026-04-21 16:01:21 +03:00

3.5 KiB

Raw Blame History

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

Root Skill (Compact Runtime Contract)

⚡ Mandatory First Line

Every response MUST start with: ✅ root-skill READ — git add/commit/push FORBIDDEN without explicit permission

🚦 State Machine

State ownership: root-skill is the single source of truth for state transitions.
Default: STATE: PLAN
Enter STATE: IMPLEMENTATION only on explicit user command.
After implementation, next response MUST return to STATE: PLAN.

🔒 Mandatory Per-Response Structure

Every response MUST include:

Current Progress

Completed sub-tasks
[/] Current active focus:
Remaining items in this task

If omitted, immediately send a correction message with the block.

Task Continuity (Required)

To prevent drift when work branches into prerequisites, every response MUST also preserve:

Main task: the original user goal
Current sub-task: what is being handled now
Prerequisite reason: why this sub-task is needed
Return point: what task is resumed after prerequisite completes

🧭 Context & Safety Protocol

Priority fallback (unless explicitly overridden for current task): root-skill > core-principles > domain skill (iac/helm/etc.) > workflow skill.

Every 3rd message include exactly: Re-verifying state: Still in [STATE], following root-skill constraints.
If a new technology appears, refresh .ai/skill-list.txt. 2.1 If loaded skills have potential overlap/conflict, declare priority in one sentence before acting.
If corrected after a mistake, run post-mortem flow and propose preventive skill update.
If requirements are unclear or assumptions are needed, load .ai/skills/grill-me/SKILL.md and clarify one question at a time before implementation.
After every implementation, ask: Is this task completed to your satisfaction?
In browser/web AI environments, load .ai/skills/web-ai/SKILL.md.
If a prerequisite task is started, explicitly state when returning to the original main task.
If long-session context gets noisy, load .ai/skills/context-hygiene/SKILL.md.
Session bootstrap gate: if user asks to read instructions first (or points to .ai at session start), complete preflight before any other work.

🔄 Active Refresh (Per Message)

Before handling each user message:

Re-read root-skill and core-principles (first ~100 lines or whole file if shorter).
Re-read .ai/skill-list.txt and select top relevant skills by name + description.
If reads fail, notify user and continue with last known summary.
Every response must include: Skills used: ...

🧩 Skill Routing

Load relevant skills from .ai/skills/<name>/SKILL.md:

Infra: iac, helm, kubernetes-access
Code: clean-code, clean-architecture
Workflow: git, write-skill, analysis, grill-me
Focus: context-hygiene (long-session refocus and branch parking)
Web: web-ai (browser/remote AI environments only)
Meta: core-principles, readme, docs

Canonicality note:

.ai/skill-list.txt is canonical for available skills and descriptions.
The routing categories above are illustrative selection helpers.

🌐 Language Rule

Documentation files MUST be in English. Chat language follows user preference.

🔗 Git Rules

See .ai/skills/git/SKILL.md for full Git constraints.

3.5 KiB Raw Blame History