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]

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.

[dingodoppelt]

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.

my little rant:
My stance is the exact opposite: Ban vibe coded slop completely.
LLMs do what they do. They don't "bridge gaps", they don't "fill in the blanks". Instead they are stochastic parrots trained on pirated material producing slop. If a token billionaire comes along and submits thousands of lines of code, we as humans can't be held responsible for making the sloppy code work.
If you want to commit a PR we already have CONTRIBUTING.md to refer to. It says the code must be tested and working.
The slop PRs we received shouldn't have been opened in the first place. I don't see any value in PRs from people who can't even tell if the LLM generated code works and only rely on the LLM assuring them that their tokens were wisely spent.
If a PR is opened there must be no slop in it. The author must have detailed knowledge of all parts because the first breakage leads to nothing but a closed PR because nobody knows why it doesn't do what it was payed to do and nobody seems to care. Speaking of "culture" in this context sounds cynical to my ears.

[ann0see]

Agree. ARCHITECTURE.md or something comparable should exist - also for humans - in docs. Comparable to the protocol.

[ann0see]

Ban vibe coded slop completely.

Only if it's clear that the contributor doesn't have understanding of the code. If they know what it does I'm definitely fine with it.

[dingodoppelt]

Ban vibe coded slop completely.

Only if it's clear that the contributor doesn't have understanding of the code. If they know what it does I'm definitely fine with it.

We will only find out once the PR is open and time has been spent with the code. This should be mitigated and I don't know how other than ban PRs written by LLMs completely.
If an author understands what he is doing, why doesn't he write it himself?

[mcfnord]

A robust application of LLM tactics would give you the time protection you want.

A submitter with little understanding of the code might drop the hot feature of the century. Today it'll show up alongside 5 loser PRs.

Historically we implicitly thought of the submitter as the first reviewer, and that part isn't true anymore. We maintain the gate where the approver needs to really believe in the change regardless of the submitter reputation or apparent understanding. And we know that's not enough, so we insist on two approvers.

If we had robust AGENTS, COMPILING, PROTOCOL, and ARCHITECTURE Markdown, the hot feature of the century would show up, and the other 5 wouldn't. Or maybe 1 of those 5 would be redirected by the agent into something worthwhile. So you only need to consider 2 PRs rather than 6.

So your thoughtful comments here wouldn't have been necessary, because the agent would have nudged me here before I submitted anything.

It's much easier to submit a PR now, and this has led to PRs of dubious merit. AI with robust coding guidance would radically improve the quality of each PR. AI triggered the new problem we've been seeing, but it's also the mitigation you're hoping for.

[dingodoppelt]

A robust application of LLM tactics would give you the time protection you want.

A submitter with little understanding of the code might drop the hot feature of the century. Today it'll show up alongside 5 loser PRs.

Historically we implicitly thought of the submitter as the first reviewer, and that part isn't true anymore. We maintain the gate where the approver needs to really believe in the change regardless of the submitter reputation or apparent understanding. And we know that's not enough, so we insist on two approvers.

If we had robust AGENTS, COMPILING, PROTOCOL, and ARCHITECTURE Markdown, the hot feature of the century would show up, and the other 5 wouldn't. Or maybe 1 of those 5 would be redirected by the agent into something worthwhile. So you only need to consider 2 PRs rather than 6.
So your thoughtful comments here wouldn't have been necessary, because the agent would have nudged me here before I submitted anything.

It's much easier to submit a PR now, and this has led to PRs of dubious merit. AI with robust coding guidance would radically improve the quality of each PR. AI triggered the new problem we've been seeing, but it's also the mitigation you're hoping for.

I don't think we should accept any generated code, unless we generate it ourselves from a given set of rules. When there is no author we don't need one at all so a corresponding commit makes clear it wasn't contributed by a human.
An LLM could go ahead and generate code from a discussion of a feature if there is nobody able to do the work. No feature is impossible to implement by hand. We're not in a hurry. Jamulus works for what it is.
Everybody can have an AI generate a Jamulus client and use that, btw.
I see PRs pop up that should really have been openend as discussions in the first place. If a need for that feature and a strategy for integration into existing code has been agreed upon (speaking of culture) and then still nobody feels able to accomplish the task, we might have an AI help us with the implementation or find bugs for us afterwards.

[ann0see]

TODO:

Port from https://github.com/mcfnord/jamulus/blob/d46a77a1420345c4e4f058b677f3e5a97dc4d6f2/AGENTS.md

[mcfnord]

For the port TODO: d46a77a is one commit behind — the final version after all the review rounds in #3789 is 22 lines: https://github.com/mcfnord/jamulus/blob/59a167fb0d9d12af5f547a16d9c2ddbbf7fbddbe/AGENTS.md

It has the granularity requirement as hard rules at the top (one PR per new file / independent fix / typo; every PR a standalone option reviewable in minutes), the renumbering rule removed, and everything else as links. Two of the linked files exist only if their PRs merge — drop the docs/ARCHITECTURE.md entry unless #3791 lands and the docs/DEPLOY.md entry unless #3790 lands. Take any or all of it.