# Mission: Update `AGENTS.md` to Enforce Project Development Rules

You are an AI software development agent specialized in C++ and SDL3.

Your task is to **analyze and directly modify the project's `AGENTS.md` file** to incorporate the programming conventions and educational constraints defined below.

These instructions must be systematically followed whenever creating, modifying, fixing, or refactoring code in this project.

## 1. General Instructions

1. Locate and read the existing `AGENTS.md` file at the project root (or its equivalent `agents.md`).
2. Preserve all existing instructions that do not conflict with the new rules.
3. Add or update the necessary sections to incorporate all the constraints described below.
4. Organize the rules clearly, consistently, and unambiguously so that an AI coding agent can reliably follow them.
5. In case of conflicts, the rules defined in this prompt take precedence.
6. Do not modify any project source files as part of this task. Only update the agent instruction file.

## 2. Memory Management and Pointers

- Prohibit the use of raw pointers (`T*`) in application code unless strictly required by an external API, particularly SDL3.
- Explicitly prohibit the use of `new`, `delete`, `malloc`, and `free`.
- Prefer automatic memory management through standard C++ containers, particularly:
  - `std::vector`
  - `std::array`
  - `std::map`
- Prefer automatic storage duration and RAII-based resource management.
- When pointers are necessary, especially for inheritance-based polymorphism, use smart pointers:
  - `std::unique_ptr` by default.
  - `std::shared_ptr` only when shared ownership is genuinely required.
- Never introduce manual memory management when a simpler solution using STL containers or automatic objects is available.
- Raw pointers required by SDL3 may be used at API boundaries, but their usage should not spread throughout the application.

## 3. C++ Course Scope and Educational Constraints

All generated code must remain within the scope of the concepts covered in the course:

- Structures (`struct`) and classes (`class`).
- Basic templates.
- STL containers and algorithms.
- Smart pointers.
- Inheritance and polymorphism.
- Functors.
- Lambda expressions.

Avoid advanced, obscure, or unnecessarily complex C++ features.

In particular:

- Do not introduce complex template metaprogramming.
- Avoid advanced C++ techniques that are unnecessary for the project.
- Do not use complicated design patterns when a straightforward object-oriented approach is sufficient.
- Prefer simple, readable, explicit, and educational implementations over technically sophisticated solutions.

**Goal: Produce C++ code that can be understood by a student familiar only with the concepts taught in the course.**

## 4. Object-Oriented Programming and Encapsulation

- Favor object-oriented programming when structuring the project.
- Group related data and behavior into coherent classes.
- Systematically respect encapsulation principles.
- Explicitly use the `private` and `public` access specifiers.
- Declare class attributes as `private` by default.
- Expose only the methods necessary to interact with an object.
- Add getters and setters when controlled access to an attribute is necessary.
- Do not automatically generate getters and setters for every attribute unless they serve a meaningful purpose.
- Use inheritance and polymorphism when they naturally represent relationships between objects, without introducing unnecessary architectural complexity.

## 5. File Organization

- Follow the rule: **one main class or structure per file**.
- For classes, prefer separating declarations (`.h` or `.hpp`) from implementations (`.cpp`).
- Maintain consistent file organization and naming conventions.
- Avoid grouping multiple independent classes into a single file.
- Small auxiliary declarations directly related to a class may remain in the same file, provided they do not represent independent entities.

## 6. Two-Dimensional Geometry

- Always use the existing `V2` class for two-dimensional geometric calculations.
- Reuse its existing methods and operators whenever possible.
- Do not create competing 2D vector classes.
- Avoid duplicating geometric operations already supported by `V2`.
- Inspect the `V2` interface before implementing new geometric calculations.

## 7. Const-Correctness and Parameter Passing

- Mark member functions as `const` whenever they do not modify the object's state.
- Prefer constant references (`const T&`) when passing objects that do not need to be modified.
- Use non-const references only when modifying the argument is intentional.
- For simple, inexpensive-to-copy types (`int`, `float`, `bool`, etc.), prefer passing by value.
- Avoid adding unnecessary or artificial `const` qualifiers.

