feat: Add hierarchical rule loading from parent directories

[KJ7LNW]

Context

Currently, Roo only loads custom rules from the immediate working directory, which creates several limitations:

1. Redundancy and Maintenance Burden: Users must duplicate common rules across multiple project directories.
2. Context Fragmentation: When working in subdirectories, the AI loses access to project-level rules.
3. Feature Branch Isolation: When developing multiple features for the same project in different directories, each needs its own complete set of rules.

This PR implements hierarchical loading of custom rules by traversing from the current working directory up to the root directory, collecting and merging rules at each level. This enables:

• Organization-wide rules at organization repository roots
• Project-wide rules at project roots
• Feature-specific rules in feature directories

Implementation

Added a new addSingleCustomInstructions function to handle loading rules from a single directory level and modified addCustomInstructions to traverse from the current directory up to the root. Rules from parent directories are loaded first (starting from root).

How to Test

• Create a .roo/rules/ directory in a parent directory of your project
• Add some rule files to it
• Create a .roo/rules/ directory in your project directory with different rules
• Verify that both sets of rules are loaded

Get in Touch

Discord: KJ7LNW

Fixes #4364

---

Important

This PR adds hierarchical rule loading from parent directories with a configurable depth, enhancing rule management across project levels.

• Behavior:
  • Implements hierarchical rule loading by traversing parent directories up to a configurable depth (parentRulesMaxDepth).
  • Rules from parent directories are loaded first, starting from the root.
• Configuration:
  • Adds parentRulesMaxDepth to global-settings.ts to control directory traversal depth.
  • UI component added in ModesView.tsx for setting parentRulesMaxDepth.
• Core Logic:
  • Modifies getRooDirectoriesForCwd() in index.ts to support parent directory traversal.
  • Uses a Set to avoid duplicate directories and ensures proper sorting.
• Testing:
  • Updates tests in index.spec.ts to cover new traversal logic and configuration.
• Localization:
  • Updates multiple localization files to include strings for parentRulesMaxDepth setting.

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

[KJ7LNW]

Cc: @swiftugandan, @yisrael-rosen, @MusiCode1 because they heart-emojii'ed this feature in Cline last year, but it was never merged.

[KJ7LNW]

This is ready for review.

[daniel-lxs]

Hey @KJ7LNW, Thanks for your contribution! The implementation looks clean and the feature addresses a real pain point.

However I would like to know what you think about allowing users to disable this behavior, specially since for some users it might be quite unexpected or undesirable (it can potentially add a lot of tokens to each request without the user knowing).

Also the implementation could really benefit from some unit tests.

Let me know what you think!

[KJ7LNW]

The setting has been added on the "Modes" page:

and console.info provides debug if necessary:

[Roo Rules] Detected .roo/rules-code directory: /home/ewheeler/src/roo/Roo3/.roo/rules-code
[Roo Rules] Detected .roo/rules directory: /home/ewheeler/src/roo/Roo3/.roo/rules
[Roo Rules] Detected .roo/rules directory: /home/ewheeler/src/roo/.roo/rules
[Roo Rules] Detected .roo/rules-code directory: /home/ewheeler/.roo/rules-code
[Roo Rules] Detected .roo/rules directory: /home/ewheeler/.roo/rules

[daniel-lxs]

Hey @KJ7LNW, it seems like the failing test is genuine. Can you take a look?

[daniel-lxs]

Not really sure how this PR is consistently triggering this test and causing it to fail.

I'll approve the changes but it would be great if @cte could take a quick look, maybe I'm missing something here.

[daniel-lxs]

Hey @KJ7LNW, I looked into the test failure and tried to sort it out.

The issue seems to come from the webview build trying to bundle Node.js-only modules like fs, path, and os, which obviously don't work in the browser. This happens because getFullModeDetails in src/shared/modes.ts was calling addCustomInstructions, which pulls in those modules.

Since src/shared/modes.ts is also used by the webview, Vite tries to include those Node modules in the browser bundle, which causes the build to fail.

I tried moving the call to addCustomInstructions into the extension side (src/core/environment/getEnvironmentDetails.ts) so it runs in Node, and passed the result into getFullModeDetails as a string.

While the tests are passing now, I still couldn’t get the actual behavior to work correctly again. Something's still off, and custom instructions aren't loading the way they should.

Please take a look when you get a chance and let me know what you find. Happy to pair on it if needed.

The unit tests need fixing

[KJ7LNW]

@daniel-lxs - I was able to reproduce it locally by running a build:

The problem was caused by d97ac5d04a27897b7259c0e78d1f1d23e2aad79d - for some reason it does not like await import("../../../core/config/ContextProxy") but require("../../../core/config/ContextProxy") works fine.

I am going to rework this pull request so leave it as in progress for now.

[KJ7LNW]

@daniel-lxs this is fixed up and ready to review

[hannesrudolph]

@KJ7LNW Thanks for your work on this PR. However, we're closing it for now, as the solution introduces complexity that seems disproportionate to the relatively niche problem described in the linked issue. At this stage, we don't have sufficient evidence indicating this impacts enough users to justify the additional complexity and maintenance overhead. If further data emerges showing broader user impact, please feel free to reopen or revisit this approach.