fix(agents): drop Aider from the instruction-file registry; fix AGENTS.md guide - #745
Conversation
…GENTS.md guide Co-Authored-By: SageOx <ox@sageox.ai> SageOx-Session: https://sageox.ai/c/ses_019fb6a6-5bf9-76a3-88cb-283c84366844
📝 WalkthroughWalkthroughThe change removes Aider from the local instruction-file registry, documents adapter-managed ChangesAgent instruction ownership
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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: 2
🤖 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 `@cmd/ox/guides/agents-md.md`:
- Line 9: Update the sentence in the guide to use “AI coworkers” instead of “AI
coding agents,” while preserving “OpenAI Agents SDK” unchanged as a product
name.
- Line 9: Update the documentation paragraph describing AGENTS.md consumers to
remove the claim that the OpenAI Agents SDK automatically reads repository-root
AGENTS.md files, or qualify it to state that the SDK receives caller-supplied
instructions through Agent.instructions. Do not imply SageOx or the SDK performs
automatic discovery.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 1f14e51a-a8d0-44f3-9353-63e5c243baf4
📒 Files selected for processing (3)
cmd/ox/guides/agents-md.mdcmd/ox/instruction_files.gocmd/ox/instruction_files_test.go
| # AGENTS.md and CLAUDE.md | ||
|
|
||
| AI coding agents read instruction files at session start to learn project conventions. Different tools historically named these files differently — `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), `.windsurfrules` (Windsurf), `GEMINI.md` (Gemini CLI), `CONVENTIONS.md` (Aider). The cross-tool convention has converged on **AGENTS.md at the repo root**, which Codex, OpenCode, Amp, Pi, Goose, and Gemini CLI all read. | ||
| AI coding agents read instruction files at session start to learn project conventions. Different tools historically named these files differently — `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), `.windsurfrules` (Windsurf), `GEMINI.md` (Gemini CLI), `CONVENTIONS.md` (Aider). The cross-tool convention has converged on **AGENTS.md at the repo root**, which Codex, OpenCode, Amp, Pi, Goose, and the OpenAI Agents SDK all read. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use the canonical term in this guide.
This sentence uses AI coding agents. The repository guideline requires AI coworker instead of agent in *.md files. Replace it with AI coworkers. Keep OpenAI Agents SDK unchanged because it is a product name.
As per coding guidelines: use canonical user-facing terminology, including AI coworker instead of agent, in *.go, *.md, and *.mdx files.
🤖 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 `@cmd/ox/guides/agents-md.md` at line 9, Update the sentence in the guide to
use “AI coworkers” instead of “AI coding agents,” while preserving “OpenAI
Agents SDK” unchanged as a product name.
Source: Coding guidelines
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- guide ---'
sed -n '1,40p' cmd/ox/guides/agents-md.md
printf '%s\n' '--- repository references to OpenAI Agents SDK and AGENTS.md ---'
rg -n -i --glob '!vendor/**' --glob '!node_modules/**' \
'OpenAI Agents SDK|openai[-_ ]agents|AGENTS\.md|Agent\.instructions|instructions' .
printf '%s\n' '--- candidate wrapper files ---'
git ls-files | rg -i '(^|/)(agent|agents|openai|codex|instructions|context|guide|readme|docs)'Repository: sageox/ox
Length of output: 50368
🌐 Web query:
OpenAI Agents SDK Python repository AGENTS.md automatic discovery Agent.instructions documentation
💡 Result:
In the OpenAI Agents SDK for Python, the AGENTS.md file and Agent.instructions property serve distinct purposes within the framework's architecture [1][2]. AGENTS.md The AGENTS.md file is a repository-level documentation file found in the root of the OpenAI Agents SDK Python repository [1][3]. Its purpose is to help contributors understand the project's structure, development workflows, and conventions [1][2]. It contains guidance on repository maintenance, testing commands, output paths, and workspace rules, rather than acting as a configuration file for agent behavior [1][2]. Agent.instructions The Agent.instructions property is a core attribute used when defining an Agent [4][5]. It acts as the "system prompt" for the Large Language Model (LLM) backing the agent, describing its role, behavioral constraints, and task-specific logic [4][6]. Key details regarding Agent.instructions: - It is technically optional in the SDK, as an Agent can be instantiated without it (defaulting to None), though it is strongly recommended to provide instructions to ensure predictable behavior [7]. - It can be provided as a static string or, in some contexts, as a function that dynamically generates instructions based on the run context [6]. Automatic Discovery There is no native feature in the core OpenAI Agents SDK labeled "automatic discovery" for Agent.instructions [4][5]. However, "automatic discovery" is a pattern used in associated ecosystem packages, such as those for Model Context Protocol (MCP) integration [8][9]. In those specific implementations, the SDK can automatically discover configuration files (e.g., mcp_agent.config.yaml) to load server definitions, allowing the agent to aggregate tools without manual registration [8][9]. This is distinct from the core agent definition logic [4][8].
Citations:
- 1: https://github.com/openai/openai-agents-python/blob/main/AGENTS.md
- 2: https://github.com/openai/openai-cookbook/blob/main/examples/agents_sdk/migrate-from-claude-agent-sdk/README.md
- 3: https://github.com/openai/openai-agents-python/blob/09ea6aa42024eb9e151832833c22d8340ee46774/AGENTS.md
- 4: https://openai.github.io/openai-agents-python/agents/
- 5: https://openai.github.io/openai-agents-python/quickstart/
- 6: https://openai.github.io/openai-agents-js/openai/agents/realtime/classes/realtimeagent/
- 7: docs: mark Agent.instructions as optional openai/openai-agents-python#3384
- 8: Add MCP support to Agent SDK openai/openai-agents-python#40
- 9: https://github.com/saqadri/openai-agents-mcp
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- guide ---'
sed -n '1,40p' cmd/ox/guides/agents-md.md
printf '%s\n' '--- repository references ---'
rg -n -i --glob '!vendor/**' --glob '!node_modules/**' \
'OpenAI Agents SDK|openai[-_ ]agents|AGENTS\.md|Agent\.instructions|instructions' .
printf '%s\n' '--- candidate files ---'
git ls-files | rg -i '(^|/)(agent|agents|openai|codex|instructions|context|guide|readme|docs)'Repository: sageox/ox
Length of output: 50368
Qualify the OpenAI Agents SDK claim. The SDK accepts caller-supplied instructions through Agent.instructions; it does not document automatic discovery of a repository-root AGENTS.md. SageOx has no wrapper that provides this discovery. Remove or qualify the SDK claim.
🤖 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 `@cmd/ox/guides/agents-md.md` at line 9, Update the documentation paragraph
describing AGENTS.md consumers to remove the claim that the OpenAI Agents SDK
automatically reads repository-root AGENTS.md files, or qualify it to state that
the SDK receives caller-supplied instructions through Agent.instructions. Do not
imply SageOx or the SDK performs automatic discovery.
Greptile SummaryThis change removes Aider’s incorrect The built CLI was checked before and after the change. The updated Confidence Score: 5/5
 T-Rex LogsWhat T-Rex did
