claudes_game/AGENTS.md

DO NOT TOUCH

• docs/TODO - Manual file only. Never read, write, restore, or commit
• docs/session_logs/ - Manual logs only. Never read or write

Orbital Mechanics Simulation - Project Memory

Architecture

• C-style C++ (structs/functions, NO classes/templates)
• Core library (liborbit.a) in src/ — simulation, physics, maneuvers, config
• Visualizer in example/src/ — Raylib/raygui rendering (moved from core)
• See docs/technical_reference.md for data structures reference
• See docs/rendering.md for rendering system reference

Coding Rules

• Use .cpp extensions (for future C++ features if needed)
• Small, focused functions
• Follow existing patterns in src/
• Minimal comments - code should be self-documenting
• No decorative comment blocks (===, ---, etc.)
• Only comment non-obvious logic
• No trailing whitespace in any files (including markdown)
  • Pre-commit hook automatically strips it
  • For markdown line breaks, use
    tag instead of two trailing spaces
• ZII (Zero Is Initialization) pattern: Initialize structs using = {0} or = {NULL} instead of individual field assignments. This guarantees all fields (including padding) are zeroed out. Example: MyStruct s = {0};

File Reading Policy

• Ask before reading files unless immediately necessary for current task
• Exception: Can read without asking if:
  • Single small file (<100 lines) clearly needed
  • File explicitly mentioned by user
• When reading multiple files or large files (>200 lines), always verify first

Git Workflow

• Small commits with logical separation
• Concise commit messages

Session Summaries

• When user requests session summary, create in docs/session_summaries/
• Format: YYYY-MM-DD-descriptive-name.md
• Keep concise: changes made, commits, results (net line count)
• Document any remaining issues not resolved in the current session
• If applicable, add a short list of next steps for the next session
• Always ask the user if we want to update the technical_reference after generating a summary

Common Commands

• Build all (lib + tests + visualizer): make
• Build library only: make lib
• Build visualizer example: make example
• Test (build + run all): make test
• Test (rebuild only): make test-build
• Test (specific tag): ./build/orbit_test '[tag_name]'
• Test (with debug output): ./build/orbit_test -s '[tag_name]'
  • needed to display 'INFO' statements for successful tests with Catch2 framework
• See docs/technical_reference.md for full build target reference

Simulation

The core simulation library is built at build/liborbit.a. The visualizer binary is at ./build/orbit_sim. Agents should NOT attempt to run the graphical simulation. Focus on testing and code changes only.

Testing Guidelines

• Always use WithinAbs() for floating-point comparisons
• Do NOT use Approx() - it is deprecated in Catch2
• Required header: <catch2/matchers/catch_matchers_floating_point.hpp>
• Usage: REQUIRE_THAT(value, WithinAbs(expected, absolute_margin))

Documentation

• Always read in docs/technical_reference.md when starting a new session
• Always read in src/*.summary.md when starting a new session