diff --git a/docs/advanced-usage/custom-instructions.md b/docs/advanced-usage/custom-instructions.md index cc53c2ca..ce8cfabf 100644 --- a/docs/advanced-usage/custom-instructions.md +++ b/docs/advanced-usage/custom-instructions.md @@ -1,61 +1,83 @@ # Custom Instructions -Roo Code allows you to customize its behavior using instructions. These instructions are added to the system prompt and influence how Roo Code responds to your requests. You can define: +Roo Code allows you to customize its behavior using custom instructions at both global and workspace levels. These instructions are added to the system prompt and influence how Roo Code responds to your requests. You can define: -* **Global Custom Instructions:** Apply to all modes. -* **Mode-Specific Custom Instructions:** Apply only to a specific mode. -* **`.clinerules` Files:** Generic rules that apply across all modes, or create mode-specific rules files like `.clinerules-code` +* **Global Custom Instructions:** Apply across all workspaces +* **Workspace-Level Instructions:** + * **Workspace-Wide:** Apply to all modes in the workspace through `.clinerules` files + * **Mode-Specific:** Apply to specific modes in the workspace through files like `.clinerules-code` + +## Preferred Language + +You can specify a preferred language for Roo Code to use. When set, this appears at the start of your custom instructions and directs Roo Code to communicate in your chosen language. You can set this in the **Prompts** tab. ## Global Custom Instructions -These instructions are added to every prompt, regardless of the active mode. They're useful for setting general preferences or providing information that's always relevant. +These instructions apply across all workspaces. They're useful for setting preferences that you want to maintain regardless of which project you're working on. **How to set them:** -1. Open the Roo Code panel (). -2. Click the "Prompts" button in the top menu bar. -3. Find the "Custom Instructions for All Modes" section. -4. Enter your instructions in the text area. -5. Click "Done" to save your changes. +1. **Open Prompts Tab:** Click the icon in the Roo Code top menu bar +2. **Find Section:** Find the "Custom Instructions for All Modes" section +3. **Enter Instructions:** Enter your instructions in the text area +4. **Save Changes:** Click "Done" to save your changes -## Mode-Specific Custom Instructions +## Workspace-Level Instructions -These instructions are added only when a specific mode is active. They allow you to fine-tune Roo Code's behavior for different tasks. +These instructions only apply within your current workspace, allowing you to customize Roo Code's behavior for specific projects. -**How to set them:** +### Workspace-Wide Instructions -1. Open the Roo Code panel (). -2. Click the "Prompts" button in the top menu bar. -3. Select the mode you want to customize from the dropdown. -4. Find the "Mode-specific Custom Instructions" section. -5. Enter your instructions in the text area. -6. Click "Done" to save your changes. +Workspace-wide instructions are defined through rule files in your workspace root, primarily using `.clinerules`. Additional support for `.cursorrules` and `.windsurfrules` is available for editor compatibility. -**Note:** Mode-specific instructions are added *after* global custom instructions. +### Mode-Specific Instructions -## `.clinerules` and `.clinerules-[mode]` Files +Mode-specific instructions can be set in two independent ways that can be used simultaneously: -For more advanced customization, you can create `.clinerules` files in your workspace root. These files contain rules that Roo Code will follow. +1. **Using the Prompts Tab:** + * **Open Tab:** Click the icon in the Roo Code top menu bar + * **Select Mode:** Under the Modes heading, click the button for the mode you want to customize + * **Enter Instructions:** Enter your instructions in the text area under "Mode-specific Custom Instructions (optional)" + * **Save Changes:** Click "Done" to save your changes -* **`.clinerules`:** Contains general rules that apply to all modes. -* **`.clinerules-[mode]`:** Contains rules specific to a particular mode (e.g., `.clinerules-code`, `.clinerules-architect`). +2. **Using Rule Files:** Create a `.clinerules-[mode]` file in your workspace root (e.g., `.clinerules-code`) -**Format:** +When both tab instructions and rule files are set for a mode, both sets of instructions will be included in the system prompt. -Each line in a `.clinerules` file represents a single rule. You can use plain English to describe the rules. +### How Instructions are Combined -## Preferred Language +Instructions are placed in the system prompt in this exact format: + +``` +==== +USER'S CUSTOM INSTRUCTIONS +The following additional instructions are provided by the user, and should be followed to the best of your ability without interfering with the TOOL USE guidelines. +[Language Preference (if set)] +[Global Instructions] +[Mode-specific Instructions] + +Rules: +[.clinerules-{mode} rules] +[.clinerules rules] +[.cursorrules rules] +[.windsurfrules rules] +``` + +### About Rule Files -You can also specify a preferred language for Roo Code to use. This will instruct Roo Code to communicate with you in that language. You can set this in the **Prompts** tab. +* **File Location:** All rule files must be placed in the workspace root directory +* **Empty Files:** Empty or missing rule files are silently skipped +* **Source Headers:** Each rule file's contents are included with a header indicating its source +* **Rule Interaction:** Mode-specific rules complement global rules rather than replacing them ## Examples of Custom Instructions -* "Always use spaces for indentation, with a width of 4 spaces." -* "Use camelCase for variable names." -* "Write unit tests for all new functions." -* "Explain your reasoning before providing code." -* "Focus on code readability and maintainability." -* "Prioritize using the most common library in the community" -* "When adding new features to websites, ensure they are responsive and accessible." +* "Always use spaces for indentation, with a width of 4 spaces" +* "Use camelCase for variable names" +* "Write unit tests for all new functions" +* "Explain your reasoning before providing code" +* "Focus on code readability and maintainability" +* "Prioritize using the most common library in the community" +* "When adding new features to websites, ensure they are responsive and accessible" By using custom instructions, you can tailor Roo Code's behavior to match your coding style, project requirements, and personal preferences. \ No newline at end of file diff --git a/docs/advanced-usage/custom-modes.md b/docs/advanced-usage/custom-modes.md index 156009e7..1621d98e 100644 --- a/docs/advanced-usage/custom-modes.md +++ b/docs/advanced-usage/custom-modes.md @@ -2,18 +2,19 @@ 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). They allow you to define: -* **A unique name and slug:** For easy identification. -* **A role definition:** A description of the mode's purpose and expertise. -* **Custom instructions:** Specific guidelines for the AI to follow in this mode. -* **Allowed tools:** Which Roo Code tools the mode can use (e.g., read files, write files, execute commands). -* **File restrictions:** (Optional) Limit file access to specific file types or patterns (e.g., only allow editing `.md` files). +* **A unique name and slug:** For easy identification +* **A role definition:** Placed at the beginning of the system prompt, this defines Roo's core expertise and personality for the mode. This placement is crucial as it shapes Roo's fundamental understanding and approach to tasks +* **Custom instructions:** Added at the end of the system prompt, these provide specific guidelines that modify or refine Roo's behavior. Unlike `.clinerules` files (which only add rules at the end), this structured placement of role and instructions allows for more nuanced control over Roo's responses +* **Allowed tools:** Which Roo Code tools the mode can use (e.g., read files, write files, execute commands) +* **File restrictions:** (Optional) Limit file access to specific file types or patterns (e.g., only allow editing `.md` files) ## Why Use Custom Modes? -* **Specialization:** Create modes optimized for specific tasks, like "Documentation Writer," "Test Engineer," or "Refactoring Expert." -* **Safety:** Restrict a mode's access to sensitive files or commands. For example, a "Review Mode" could be limited to read-only operations. -* **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes. -* **Team Collaboration:** Share custom modes with your team to standardize workflows. +* **Specialization:** Create modes optimized for specific tasks, like "Documentation Writer," "Test Engineer," or "Refactoring Expert" +* **Default Modes Tool Access Customization:** Modify which tools are allowed for the default modes (Code, Architect, Ask). Note that restricting tools for default modes may cause unintended outcomes in Roo Code's performance +* **Safety:** Restrict a mode's access to sensitive files or commands. For example, a "Review Mode" could be limited to read-only operations +* **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes +* **Team Collaboration:** Share custom modes with your team to standardize workflows ## Creating Custom Modes @@ -21,157 +22,169 @@ You have three options for creating custom modes: ### 1. Ask Roo! (Recommended) -The easiest way to create or modify a custom mode is to simply **ask Roo Code to do it!** For example: +You can quickly create a basic custom mode by asking Roo Code to do it for you. For example: > Create a new mode called "Documentation Writer". It should only be able to read files and write Markdown files. -Or, to modify an existing mode: - -> Modify the "Code" mode to only allow reading files. - -Roo Code will guide you through the process. +Roo Code will guide you through the process. However, for fine-tuning modes or making specific adjustments, you'll want to use the Prompts tab or manual configuration methods described below. ### 2. Using the Prompts Tab -1. **Open the Prompts Tab:** Click the icon in the Roo Code top menu bar. -2. **Click "Create New Mode":** Use the button to add a new mode. -3. **Fill in the Fields:** Enter the mode's name, role definition, custom instructions, and select the allowed tool groups. -4. **Click "Create Mode":** Save your new mode. +1. **Open Prompts Tab:** Click the icon in the Roo Code top menu bar +2. **Create New Mode:** Click the button to the right of the Modes heading +3. **Fill in Fields:** + * **Name:** Enter a display name for the mode + * **Slug:** Enter a lowercase identifier (letters, numbers, and hyphens only) + * **Save Location:** Choose Global (via `cline_custom_modes.json`, available across all workspaces) or Project-specific (via `.roomodes` file in project root) + * **Role Definition:** Define Roo's expertise and personality for this mode (appears at the start of the system prompt) + * **Available Tools:** Select which tools this mode can use + * **Custom Instructions:** (Optional) Add behavioral guidelines specific to this mode (appears at the end of the system prompt) +4. **Create Mode:** Click the "Create Mode" button to save your new mode -Note: Adding/editing file type restrictions is not yet supported in the prompts tab UI. +Note: File type restrictions can only be added through manual configuration. ### 3. Manual Configuration -Custom modes can be configured by directly editing JSON files. There are two locations for custom mode configurations: +You can configure custom modes by editing JSON files through the Prompts tab: -1. **Global Configuration:** - * Located at `[path to global extension storage]/rooveterinaryinc.roo-cline/settings/cline_custom_modes.json` - * These modes are available across all projects. +Both global and project-specific configurations can be edited through the Prompts tab: -2. **Project-Specific Configuration:** - * Located in a `.roomodes` file in your project's root directory. - * These modes are only available within that specific project. - * **Project-specific modes take precedence over global modes with the same slug.** This means if you define a mode with the slug "code" in your `.roomodes` file, it will override the global "code" mode when you're working in that project. +1. **Open Prompts Tab:** Click the icon in the Roo Code top menu bar +2. **Access Settings Menu:** Click the button to the right of the Modes heading +3. **Choose Configuration:** + * Select "Edit Global Modes" to edit `cline_custom_modes.json` (available across all workspaces) + * Select "Edit Project Modes" to edit `.roomodes` file (in project root) +4. **Edit Configuration:** Modify the JSON file that opens +5. **Save Changes:** Roo Code will automatically detect the changes -To edit either configuration: +## Configuration Precedence -1. **Open the Prompts Tab:** Click the icon in the Roo Code top menu bar. -2. **Open the Settings File:** Click the icon in the top right corner of the "Prompts" tab. (This will allow you to edit either the Global or project-specific configuration file. You can also edit the project-specific configuration by manually creating/opening the `.roomodes` file in your project's root directory.) -3. **Edit the JSON:** Add or modify mode configurations within the `customModes` array, following the format described below. -4. **Save the File:** Roo Code will automatically detect the changes. +Mode configurations are applied in this order: -## Custom Mode Configuration (JSON Format) +1. Project-level mode configurations (from `.roomodes`) +2. Global mode configurations (from `cline_custom_modes.json`) +3. Default mode configurations -Both global and project-specific configuration files use the same JSON format. The configuration is a JSON object with a `customModes` key, which contains an array of mode definitions. Each mode definition is a JSON object with the following properties: +This means that project-specific configurations will override global configurations, which in turn override default configurations. -* `slug`: (Required) A unique identifier for the mode (lowercase letters, numbers, and hyphens). Shorter is better. -* `name`: (Required) The display name for the mode. -* `roleDefinition`: (Required) A detailed description of the mode's role and capabilities. -* `groups`: (Required) An array of allowed tool groups. Each group can be specified either as a string (e.g., `"edit"` to allow editing any file) or with file restrictions (e.g., `["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }]` to only allow editing markdown files). - * Available tool groups are: `"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"`. - * **Understanding `fileRegex`:** The `fileRegex` property uses a *regular expression* (or *regex*) to define which files the mode is allowed to edit. A regular expression is a sequence of characters that specifies a search pattern. Here's a breakdown of some common regex components used in the examples: - * `\.`: Matches a literal dot (`.`). The backslash is used to "escape" the dot, since a dot has a special meaning in regular expressions (matching any character). - * `(test|spec)`: Matches either "test" or "spec". The parentheses create a *capturing group*, and the pipe (`|`) acts as an "or". - * `(js|ts|jsx|tsx)`: Matches "js", "ts", "jsx", or "tsx". - * `$`: Matches the end of the string. This ensures that the entire filename matches the pattern, not just a part of it. - * For example, `\\.md$` matches any filename that ends with ".md". `\\.(test|spec)\\.(js|ts|jsx|tsx)$` matches filenames like "myComponent.test.js", "utils.spec.ts", etc. - * You can learn more about regular expressions on websites like [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions). -* `customInstructions`: (Optional) Additional instructions for the mode. - -Here are some examples: +## Custom Mode Configuration (JSON Format) -**Example 1: A simple documentation writer mode (could be global or project-specific):** +Both global and project-specific configurations use the same JSON format. Each configuration file contains a `customModes` array of mode definitions: ```json { "customModes": [ { - "slug": "docs-writer", - "name": "Docs Writer", - "roleDefinition": "You are a technical writer specializing in creating clear and concise documentation.", - "customInstructions": "Focus on explaining concepts and providing examples. Use Markdown format.", - "groups": [ - "read", - ["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }] - ] + "slug": "mode-name", + "name": "Mode Display Name", + "roleDefinition": "Mode's role and capabilities", + "groups": ["read", "edit"], + "customInstructions": "Additional guidelines" } ] } ``` -**Example 2: A test engineer mode (could be global or project-specific):** +### Required Properties + +#### `slug` +* A unique identifier for the mode +* Use lowercase letters, numbers, and hyphens +* Keep it short and descriptive +* Example: `"docs-writer"`, `"test-engineer"` + +#### `name` +* The display name shown in the UI +* Can include spaces and proper capitalization +* Example: `"Documentation Writer"`, `"Test Engineer"` + +#### `roleDefinition` +* Detailed description of the mode's role and capabilities +* Defines Roo's expertise and personality for this mode +* Example: `"You are a technical writer specializing in clear documentation"` + +#### `groups` +* Array of allowed tool groups +* Available groups: `"read"`, `"edit"`, `"browser"`, `"command"`, `"mcp"` +* Can include file restrictions for the `"edit"` group +##### File Restrictions Format ```json -{ - "customModes": [ - { - "slug": "test-engineer", - "name": "Test Engineer", - "roleDefinition": "You are a test engineer responsible for writing unit and integration tests.", - "groups": [ - "read", - ["edit", { "fileRegex": "\\.(test|spec)\\.(js|ts|jsx|tsx)$", "description": "Test files only" }] - ] - } - ] -} +["edit", { + "fileRegex": "\\.md$", + "description": "Markdown files only" +}] ``` -**Example 3: Adding a new mode in a `.roomodes` file (project-specific):** +### Optional Properties + +#### `customInstructions` +* Additional behavioral guidelines for the mode +* Example: `"Focus on explaining concepts and providing examples"` + +### Understanding File Restrictions + +The `fileRegex` property uses regular expressions to control which files a mode can edit: +* `\\.md$` - Match files ending in ".md" +* `\\.(test|spec)\\.(js|ts)$` - Match test files (e.g., "component.test.js") +* `\\.(js|ts)$` - Match JavaScript and TypeScript files + +Common regex patterns: +* `\\.` - Match a literal dot +* `(a|b)` - Match either "a" or "b" +* `$` - Match the end of the filename + +[Learn more about regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) + +### Example Configurations + +Each example shows different aspects of mode configuration: + +#### Basic Documentation Writer ```json { - "customModes": [ - { - "slug": "data-scientist", - "name": "Data Scientist", - "roleDefinition": "You are Roo, a data scientist with expertise in data analysis, machine learning, and statistical modeling.", - "groups": [ - "read", - "edit", - "command" - ], - "customInstructions": "Focus on data analysis and machine learning tasks." - } - ] + "customModes": [{ + "slug": "docs-writer", + "name": "Documentation Writer", + "roleDefinition": "You are a technical writer specializing in clear documentation", + "groups": [ + "read", + ["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }] + ], + "customInstructions": "Focus on clear explanations and examples" + }] } ``` -**Example 4: Overriding an existing mode in a `.roomodes` file (project-specific):** - +#### Test Engineer with File Restrictions ```json { - "customModes": [ - { - "slug": "code" - "name": "Code (Project-Specific)", - "roleDefinition": "You are Roo, a highly skilled software engineer. In this project, you have limited file access.", - "groups": [ - "read", - ["edit", { "fileRegex": "\\.(js|ts)$", "description": "JavaScript and TypeScript files only" }] - ], - "customInstructions": "Focus on JS and TS files in this project." - } - ] + "customModes": [{ + "slug": "test-engineer", + "name": "Test Engineer", + "roleDefinition": "You are a test engineer focused on code quality", + "groups": [ + "read", + ["edit", { "fileRegex": "\\.(test|spec)\\.(js|ts)$", "description": "Test files only" }] + ] + }] } ``` -**Example 5: Mode with File Restrictions (can be used in global or .roomodes)** +#### Project-Specific Mode Override ```json { - "customModes": [ - { - "slug": "markdown-editor", - "name": "Markdown Editor", - "roleDefinition": "You are Roo, a markdown editor with expertise in editing and formatting markdown files.", - "groups": [ - "read", - ["edit", { "fileRegex": "\\.md$", "description": "Markdown files only" }], - "browser" - ], - "customInstructions": "Focus on editing and formatting markdown files." - } - ] + "customModes": [{ + "slug": "code", + "name": "Code (Project-Specific)", + "roleDefinition": "You are a software engineer with project-specific constraints", + "groups": [ + "read", + ["edit", { "fileRegex": "\\.(js|ts)$", "description": "JS/TS files only" }] + ], + "customInstructions": "Focus on project-specific JS/TS development" + }] } ``` By following these instructions, you can create and manage custom modes to enhance your workflow with Roo-Code.