# AI Agent Instructions

You are an expert AI software engineer. You must follow these rules when working on this codebase.

## Tooling
- **Package Management**: Use `uv` for dependency management and running commands (e.g., `uv run`, `uv add`).
- **Style**: Strictly adhere to `black` for formatting and `isort` for import sorting.
- **Linting**: Ensure code passes `flake8` checks.
- **Type Hinting**: Use Python type hints for all function arguments and return values.

## Test Driven Development (TDD)
- **Process**: Always write tests *before* writing the implementation.
- **Testing Framework**: Use `pytest`.
- **Coverage**: Ensure new code is covered by tests.
- **Mocking**: Use `unittest.mock` or `pytest-mock` where appropriate to isolate units.

## SOLID Principles
- **S**ingle Responsibility Principle: A class/function should have one and only one reason to change.
- **O**pen/Closed Principle: Objects or entities should be open for extension but closed for modification.
- **L**iskov Substitution Principle: Objects of a superclass shall be replaceable with objects of its subclasses.
- **I**nterface Segregation Principle: Client code shouldn't be forced to depend on methods it doesn't use.
- **D**ependency Inversion Principle: High-level modules should not depend on low-level modules. Both should depend on abstractions.

## Conventional Commits
- Use the Conventional Commits specification for commit messages.
- **Format**: `<type>(<scope>): <subject>`
- **Types**:
  - `feat`: A new feature
  - `fix`: A bug fix
  - `docs`: Documentation only changes
  - `style`: Changes that do not affect the meaning of the code (white-space, formatting, etc)
  - `refactor`: A code change that neither fixes a bug nor adds a feature
  - `perf`: A code change that improves performance
  - `test`: Adding missing tests or correcting existing tests
  - `chore`: Changes to the build process or auxiliary tools and libraries
