Skip to content

Add agent instructions for Jamulus #3785

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ann0see wants to merge 3 commits into
base: main
Choose a base branch
from
+82 −0
Open

Add agent instructions for Jamulus #3785

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
15d7319
CONTRIBUTING.md: point agent-assisted contributors at AGENTS.md
mcfnord Aug 13, 2026
540c4cf
Add agent instructions for Jamulus
ann0see Aug 13, 2026
2b52493
AGENTS.md aktualisieren
ann0see Aug 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 80 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Jamulus — Agent Instructions

Real-time networked music jamming app. Qt/C++ qmake project. Client and server share one codebase; entry point: `src/main.cpp`. Configure `CONFIG` flags in `Jamulus.pro`.

**Make the smallest possible change. One logical change per PR. Never mix refactoring with fixes/features.**

Priority order: Stability > Low latency / real-time safety > Backwards compatibility > Maintainability > New features. This order resolves conflicts only — new features are welcome.

---

## Build

Linux: `qmake && make` (use `qmake-qt5` on Fedora). Headless server: `qmake "CONFIG+=headless serveronly" && make`. First run: `git submodule update --init` (oboe for Android). Run `make distclean` before re-running `qmake` with different `CONFIG` flags. Full per-platform table: `COMPILING.md`.

macOS: `qmake QMAKE_APPLE_DEVICE_ARCHS=arm64 QT_ARCH=arm64 -spec macx-xcode Jamulus.pro` (Use `x86_64` on Intel Macs; `macx-clang` if using `make`). Then `xcodebuild build`, and `macdeployqt ./{Debug,Release}/Jamulus.app`.

**Testing:** run headless server (args `-s -n`), connect a client (e.g. via: `-n -c localhost`; may need jackd running on Linux. Run dummy Jack via: `jackd -d dummy`), exercise the change; use the JSON-RPC API (`docs/JSON-RPC.md`) where possible. State what you tested in the PR with evidence. GitHub Actions builds multiple platforms — on failure read the failing step's log.

## Never Do

**`Never Do` rules are absolute**

- Introduce code that prevents processing of audio within the minimum cycle time for any frame (i.e. worst case must remain viable); DO test this and produce evidence to support the change
- this covers sound process in `src/sound`, network processing in `src/socket.cpp` and mixing in `src/server.cpp`
- potential problems include (but not limited to): memory allocation, file I/O, locks
- where possible, move processing off the real-time thread with queued signals
- Trust values from remote clients — validate size/bounds on all network input (malformed input crashes).
- Edit generated files (`moc_*.cpp`, `ui_*.h`, `qrc_*.cpp`, `*.qm`) — regenerate; don't edit/reformat third-party code in `libs/`.
- Edit `ChangeLog` directly — use a `CHANGELOG:` line in the PR.

Comment thread
pljones marked this conversation as resolved.
## Always

- Attach test evidence (logs/output) to the PR — never just assert something works.
- Say so if you did not run or verify something.

## Ask first

- Architecture changes (networking/protocol, threading, build system) — open an issue to discuss (see `CONTRIBUTING.md`).

## Qt / portability

- Minimum Qt: **5.12.2**. Qt 6 recommended (iOS: Qt 5.15+ required, Qt 6 iOS buggy). Guard newer APIs with `#if QT_VERSION >= QT_VERSION_CHECK(...)`.
- C++11 (C++17 on Android for Oboe).
- Preserve platform support.
- Desktop: Windows 10+, macOS 10.10+, Ubuntu 20.04+/Debian 11+.

## Style (C / C++ / Obj-C++)

- **CI uses clang-format** (version in `.github/workflows/coding-style-check.yml`).
- Run `make clang_format` before committing (works only after qmake).
- CI runs **shellcheck + shfmt** on `.sh` files; **pylint** (config: `.pylintrc`) on `.py` files in `tools/`.
- New contributions: AGPL 3.0+ license header. Pre-3.12.1dev code: GPL 3.0+ (see `CONTRIBUTING.md`).
- Use `tr ( "Hello %1" ).arg ( name )` for user-facing strings — never string concatenation.

## JSON-RPC

- Changing RPC methods (e.g. `src/clientrpc.cpp` / `src/serverrpc.cpp`) requires regenerating `docs/JSON-RPC.md` with `tools/generate_json_rpc_docs.py` (CI fails otherwise).
- Requires `--jsonrpcport` + `--jsonrpcsecretfile` at runtime. Binds to localhost by default. Secret requires ≥16 characters.

## PR expectations

- One logical change per PR — no unrelated cleanup or reformatting of untouched code. Discuss features in an issue before implementing. See `CONTRIBUTING.md`.
- Branch names starting with `autobuild` trigger CI builds on your fork.
- Follow `.github/pull_request_template.md`. Include `CHANGELOG:` line. Add `AUTOBUILD: Please build all targets` for skipped targets (iOS, Windows JACK, Linux armhf/arm64) if touched; see `.github/workflows/autobuild.yml`.
- Builds? Tested? Smallest change possible? Self reviewed against "Priority order" above?
- Disclose AI-generated text at the end of Comments/PRs. (e.g: `> 🤖 Used AI: <model>, <harness>`) — never in code comments.

