Merge pull request 'Add BeatGlow agent instructions and feature-branch workflow' (#2) from chore/agent-branch-policy into main

Reviewed-on: #2
This commit was merged in pull request #2.
This commit is contained in:
maze committed 2026-10-29 18:49:13 +01:00
commit e4c2060422
5 files changed
+158

No files matched your search

+2
View File
@@ -16,6 +16,8 @@
!README.md
!LICENSE
!/AGENTS.md
!/docs/agents/*.md
# README screenshots and wiring illustrations
!/asset/image/beatglow-*.gif
+100
View File
@@ -0,0 +1,100 @@
# BeatGlow agent guide
BeatGlow is a Go music visualizer for embedded Linux audio players, especially
Raspberry Pi systems. Read the relevant code and these guides before changing it:
- [Coding conventions](docs/agents/CodingConventions.md)
- [Operational guidance](docs/agents/OperationalDoctrine.md)
- [Go documentation](docs/agents/GoDocs.md)
## Git and Gitea workflow
- Create and switch to a feature branch before editing files or making commits.
- Never commit directly on `main` or `master`.
- Use descriptive branch names, such as `feature/mpd-fifo-output-monitoring`,
`fix/readme-images`, or `chore/agent-instructions`.
- Continue on an existing feature branch when working on the same task. Create a
separate branch from the target branch for unrelated work.
- If changes already exist on `main` or `master`, create a feature branch that
preserves those changes before committing them.
- Open pull requests against the target branch; do not merge or push changes
directly to `main` or `master` unless the user explicitly requests it.
- Base new work on `main` (normally `origin/main`); fetch when remote state matters.
Do not discard local changes or rewrite unrelated commits to update the base.
- Make focused commits with concise, descriptive subjects.
- Use the configured remote; this project uses Gitea. MR and PR refer to the same
review workflow here. Do not assume GitHub tooling works with Gitea.
- PR descriptions should explain the problem, resulting behavior, verification,
and remaining limitations. Reference an issue only when one exists, and mark it
closed only if the change completes it. Target the branch the work is based on.
- When API authentication is unavailable, push the requested feature branch and
provide the creation link; distinguish a pushed branch from a submitted PR.
## Project map
| Location | Responsibility |
| --- | --- |
| `cmd/beatglow/` | CLI, configuration discovery, installation and startup |
| `controller.go`, `context.go`, `hardware.go` | Component setup, events, rendering and audio processing |
| `config/` | HCL configuration and user settings; examples in `beatglow.conf` |
| `app/layout/`, `app/widget/`, `app/shader/`, `app/font/` | Screens, widgets, visual effects and embedded fonts |
| `player/` | Player contracts, registration and automatic detection |
| `player/mpd/` | MPD connections, commands, metadata and artwork |
| `player/raudio/`, `player/volumio/`, `player/moode/`, `player/runeaudio/` | Distribution-specific integrations; inspect implementation completeness |
| `player/all/` | Side-effect imports that load player drivers |
| `sound/` | PCM file/FIFO sources and audio diagnostics |
| `hardware/` | Display setup, combined displays, Linux network information and inputs |
| `internal/`, `testdata/` | Internal helpers and test fixtures |
| `asset/image/`, `doc/hardware/` | README illustrations and hardware references |
Player detection runs in ascending priority order. Register distribution-specific
detectors ahead of generic MPD and import new drivers through `player/all/`.
Keep PCM sample format, channels and rate consistent with the configured producer.
## Build and verification
Use the Go version required by `go.mod` or newer. The display dependency currently
resolves to `../display`; check that checkout exists before diagnosing dependencies.
Do not silently remove the replacement or upgrade dependencies for unrelated work.
```sh
# Existing Makefile target: Linux ARM binary, written to ./beatglow
make beatglow
# Linux ARM64 binary without overwriting the repository's local executable
GOOS=linux GOARCH=arm64 go build -o /tmp/beatglow ./cmd/beatglow
# Execute on Linux; narrow package paths for focused changes
go test ./...
go vet ./...
# On macOS: compile Linux tests only; /usr/bin/true does not execute them
GOOS=linux GOARCH=arm64 go test -exec /usr/bin/true ./player/...
git diff --check
```
Run `goimports` on changed Go files. The Makefile has no test, lint, integration-test,
or generation targets. Linux wireless helpers prevent some packages from building
natively on macOS. Report cross-compilation separately from executed tests and
hardware verification. Use race tests on Linux when changing shared state.
Known failures observed during setup include a log-format vet error in
`app/font/font.go` and a float32/float64 test mismatch in `internal/calc/calc_test.go`.
Recheck their current status; report unrelated failures without hiding them or
expanding scope automatically.
## Assets and dependencies
The repository uses an allowlist `.gitignore`. Verify new docs and assets appear
in Git; add narrow exceptions when needed. README images belong in `asset/image/`.
Check that all Markdown image targets exist and are tracked.
PDF, BDF and TTF filters are configured in local `.gitattributes`; check the actual
attributes and Git LFS availability before adding or changing these files. Preserve
real assets and LFS objects. Never substitute placeholders to pass a build.
## Sources
Structure inspired by [Flow's AGENTS.md](https://github.com/onflow/flow-go/blob/master/AGENTS.md).
The linked local guides are project-specific adaptations, not verbatim imports.
+19
View File
@@ -0,0 +1,19 @@
# Coding conventions
- Use idiomatic Go, `goimports`, and the surrounding package's naming and import style.
Extend existing contracts instead of introducing parallel registries or layers.
- Wrap propagated errors with useful context and `%w`. Use `errors.Is` or
`errors.As` when callers need to recognize them.
- Decide recovery at the caller: a disconnected MPD server can be retried, while
unusable startup configuration should return an error. Explain intentional
recovery; avoid silent failures and unnecessary process termination.
- Use structured Logrus fields for component, device, connection and path context.
Keep frame/sample loops quiet; log meaningful transitions and actionable failures.
- Keep display refreshes and controller event handling responsive. Close owned
connections, files and tickers; make goroutine shutdown explicit. Review channel
ownership and synchronization when changing lifecycle behavior.
- Validate protocol responses, HCL values, dimensions and PCM formats before use.
Respect Linux build constraints and hardware-specific dependencies.
- Put focused tests beside implementations. Cover parsing, malformed input,
detection precedence, failures and recovery with temporary files or fake servers.
Unit tests should run without physical GPIO, displays or a live MPD instance.
+19
View File
@@ -0,0 +1,19 @@
# Go documentation
- Document new or changed exported APIs and interfaces. Explain private code when
its lifecycle, protocol behavior or invariants are not clear from the code.
- Start API comments with the declared name and write complete sentences. Use
paragraphs and Go doc links such as `[Player]` for relevant Go identifiers.
- Describe the contract: parameter constraints, units, defaults, return values,
blocking behavior and resource ownership when they matter to callers.
- For error returns, explain actionable failure conditions and recognizable
sentinel errors that the implementation actually returns. Do not invent error
types, guarantees or recovery behavior.
- State concurrency restrictions explicitly. Do not assume a type is safe for
concurrent use simply because no warning exists.
- Keep interface contracts and implementations consistent. Explain meaningful
deviations rather than copying comments mechanically.
- For documentation-only tasks, preserve runtime behavior. Correct inaccurate
documentation after checking the implementation; keep separate logic fixes scoped.
- Wrap prose around 100 characters where practical. Avoid documenting obvious
implementation steps or adding repetitive boilerplate.
+18
View File
@@ -0,0 +1,18 @@
# Operational guidance
- Follow the user's task and established preferences. Continue authorized work
without repeatedly asking for confirmation; clarify genuinely missing decisions.
- Inspect the code, branch, diff and relevant documentation before making changes.
Verify external protocol behavior against upstream documentation when needed.
- Keep changes within scope and preserve unrelated work. Explain a necessary
scope change instead of silently bundling cleanup or dependency updates.
- Communicate directly and briefly. Explain findings, behavior changes and remaining
uncertainty; avoid flattery and unsupported claims.
- Review the surrounding component after editing, including configuration,
registration, lifecycle and callers affected by an interface change.
- Test the behavior that changed. State which tests ran, which checks only
compiled, and what requires Linux, hardware, network access or authentication.
- Describe recoverable device/server failures realistically. Do not label an issue
critical without evidence or claim a fix is verified on hardware without testing it.
- Finish with concise results, links to changed files or the PR, and material
limitations. Never report a PR created when only its branch was pushed.