# AGENTS.md - Instructions for Junie

## Project Overview
This project is a high-performance modern C++ application featuring an advanced backend architecture. Junie must follow modern standards, clean code principles, and efficient resource management.

---

## Modern C++ Standards (C++20/C++23)
- **Language Standard:** Write code strictly targeting **C++20** or later. Do not use legacy pre-C++11 or C++11/14 patterns.
- **Ranges & Views:** Prefer `std::ranges` and `std::views` (using pipe syntax `|`) for filtering, transforming, and iterating through standard containers instead of writing raw `for` loops or explicit `begin`/`end` iterators.
- **Concepts:** Use `concepts` and `requires` clauses to constrain templates. Avoid old SFINAE (`std::enable_if`) techniques.
- **Initialization:** Use direct initialization or designated initializers for aggregate types to maximize readability.

---

## Memory Management & Performance (Strict RAII)
- **Raw Pointers:** Absolute ban on raw `new` and `delete`. Manual memory management is strongly discouraged.
- **Exclusive Ownership:** Prefer `std::unique_ptr` by default, instantiated via `std::make_unique`.
- **Argument Passing:**
  - Pass heavy, non-modifiable objects by constant reference (`const T&`).
  - Pass by value (`T`) only if the function intends to take ownership or make a copy, utilizing `std::move`.
- **Move Semantics:** Implement move constructors and move assignment operators (`&&`) for resource-heavy components. Ensure strict adherence to the Rule of Five.

---

## Concurrency & Multithreading
- **Modern Primitives:** Always prefer `std::jthread` over `std::thread`, as it automatically manages its own RAII lifecycle and signals cooperative cancellation on destruction.
- **Thread Safety:** Use `std::unique_lock`, `std::lock_guard`, or `std::scoped_lock` (when handling multiple mutexes) to protect critical sections.
- **Lock-free Basics:** Prefer atomic operations (`std::atomic`) for simple shared primitive types.

---

## Compile-Time Safety & Robustness
- **Compile-Time Validation:** Use `static_assert` wherever possible to enforce architectural assumptions and constraints during the build phase.
- **Constexpr:** Mark functions and variables as `constexpr` (or `consteval`) to force computation at compile-time whenever feasible.
- **Type Safety & Errors:** Use `std::optional` to express the absence of a value. Use `std::variant` or custom error/result structures for structured error handling. Do not return magic error numbers (e.g., `-1`) or null pointers for error states.

---

## Structural & Project Constraints
- **Header Guards:** Always use `#pragma once` at the top of header files instead of old-fashioned `#ifndef` include guards.
- **Architecture Style:** If introducing lightweight internal utilities, prefer a clean, modular **Header-Only** structure (with `inline` functions/variables) to keep dependencies streamlined, unless compilation times dictate otherwise.
- **Code Formatting:** All generated code must comply with the `.clang-format` specification present in the repository root.

---

## Strict Guardrails & Bans
- **NO PYTHON:** Under no circumstances should you generate, modify, or suggest Python scripts, Python bindings, or Python-based automation tools. The tooling and automation landscape of this environment must remain purely native (C++, Shell, or CMake).
- **Public API Modifications:** Do not change public function signatures or break backward compatibility in core interface headers without explicit confirmation in your plan.