moilanik 102f593909 feat: configurable docs folders + mandatory instructions rules

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.

2026-03-06 09:42:48 +02:00

1.6 KiB

Raw Blame History

Docs Folder Instructions

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

Contains everything AI needs to avoid bad suggestions:

What the system does
Key components and their relationships
Technical decisions and why they were made
What NOT to do (pitfalls, constraints)

Keep under 200 lines. Link to architecture.md for diagrams.

architecture.md

Start with a Mermaid diagram
Explain components and data flows
Written in English

Factory template marker

docs/ai-context.md and docs/architecture.md may start with this block:

<!-- ai-superpower:template
  STATUS: factory default — not yet filled in
  ...
-->

When you first touch a file that has this marker — even just to read it before writing — remove the marker line as the very first edit:

Remove the line 
Then write the actual content

The marker's presence tells apply.sh the file has not been edited yet and will be overwritten on the next run. Once removed, the file is owned by the project and will never be overwritten.

Rules

Docs are not a changelog — no "updated X on date Y"
If a doc exceeds ~150 lines, split it
If asked to document something, put it in docs/ — not README, not inline comments

1.6 KiB Raw Blame History