35 lines
1.7 KiB
Markdown
35 lines
1.7 KiB
Markdown
---
|
|
name: docs
|
|
description: Rules for maintaining the project's documentation folder (ai-context.md and architecture.md). Use when editing or creating project documentation files.
|
|
category: workflow
|
|
impact: low
|
|
---
|
|
|
|
> **🏷️ Category:** `Meta-Skill` | **⚙️ Applies to:** Project Documentation Management
|
|
|
|
# Docs Folder Instructions
|
|
|
|
## 🎯 Purpose
|
|
Maintain standardized documentation boundaries within the project, ensuring `ai-context.md` and `architecture.md` are correctly purposed and formatted.
|
|
|
|
## 🚨 Prohibitions
|
|
- **NEVER treat docs as a changelog.** Do not write "updated X on date Y".
|
|
- **NEVER let a single documentation file exceed ~150 lines.** Split it if it grows too large.
|
|
- **NEVER put architectural documentation in the `README.md` or inline comments.** It belongs in `docs/`.
|
|
- **NEVER leave the `<!-- ai-superpower:template -->` marker in a file after editing.** It must be removed immediately upon first touch.
|
|
|
|
## Workflows
|
|
|
|
### The Factory Template Marker
|
|
`docs/ai-context.md` and `docs/architecture.md` may start with a block like:
|
|
```html
|
|
<!-- ai-superpower:template
|
|
STATUS: factory default — not yet filled in
|
|
-->
|
|
```
|
|
**CRITICAL ACTION:** When you first touch a file that has this marker (even just to read/edit it), you MUST remove the `<!-- ai-superpower:template -->` block as your very first edit. This prevents `apply.sh` from accidentally overwriting it in the future.
|
|
|
|
### Documentation Types
|
|
- **`<docs>/ai-context.md` (For AI):** Project context — architecture, decisions, pitfalls. Link to `architecture.md` for diagrams rather than including them here.
|
|
- **`<docs>/architecture.md` (For Human + AI):** System overview with Mermaid diagrams. Must start with a Mermaid diagram and explain data flows in English.
|