Add AGENTS.md #61

Merged

JackFrostbyte merged 1 commit from feature/issue-53-add-agents-md into develop

2026-05-15 20:46:41 -04:00

McJuniorstein commented

2026-05-15 20:13:11 -04:00

Collaborator

Summary

Adds AGENTS.md — the cross-LLM project conventions file.
Source: JackFrostbyte's GPT-assisted draft (issue #53). Review posted in issue thread; revisions agreed in @JackFrostbyte's most recent comment.
Applies all three must-fix items and all four nice-to-have additions from the review.

What changed vs. the draft

Must-fix (per @JackFrostbyte's review reply)

§15 trimmed to real future/open work. Removed items already completed by merged PRs:
- previous_sigterm_handler cleanup → completed by PR #54.
- Zero-byte skeleton files cleanup → completed by PR #52.
- SIGHUP handling → completed by PR #55.
- leave_dark_blue doc/default mismatch → completed by PR #56.
- Kept: scheduler weighting; OpenRGB GUI conflict note.
§20 rewritten with the specific identity convention per contributor's tooling:
- Claude Code via McJuniorstein → Claude (via McJuniorstein) <mcjuniorstein@proton.me> Git author.
- GPT-assisted work via JackFrostbyte → Jack's normal Git identity; GPT attribution lives in commit body / PR / issue comment, not the author field.
- Explicit: no history rewrites.
Version policy + hotfix flow added to §2. v1.0.X / v1.1.X / v1.2 lanes; hotfix branches from main, tag, then cherry-pick/merge back to develop. §4 PR rule #1 updated to acknowledge the hotfix exception.

Nice-to-have (per @JackFrostbyte's review reply)

Snapshot/staleness markers added at the top of §10 (hardware), §12 (animation expectations), §14 (OpenRGB startup) using the wording specified: Snapshot as of 13-05-2026 — verify against current repo state before relying on specific details.
Issue-start coordination step added to §21 — LLMs check for an open PR / existing feature/issue-N-* branch / recent comments before starting parallel work.
docs/research/ pattern documented as a subsection in §19 (Research and RFC-style planning). One file per source/investigation, YYYY-MM-DD-topic.md naming.
v1.2 portability deferral added as a §15 subsection — restructuring §10 and §12 into reference examples is out of scope for v1.0.X and v1.1.X.

One small extra (flagging for your call)

§14 acknowledges PR #60. Your review predated PR #60 (merged ~3 hours later the same day), so the "Current chosen direction" paragraph in the draft already described what PR #60 implemented. I tightened the section heading from "Current OpenRGB startup issue context" to "OpenRGB startup context", changed the "Current chosen direction" header to "Chosen direction (implemented)", and added a one-line note at the end pointing at the landed files (systemd/user/openrgb-sdk.service, scripts/wait_for_openrgb_i2c.py, docs/systemd-user-service.md). If you'd rather keep §14 verbatim as you reviewed it and handle the PR #60 acknowledgment in a follow-up, say the word and I'll revert that part.

Verification

ruff check src tests scripts — all checks passed
git status --short — only AGENTS.md staged; docs/research/ deliberately left untracked (out of scope for this PR)
git diff reviewed
Dry-run smoke test — N/A, docs-only
Hardware verification — N/A, docs-only

Hardware verification

Not required.

Linked issue

Closes #53.

## Summary - Adds `AGENTS.md` — the cross-LLM project conventions file. - Source: JackFrostbyte's GPT-assisted draft (issue #53). Review posted in issue thread; revisions agreed in @JackFrostbyte's most recent comment. - Applies all three must-fix items and all four nice-to-have additions from the review. ## What changed vs. the draft ### Must-fix (per @JackFrostbyte's review reply) 1. **§15 trimmed to real future/open work.** Removed items already completed by merged PRs: - `previous_sigterm_handler` cleanup → completed by PR #54. - Zero-byte skeleton files cleanup → completed by PR #52. - SIGHUP handling → completed by PR #55. - `leave_dark_blue` doc/default mismatch → completed by PR #56. - Kept: scheduler weighting; OpenRGB GUI conflict note. 2. **§20 rewritten** with the specific identity convention per contributor's tooling: - Claude Code via McJuniorstein → `Claude (via McJuniorstein) <mcjuniorstein@proton.me>` Git author. - GPT-assisted work via JackFrostbyte → Jack's normal Git identity; GPT attribution lives in commit body / PR / issue comment, not the author field. - Explicit: no history rewrites. 3. **Version policy + hotfix flow added to §2.** v1.0.X / v1.1.X / v1.2 lanes; hotfix branches from `main`, tag, then cherry-pick/merge back to `develop`. §4 PR rule #1 updated to acknowledge the hotfix exception. ### Nice-to-have (per @JackFrostbyte's review reply) 4. **Snapshot/staleness markers** added at the top of §10 (hardware), §12 (animation expectations), §14 (OpenRGB startup) using the wording specified: `Snapshot as of 13-05-2026 — verify against current repo state before relying on specific details.` 5. **Issue-start coordination step** added to §21 — LLMs check for an open PR / existing `feature/issue-N-*` branch / recent comments before starting parallel work. 6. **`docs/research/` pattern** documented as a subsection in §19 (Research and RFC-style planning). One file per source/investigation, `YYYY-MM-DD-topic.md` naming. 7. **v1.2 portability deferral** added as a §15 subsection — restructuring §10 and §12 into reference examples is out of scope for v1.0.X and v1.1.X. ### One small extra (flagging for your call) **§14 acknowledges PR #60.** Your review predated PR #60 (merged ~3 hours later the same day), so the "Current chosen direction" paragraph in the draft already described what PR #60 implemented. I tightened the section heading from "Current OpenRGB startup issue context" to "OpenRGB startup context", changed the "Current chosen direction" header to "Chosen direction (implemented)", and added a one-line note at the end pointing at the landed files (`systemd/user/openrgb-sdk.service`, `scripts/wait_for_openrgb_i2c.py`, `docs/systemd-user-service.md`). If you'd rather keep §14 verbatim as you reviewed it and handle the PR #60 acknowledgment in a follow-up, say the word and I'll revert that part. ## Verification - [x] `ruff check src tests scripts` — all checks passed - [x] `git status --short` — only `AGENTS.md` staged; `docs/research/` deliberately left untracked (out of scope for this PR) - [x] `git diff` reviewed - [ ] Dry-run smoke test — N/A, docs-only - [ ] Hardware verification — N/A, docs-only ## Hardware verification Not required. ## Linked issue Closes #53.

McJuniorstein added 1 commit

2026-05-15 20:13:11 -04:00

Add AGENTS.md 3fa4839866