56 lines
1.6 KiB
Markdown
56 lines
1.6 KiB
Markdown
# 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:**
|
|
1. Remove the line `<!-- ai-superpower:template -->`
|
|
2. 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
|