volaTile/AGENTS.md

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.