Add AGENTS.md: a 22-line agent entry point by mcfnord · Pull Request #3789 · jamulussoftware/jamulus

mcfnord · 2026-07-17T19:32:36Z

Now a single new file, per review. AGENTS.md is 22 lines — short enough for any context window — and leads with hard PR-granularity rules: smallest independently mergeable unit, one PR per new file / independent fix / typo, every PR a standalone option reviewable in minutes. The rest is links to the existing docs plus the few facts an agent can't cheaply discover (no test suite → how to verify; real-time path; untrusted input; generated files; CHANGELOG/AUTOBUILD conventions).

It starts from @ann0see's #3785 draft — structure and much content survive. If you'd rather land AGENTS.md via #3785, I'm happy to close this one; maintainers' choice.

Everything else from earlier revisions of this PR is now its own single-file PR:

Add docs/DEPLOY.md: deploying a self-built server binary #3790 — docs/DEPLOY.md
Add docs/ARCHITECTURE.md: system overview, source map, threading model #3791 — docs/ARCHITECTURE.md
Fix typo in CONTRIBUTING.md: concatinations -> concatenations #3792 — CONTRIBUTING.md typo fix
CONTRIBUTING.md: point agent-assisted contributors at AGENTS.md #3793 — CONTRIBUTING.md pointer paragraph for agent-assisted contributions

The GCC 13 moc issue formerly documented in COMPILING.md here will return as a build fix instead, per review.

CHANGELOG: SKIP

🤖 Generated with Claude Code

