Add hierarchical AGENTS.md knowledge base for AI-assisted development#320
Open
vboufleur wants to merge 2 commits into
Open
Add hierarchical AGENTS.md knowledge base for AI-assisted development#320vboufleur wants to merge 2 commits into
vboufleur wants to merge 2 commits into
Conversation
📝 WalkthroughWalkthroughAdds seven new AGENTS.md documentation files that codify OmniWM architecture, module responsibilities, IPC protocol, tooling and style rules, strict Swift concurrency expectations, dependency-injection/testing guidance, and contributor checklists. ChangesOmniWM Architectural Documentation (docs-only)
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (2)
Sources/OmniWMIPC/AGENTS.md (1)
46-51: ⚡ Quick winConsider adding protocol version guidance for queries.
The "Adding New Commands" section explicitly mentions bumping the protocol version for breaking changes (line 44), but this section omits similar guidance. Query changes can also break compatibility. Based on learnings, protocol version should be bumped for any breaking IPC changes.
📋 Suggested addition
## Adding New Queries 1. Add case to `IPCQueryName` enum 2. Define response payload struct (must be `Codable, Equatable, Sendable`) 3. Add descriptor to automation manifest 4. Handle in `IPCQueryRouter` +5. Bump protocol version if breaking change🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@Sources/OmniWMIPC/AGENTS.md` around lines 46 - 51, Add guidance to the "Adding New Queries" section to remind contributors to bump the IPC protocol version for any breaking changes: explicitly state that when modifying IPCQueryName, changing the response payload struct signature (types/properties), altering the automation manifest descriptor, or changing how IPCQueryRouter handles queries in a way that is not backward compatible, the protocol version must be incremented (matching the "Adding New Commands" guidance). Mention whether major/minor/patch semantics are used and where to update the protocol version constant so authors know the exact place to change it.Tests/OmniWMTests/AGENTS.md (1)
65-72: ⚡ Quick winAdd verification step to testing workflow.
The checklist should remind developers to run the verification suite. Based on learnings, developers should run
make verify(which includes format-check, lint, no-zig-audit, build, and test) before committing changes.📋 Suggested addition
## Writing New Tests 1. Create `{Feature}Tests.swift` 2. Use `@Suite `@MainActor` struct` 3. Use factory functions from support files for state setup 4. Call `resetSharedControllerStateForTests()` if touching global state 5. Prefer `#expect()` over complex assertion helpers 6. For layout tests, use `makeLayoutPlanTestController` + `waitForLayoutPlanRefreshWork()` +7. Run `make verify` before committing (includes format-check, lint, build, and test)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@Tests/OmniWMTests/AGENTS.md` around lines 65 - 72, Add a final verification step to the test-writing checklist: append a new numbered item after step 6 that instructs developers to run the full verification suite using the shell command `make verify` (this runs format-check, lint, no-zig-audit, build, and test). Edit the AGENTS.md checklist where the numbered items (1–6) are listed and add the new step text recommending `make verify` before committing, ensuring it references the command exactly as `make verify`.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 11-13: The fenced code block containing the architecture line
starting with "Input (Hotkeys, AX, Mouse, CGS) → WMEvent → Reconcile ..." has no
language tag and triggers markdownlint MD040; fix it by adding a language
identifier (e.g., "text") immediately after the opening ``` so the block becomes
```text ... ```, ensuring the markdown linter recognizes the fenced block
language.
In `@Sources/OmniWM/Core/AGENTS.md`:
- Around line 9-21: The markdown code fence for the pipeline diagram lacks a
language identifier which triggers markdownlint MD040; update the opening fence
from ``` to include a language (e.g., ```text) so the block is annotated —
modify the fenced block that contains the pipeline diagram (the Input Layer →
Output Layer diagram in AGENTS.md) to use a language identifier such as "text".
In `@Sources/OmniWM/Core/Controller/AGENTS.md`:
- Around line 50-52: The guide uses inconsistent coordinator names—replace all
occurrences of FocusBridgeCoordinator and KeyboardFocusLifecycleCoordinator with
the unified name FocusLifecycleCoordinator and update the prose to describe the
deferred focus pending → confirmed pattern handled by FocusLifecycleCoordinator;
ensure the header "Focus Bridge (Deferred Focus)" and any explanatory lines
reference FocusLifecycleCoordinator and the "pending → confirmed" flow so the
guide consistently maps the focus lifecycle to FocusLifecycleCoordinator.
In `@Sources/OmniWM/Core/Reconcile/AGENTS.md`:
- Around line 41-55: The fenced code block in AGENTS.md (the block starting with
``` and the event flow lines like "Raw Event (AX/CGS/Input)" through
"ReconcileTxn recorded for audit") lacks a language identifier and triggers
markdownlint MD040; add a language token (e.g., "text") after the opening
backticks so the fence becomes ```text to silence MD040 and preserve rendering.
In `@Sources/OmniWMIPC/AGENTS.md`:
- Around line 16-22: Update the File Map in AGENTS.md to list the two missing
support files so the total equals six; locate the section that currently lists
IPCModels.swift, IPCAutomationManifest.swift, IPCWire.swift, and
IPCSocketPath.swift and add the two omitted filenames (the small helper/support
files present in the module, e.g., the actual support files that correspond to
socket/message helpers—replace this placeholder with the real filenames found in
the repo) so the document accurately enumerates all six files and their brief
descriptions.
---
Nitpick comments:
In `@Sources/OmniWMIPC/AGENTS.md`:
- Around line 46-51: Add guidance to the "Adding New Queries" section to remind
contributors to bump the IPC protocol version for any breaking changes:
explicitly state that when modifying IPCQueryName, changing the response payload
struct signature (types/properties), altering the automation manifest
descriptor, or changing how IPCQueryRouter handles queries in a way that is not
backward compatible, the protocol version must be incremented (matching the
"Adding New Commands" guidance). Mention whether major/minor/patch semantics are
used and where to update the protocol version constant so authors know the exact
place to change it.
In `@Tests/OmniWMTests/AGENTS.md`:
- Around line 65-72: Add a final verification step to the test-writing
checklist: append a new numbered item after step 6 that instructs developers to
run the full verification suite using the shell command `make verify` (this runs
format-check, lint, no-zig-audit, build, and test). Edit the AGENTS.md checklist
where the numbered items (1–6) are listed and add the new step text recommending
`make verify` before committing, ensuring it references the command exactly as
`make verify`.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 09d083bd-a322-4a2c-b21e-a1a3b0ec7901
📒 Files selected for processing (7)
AGENTS.mdSources/OmniWM/Core/AGENTS.mdSources/OmniWM/Core/Controller/AGENTS.mdSources/OmniWM/Core/Layout/Niri/AGENTS.mdSources/OmniWM/Core/Reconcile/AGENTS.mdSources/OmniWMIPC/AGENTS.mdTests/OmniWMTests/AGENTS.md
- Add 'text' language identifier to fenced code blocks (MD040) - Fix inconsistent coordinator name: FocusBridgeCoordinator → KeyboardFocusLifecycleCoordinator - Complete IPC file map with IPCRuleValidator.swift and WorkspaceAddressing.swift
Owner
|
@vboufleur Hi thank you ❤️ I'll take a look at this on the next free day, the only problem O have with agents.md is how much context they use and if too strict can actually be counter productive and change your intent, my current one is only 4 lines, do not write code comments, do not create new branches or push commits, do not alter tests or production code if a test fails just notify the users, and I forgot the 4th one |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Hi!
This is a simple PR for adding docs for agents to better work on it. It was generated using the
/init-deepcmd of oh-my-openagent on Claude Opus 4.6Feel free to add changes to the files. I'm not that experience with the app but I plan to later add a feature for scrolling all windows horizontally as soon as a window is selected with the mouse and is moved, trying to make the experience as similar as possible to my favorite WM, PaperWM on Gnome. These files can help to implement it, and can be useful to the community as well.
Here's the summary by Copilot:
Summary by CodeRabbit