Reviews (1): Last reviewed commit: "fix(agents): drop Aider from the instruc..." | Re-trigger Greptile |
1 participant
Summary
Two documentation-vs-code contradictions found while reviewing #738 against
origin/main. Both are cases whereoxsaid one thing and did another, and neither would ever surface as a crash — only as an AI coworker that silently never got primed.1. Aider was registered against a file it does not read
cmd/ox/instruction_files.golisted Aider withProjectFiles: []string{"AGENTS.md"}. Aider loads only what.aider.conf.yml'sread:directive names —CONVENTIONS.mdby default. MeanwhileREADME.mdanddocs/guides/agent-compatibility.mdboth advertisedCONVENTIONS.md, so the registry and the docs disagreed about Aider's own instruction file.AGENTS.mdis already claimed by Codex, OpenCode, Amp, and Goose withDetectFn: nil, andDetectedInstructionFilesdedupes by resolved path — so Aider's entry never produced a target, for any file, in any repo. It was documentation-as-code, and the documentation was wrong.ox-adapter-aiderownsCONVENTIONS.mdend to end — install, check, uninstall, diagnose — under its ownox:prime:aider:start/:endmarker pair. That path works today and is what the docs describe.flowchart LR INIT["ox init"] --> REG["InstructionFileRegistry"] REG --> AMD["AGENTS.md<br/>ox:prime markers"] AMD -.->|"deduped away, and Aider never reads it"| DEAD["no effect"] ADAPT["ox adapter install aider"] --> CONV["CONVENTIONS.md<br/>ox:prime:aider block"] CONV --> LOADS["Aider loads it via<br/>the .aider.conf.yml read directive"]Removed the entry rather than repointing it at
CONVENTIONS.md. Repointing would stack a second, differently-marked copy of the same prime instruction on top of the adapter's block — precisely what the neighbouring Goose spec's comment rejects for.goosehints. WithDetectFn: nilit would also inject into any repo that happens to have aCONVENTIONS.md, Aider or not. An inline comment now sits where the entry was so it does not get re-added.No doc changes needed —
README.mdand the compatibility guide already saidCONVENTIONS.md.2. The AGENTS.md guide contradicted itself in one sentence
cmd/ox/guides/agents-md.mdnamedGEMINI.mdas Gemini CLI's instruction file and then, in the same sentence, listed Gemini CLI among the tools that readAGENTS.md.instruction_files.goregisters Gemini againstGEMINI.mdonly. Replaced the trailing item with "the OpenAI Agents SDK", which is what the text said before it drifted.Context: PR #738
This branch came out of reviewing #738 against the latest
main. That PR turned out to be entirely superseded by #739 and #740 — three of its files were already byte-identical tomain, and merging it would have regressedmain(Goose demoted from a shipped adapter back to marker-only,sageox/agentxdowngradedv0.1.13tov0.1.12, and "AI coworker" rewritten to "agent" against the terminology rule). #738 is now closed with a comment mapping each piece to where it landed. The one line worth keeping from it is theagents-md.mdfix above.Tracked as
ox-fbrm(closed). Still open from the same audit and not in this PR:ox-h064(adapter compliance suite has noTestXxxentry point) andox-osm5(gemini/pi/aider ship an unregisteredrules.go).Test Plan
TestInstructionFileRegistry_AiderIsAdapterOwned— new. Asserts no registry spec claimsaiderand no spec listsCONVENTIONS.md. Written against the general class, not the one instance: a spec that names an instruction file its agent does not load, or that the agent's own adapter already owns.instruction_files.gotoHEAD, ran the new test alone, watched it fail onShould not be: "aider", then restored the fix and watched it pass. A test that is green both ways guards nothing.make lint— 0 issues.go test ./cmd/ox/...— pass (117s), including the pre-existingTestDetectedInstructionFiles_*andTestRemoveInstructionFileMarkers_*suites that exercise the registry end to end. Two stale comments in those tests that named Aider as anAGENTS.mdsharer now name Goose.go build ./cmd/ox && ox guide agents-mdemits the corrected sentence, confirming thego:embedcopy picked it up.No behavior change to verify manually: the removed registry entry was already unreachable via dedup, so
ox initwrites exactly the same files before and after.Checklist (expand if needed)
TestInstructionFileRegistry_AiderIsAdapterOwned, verified red without the fix/security-reviewon the diff, or N/A documented — N/A: docs + a registry-literal deletion + a test. Touches none ofinternal/auth/,internal/mcp/,internal/session/raw_writer.go,cmd/ox/prepush_scan.go,internal/upgrade/, orgo.sumCo-Authored-By: SageOx
Co-authored-by: SageOx ox@sageox.ai
Summary by CodeRabbit
Documentation
AGENTS.mdguidance to reference the OpenAI Agents SDK instead of Gemini CLI.Bug Fixes
CONVENTIONS.mdconfiguration is recognized through its adapter without being incorrectly treated as a shared instruction file.