What specific problem does this solve?

Roo Code's Custom Modes allow flexible natural language guidance through YAML files (e.g., embedding instructions in prompt fields for agent behavior like code generation or refactoring), but this is tool-specific and doesn't interoperate with other AI coding agents. Developers using multiple tools (e.g., Roo Code alongside Aider, Cline, or GitHub Copilot) must maintain separate configs—.roomodes or YAML for Roo, CONVENTIONS.md for Aider, .clinerules/ for Cline—leading to redundancy, increased maintenance, and fragmentation. This is especially problematic in collaborative or multi-tool workflows, where consistent rules (e.g., coding styles, security practices, testing workflows) can't be shared seamlessly.

Adopting the Agent Rules standard addresses this by enabling an AGENTS.md file (in addition to existing conventions) in the project root to provide natural language guidelines usable across agents. Benefits include:

• Interoperability: Define rules once (e.g., "Prefer async/await, aim for 80% test coverage") and reuse them without duplication.
• Efficiency: Reduces setup time, version control clutter, and errors in mixed-agent environments.
• Scalability: Simplifies team consistency in large projects or monorepos, inspired by standards like EditorConfig.
  Current tools supporting/configurable for Agent Rules: Codex CLI (native), Aider (via config), Gemini CLI (via settings.json), and OpenCode (native). For details, see https://agent-rules.org/.

Supporting a basic standard makes it easy for developers to try new tools, e.g. if a corporate team uses ChatCPT Codex but an individual developer wants to use Roo (and maybe they like the extended configurability of Roo modes)

Additional context (optional)

The Agent Rules initiative (https://agent-rules.org/) is a minimalist spec for a unified Markdown/plain text file, focusing on natural language without required structure. It's backward-compatible, allowing Roo Code to load AGENTS.md alongside Custom Modes/.roomodes. This aligns with Roo's emphasis on customizable agents (e.g., via MCP) and could position it as an early adopter, boosting community appeal—similar to how EditorConfig unified editor configs. No existing issues/PRs on standardization found in the repo, but it ties into discussions on mode extensibility (e.g., YAML prompt enhancements in v3.18+ release notes).

Roo Code Task Links (Optional)

No response

Request checklist

• I've searched existing Issues and Discussions for duplicates
• This describes a specific problem with clear impact and context

Interested in implementing this?

• Yes, I'd like to help implement this feature

Implementation requirements

• I understand this needs approval before implementation begins

How should this be solved? (REQUIRED if contributing, optional otherwise)

Implement support by checking for AGENTS.md in the project root and incorporating its content as natural language into agent prompts or as a default Custom Mode. Keep it optional/complementary to existing YAML modes.

1. Detection and Loading: In the extension activation (e.g., src/extension.ts), get the workspace root (via vscode.workspace.workspaceFolders). Check fs.existsSync(root + '/AGENTS.md'), read as UTF-8 text if present.
2. Integration: Treat as natural language—append to global system prompts (e.g., in src/llm/promptBuilder.ts or src/agents/agent.ts: prompt += \n\nProject Guidelines: ${agentsContent}). Or create a virtual Custom Mode (YAML-like object) with { prompt: agentsContent, alwaysApply: true }.
3. Fallback/Conjunction: Load alongside .roomodes/Custom Modes; if conflicts, prioritize AGENTS.md or make toggleable.
4. Settings: Add a VS Code setting (package.json): "roo.useAgentRules" (boolean, default: true) to enable/disable.
5. Docs: Update README/docs.roocode.com with a section on Agent Rules, including examples.

This is a relatively small amount of effort.

How will we know it works? (Acceptance Criteria - REQUIRED if contributing, optional otherwise)

• Unit Tests: Add tests in src/tests/ (mock fs, verify AGENTS.md content in prompts/modes).
• Integration Tests: Simulate workspace with AGENTS.md; check chat/refactor outputs include rules (e.g., agent follows "use async/await").
• User Verification: In UI (chat popover), display loaded rules; confirm via logs or references list.
• Success Metrics: No regressions in Custom Modes; positive feedback in issues; adoption tracked via mentions of AGENTS.md in community modes.

Test case

• Given a Roo Code extension environment with the proposed changes implemented and a test workspace containing an AGENTS.md file in the project root with sample natural language rules (e.g., "Prefer async/await over callbacks").
• When the extension is activated and a chat/refactor session is initiated.
• Then the agent prompts or Custom Modes should include the content from AGENTS.md (verified via unit tests mocking fs in src/tests/, e.g., asserting rules are appended to prompts).
• And integration tests simulating the workspace should confirm outputs follow the rules (e.g., generated code uses async/await), with UI elements like the chat popover displaying loaded rules and logs/references confirming inclusion without errors.
• But if AGENTS.md is missing or the setting is disabled, existing Custom Modes should function without regressions.

Technical considerations (REQUIRED if contributing, optional otherwise)

• Dependencies: Use Node fs/path (already in repo); no new libs needed.
• Performance: Minimal—one file check/read per session; handle large files by truncating if token limits hit.
• Edge Cases: Empty/missing file (ignore); non-UTF-8 (fallback to defaults); monorepos (load from root only, or extend to hierarchy later).
• Compatibility: Ensure works with MCP (append to mode configs); test on Windows/macOS/Linux.

Trade-offs and risks (REQUIRED if contributing, optional otherwise)

• Continuing with a fragmented system of configuration (the existing) is possible, but makes it more difficult for teams where there are users of multiple tools.
• Roo does have an existing configuration system with a lot more features (using modes). Supporting a standard file is meant to be a minimal standard and be usable alongside custom rule systems, i.e. both.
• Standardisation is more important than the specific file name, but AGENTS.md is a generic name and already used by two tools, plus usable in configurable tools.
• Trade-offs: Slight added complexity (extra check) vs. major interoperability gains; optional setting mitigates for minimalists.
• Risks: If not toggled, could bloat prompts in rare cases (mitigate with truncation); potential merge conflicts if AGENTS.md contradicts modes (document as user-managed). Low adoption risk if not promoted, but linking to https://agent-rules.org/ helps.
• Other tools might put all of their rules into AGENTS.md, e.g. a section on HTML and another section on front end code, etc. Roo would approach this by having separate modes for each. There is a potential that instructions from the other scenarios could pollute a specific mode (although presumably the instructions for the same scenarios would be the same and be reinforced). One potential solution is to add a flag to the Roo modes to be able toi disable the shared guidance (disable AGENTS.md) for that mode.

Disclaimer: I am the maintainer of https://agent-rules.org/