From 598db63a707678e0c639658e049f8f499707780e Mon Sep 17 00:00:00 2001 From: moilanik Date: Mon, 13 Apr 2026 10:38:16 +0300 Subject: [PATCH] docs(ai): introduce state machine flow and Mermaid rendering rules Implement a mandatory State Machine model (PLAN and IMPLEMENTATION states) in root instructions to prevent the AI from generating code prematurely. The rules require mechanical reloading of skill files during execution to combat context-window memory loss. Also update Mermaid diagram instructions to explicitly ban
tags for newlines and prohibit raw angle brackets (<, >) in nodes, enforcing real newlines and HTML entities (<, >) to fix rendering issues. --- .ai/ai-root-instructions.md | 21 ++++++++++++++++++- .../skills/mermaid.instructions.md | 16 +++++++++++++- 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/.ai/ai-root-instructions.md b/.ai/ai-root-instructions.md index 938d1ea..d43618e 100644 --- a/.ai/ai-root-instructions.md +++ b/.ai/ai-root-instructions.md @@ -15,7 +15,26 @@ Your response MUST always begin with: Then continue with your actual response on the next line. -This allows the user to verify you have read this file every time. +## 🚦 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 ``:** +- **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 ``:** +- **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. --- diff --git a/.ai/instructions/skills/mermaid.instructions.md b/.ai/instructions/skills/mermaid.instructions.md index 174aaac..418dcac 100644 --- a/.ai/instructions/skills/mermaid.instructions.md +++ b/.ai/instructions/skills/mermaid.instructions.md @@ -17,7 +17,7 @@ Use `-- "text" -->` syntax, **not** `-->|text|` syntax. ## Line Breaks (Multiline Text) -Do not use `\n` for line breaks inside Mermaid nodes or labels. It does not always render correctly. +Do not use `\n`, `
`, or `
` for line breaks inside Mermaid nodes or labels. They do not always render correctly. Instead, use actual line breaks (real newlines) inside quoted text. ``` @@ -25,6 +25,20 @@ Instead, use actual line breaks (real newlines) inside quoted text. Second line"] ❌ B["First line\nSecond line"] +❌ C["First line
Second line"] +``` + +--- + +## Angle Brackets and Special Characters + +Do not use raw `<` or `>` characters in Mermaid nodes or labels (e.g. `-idp-deployment`), as they are often parsed as HTML tags and break rendering. +Instead, use HTML entities `<` and `>`. + +``` +✅ A["<customer>-idp-deployment"] + +❌ B["-idp-deployment"] ``` ---