Skip to content

fix(agents): drop Aider from the instruction-file registry; fix AGENTS.md guide #745

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rsnodgrass merged 1 commit into from
Jul 31, 2026
+31 −11
Merged

fix(agents): drop Aider from the instruction-file registry; fix AGENTS.md guide #745

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cmd/ox/guides/agents-md.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ audience: both

# 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.

@coderabbitai coderabbitai Bot Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 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:

🏁 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.


SageOx supports both `AGENTS.md` and `CLAUDE.md` and follows the convention of treating them as siblings — typically `CLAUDE.md` is a symlink to `AGENTS.md` so both work without duplication.

Expand Down
15 changes: 7 additions & 8 deletions cmd/ox/instruction_files.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@ const (
agentCline = "cline"
agentOpenCode = "opencode"
agentAmp = "amp"
agentAider = "aider"
agentGoose = "goose"
)

Expand Down Expand Up @@ -160,13 +159,13 @@ var InstructionFileRegistry = []InstructionFileSpec{
MarkerFormat: markerFormatMarkdown,
DetectFn: nil, // shares AGENTS.md
},
{
AgentType: agentAider,
DisplayName: "Aider",
ProjectFiles: []string{"AGENTS.md"},
MarkerFormat: markerFormatMarkdown,
DetectFn: nil, // shares AGENTS.md
},
// Aider is deliberately absent. It reads whatever .aider.conf.yml's `read:`
// points at — CONVENTIONS.md by default — never AGENTS.md, so an AGENTS.md
// entry here marked a file Aider does not load while the docs promised
// CONVENTIONS.md. ox-adapter-aider owns CONVENTIONS.md end to end (install,
// check, uninstall, diagnose) under its own ox:prime:aider markers; adding a
// CONVENTIONS.md entry here would stack a second, differently-marked copy of
// the same prime instruction on top of the adapter's block. See ox-fbrm.
{
AgentType: agentGoose,
DisplayName: "Goose",
Expand Down
25 changes: 23 additions & 2 deletions cmd/ox/instruction_files_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ func TestDetectedInstructionFiles_EmptyDir(t *testing.T) {

targets := DetectedInstructionFiles(root)

// agents with nil DetectFn (Codex, OpenCode, Amp, Aider) always pass detection,
// agents with nil DetectFn (Codex, OpenCode, Amp, Goose) always pass detection,
// so AGENTS.md appears via them even in an empty dir
names := targetRelPaths(targets)
assert.Contains(t, names, "AGENTS.md", "AGENTS.md should appear (shared by nil-DetectFn agents)")
Expand Down Expand Up @@ -98,7 +98,7 @@ func TestDetectedInstructionFiles_DeduplicatesSharedFiles(t *testing.T) {

targets := DetectedInstructionFiles(root)

// AGENTS.md is listed by Claude Code, Codex, OpenCode, Amp, and Aider.
// AGENTS.md is listed by Claude Code, Codex, OpenCode, Amp, and Goose.
// Dedup should ensure it appears only once.
names := targetRelPaths(targets)
count := 0
Expand Down Expand Up @@ -615,6 +615,27 @@ func TestInstructionFileRegistry_GooseSharesAgentsMd(t *testing.T) {
assert.False(t, goose.Creatable, "AGENTS.md is a primary file; Creatable would be redundant")
}

// TestInstructionFileRegistry_AiderIsAdapterOwned pins Aider OUT of this
// registry. Aider loads only what .aider.conf.yml's `read:` names —
// CONVENTIONS.md by default — so an AGENTS.md entry marked a file Aider never
// reads while README.md and docs/guides/agent-compatibility.md both promised
// CONVENTIONS.md. ox-adapter-aider owns CONVENTIONS.md end to end under its own
// ox:prime:aider markers, so a CONVENTIONS.md entry here is equally wrong: it
// would stack a second, differently-marked prime block on the adapter's.
//
// Failure prevented (the general class, not just Aider): a registry spec that
// names an instruction file its agent does not actually load, or that the
// agent's own adapter already owns — either way ox reports the agent as primed
// when it is not, or double-primes it.
func TestInstructionFileRegistry_AiderIsAdapterOwned(t *testing.T) {
for _, spec := range InstructionFileRegistry {
assert.NotEqual(t, "aider", spec.AgentType,
"Aider must not be in the instruction-file registry — ox-adapter-aider owns CONVENTIONS.md")
assert.NotContains(t, spec.ProjectFiles, "CONVENTIONS.md",
"spec %s lists CONVENTIONS.md, which ox-adapter-aider already writes under its own markers", spec.AgentType)
}
}

func TestInstructionFileRegistry_PrimaryFilesAreMarkdown(t *testing.T) {
// AGENTS.md and CLAUDE.md must use markdown format -- they support HTML comments
for _, spec := range InstructionFileRegistry {
Expand Down
Loading