docs: enhance custom instructions and modes documentation with file structure examples (#123)

Author: hannesrudolph

docs/features/custom-instructions.md

@@ -2,6 +2,45 @@
 
 Custom Instructions allow you to personalize how Roo behaves, providing specific guidance that shapes responses, coding style, and decision-making processes.
 
+:::info Instruction File Locations
+You can provide custom instructions using dedicated files or directories within your workspace. This allows for better organization and version control.
+
+**Workspace-Wide Instructions:** Apply to all modes in the project.
+*   **Preferred Method: Directory (`.roo/rules/`)**
+    ```
+    .
+    ├── .roo/
+    │   └── rules/          # Workspace-wide rules
+    │       ├── 01-general.md
+    │       └── 02-coding-style.txt
+    └── ... (other project files)
+    ```
+*   **Fallback Method: Single File (`.roorules`)**
+    ```
+    .
+    ├── .roorules           # Workspace-wide rules (single file)
+    └── ... (other project files)
+    ```
+
+**Mode-Specific Instructions:** Apply only to a specific mode (e.g., `code`).
+*   **Preferred Method: Directory (`.roo/rules-{modeSlug}/`)**
+    ```
+    .
+    ├── .roo/
+    │   └── rules-code/     # Rules for "code" mode
+    │       ├── 01-js-style.md
+    │       └── 02-ts-style.md
+    └── ... (other project files)
+    ```
+*   **Fallback Method: Single File (`.roorules-{modeSlug}`)**
+    ```
+    .
+    ├── .roorules-code      # Rules for "code" mode (single file)
+    └── ... (other project files)
+    ```
+The directory methods take precedence if they exist and contain files. See [Workspace-Level Instructions](#workspace-level-instructions) and [Mode-Specific Instructions](#mode-specific-instructions) for details.
+:::
+
 ## What Are Custom Instructions?
 
 Custom Instructions define specific behaviors, preferences, and constraints beyond Roo's basic role definition. Examples include coding style, documentation standards, testing requirements, and workflow guidelines.

docs/features/custom-modes.md

@@ -2,6 +2,28 @@
 
 Roo Code allows you to create **custom modes** to tailor Roo's behavior to specific tasks or workflows. Custom modes can be either **global** (available across all projects) or **project-specific** (defined within a single project).
 
+:::info Mode-Specific Instruction File Locations
+You can provide instructions for custom modes using dedicated files or directories within your workspace. This allows for better organization and version control compared to only using the JSON `customInstructions` property.
+
+**Preferred Method: Directory (`.roo/rules-{mode-slug}/`)**
+```
+.
+├── .roo/
+│   └── rules-docs-writer/  # Example for mode slug "docs-writer"
+│       ├── 01-style-guide.md
+│       └── 02-formatting.txt
+└── ... (other project files)
+```
+
+**Fallback Method: Single File (`.roorules-{mode-slug}`)**
+```
+.
+├── .roorules-docs-writer  # Example for mode slug "docs-writer"
+└── ... (other project files)
+```
+The directory method takes precedence if it exists and contains files. See [Mode-Specific Instructions via Files/Directories](#mode-specific-instructions-via-filesdirectories) for details.
+:::
+
 ## Why Use Custom Modes?
 
 *   **Specialization:** Create modes optimized for specific tasks, like "Documentation Writer," "Test Engineer," or "Refactoring Expert"