---
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: meta
---

> **🏷️ 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.