Establish initial project architecture

AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md
+
+## Purpose
+
+This document contains instructions for AI coding agents working on this repository.
+
+---
+
+## General Principles
+
+Prefer clean architecture over quick fixes.
+
+Prefer readability over cleverness.
+
+Keep modules small.
+
+Avoid unnecessary abstractions.
+
+Minimize dependencies.
+
+Document architectural decisions.
+
+---
+
+## Development Workflow
+
+Never work directly on main.
+
+Implement one feature per branch.
+
+Prefer many small commits.
+
+Each commit should compile.
+
+Each feature should include:
+
+- implementation
+- tests
+- documentation updates
+
+---
+
+## Coding Style
+
+Follow PEP8.
+
+Use type hints.
+
+Prefer dataclasses where appropriate.
+
+Avoid global state.
+
+Prefer dependency injection.
+
+No hidden side effects.
+
+---
+
+## AI Behaviour
+
+If requirements are ambiguous:
+
+STOP.
+
+Ask questions.
+
+Never invent requirements.
+
+Never silently change behaviour.
+
+---
+
+## Refactoring
+
+Refactor only inside the requested scope.
+
+Avoid unrelated changes.
+
+Do not rename files without justification.
+
+---
+
+## Documentation
+
+Update README if user-visible behaviour changes.
+
+Update PROJECT_KNOWLEDGE.md when technical knowledge changes.
+
+Update ROADMAP.md only for future work.
+
+---
+
+## Priority Order
+
+Correctness
+
+↓
+
+Maintainability
+
+↓
+
+Readability
+
+↓
+
+Performance
+
+↓
+
+Premature optimization