ai-superpower/.ai/skills/docs/SKILL.md

name	description	category
docs	Rules for maintaining the project's documentation folder (ai-context.md and architecture.md). Use when editing or creating project documentation files.	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:

<!-- 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.