From 102f593909c815efd9d6926830ac145d89bcf569 Mon Sep 17 00:00:00 2001 From: moilanik Date: Fri, 6 Mar 2026 09:42:48 +0200 Subject: [PATCH] feat: configurable docs folders + mandatory instructions rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit config.yaml: new repo-root config file with docs_folders list (docs, documentation, doc). apply.sh reads this list and picks the first existing folder per project instead of hardcoding docs/. Instructions: - core-principles: add No Vibe Coding and No Touching .ai/ sections - ai-root-instructions: add mandatory instructions block — rules stay active for the whole session, not just at start; AI must stop and announce if instructions were not loaded - project-context, docs: updated to list all docs folder alternatives and reference config.yaml as the source of truth FR-5.0 added to apply-requirements.md. README step 4 updated. --- .ai/ai-root-instructions.md | 21 +++++++++++++++-- .../behavior/core-principles.instructions.md | 23 +++++++++++++++++++ .../behavior/docs.instructions.md | 6 +++-- .../behavior/project-context.instructions.md | 12 ++++++++-- README.md | 2 +- apply.sh | 19 +++++++++++++-- config.yaml | 11 +++++++++ docs/apply-requirements.md | 3 ++- 8 files changed, 87 insertions(+), 10 deletions(-) create mode 100644 config.yaml diff --git a/.ai/ai-root-instructions.md b/.ai/ai-root-instructions.md index ad9fe95..1c5ac58 100644 --- a/.ai/ai-root-instructions.md +++ b/.ai/ai-root-instructions.md @@ -1,6 +1,6 @@ # AI Assistant Guidelines -**Updated**: 2026-03-04 +**Updated**: 2026-03-06 --- @@ -26,6 +26,23 @@ You understand: --- +## 🔒 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. @@ -90,6 +107,6 @@ Always active → instructions/behavior/core-principles.i --- -**Last Updated**: 2026-03-04 +**Last Updated**: 2026-03-06 **Maintained By**: Project Owner **AI Assistants**: Follow these guidelines strictly - no exceptions diff --git a/.ai/instructions/behavior/core-principles.instructions.md b/.ai/instructions/behavior/core-principles.instructions.md index cd2f7c6..97c903f 100644 --- a/.ai/instructions/behavior/core-principles.instructions.md +++ b/.ai/instructions/behavior/core-principles.instructions.md @@ -1,5 +1,26 @@ # Core Principles +## 🚫 Absolute Prohibitions + +### No Vibe Coding +**Vibe coding is completely forbidden.** + +Vibe coding means generating code by feel, momentum, or pattern-matching without understanding. Every line written must be: +- Understood by the AI before it is written +- Justified by the actual requirement +- The minimum needed to satisfy the requirement + +If the AI cannot explain why a specific line of code is correct, it must stop and ask — not guess and continue. + +### No Touching `.ai/` Without Explicit Instruction +The `.ai/` folder contains shared AI instructions used across all projects. It must **never** be modified unless the user explicitly asks to edit the instructions. + +- ❌ Do not add, edit, or delete files in `.ai/` as part of any other task +- ❌ Do not "improve" or "update" instructions while working on project code +- ✅ Only touch `.ai/` when the user's request is specifically about the instructions themselves + +--- + ## 🎯 Fundamental Rules ### 1. Analysis Before Action @@ -84,6 +105,8 @@ git status 9. ❌ **Use sed/awk/terminal for ANY file edits** - ALWAYS use file tools 10. ❌ **Use cat/echo/redirect operators (>, >>, <<) for file modifications** 11. ❌ **Modify files via terminal in ANY way** +12. ❌ **Vibe code** — never generate code by feel or momentum; understand every line +13. ❌ **Touch `.ai/`** unless the user explicitly asks to edit the instructions --- diff --git a/.ai/instructions/behavior/docs.instructions.md b/.ai/instructions/behavior/docs.instructions.md index aaf109a..7d9e638 100644 --- a/.ai/instructions/behavior/docs.instructions.md +++ b/.ai/instructions/behavior/docs.instructions.md @@ -2,10 +2,12 @@ ## Required Files +The docs folder may be named `docs/`, `documentation/`, or `doc/` — check which exists in the project. The full list is defined in `ai-superpower/config.yaml`. + | File | Audience | Purpose | |------|----------|---------| -| `docs/ai-context.md` | AI | Project context — architecture, decisions, pitfalls | -| `docs/architecture.md` | Human + AI | System overview with Mermaid diagrams | +| `/ai-context.md` | AI | Project context — architecture, decisions, pitfalls | +| `/architecture.md` | Human + AI | System overview with Mermaid diagrams | --- diff --git a/.ai/instructions/behavior/project-context.instructions.md b/.ai/instructions/behavior/project-context.instructions.md index 3273bb6..29d3261 100644 --- a/.ai/instructions/behavior/project-context.instructions.md +++ b/.ai/instructions/behavior/project-context.instructions.md @@ -4,7 +4,7 @@ **This file does not contain project-specific information.** -Each project maintains its own context document. When working in a project, find and read: +Each project maintains its own context document. When working in a project, search for `ai-context.md` in the following folders (in order): ``` docs/ai-context.md @@ -12,7 +12,15 @@ documentation/ai-context.md doc/ai-context.md ``` -Use whichever documentation folder the project already has. +These are the standard alternatives defined in `ai-superpower/config.yaml`. Use whichever folder exists in the project. If multiple exist (unlikely), prefer the first in the list above. + +Also look for `architecture.md` in the same folder: + +``` +docs/architecture.md +documentation/architecture.md +doc/architecture.md +``` This file contains everything you need to understand the project: - Architecture overview diff --git a/README.md b/README.md index 01865cd..d92863e 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ What it does: 1. Clones (or updates) this repo into `dev_root/ai-superpower/` 2. Scans for all projects (up to 4 levels deep) and creates a `.ai` symlink in each pointing to `ai-superpower/.ai/` 3. Adds `.ai` to each project's `.gitignore` -4. Creates `docs/ai-context.md` and `docs/architecture.md` templates in projects that have a `docs/` folder but no such files yet — asks first if the folder doesn't exist +4. Creates `ai-context.md` and `architecture.md` templates in the project's docs folder (`docs/`, `documentation/`, `doc/` — whichever exists) if the files are missing; asks first if no docs folder exists. The list of folder names is configured in `config.yaml`. 5. Writes a `.ai-superpower.version` file to your dev root with the run timestamp and commit hash ``` diff --git a/apply.sh b/apply.sh index f013ed5..af47470 100755 --- a/apply.sh +++ b/apply.sh @@ -40,6 +40,13 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" DEV_ROOT="${2:?DEV_ROOT not passed — re-run via curl}" AI_TARGET="$SCRIPT_DIR/.ai" TEMPLATE_MARKER="