Add agent instructions for Jamulus

[ann0see]

Short description of changes

Adds agent instructions for opencode/claude code/... since we have an increasing amount of agent/AI PRs.
CHANGELOG: SKIP

Context: Fixes an issue?

No

Does this change need documentation? What needs to be documented and how?

This is documentation

Status of this Pull Request

Ready for review.

What is missing until this pull request can be merged?

Review for conciseness. @mcfnord had AI contributions - I assume that he knows if this prompt is good enough.

Checklist

• I've verified that this Pull Request follows the general code principles
• I tested my code and it does what I want (Somewhat. It's non deterministic anyway...)
• I waited some time after this Pull Request was opened and all GitHub checks completed without errors.
• I've filled all the content above

[dingodoppelt]

CONTRIBUTING.md still lacks info on fully AI generated contributions.
I got the impression that when AI gets used for actual code generation the contribution guidelines don't seem to work too well.
I feel like the points "Submitting code and getting started", Testing and Ownership need an overhaul because we address "authors" when there actually aren't any.
I think we need to apply what we expect from human authors even more strictly to AI contributions.
Honestly I'm no fan of vibe coded stuff, even if it works™. Can't help it...

[softins]

Honestly I'm no fan of vibe coded stuff, even if it works™. Can't help it...

I agree. I'm happy for AI to show me how to do something, but then I re-implement the technique myself. I wouldn't want to include code that I don't understand how or why it works!

[ann0see]

Yes sure. But I still think that if the code is understood and well written it's fine. But yes, we need to update CONTRIBUTING.md

[mcfnord]

My experience has been that an agent should author this kind of guidance, and the agent should be asked to evolve the guidance when an agent makes an error and then recovers from the error with or without human intervention ("a teachable moment").

I say something like, "You made an error while fixing/making this, and then we recovered from the error. Let's add guidance to AGENTS.md that would help prevent this kind of error next time."

I asked Fable to review this PR against my own CLAUDE.md (basically same function as AGENTS.md). This is primarily because a model like Fable can produce great guidance that a lesser model like Sonnet can follow. Its overall view is: good foundation, accurate throughout, worth merging after additions.

Here are 5 observations it provided:

1. The PR documents the mechanics but not the physics. Everything in the file is about how to submit code (format, build, regen docs). Nothing is about what kind of program this is: audio and network processing run on real-time paths where a blocking call, heap allocation, or contended lock causes audible dropouts for every musician on the server. A human contributor absorbs this from reading the code; an agent asked to "add logging to channel.cpp" will happily put a synchronous call in the receive path. This deserves its own section, roughly:

Real-time constraints
socket.cpp, channel.cpp, and the audio callback path are latency-critical. No blocking I/O, no locks shared with non-RT threads, no allocation in the per-packet path. If a feature needs slow work (DNS, HTTP, disk), do it asynchronously and fail open.

My view on this: This is some pretty technical, fundamental stuff, and I think I know why it mentions this. I had added a mechanism to my servers to keep out known attack vectors (ASNs and a few IP ranges), but my lookup was synchronous, and every 20 seconds, the whole server would freeze for 100ms, for everyone. People wouldn't stay. :) If it was easy-breezy for me to introduce that problem, perhaps it's basic guidance for any agent to avoid making such a blunder.

2. protocol.cpp needs two rules, stated together. It's the file agents are most likely to touch and the one with the most invisible constraints:
   (a) it parses UDP from arbitrary internet hosts, so every length/count field is adversarial — bounds-check before use;
   (b) the wire format is a compatibility contract with every old client and server in the wild — never renumber PROTMESSID_x values or change existing message layouts; extend by adding new message IDs. The format spec is already in the file's header comment; AGENTS.md just needs to say "read it, and these two rules are non-negotiable."

My view: Maybe this guidance gets too far into the weeds in some ways, or maybe not. When your project has non-negotiable architectural laws, it's good to include them in tose terms. I started with a "CONSTITUTION" in the earliest comments of a script file, with numbered LAWS. The location (first comments, or AGENTS.md) assures these always get read, and fundamentally unwise changes just don't happen (because they'd break the LAW).

3. "No automated test suite" is an accurate fact and useless guidance. It tells an agent what it can't do and nothing about what it should do, so verification will be skipped or improvised. Replace with a recipe:

No automated tests. To verify a change, build a headless server (qmake "CONFIG+=headless serveronly" && make, run with --server --nogui), connect a client instance, and exercise the changed behavior. State in the PR what you tested.

My view: I agree. Spell out what it should do.

4. The file solves the wrong half of the AI-PR problem. The stated motivation is "an increasing amount of agent/AI PRs" — but what makes those painful for maintainers is rarely formatting; it's scope: drive-by refactors, five changes in one PR, features nobody asked for. The mechanical rules here make bad PRs tidier, not fewer. Add a short "Scope" section: one logical change per PR, no unrelated cleanup or reformatting of untouched code, discuss features in an issue before implementing, and link CONTRIBUTING.md (currently never referenced).

My view: Perhaps so. And notice that AGENTS.md can and probably should link through to CONTRIBUTING.md and any other pre-existing guidance. Agents will investigate these hyperlinked guidance Markdown files, but AGENTS.md (or CLAUDE.md) are considered the start points. So we'd link from AGENTS.md to COMPILING.md, CONTRIBUTING.md, SECURITY.md, and I guess README.md. this is exactly the kind of upgrade an agent can perform for us, and if we add AGENTS.md, I can ask Fable for an agent-ready makeover of these files, with AGENTS.md as the root file.

5. Small fixes, verified against the repo:

• Typos: "discription" → "description", "More infos" → "More info".
• The clang-format line is garbled ("Before committing … or after qmake Jamulus.pro, run…"). Clearer: "Run make clang_format before
  committing (the target exists only after qmake has generated the Makefile)."
• Missing trap from Jamulus.pro:1191-1192: if you add a new source directory or file extension, you must also update
  .github/workflows/coding-style-check.yml and .clang-format-ignore, or CI and local formatting silently diverge.
• The "Before finishing" checklist repeats earlier rules verbatim; either cut it or make it the only place the checklist lives.

---

Maybe pick out the fixes or ideas you find most compelling for this PR and merge it, and we'll start evolving all of our guidance Markdown content over time, especially when we see a real-world error that could have been avoided by a little tip in AGENTS.md.

Regarding the larger discussion, I am also concerned that it's now easy to produce PRs, but it's ultimately a blessing, even if it means we need vigilant gatekeeping by humans.

My fork of Jamulus has a CLAUDE.md that might interest you. One thing I notice is all those architecture pitfalls. I've found different library requirements for deployment to Ubuntu 22 vs. 24 vs. 26, on ARM vs. x86, as well as gotchas when on very small (half-gb) RAM scenarios.

[ann0see]

My experience has been that an agent should author this kind of guidance

This was done with open code and corrected by hand.

I instructed it to be brief also as I wanted to make sure that small (local) models can also benefit from it.

[mcfnord]

This YouTube video explains why small models running locally aren't suited to agentic programming tasks, but AGENTS.md is typically loaded into context before every interaction with an agent while using any model, so concision is always in style.

[ann0see]

Qwen3 27b works for easy tasks. Maybe that counts as medium sized. Will check the video soon.

[pljones]

Not quite right.

Suggested change

	- New files must carry an AGPL 3.0 (or later) license header. Existing pre-3.12.1
	- New files must carry an AGPL 3.0 (or later) license header.
	- Existing pre-3.12.1 code being amended should already carry combined AGPL 3.0 and GPL 2.0 (or later) license blocks.

[pljones]

Qwen3 27b works for easy tasks. Maybe that counts as medium sized. Will check the video soon.

Let me put it this way, none of my local machines is capable of running a local LLM (well, maybe above 2b). Anything in the Jamulus source directory that is going to mislead Cursor or VSCode running against cloud instances is going to have negative impacts - and reducing the scope of what the LLM considers as potential context is as good as misleading it.

[ann0see]

Agree. Also I believe context must be as concise and information dense as possible.

[mcfnord]

I believe context must be as concise and information dense as possible.

Let's be as concise and dense as possible, but go as deep as we must to prevent common errors and pitfalls.

• A new ARCHITECTURE.md should forewarn people before they try submitting PRs of unsuited, DOA JSON-RPC features, as I have done.
• A new ARCHITECTURE.md probably should have prevented me from putting a synchronous task in a real-time thread, as I did last month.
• My CLAUDE.md adds details about compiling that I don't see today in COMPILING.md. I've accrued those because I build server binaries on a somewhat diverse set of cloud Linux scenarios.

LLMs will "bridge the gap" and "fill in the blanks" which is fascinating, but the goal of AGENTS.md is to prevent speculations that just lead to failures and problems. I'd like to see a culture here where people submit Markdown PRs for agent use that (concisely and densely) would have prevented the pitfalls they experienced when agentically programming this repo.