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