AGENTS.md (based on the draft in jamulussoftware#3785) is the entry point for coding agents: scope rules, the architecture laws whose violation causes audible failures (real-time path, wire compatibility, adversarial input), the do-not-edit list, a concrete manual verification recipe, and links to the existing docs. DEPLOY.md covers the step after COMPILING.md: moving a self-built server binary onto production hosts — architecture/glibc matching, ldd verification, systemd, UDP buffer tuning, firewalling, and a post-deploy checklist. Every rule corresponds to a real-world failure. COMPILING.md gains a GCC 13 moc workaround and a link to DEPLOY.md; CONTRIBUTING.md gains a pointer to AGENTS.md stating that its rules apply to agent-assisted work without exception. Co-Authored-By: Claude Fable 5 <[email protected]>

mcfnord · 2026-07-17T19:49:43Z

This PR is based on Markdown I've accrued in my fork. I bet it overlaps with URL-based docs in ways we might try avoiding. I introduce a DEPLOY.md, which includes guidance I use to deploy custom servers. Perhaps a way to approach this is by letting people express uncertainty, or certainty, about specific sections. I think "say less" is a good mindset, and I often ask AI things like, "If we could only say one thing, what would it be?" That said, it's not dramatically important to be exceedingly concise in this kind of content. Instead, it's helpful to produce guidance using a very-frontier model that can be carried out by any reasonable model. Context space for this kind of guidance is precious, but most of this guidance is also precious. I bet a broad class of newbie pitfalls can be eliminated with this kind of guidance. All that said, this is not my direct work and I present it with a dramatically lower assurance of its quality than accompany most of my PRs. I have not reviewed it by line-by-line code standards practiced in this repo. (Not even close.) But it is operational insight from my handling of the (mostly server) repo. I also have learned over 25 years as a technical writer that it is unwise to apply standards for code review to non-code materials. Instead, I suggest a more rapid iteration model similar to Wikipedia editing philosophy. We are at a unique juncture where a flawed but powerful side-kick can RTFM even where humans fail. This might raise our ability to nurture wins and prevent failures/wasted effort at a new and higher level.

ann0see · 2026-07-17T20:04:05Z

This should go into docs/

Actually, open another PR for new files. In the best case we'd have one per file. This ensures that nothing is blocked by review.

Done: docs/DEPLOY.md → #3790, docs/ARCHITECTURE.md → #3791, typo → #3792, CONTRIBUTING pointer paragraph → #3793. This PR is now AGENTS.md alone.

ann0see · 2026-07-17T20:05:03Z

-To control the server with systemd, runtime options and similar, refer to the [Server manual](https://jamulus.io/wiki/Server-Linux).
+To control the server with systemd, runtime options and similar, refer to the [Server manual](https://jamulus.io/wiki/Server-Linux). If you plan to copy the binary onto other machines, read [DEPLOY.md](DEPLOY.md) first — architecture and library mismatches between build and target hosts are the most common cause of broken deployments.
+
+### Troubleshooting: moc errors with GCC 13+


We should fix this then.

Agreed. I can reproduce the failure on Ubuntu 24.04 (GCC 13.3 / Qt 5.15.13) and will open a separate PR that fixes it in the build itself. Once that merges, this section can shrink to a sentence or disappear.

Update: I tried to reproduce this on clean main before writing a fix — Ubuntu 24.04, GCC 13.3, Qt 5.15.13, both CONFIG+=headless serveronly and CONFIG+=headless — and both build cleanly. The failure I had seen involves my fork's additions, not upstream code. So there is nothing to fix here, no build-fix PR is coming, and this troubleshooting section was rightly dropped from the PR.

ann0see · 2026-07-17T20:06:42Z

+Violating these causes audible failures for every connected musician, so they are non-negotiable:
+
+1. **Never block the real-time path.** The audio capture/playback callbacks (`src/sound/`) and the server's UDP receive → mix → send path (`socket.cpp`, `channel.cpp`, `server.cpp`) must not perform blocking I/O (DNS, HTTP, disk, database), wait on locks contended by non-real-time threads, or do unbounded allocation per packet. Slow work must run asynchronously on another thread; when its result isn't ready, the real-time path fails open and continues. A single synchronous lookup here freezes the audio of everyone on the server.
+2. **The wire protocol is a compatibility contract.** `protocol.cpp` must interoperate with every older client and server in the wild. Never renumber `PROTMESSID_*` values, never change the layout of an existing message — extend only by adding new message IDs. Read the header comment in `src/protocol.cpp` and [docs/JAMULUS_PROTOCOL.md](docs/JAMULUS_PROTOCOL.md) before touching it.


Did this renumbering really happen?

I'm not aware of this happening.

Then remove it.

ann0see · 2026-07-17T20:07:29Z

+- [COMPILING.md](COMPILING.md) — building on every supported platform.
+- [DEPLOY.md](DEPLOY.md) — moving a self-built server binary onto production hosts and verifying it.
+- [docs/JAMULUS_PROTOCOL.md](docs/JAMULUS_PROTOCOL.md) — the wire protocol.
+- [SECURITY.md](SECURITY.md) — report vulnerabilities to [email protected], never in a public issue.


Would an agent open an issue automatically?

It could, yes. Github has a high degree of automation support for its features.

(AI has been handling your requests in near-real time, including comments made in my name.)

I'd then appreciate to know what is AI and what is you :-)

ann0see · 2026-07-17T20:08:02Z

+- Features must be agreed in a GitHub issue or Discussion **before** coding — see CONTRIBUTING.md. If no agreement exists, propose; don't implement.
+- Stability outranks everything: Jamulus runs live performances. Prefer not adding a feature over adding risk (KISS principles in CONTRIBUTING.md).
+
+## Architecture laws


I'd prefer those to live somewhere else. I believe it's model specific...

Agreed — moved to a new docs/ARCHITECTURE.md, written for humans as well as agents: system overview, source map, threading model, and these invariants. AGENTS.md now carries only one-line summaries and a link.

ann0see · 2026-07-17T20:08:39Z

+
+- Naming your branch `autobuild/<name>` triggers CI builds of all targets on your fork — use it before opening the PR.
+- Include the `CHANGELOG:` line, and for new dependencies or build changes add `AUTOBUILD: Please build all targets` to the PR description.
+- PRs need two approving reviews to merge; the submitter is responsible for follow-up questions and agreed changes (see CONTRIBUTING.md).


Why is this needed? I don't think an agent should need to care about this.

- DEPLOY.md -> docs/DEPLOY.md, links adjusted, license header added - The "Architecture laws" section of AGENTS.md moves to a new docs/ARCHITECTURE.md written for humans as well as agents: system overview, source map, threading model, connection/protocol model, and the three stability invariants. AGENTS.md now links to it. - Reworded the protocol rule to make clear it is preventive (message IDs are frozen), not a report of past renumbering - Dropped the merge-mechanics bullet from AGENTS.md Co-Authored-By: Claude Fable 5 <[email protected]>

ann0see · 2026-07-17T20:26:28Z

+
+A directory is a Jamulus server acting as a registry. Ordinary servers register with it (`CLM_REGISTER_SERVER_EX`) and re-register periodically as a keepalive; clients ask it for the server list (`CLM_REQ_SERVER_LIST`). Because listed servers may sit behind NAT, the directory also brokers hole punching: it asks a server to send `CLM_SEND_EMPTY_MESSAGE` to a client's address so the client's follow-up packets can get through. Both sides of this are implemented in `CServerListManager`.
+
+## Where common changes go


I'd like to have a discussion here. I believe this would then live in AGENTS.md rather. But not sure.
I really want to have an extremely short AGENTS.md as I still stand behind needing to be able to load this into a small context window.

A small context window is not a realistic agentic scenario, because the open weight models only run effectively on datacenter hardware. I still want to offload everything from the main .md (AGENTS.md) into sub-.mds that it mentions and describes.

I still would like to have AGENTS.md small regardless.
I do have a context window of about 200 000 T (theoretical) for a local model I deem useful. However we should still ensure to not waste it.

ARCHITECTURE.md is now its own PR (#3791) — that discussion is invited there. Agreed on extremely short: AGENTS.md here is now 22 lines and just links out.

ann0see · 2026-07-17T20:27:08Z

+
+## Source map
+
+| Files | Responsibility |


Opencode Free Pickle just reads the files itself by enumerating src/ automatically.

ann0see · 2026-07-17T20:28:23Z

 - Insert a space before and after `(` and `)`. There should be no space between `)` and `;` or before an empty `()`.
 - Enclose all bodies of `if`, `else`, `while`, `for`, etc. in braces `{` and `}` on separate lines.
- Do not use concatinations in strings with parameters. Instead use substitutions. **Do:** `QString ( tr ( "Hello, %1. Have a nice day!" ) ).arg( getName() )` **Don't:** `tr ( "Hello " ) + getName() + tr ( ". Have a nice day!" )` ...to make translation easier.
+- Do not use concatenations in strings with parameters. Instead use substitutions. **Do:** `QString ( tr ( "Hello, %1. Have a nice day!" ) ).arg( getName() )` **Don't:** `tr ( "Hello " ) + getName() + tr ( ". Have a nice day!" )` ...to make translation easier.


Open a separate PR which only contains this typo fix. This will be a trivial merge

Done — #3792.

ann0see · 2026-07-17T20:29:29Z

But it didn't split it out into different PRs...

ann0see · 2026-07-17T20:30:13Z

Claude Fable 5

Very expensive model ;-).

ann0see · 2026-07-17T20:31:18Z

Actually, I think that AGENTS.md should be extremely clear to open multiple PRs if possible and ensure that changes remain reviewable.

…ring rule docs/DEPLOY.md and docs/ARCHITECTURE.md move to separate one-file PRs so nothing here blocks their review. The protocol-renumbering rule is removed — it described a problem nobody has had. Co-Authored-By: Claude Fable 5 <[email protected]>

ann0see · 2026-07-17T20:38:10Z

Closing as has been split into multiple PRs.

mcfnord · 2026-07-17T20:46:43Z

Split complete: this PR is now a single 22-line AGENTS.md, and it now states your granularity requirement as a hard rule — one PR per new file, per independent fix, per typo; every PR a standalone option reviewable in minutes. The pieces: #3790 (DEPLOY), #3791 (ARCHITECTURE), #3792 (typo), #3793 (CONTRIBUTING pointer). The GCC 13 moc issue will come back as a build fix rather than documentation.

ann0see · 2026-07-17T20:49:55Z

I suppose that #3789 (comment) was an AI comment?

ann0see reviewed Jul 17, 2026

View reviewed changes

This was referenced Jul 17, 2026

Add docs/DEPLOY.md: deploying a self-built server binary #3790

Closed

Add docs/ARCHITECTURE.md: system overview, source map, threading model #3791

Open

Fix typo in CONTRIBUTING.md: concatinations -> concatenations #3792

Merged

ann0see closed this Jul 17, 2026

mcfnord mentioned this pull request Jul 17, 2026

CONTRIBUTING.md: point agent-assisted contributors at AGENTS.md #3793

Open

mcfnord changed the title ~~Agent-ready docs: AGENTS.md, DEPLOY.md, COMPILING.md/CONTRIBUTING.md additions~~ Add AGENTS.md: a 22-line agent entry point Jul 17, 2026

mcfnord mentioned this pull request Jul 17, 2026

Add agent instructions for Jamulus #3785

Open

4 tasks


		A directory is a Jamulus server acting as a registry. Ordinary servers register with it (`CLM_REGISTER_SERVER_EX`) and re-register periodically as a keepalive; clients ask it for the server list (`CLM_REQ_SERVER_LIST`). Because listed servers may sit behind NAT, the directory also brokers hole punching: it asks a server to send `CLM_SEND_EMPTY_MESSAGE` to a client's address so the client's follow-up packets can get through. Both sides of this are implemented in `CServerListManager`.

		## Where common changes go

Uh oh!

Conversation

mcfnord commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcfnord commented Jul 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcfnord Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ann0see Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ann0see Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ann0see commented Jul 17, 2026

Uh oh!

ann0see commented Jul 17, 2026

Uh oh!

ann0see commented Jul 17, 2026

Uh oh!

ann0see commented Jul 17, 2026

Uh oh!

mcfnord commented Jul 17, 2026

Uh oh!

ann0see commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

mcfnord commented Jul 17, 2026 •

edited

Loading

mcfnord Jul 17, 2026 •

edited

Loading

ann0see Jul 17, 2026 •

edited

Loading

ann0see Jul 17, 2026 •

edited

Loading