CubicSDR/AGENTS.md

Agent Instructions

This is a C++ Software-Defined Radio application (CubicSDR) built with wxWidgets, OpenGL, liquid-dsp, and SoapySDR.

Project Documentation

• docs/RECOMMENDATIONS.md — Project evaluation, strengths, weaknesses, and priority-ranked improvement recommendations
• docs/PLAN.md — Index of implementation plans with risk/effort estimates and execution order
• docs/design/ — Architecture documentation (signal flow, threading model, modem system)
• docs/plans/ — Individual implementation plans for each recommendation:
  • add-unit-tests.md — Test infrastructure and initial test coverage
  • fix-gitignore.md — Comprehensive .gitignore patterns
  • modernize-cmake.md — CMake 2.8 → 3.14+ modernization
  • smart-pointers.md — Replace raw new/delete with std::unique_ptr
  • split-appframe.md — Split monolithic AppFrame.cpp into multiple files
  • remove-c4996-suppression.md — Address unsafe CRT function usage
  • replace-reinterpret-cast.md — Fix undefined behavior in DataTree
  • update-vendored-deps.md — Update or replace third-party libraries
  • add-ci-test-execution.md — Run tests in CI pipeline
  • resolve-todos.md — Address open TODO/FIXME markers

Build

CMake-based. See CMakeLists.txt for build configuration. The project targets C++14 on Windows (MSVC), macOS, and Linux.

Key Directories

• src/ — Application source (sdr/, demod/, audio/, visual/, modules/modem/, util/)
• external/ — Vendored third-party libraries (lodepng, tinyxml, rtaudio, liquid-dsp, hamlib, cubicvr2)
• .circleci/ — CI configuration (builds only, no test execution)
• font/ — Bitmap fonts
• cmake/ — CMake helper modules

Conventions

• Follow existing code style in each file
• Do not add comments unless asked
• SPDX license headers on source files: // Copyright (c) Charles J. Cliffe // SPDX-License-Identifier: GPL-2.0+

Documentation Guidelines

When creating or updating documentation in docs/, avoid brittle content that will drift from the codebase:

• No specific line numbers — Reference functions/classes, not line numbers (e.g., "In CubicSDR.cpp" not "on line 390")
• No exact counts — Avoid "197 source files" or "18 TODOs" — use qualitative terms like "multiple" or "several"
• No "Last Updated" timestamps — They create maintenance burden with zero value
• No redundant preambles — Don't repeat "CubicSDR is a cross-platform..." in every doc when PLAN.md already links everything
• No theoretical discussions — Keep design considerations in code comments, not implementation plans
• Reference functions, not lines — "In the OnInit() method" is durable; "on line 390" is not
• Keep actionable content only — File lists, verification criteria, and rollback strategies are durable; inventories of current state go stale

Session Logging

Log your work to AGENT-LOG.md in the project root. For each session, append a section with:

• Date and model name
• Numbered list of actions taken
• Tables of files created/modified with brief descriptions

Log Maintenance

• Capture outcomes, not process. If something is added then later removed in the same session, just note the removal and why — don't keep both.
• Compact iterative fixes. Multiple passes over the same files (fix errors → fix different errors → fix original errors) should compress into a single summary, not three separate entries.
• Drop files that no longer exist. If a file was created then deleted, remove it from the file table or note it as "(deleted)" — don't leave stale entries.
• Keep the log scannable. A log entry should answer "what changed and why" in a few bullet points. If it takes more than that, it's too detailed.