move to a seperate docs directory

ARCH.md

@@ -1,34 +0,0 @@
-# ARCH - [project name]
-
-Architectural decisions and their reasoning. What components are used, how will they communicate, what libraries are to be used...
-
-## Overview
-
-Short description of structure. Diagrams and pictures are helpful.
-
-## Tech stack
-
-Brief description of technologies to be used.
-
-For example:
-- Pyton, 3.11+, Async support required
-- Pytest, 8.x, Testing
-
-## Most important architectural decisions.
-
-Examples:
-
-### Polling vs events
-- Decision: Polling every 10s
-- Options: Using interrupts
-- Why?: More simple to implement.
-
-## File structure
-
-src/
-  main.py
-  config.py
-
-tests/
-  tests.py
-

CONVENTIONS.md

@@ -1,23 +0,0 @@
-# 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

README.md

@@ -1,16 +1,37 @@
 # Aider project skeleton
 
-A personal template for starting new projects with Aider. Focused on disciplined AI assisted development. Loads SPEC, ARCH, CONVENTIONS and TESTS into AI context automatically so the model works against documented requirements instead of vibes.
+A personal template for starting new projects with AI coding tools. Focused on disciplined AI assisted development. Loads SPEC, ARCH, CONVENTIONS and TESTS into AI context automatically so the model works against documented requirements instead of vibes.
+
+## Quick start
+
+```bash
+git clone git@git.sirian.me:sirian/template-project.git my-project
+cd my-project
+rm -rf .git && git init && git add . && git commit -a -m "Initial commit from skeleton"
+```
+
+## Minimum starting point
+
+Before writing any code fill these two things:
+
+### 1. SPEC.md
+
+What are you building and who is it for?
+
+### 2. ARCH.md
+
+Stack and commands. What technologies and what commands does the AI need to know?
+
 
 ## What's in here
 
 - .aider.conf.yml - Aider config (models, auto-test..)
 - .gitignore - Common stuff easy to forget. 
-- SPEC.md - What the project does
-- ARCH.md - How it's built
-- CONVENTIONS.md - Code style rules the AI follows
-- TESTS.md - Test cases in natural language
-- JOURNAL.md - Personal session notes
+- docs/SPEC.md - What the project does
+- docs/ARCH.md - How it's built
+- docs/CONVENTIONS.md - Code style rules
+- docs/TESTS.md - Test cases in natural language
+- docs/JOURNAL.md - Personal session notes
 
 ## Philosophy
 

docs/ARCH.md

@@ -0,0 +1,43 @@
+# ARCH - [project name]
+
+Architectural decisions and their reasoning. What components are used, how will they communicate, what libraries are chosen...
+
+## Overview
+
+Short description of what we are building and its structure. 3-5 sentences.
+
+## Tech stack
+
+Brief description of technologies to be used.
+
+Example:
+- Pyton 3.11+, Async support required
+- Pytest 8.x, Testing
+
+## Commands
+
+- Lint: "ruff check src/"
+- Test: "pytest tests/ -x --tb=short"
+
+## File structure
+
+Example:
+src/
+  main.py
+  config.py
+
+tests/
+  test_main.py
+
+
+## architectural decisions.
+
+One section per non-obvious decision. What we choose, what we rejected, why. 
+
+Example:
+### Polling vs events
+- Decision: Polling every 10s
+- Options: Using interrupts
+- Why?: More simple to implement.
+
+

docs/CONVENTIONS.md

@@ -0,0 +1,39 @@
+# CONVENTIONS
+
+Rules for AI coding assistants working in this project. 
+
+## Code style
+- Follow the existing style in whatever file you're reading
+- Run the project's linter after every change and fix all issues
+- No "clever" one-liners if a longer form is clearer
+- No comments that restate the code. Comments explain "why" not "what"
+
+## Naming
+- Files and directories: snake_case
+- Functions and variables: snake_case
+- Classes: PascalCase
+- Database tables: snake_case, plural
+- No single-letter variable names. Except "i", "j", "k" in loop index
+
+## Patterns
+- Every API endpoint validates input before processing.
+- Errors use the frameworks standard error mechanism. Dont invent your own.
+
+## What NOT to do
+- Do not add new dependencies without explicit instruction. If proposing a dependency describe it in plain text. Do not install it.
+- Do not refactor adjacent code "while you're at it". Stay within the scope of the request.
+- Do not assume environment variables exist. If a new environment variable is needed state it clearly and add it to '.env.example'
+- Do not suppress type checker or linter errors without a comment explaining why.
+- Do not commit code that fails lint, type check or tests. 
+
+## Git
+- One logical change per commit
+- Commit messages are in imperative mood, lowercase and max 72 char title.
+- Good: "add email validation to user signup"
+- BAD: "added email validation to user signup"
+- BAD: "fix stuff"
+
+## Testing
+- Test files mirror source structure: "src/users/service.py" -> "tests/users/test_service.py"
+- Mock only external IO boundaries. Never mock our own modules, services or utilities.
+- Every new endpoint needs at minimum one test for the success case and one test for a validation error case.