## Posting (comments, issues, discussions)

- Test any claim you can test before posting it — a build, a log, a run — and cut what you can't; *presumably*, *should*, and *likely* mark sentences that need a measurement or deletion.
- Comment only when you add evidence or an answer the thread lacks, in the shortest form that carries it; wait out an active human exchange, re-read the thread just before posting — it may have moved while you drafted — and treat a maintainer's stated preference about engagement as the rule.
- If a posted comment proves wrong or incomplete, edit it in place so the error leaves the page; new evidence on the same finding also belongs in the existing comment, not a new one.
- Open a new issue only for a defect you can reproduce, with the reproduction in the body; open a new PR only after a maintainer has agreed the change is wanted; leave starting discussions to humans.

## Read when relevant

@mcfnord mcfnord Aug 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI: The file covers code and PR mechanics; this adds the posting side in four sentences. The first rule is the minimum worth keeping if space is tight.

Suggested change
## Read when relevant
## Posting (comments, issues, discussions)
- Test any claim you can test before posting it — a build, a log, a run — and cut what you can't; *presumably*, *should*, and *likely* mark sentences that need a measurement or deletion.
- Comment only when you add evidence or an answer the thread lacks, in the shortest form that carries it; wait out an active human exchange, re-read the thread just before posting — it may have moved while you drafted — and treat a maintainer's stated preference about engagement as the rule.
- If a posted comment proves wrong or incomplete, edit it in place so the error leaves the page; new evidence on the same finding also belongs in the existing comment, not a new one.
- Open a new issue only for a defect you can reproduce, with the reproduction in the body; open a new PR only after a maintainer has agreed the change is wanted; leave starting discussions to humans.
## Read when relevant

@mcfnord mcfnord Aug 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In theory some of this could push off to a file named COMMENTING.md. I am a little desperate to cram project-revolutionizing guidance past your brevity & concision gate. I could submit a draft COMMENTING.md and we could just link to it. That's a good design because whether to comment is a gated question that AGENTS.md can notice and investigate. But you keep saying you want to push and I keep feeling a little desperate that you are still not getting what needs getting. Nor do I think it's some infinite supply of guidance. But effective AGENTS.md sound really powerful to me an extremely concise and brief AGENTS.md seem less interesting. Maybe I'm stupid here. I just hope we can level up with guidance like this soon so there's less turmoil and frustration.

@ann0see ann0see Aug 15, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For sure it's a trade off. However the goal is to not waste tokens. If you can say something in 5 words why do we need 10. I expect a machine to understand brief sentences and not need fillers or overly long sentences. We can change this later anyway.

@mcfnord mcfnord Aug 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most LLMs are able to pare the suggested additions down further, and most of them could live in a COMMENTING.md instead. Granted, even the crudest form of "test every claim" would be a leap from where the PR is now. But a powerful model can write instructions with real nuance in them, and a lesser model can follow more of that nuance than you'd expect. We shouldn't ask lesser models to write the nuance, but we also shouldn't grind a powerful model's instructions into baby food before handing them down. There's no filler here. There's nuance, and I will make you love it eventually.

@pljones pljones Aug 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line 79. For the benefit of other readers, I think it's generally polite to mark an edit in place -- if something previously stated is wrong, sometimes it's helpful to say "subsequently proved wrong" and ~strike it out~ so a reader knows. Similarly, additional content should be delineated from the original (with guidance on where it fits in, if needs be).

A comment that is totally superseded should be edited to "delete, content misleading" or similar and replaced with a new, later comment.

(Maybe that last is the most succinct form...)

@pljones pljones Aug 16, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I agree, a COMMENTING.md might be useful if fleshing these out is needed -- with a "Read only where commenting" note, so it's not always in context.


- `CONTRIBUTING.md` — process, style, licensing
- `COMPILING.md` — full build per platform, CONFIG flags table
- `docs/JAMULUS_PROTOCOL.md` — network protocol, packet IDs, ack rules
- `SECURITY.md` — security reporting
2 changes: 2 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ We’d really appreciate your support! Please ensure that you understand the fol
- Otherwise, please [post on the GitHub Discussions](https://github.com/jamulussoftware/jamulus/discussions) and say that you are planning to do some coding and explain why. Then we can discuss the specification.
- Please begin coding only after we have agreed on a specification to avoid putting a lot of effort into something that may not be accepted later.

If you work with an AI coding agent, [AGENTS.md](AGENTS.md) is its entry point into this repository. Everything in this document applies to agent-assisted contributions without exception: you remain the author, and you are expected to understand and stand behind every line you submit.


## Jamulus project/source code general principles

Expand Down
Loading