feat: add support for Agent Rules standard via AGENTS.md (#5966) #5969

roomote · 2025-07-20T01:59:27Z

Implements #5966 - Adds support for the Agent Rules standard (agent-rules.org) via project root AGENTS.md files. This enables unified natural language guidelines across different AI coding tools.

Changes

Added AGENTS.md detection and loading in custom-instructions.ts
Added VS Code setting roo-cline.useAgentRules (default: true) to enable/disable the feature
Integrated AGENTS.md content into the existing custom instructions system
Added comprehensive test coverage for the new functionality
Updated README to mention Agent Rules support

Implementation Details

AGENTS.md is loaded from the project root directory when present
The content is included in the rules section of the prompt, after rooIgnore but before generic rules
The feature is optional and backward compatible - if AGENTS.md is not present, the system works as before
Users can disable the feature via VS Code settings if needed

Testing

All existing tests pass
Added 6 new test cases specifically for AGENTS.md functionality
Tests cover: file loading, error handling, setting integration, and content formatting

This implementation follows the approach outlined in the issue description, making AGENTS.md optional and complementary to existing YAML modes.

Important

Adds support for AGENTS.md files in the prompt system, with a new setting to enable/disable its use, and updates tests and documentation accordingly.

Behavior:
- Adds support for AGENTS.md in custom-instructions.ts, integrating content into the prompt system.
- Introduces roo-cline.useAgentRules setting in package.json to enable/disable AGENTS.md loading (default: true).
- Updates RooProtectedController to protect AGENTS.md files.
Implementation:
- Loads AGENTS.md from project root, included in prompt rules section.
- Backward compatible: system functions without AGENTS.md if not present.
Testing:
- Adds tests in custom-instructions.spec.ts for AGENTS.md loading and error handling.
- Updates system-prompt.spec.ts to test useAgentRules setting.
Documentation:
- Updates README.md and localization files to mention AGENTS.md support.

^{This description was created by}^{for d3fb2b4. You can customize this summary. It will automatically update as commits are pushed.}

src/package.nls.fr.json

- Add AGENTS.md detection and loading in custom-instructions.ts - Add VS Code setting "roo-cline.useAgentRules" (default: true) - Integrate with existing custom instructions system - Add comprehensive test coverage for AGENTS.md functionality - Update README to mention Agent Rules support This enables unified natural language guidelines across different AI coding tools following the agent-rules.org standard.

- Revert README.md changes (no longer needed) - Add agent-rules.org link to useAgentRules setting description - Change default value of useAgentRules to false - Update tests to reflect new default behavior - Update all language translations with the new setting description

As requested in PR review, removing the Agent Rules mention from README.md since the feature is now disabled by default.

ellipsis-dev · 2025-07-23T20:29:02Z

src/core/prompts/sections/custom-instructions.ts

@@ -297,6 +318,14 @@ export async function addCustomInstructions(
 		rules.push(options.rooIgnoreInstructions)
 	}

+	// Add AGENTS.md content if enabled (default: false)


The condition for including AGENTS.md has been changed from options.useAgentRules !== false to options.useAgentRules === true, and the comment now says "default: false". This conflicts with the PR description which states the default should be true. Please clarify and align the default behavior (and documentation) for useAgentRules.

mrubens · 2025-07-23T20:38:41Z

@roomote-agent can you add AGENTS.md to the list of protected files?

roomote · 2025-07-23T20:40:35Z

Hi @mrubens! I see your request to add AGENTS.md to the list of protected files. I'll work on this right away.

roomote · 2025-07-23T20:50:11Z

Hi @mrubens! I've successfully added AGENTS.md to the list of protected files.

Here's what I did:

Added "AGENTS.md" to the PROTECTED_PATTERNS array in RooProtectedController.ts
Added a test case to verify AGENTS.md is protected
Updated the getProtectedPatterns test to include AGENTS.md

All tests are passing and CI checks have completed successfully. The AGENTS.md file will now be write-protected and require approval for modifications, just like other Roo configuration files.

src/core/prompts/system.ts

mrubens · 2025-07-23T21:00:29Z

@roomote-agent i think we should default this setting to true

roomote · 2025-07-23T21:01:09Z

Hi @mrubens! Great question about the design choice.

The AGENTS.md file approach was chosen over passing rules through settings for several key reasons:

Interoperability: The Agent Rules standard (agent-rules.org) is designed to work across multiple AI coding tools. By using a standardized file in the project root, teams can define rules once and have them work with Roo Code, Aider, Cline, and other compatible tools. Settings would be Roo-specific and defeat this cross-tool compatibility.
Version Control: AGENTS.md lives in the project repository, making it easy to version control, review in PRs, and share across the team. VS Code settings are typically user-specific or workspace-specific and harder to manage consistently across a team.
Portability: When developers clone a project, the AGENTS.md file comes with it automatically. They don't need to configure settings or copy configuration between machines.
Separation of Concerns: Project-specific coding guidelines belong with the project code, not in editor settings. This follows the same philosophy as .editorconfig, .prettierrc, etc.

The VS Code setting (roo-cline.useAgentRules) is used only to enable/disable the feature, giving users control while keeping the actual rules in the standardized file format.

This approach aligns with the issue #5966 goals of reducing fragmentation and enabling teams to maintain consistent guidelines across different AI tools.

roomote · 2025-07-23T21:02:28Z

Hi @mrubens! I see your comment about defaulting the useAgentRules setting to true. I'll make that change now.

@mrubens

- Updated default value in package.json from false to true - Updated implementation to load AGENTS.md when useAgentRules is undefined - Updated test expectations to match new default behavior - Updated fallback values in Task.ts and generateSystemPrompt.ts This enables AGENTS.md loading by default as requested by @mrubens

roomote · 2025-07-23T21:25:34Z

✅ Done! I've updated the default value of useAgentRules to true as requested.

Changes made:

Updated useAgentRules default from false to true in src/package.json
Modified the condition in custom-instructions.ts to check for !== false instead of === true to properly handle the undefined case
Updated test expectations in custom-instructions.spec.ts to reflect the new default behavior
Fixed test mocks in custom-instructions-global.spec.ts to account for AGENTS.md being loaded by default

All CI checks are now passing! The Agent Rules standard (AGENTS.md) will now be loaded by default when the setting is not explicitly configured.

Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>

roomote bot requested review from mrubens, cte and jr as code owners July 20, 2025 01:59

github-project-automation bot added this to Roo Code Roadmap and Roo Code Roadmap Jul 20, 2025

github-project-automation bot moved this to New in Roo Code Roadmap Jul 20, 2025

github-project-automation bot moved this to Triage in Roo Code Roadmap Jul 20, 2025

dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. documentation Improvements or additions to documentation enhancement New feature or request labels Jul 20, 2025

hannesrudolph added the Issue/PR - Triage New issue. Needs quick review to confirm validity and assign labels. label Jul 20, 2025

roomote bot mentioned this pull request Jul 20, 2025

Add Support for Agent Rules Standard via Project Root AGENTS.md for Unified Natural Language Guidelines #5966

Closed

4 tasks

daniel-lxs moved this from Triage to PR [Needs Prelim Review] in Roo Code Roadmap Jul 22, 2025

hannesrudolph added PR - Needs Preliminary Review and removed Issue/PR - Triage New issue. Needs quick review to confirm validity and assign labels. labels Jul 22, 2025

ellipsis-dev bot reviewed Jul 23, 2025

View reviewed changes

src/package.nls.fr.json Outdated Show resolved Hide resolved

daniel-lxs approved these changes Jul 23, 2025

View reviewed changes

dosubot bot added lgtm This PR has been approved by a maintainer size:XS This PR changes 0-9 lines, ignoring generated files. and removed size:L This PR changes 100-499 lines, ignoring generated files. labels Jul 23, 2025

roomote-agent and others added 2 commits July 23, 2025 15:08

daniel-lxs force-pushed the feature/agent-rules-support branch from 2c7a4a7 to d149c5b Compare July 23, 2025 20:09

dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. and removed size:XS This PR changes 0-9 lines, ignoring generated files. labels Jul 23, 2025

daniel-lxs added 2 commits July 23, 2025 15:19

fix: revert README.md changes for AGENTS.md feature

073e817

As requested in PR review, removing the Agent Rules mention from README.md since the feature is now disabled by default.

fix: ensure AGENTS.md only loads when useAgentRules is explicitly true

2fc7bf5

ellipsis-dev bot reviewed Jul 23, 2025

View reviewed changes

feat: add AGENTS.md to protected files list

8456f02

daniel-lxs moved this from PR [Needs Prelim Review] to PR [Needs Review] in Roo Code Roadmap Jul 23, 2025

hannesrudolph added PR - Needs Review and removed PR - Needs Preliminary Review labels Jul 23, 2025

mrubens reviewed Jul 23, 2025

View reviewed changes

src/core/prompts/system.ts Outdated Show resolved Hide resolved

roomote-agent added 2 commits July 23, 2025 21:06

fix: update test mocks to account for AGENTS.md being loaded by default

e3c11af

mrubens and others added 5 commits July 24, 2025 00:12

Type cleanup

f77189b

Fixes to generateSystemPrompt

aa4b35e

Update src/package.nls.fr.json

565b4ef

Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>

Update custom-instructions-global.spec.ts

9ad49a1

Ensure that all settings are passed in

d3fb2b4

mrubens approved these changes Jul 24, 2025

View reviewed changes

mrubens merged commit 3977bbc into main Jul 24, 2025
10 checks passed

mrubens deleted the feature/agent-rules-support branch July 24, 2025 04:42

github-project-automation bot moved this from PR [Needs Review] to Done in Roo Code Roadmap Jul 24, 2025

github-project-automation bot moved this from New to Done in Roo Code Roadmap Jul 24, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add support for Agent Rules standard via AGENTS.md (#5966) #5969

feat: add support for Agent Rules standard via AGENTS.md (#5966) #5969

Uh oh!

roomote bot commented Jul 20, 2025 •

edited by ellipsis-dev bot

Loading

Uh oh!

Uh oh!

ellipsis-dev bot Jul 23, 2025

Uh oh!

mrubens commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

Uh oh!

mrubens commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

feat: add support for Agent Rules standard via AGENTS.md (#5966) #5969

feat: add support for Agent Rules standard via AGENTS.md (#5966) #5969

Uh oh!

Conversation

roomote bot commented Jul 20, 2025 • edited by ellipsis-dev bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Implementation Details

Testing

Uh oh!

Uh oh!

ellipsis-dev bot Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

mrubens commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

Uh oh!

mrubens commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

roomote bot commented Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

roomote bot commented Jul 20, 2025 •

edited by ellipsis-dev bot

Loading