Roo-Code Rules Directory Support Design Document

# 🎨 Design Doc: Roo-Code Rules Directory Support ## 1. Overview ### 1.1 Purpose This design document defines the specifications for implementing directory-based rule support in Roo-Code, similar to Cline. Specifically, it aims to enable users to manage rule files using the `.roo/rules/*.md` directory structure. ### 1.2 Background Currently, Roo-Code supports the following rule file formats: - `.roorules` - Global rule file - `.roorules-${mode}` - Mode-specific rule file Cline, on the other hand, supports multiple files within a directory. By introducing this feature to Roo-Code, users will be able to split rules into multiple files, enabling more flexible management. ### 1.3 Scope - Support for `.roo/rules/*.md` directory structure - Maintaining compatibility with existing rule file formats - Integration with Roo-Code's mode functionality - Proposal to migrate the `.roomodes` file to `.roo/modes` ## 2. Requirements ### 2.1 Functional Requirements 1. Read `.md` files in the `.roo/rules/` directory as rule files 2. Maintain compatibility with existing `.roorules` and `.roorules-${mode}` files 3. Support mode-specific rule directories (`.roo/rules-${mode}/`) 4. Read directory files in alphabetical order by filename 5. Display filenames as headers before each rule 6. Appropriately combine content from multiple rule files ## 3. Design ### 3.1 Directory Structure ``` Project Root/ ├── .roorules # Existing global rule file (single file) ├── .roorules-${mode} # Existing mode-specific rule file (single file) ├── .rooignore # Maintained at project root ├── .roomodes # Current mode definition file (to be migrated to .roo/modes in the future) ├── .roo/ # New Roo configuration directory │ ├── modes # Future location for mode definition file │ ├── rules/ # Global rules directory │ │ ├── 01-general.md # Rule file (markdown format) │ │ ├── 02-coding.md # Rule file │ │ └── ... │ └── rules-${mode}/ # Mode-specific rules directory │ ├── 01-specific.md # Mode-specific rule file │ └── ... ``` ### 3.2 Priority Order The priority order for loading rule files will be as follows: 1. Mode-specific rules 1. Files in the `.roo/rules-${mode}/` directory 2. `.roorules-${mode}` file 2. Global rules 1. Files in the `.roo/rules/` directory 2. `.roorules` file Within the same priority level, files in directories will take precedence over single files. This approach encourages migration to the directory structure. ### 3.3 Migration of the .roomodes File Currently, mode definitions are stored in the `.roomodes` file (JSON format) at the project root. We propose migrating this file to `.roo/modes` in the future. Migration plan: 1. Initially support both `.roomodes` and `.roo/modes` files 2. Prioritize `.roo/modes` if it exists 3. Deprecate `.roomodes` in future versions and recommend migration to `.roo/modes` 4. End support for `.roomodes` after a sufficient migration period This migration will consolidate all Roo-Code related configuration files in the `.roo/` directory, resulting in a more organized structure. ## 4. Compatibility and Migration ### 4.1 Backward Compatibility - Existing `.roorules` and `.roorules-${mode}` files will continue to be supported - New directory structures will take precedence if they exist - The `.rooignore` file will remain unchanged at the project root - The `.roomodes` file will continue to be supported at the project root for the time being ### 4.2 Migration Guidance We will provide users with the following migration steps: 1. Create a `.roo/rules/` directory at the project root 2. Split the content of existing `.roorules` files appropriately and save them as files with `.md` extensions 3. Use meaningful filenames that reflect the content, with numeric prefixes to control order if needed (e.g., `01-general.md`) 4. Similarly migrate mode-specific rules to the `.roo/rules-${mode}/` directory 5. Use directory names that match the `slug` defined in the `.roomodes` file 6. Consider migrating the `.roomodes` file to `.roo/modes` in the future ## 5. Implementation Plan ### 5.1 Implementation Steps 1. Implement functionality to read rule files from the `.roo/rules/` directory 2. Implement functionality to read mode-specific rules from the `.roo/rules-${mode}/` directory 3. Implement rule combination processing based on priority 4. Ensure compatibility with existing rule files 5. Update documentation ### 5.2 Impact Areas - Changes to the `src/core/prompts/sections/custom-instructions.ts` file - Updates to related test files ## 6. Rationale We chose the `.roo/rules/*.md` structure and future migration to `.roo/modes` for the following reasons: 1. The `.roo/` directory serves as a versatile location for storing other configurations in the future 2. The `rules/` subdirectory clearly indicates its purpose 3. Limiting to the `.md` extension explicitly indicates that rule files are in markdown format 4. Consistency is maintained with mode-specific rule directories (`.roo/rules-${mode}/`) 5. Keeping `.rooignore` at the project root minimizes impact on existing users 6. Gradual migration from `.roomodes` to `.roo/modes` will consolidate all configuration files in one location ## 7. Conclusion The `.roo/rules/*.md` directory support proposed in this design document significantly enhances Roo-Code's rule management capabilities. Users will be able to divide rules logically and manage them in a more organized manner. The design maintains compatibility with existing functionality while enabling more flexible rule management. Additionally, the future migration from `.roomodes` to `.roo/modes` will consolidate all Roo-Code related configuration files in the `.roo/` directory, resulting in a more organized structure. This will make it easier for users to locate configuration files and simplify management.