Initial commit

CONVENTIONS.md

@@ -0,0 +1,23 @@
+# CONVENTIONS
+
+Rules ai tools must follow
+
+## General
+
+- Write code you understand yourself. If you cannot explain a line it doesn't belong here
+- No "clever" one-liners if a longer form is clearer
+- Function name says what it does, docstring why
+- No comments that restate the code. Comments say "why" not "what"
+
+## Git
+
+- One logical change per commit
+- Commit message in active voice: "add feature x" NOT "added feature X"
+
+
+## What NOT to do
+
+- No new dependencies without discussion (propose to ARCH.md, don't add)
+- Don't mess with code style. Follow what is already there
+- Don't refactor adjacent code "while you're at it"
+- No assumed environment variables without decumenting in ARCH.md