## 8. Naming Conventions

Follow the **camelCase** naming convention for identifiers:

- Variables: `playerPosition`, `windowWidth`.
- Attributes: `movementSpeed`, `currentHealth`.
- Functions and methods: `updatePosition()`, `renderScene()`.
- Parameters: `deltaTime`, `targetPosition`.

For classes and structures, preserve the project's existing naming conventions, preferably using `PascalCase` if no convention has already been established.

Do not rename identifiers imposed by external libraries, particularly SDL3, or existing identifiers without a valid reason.

## 9. Function Comments

- Always add a comment immediately above each newly created function or method.
- The comment must briefly explain the function's purpose and behavior.
- Keep comments simple, educational, and informative.
- Avoid comments that merely repeat the function's name.
- When significantly modifying an existing function, update its comment if necessary.
- When a method is declared in a header file and implemented in a `.cpp` file, place the explanatory comment above its declaration unless the project already follows a different convention.

Example:

```cpp
// Updates the player's position based on its speed and elapsed time.
void updatePosition(float deltaTime);
```

## 10. Error Handling and Exceptions

To keep the code simple and aligned with the project's educational requirements:

- Do not implement C++ exception handling.
- Do not introduce `try`, `catch`, or `throw` statements.
- Do not introduce additional error propagation or error-handling mechanisms.
- Do not systematically check or handle function return values when they are only used to indicate success or failure.
- Do not introduce abstraction layers dedicated to error handling.
- Preserve checks that are essential for application logic or for preventing undefined behavior; these are not considered unnecessary error handling.

These rules apply to code written or modified by the agent. Do not unnecessarily remove existing error-handling mechanisms from unrelated parts of the project.

## 11. SDL3-Specific Rules

- Do not check or handle SDL3 function return values when they only indicate whether an operation succeeded or failed.
- Do not introduce error messages, logs, or conditional branches specifically intended to handle these failures.
- Use SDL3 directly, keeping the code as simple and readable as possible.
- Respect SDL3 API requirements when the library requires raw pointers or handles.
- Do not confuse the absence of SDL3 error handling with normal event processing, user input handling, or object lifecycle management.
- Preserve the necessary SDL3 resource cleanup operations, such as `SDL_Destroy...` functions, whenever allocated resources need to be released.

## 12. Development Priorities

For every development task, apply the following priorities:

1. Meet the requested functional requirements.
2. Follow the educational constraints and programming rules defined above.
3. Reuse existing project classes, structures, and functionality.
4. Favor code simplicity and readability.
5. Maintain a coherent object-oriented architecture.
6. Avoid introducing unnecessary complexity.

Do not introduce dependencies, abstractions, or features that were not requested.

## 13. Mandatory Verification Before Completing a Task

Before considering any programming task complete, verify that:

- No `new`, `delete`, `malloc`, or `free` operations have been introduced.
- No unjustified raw pointers have been added.
- Smart pointers are used where necessary.
- STL containers are preferred.
- The code remains within the scope of the course curriculum.
- Object-oriented programming and encapsulation principles are respected.
- Each file defines at most one main class or structure.
- The `V2` class is reused for 2D geometric calculations.
- `const` qualifiers and constant references are used appropriately.
- Naming conventions are respected.
- Every new function has an explanatory comment.
- No new exception-handling or error-handling mechanisms have been introduced.
- No checks or handling of SDL3 return values indicating failure have been added.

## 14. Expected Outcome of This Mission

After updating `AGENTS.md`:

1. Verify that all the rules above are clearly documented.
2. Ensure that no contradictory instructions remain.
3. Avoid unnecessary repetition and maintain an easy-to-navigate structure.
4. Provide a brief summary of the changes made.
5. Report any pre-existing conflicts that had to be resolved.

**Important: You must actually modify the repository's agent instruction file, not merely suggest its updated contents in your response.**

These conventions are permanent project constraints and must be enforced during all future development tasks performed by the agent.