Adapt agent guidance and supporting docs for BeatGlow

This commit is contained in:
maze committed 2026-10-29 17:44:29 +01:00
1 parent 7916bc0b78
commit 07dc1ec5b3
5 files changed
+154 -1

No files matched your search

+22
View File
@@ -0,0 +1,22 @@
# Coding conventions
- Use idiomatic Go, `gofmt`, 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.
Adapted from [Flow's coding guide](https://github.com/onflow/flow-go/blob/master/docs/agents/CodingConventions.md),
with BeatGlow-specific lifecycle, logging and hardware guidance.
+21
View File
@@ -0,0 +1,21 @@
# 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.
Adapted from [Flow's Go documentation guide](https://github.com/onflow/flow-go/blob/master/docs/agents/GoDocs.md).
+20
View File
@@ -0,0 +1,20 @@
# 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.
Adapted from [Flow's operational guide](https://github.com/onflow/flow-go/blob/master/docs/agents/OperationalDoctrine.md).