1 changed files with 299 additions and 0 deletions
Unified View
Diff Options
-
+299 -0AGENTS.md
+ 299
- 0
AGENTS.md
View File
| @@ -0,0 +1,299 @@ | |||||
| # AGENTS.md | |||||
| This file is the repo-level working guide for humans, coding agents, and LLMs. | |||||
| Read it before making changes. | |||||
| --- | |||||
| ## 1. Purpose of this file | |||||
| Use this file as the canonical "how to work in this repo" guide. | |||||
| It is intentionally practical and operational. | |||||
| Use it to answer questions like: | |||||
| - Where should changes go? | |||||
| - What must not be committed? | |||||
| - How should builds/tests be run? | |||||
| - Which docs are canonical? | |||||
| - How should debugging work be documented? | |||||
| - How should agents behave when touching this repo? | |||||
| --- | |||||
| ## 2. Repo intent | |||||
| `sd r-wideband-suite` is a Go-based SDR analysis and streaming system with: | |||||
| - live spectrum/waterfall UI | |||||
| - signal detection/classification | |||||
| - extraction / demodulation / recording | |||||
| - GPU-assisted paths | |||||
| - streaming audio paths | |||||
| - extensive telemetry/debugging support | |||||
| This repo has gone through active streaming-path and audio-click debugging. | |||||
| Do not assume older comments, notes, or experimental code paths are still authoritative. | |||||
| Prefer current code, current docs in `docs/`, and current branch state over historical assumptions. | |||||
| --- | |||||
| ## 3. Canonical documentation | |||||
| ### Keep as primary references | |||||
| - `README.md` | |||||
| - high-level project overview | |||||
| - build/run basics | |||||
| - feature summary | |||||
| - `ROADMAP.md` | |||||
| - longer-lived architectural direction | |||||
| - `docs/known-issues.md` | |||||
| - curated open engineering issues | |||||
| - `docs/telemetry-api.md` | |||||
| - telemetry endpoint documentation | |||||
| - `docs/telemetry-debug-runbook.md` | |||||
| - telemetry/debug operating guide | |||||
| - `docs/audio-click-debug-notes-2026-03-24.md` | |||||
| - historical incident record and final resolution notes for the audio-click investigation | |||||
| ### Treat as historical / contextual docs | |||||
| Anything in `docs/` that reads like an incident log, deep debug note, or one-off investigation should be treated as supporting context, not automatic source of truth. | |||||
| ### Do not create multiple competing issue lists | |||||
| If new open problems are found: | |||||
| - update `docs/known-issues.md` | |||||
| - keep raw reviewer/ad-hoc reports out of the main repo flow unless they are converted into curated docs | |||||
| --- | |||||
| ## 4. Branching and workflow rules | |||||
| ### Current working model | |||||
| - Use focused branches for real feature/fix work. | |||||
| - Do not keep long-lived junk/debug branches alive once the useful work has been transferred. | |||||
| - Prefer short-lived cleanup branches for docs/config cleanup. | |||||
| ### Branch hygiene | |||||
| - Do not pile unrelated work onto one branch if it can be split cleanly. | |||||
| - Keep bugfixes, config cleanup, and large refactors logically separable when possible. | |||||
| - Before deleting an old branch, ensure all useful work is already present in the active branch or merged into the main line. | |||||
| ### Mainline policy | |||||
| - Do not merge to `master` blindly. | |||||
| - Before merge, prefer at least a short sanity pass on: | |||||
| - live playback | |||||
| - recording | |||||
| - WFM / WFM_STEREO / at least one non-WFM mode if relevant | |||||
| - restart behavior if the change affects runtime state | |||||
| --- | |||||
| ## 5. Commit policy | |||||
| ### Commit what matters | |||||
| Good commits are: | |||||
| - real code fixes | |||||
| - clear docs improvements | |||||
| - deliberate config-default changes | |||||
| - cleanup that reduces confusion | |||||
| ### Do not commit accidental noise | |||||
| Do **not** commit unless explicitly intended: | |||||
| - local debug dumps | |||||
| - ad-hoc telemetry exports | |||||
| - generated WAV debug windows | |||||
| - temporary patch files | |||||
| - throwaway reviewer JSON snapshots | |||||
| - local-only runtime artifacts | |||||
| ### Prefer small, readable commit scopes | |||||
| Examples of good separate commit scopes: | |||||
| - code fix | |||||
| - config default cleanup | |||||
| - doc cleanup | |||||
| - known-issues update | |||||
| --- | |||||
| ## 6. Files and paths that need extra care | |||||
| ### Config files | |||||
| - `config.yaml` | |||||
| - `config.autosave.yaml` | |||||
| Rules: | |||||
| - These can drift during debugging. | |||||
| - Do not commit config changes accidentally. | |||||
| - Only commit them when the intent is to change repo defaults. | |||||
| - Keep in mind that `config.autosave.yaml` can override expected runtime behavior after restart. | |||||
| ### Debug / dump artifacts | |||||
| Examples: | |||||
| - `debug/` | |||||
| - `tele-*.json` | |||||
| - ad-hoc patch/report scratch files | |||||
| - generated WAV capture windows | |||||
| Rules: | |||||
| - Treat these as local investigation material unless intentionally promoted into docs. | |||||
| - Do not leave them hanging around as tracked repo clutter. | |||||
| ### Root docs | |||||
| The repo root should stay relatively clean. | |||||
| Keep only genuinely canonical top-level docs there. | |||||
| One-off investigation output belongs in `docs/` or should be deleted. | |||||
| --- | |||||
| ## 7. Build and test rules | |||||
| ### General rule | |||||
| Prefer the repo's own scripts and established workflow over ad-hoc raw build commands. | |||||
| ### Important operational rule | |||||
| Before coding/build/test sessions on this repo: | |||||
| - stop the browser UI | |||||
| - stop `sdrd.exe` | |||||
| This avoids file locks, stale runtime state, and misleading live-test behavior. | |||||
| ### Build preference | |||||
| Use the project scripts where applicable, especially for the real app flows. | |||||
| Examples already used during this project include: | |||||
| - `build-sdrplay.ps1` | |||||
| - `start-sdr.ps1` | |||||
| Do **not** default to random raw `go build` commands for full workflow validation unless the goal is a narrow compile-only sanity check. | |||||
| ### GPU / native-path caution | |||||
| If working on GPU/native streaming code: | |||||
| - do not assume the CPU oracle path is currently trustworthy unless you have just validated it | |||||
| - do not assume old README notes inside subdirectories are current | |||||
| - check the current code and current docs first | |||||
| --- | |||||
| ## 8. Debugging rules | |||||
| ### Telemetry-first, but disciplined | |||||
| Telemetry is available and useful. | |||||
| However: | |||||
| - heavy telemetry can distort runtime behavior | |||||
| - debug config can accidentally persist via autosave | |||||
| - not every one-off probe belongs in permanent code | |||||
| ### When debugging | |||||
| Prefer this order: | |||||
| 1. existing telemetry and current docs | |||||
| 2. focused additional instrumentation | |||||
| 3. short-lived dumps / captures | |||||
| 4. cleanup afterward | |||||
| ### If you add debugging support | |||||
| Ask: | |||||
| - Is this reusable for future incidents? | |||||
| - Should it live in `docs/known-issues.md` or a runbook? | |||||
| - Is it temporary and should be removed after use? | |||||
| ### If a reviewer provides a raw report | |||||
| Do not blindly keep raw snapshots as canonical repo docs. | |||||
| Instead: | |||||
| - extract the durable findings | |||||
| - update `docs/known-issues.md` | |||||
| - keep only the cleaned/curated version in the main repo flow | |||||
| --- | |||||
| ## 9. Documentation rules | |||||
| ### Prefer curated docs over raw dumps | |||||
| Good: | |||||
| - `docs/known-issues.md` | |||||
| - runbooks | |||||
| - architectural notes | |||||
| - incident summaries with clear final status | |||||
| Bad: | |||||
| - random JSON reviewer dumps as primary docs | |||||
| - duplicate issue lists | |||||
| - stale TODO/STATE files that nobody maintains | |||||
| ### If a doc becomes stale | |||||
| Choose one: | |||||
| - update it | |||||
| - move it into `docs/` as historical context | |||||
| - delete it | |||||
| Do not keep stale docs in prominent locations if they compete with current truth. | |||||
| --- | |||||
| ## 10. Known lessons from recent work | |||||
| These are important enough to keep visible: | |||||
| ### Audio-click investigation lessons | |||||
| - The final click bug was not a single simple DSP bug. | |||||
| - Real causes included: | |||||
| - shared-buffer mutation / aliasing | |||||
| - extractor reset churn from unstable config hashing | |||||
| - streaming-path batch rejection / fallback behavior | |||||
| - Secondary contributing issues existed in discriminator bridging and WFM mono/plain-path filtering. | |||||
| ### Practical repo lessons | |||||
| - Silent fallback paths are dangerous; keep important fallthrough/fallback visibility. | |||||
| - Shared IQ buffers should be treated very carefully. | |||||
| - Debug artifacts should not become permanent repo clutter. | |||||
| - Curated issue tracking in Git is better than keeping raw review snapshots around. | |||||
| --- | |||||
| ## 11. Agent behavior expectations | |||||
| If you are an AI coding agent / LLM working in this repo: | |||||
| ### Do | |||||
| - read this file first | |||||
| - prefer current code and current docs over old assumptions | |||||
| - keep changes scoped and explainable | |||||
| - separate config cleanup from code fixes when possible | |||||
| - leave the repo cleaner than you found it | |||||
| - promote durable findings into curated docs | |||||
| ### Do not | |||||
| - commit local debug noise by default | |||||
| - create duplicate status/todo/issue files without a strong reason | |||||
| - assume experimental comments or old subdirectory READMEs are still correct | |||||
| - leave raw reviewer output as the only source of truth | |||||
| - hide fallback behavior or silently ignore critical path failures | |||||
| --- | |||||
| ## 12. Recommended doc update pattern after meaningful work | |||||
| When a meaningful fix or investigation lands: | |||||
| 1. update code | |||||
| 2. update any relevant canonical docs | |||||
| 3. update `docs/known-issues.md` if open issues changed | |||||
| 4. remove or archive temporary debug artifacts | |||||
| 5. keep the repo root and branch state clean | |||||
| --- | |||||
| ## 13. Minimal pre-commit checklist | |||||
| Before committing, quickly check: | |||||
| - Am I committing only intended files? | |||||
| - Are config changes intentional? | |||||
| - Am I accidentally committing dumps/logs/debug exports? | |||||
| - Should any reviewer findings be moved into `docs/known-issues.md`? | |||||
| - Did I leave stale temporary files behind? | |||||
| --- | |||||
| ## 14. If unsure | |||||
| If a file looks ambiguous: | |||||
| - canonical + actively maintained -> keep/update | |||||
| - historical but useful -> move or keep in `docs/` | |||||
| - stale and confusing -> delete | |||||
| Clarity beats nostalgia. | |||||