Initial commit

AGENTS.md

@@ -0,0 +1,83 @@
+# AI Agents - Project Rules
+
+**Document Version:** v4 (independent, incremented on structural changes)
+
+Rules and instructions for AI assistants (Claude Code, Cursor, Copilot, etc.)
+
+## First-time setup
+
+- **On first read of this file, immediately read all other `.md` files in the project root** (e.g. `PROJECT.md`, `CHANGELOG.md`, `DESIGN_DOCUMENT.md`) to get full project context before starting any task.
+
+## Language
+
+- **Always write all documentation in English**
+
+## Dependency Management
+
+- **Always use `poetry add`** to add dependencies, **never edit `pyproject.toml` directly**
+  ```bash
+  poetry add requests
+  poetry add --group dev pytest
+  ```
+- Use `poetry remove` to remove dependencies — **never edit `pyproject.toml` manually**
+
+## Project Structure
+
+- Entry points are in the project root (named after project or by purpose: `project_name.py`, `cli.py`, `gui.py`, `server.py`)
+- A project can have multiple entry points
+- All modules belong in the `src/` folder
+- Tests belong in the `tests/` folder
+- Virtual environment is in `.venv/` (do not copy, do not generate)
+
+## Code
+
+- Always use type annotations
+- Follow PEP8 and format with Ruff (88 characters per line)
+- Before commit run `poetry run ruff check` and `poetry run mypy`
+
+## Testing
+
+- **Use pytest exclusively** - never use the `unittest` module
+- No `unittest.TestCase` classes, no `self.assert*` methods
+- Use plain `assert` statements and pytest fixtures
+
+## Running
+
+- Use `poetry run` to run scripts:
+  ```bash
+  poetry run python project_name.py
+  poetry run pytest
+  ```
+
+## Logging
+
+- Use **loguru** for logging - never use `print()` for debugging
+- Never log secrets, passwords, tokens, or API keys
+
+## Environment and Secrets
+
+- Store secrets in `.env` file with `ENV_DEBUG=true/false` variable
+- Load secrets using `python-dotenv` and `os.getenv()`
+- **Never commit `.env` file**
+
+## Git
+
+- `.gitignore` should contain: `.venv/`, `__pycache__/`, `*.pyc`, `.mypy_cache/`, `.env`
+- Do not commit `poetry.lock` only if it's a library (for applications, commit it)
+- **Never commit this documentation** (`DESIGN_DOCUMENT.md`, `AGENTS.md`, `.claudeignore`)
+- `PROJECT.md` **should be committed** - it's project-specific
+
+## Versioning
+
+- **Always ask user before bumping version** - never increase version automatically
+- **Keep `CHANGELOG.md` updated** - document all significant changes as they are made
+- Update `CHANGELOG.md` with changes before version bump
+- Version is defined in `pyproject.toml` under `[project]` section
+- Follow semantic versioning (MAJOR.MINOR.PATCH)
+
+## Task Management
+
+- **When completing tasks, mark them as done** - if you finish any task with a checkbox anywhere in project documentation, check it off as completed `[ ]` → `[x]`
+- **Track all work** - this applies to tasks in `PROJECT.md` (TODO section, Development Roadmap, any checklists) and other documentation
+- **Update documentation** - when completing changes, update relevant sections in `PROJECT.md`, `CHANGELOG.md`, and architecture diagrams
+- **Keep task lists current** - completed items with `[x]` stay visible to show progress history