99d13e6e4a
- apply.sh: direct-run guard (only curl | bash allowed) - apply.sh: DEV_ROOT passed as explicit arg from bootstrap - apply.sh: .ai/ copied to dev root as real folder; projects symlink there - apply.sh: counters + detailed summary (version prev→new, templated, refreshed, no-docs) - apply.sh: find errors silenced, no crash on empty dev root - .ai-superpower: added warning comment about deletion side effects - .gitignore: .ai-instructions.conf → .ai-superpower.version - scripts/: removed (hello.sh, scan-projects-with-git.sh, verify-docs-folder.sh, add-ai-context-to-docs-folder.sh) - templates: monorepo sections split into AI instructions + developer instructions - README.md: rewritten to match current architecture and behaviour - docs/apply-requirements.md: FR-2.4, FR-3, FR-5, FR-6, FR-7, FR-8 updated - docs/apply-usecases.md: full detailed Mermaid flowchart replacing placeholder
54 lines
1.5 KiB
Markdown
54 lines
1.5 KiB
Markdown
# Docs Folder Instructions
|
|
|
|
## Required Files
|
|
|
|
| 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
|