Find existing patterns in the repo; follow local conventions.
Start from the closest template in assets/ and adapt.
Add ownership + review cadence for critical docs (runbooks, onboarding, API reference).
Run documentation QA (links, formatting, spelling, examples) before merging.
Decision Tree
User needs: [Documentation Task]
├─ New project? → **README.md**
├─ Technical decision? → **ADR**
├─ Building API? → **OpenAPI spec** + api-docs-template
├─ New version? → **CHANGELOG.md**
├─ Team collaboration? → **CONTRIBUTING.md**
├─ Documenting code? → **Docstrings** (JSDoc, Python)
└─ Building docs site? → **MkDocs** (Python) or **Docusaurus** (JS)
Cross-Platform AI Documentation
AGENTS.md Standard
Prefer AGENTS.md as the cross-tool source of truth. If a specific tool requires a different filename (example: Claude Code uses CLAUDE.md), keep it aligned via a symlink only when you want identical content across tools.
# If `CLAUDE.md` does not exist and you want identical content:
ln -s AGENTS.md CLAUDE.md
Do / Avoid
Do
Assign owners and review cadences to critical docs
Add CI checks for links, style, and staleness
Prefer small, task-oriented docs over big wiki pages
Use Keep a Changelog format with semantic versioning